Ember CLI Mirage v1.0.0-beta.1

We've started the release process for v1.0! This major version is mostly focused on solidifying Mirage's existing APIs and ensuring there are no outstanding bugs. Once we move into 1.0, we can refocus on prioritizing new feature development.

This release is the first beta release of 1.0, and the only additional work needed to finalize 1.0 is a modernization of the docs.

Please try it out in your apps and report back any issues!

There are three 💥breaking changes in this release:

Remove Faker.js
Remove deprecated forms of create, createList and normalizedRequestAttrs
The normalizeIds serializer property now defaults to true

Other than these items, 1.0 should not involve any changes to your code.

If you run into any issues during the upgrade process, please open an issue or ping me in #ec-mirage on Discord!

1. Remove Faker.js

When Mirage was first released, including npm libraries into Ember CLI apps was difficult. You needed to generate a vendor shim and call app.import in order to use the library in your application code.

Because of all this ceremony, it was common for addons to do that work for you, and bundle related packages. This is exactly what Mirage did for Faker.js, a useful library to have alongside your Mirage factory definitions.

There's a few problems with this, most notably that users had to use the version of Faker that was bundled with Mirage. It was frustrating not being able to take advantage of new Faker features until Mirage upgraded its bundled version.

Now, thanks to Ember Auto Import, this is no longer the case. Using dependencies directly from npm is painless – just yarn/npm install them and import them directly from your ES6 classes. Thanks to Auto Import, all that ceremony is taken care of for you.

This also means that users can easily manage their project's version of Faker (and other similar dependencies) independently of the version of Mirage they're using.

For this reason, in 1.0 we are no longer bundling Faker.js with Mirage. This is a breaking change.

Here are the steps you'll need to take to fix this:

Install Ember Auto Import (if it's not already installed)

ember install ember-auto-import

Install Faker.js directly from npm:

yarn add -D faker

# or npm install --save-dev faker

Change all imports of faker from the ember-cli-packge to import directly from faker:

- import { Factory, faker } from 'ember-cli-mirage';
+ import { Factory } from 'ember-cli-mirage';
+ import faker from 'faker';

There is a codemod that will do this for you, thanks to the gracious work of Casey Watts.

Additionally, when I originally bundled Faker, I monkey-patched it with some methods that I thought would be "useful" additions. I thought this was a good idea at the time... it wasn't. 🙈

You can look at the module from v0.4.15 to see that we added the faker.list.random, faker.list.cycle and faker.random.number.range methods, so if you use these methods too, you'll need to refactor them.

Fortunately, two of them have been added to recent versions of Faker, and one can be replaced with some simple JS.

For faker.list.random, use faker.random.arrayElement:

  countries() {
-   return faker.list.random([ 'United States of America', 'Canada', 'Mexico' ]);
+   return faker.random.arrayElement([ 'United States of America', 'Canada', 'Mexico' ]);
  }

For faker.list.cycle, use the remainder (modulo) operator:

  countries(i) {
-   return faker.list.cycle([ 'United States of America', 'Canada', 'Mexico' ]);

+   let countries = [ 'United States of America', 'Canada', 'Mexico' ];
+   
+   return countries[i % countries.length];
  }

For faker.random.number.range, use faker.random.number with min and max options:

  age() {
-   return faker.random.number.range(18, 65);
+   return faker.random.number({ min: 18, max: 65 });
  }

After that, you should be on your own with regards to Faker! Thanks to Auto Import, you can change versions, or even try out other libraries like Chance.js, and rest easy knowing Mirage is a bit slimmer and one less thing is beyond your control.

2. Remove deprecated forms of `create`, `createList` and `normalizedRequestAttrs`

There are several places in Mirage's APIs that were intended to be used with singularized versions of model names, but just so happened to work if a non-singularized version was passed in.

This behavior was discovered during a refactor, and the non-singularized versions were maintained to avoid breaking apps. Now that we're moving to 1.0, we're removing this deprecated/unintentional behavior.

server.create and server.createList were coded to take a singularized model name, e.g. server.create('user'). It just so happens that server.create('users') also works. That pluralized version is now removed from Mirage.

If you're running the latest 0.x version you should see a deprecation message letting you know where to change it. Otherwise, it should be a pretty mechanic change from things like server.create('users') to server.create('user').

Note this also applies to server.createList – the correct form is server.createList('user', 3), and the pluralized form server.createList('users', 3) is now unsupported.
this.normalizedRequestAttrs in a route handler optionally takes a modelName as an argument. This is if your URLs are non-standard and Mirage cannot guess the modelName from the URL path.

In this case, you can call this.normalizedRequestAttrs('blog-post') to tell Mirage to expect the payload to be for a blog-post model.

This API was intended to be used with dasherized names, because that's how compound model names are specified throughout Mirage when they are represented as strings.

It just so happened that this.normalizedRequestAttrs('blogPost') also worked, by chance, until a refactor. So, that behavior was kept but now is being removed.

The correct usage is this.normalizedRequestAttrs('blog-post'). Using the camelized version of the model name is no longer supported.

If either of these changes cause a ton of refactoring pain, we can try to marshal some resources to help write a codemod. Please open an issue if that's the case!

3. The `normalizeIds` serializer property now defaults to true

This applies to the ActiveModelSerializer and RestSerializer.

The normalize property on serializers helps Mirage's shorthands work by transforming differently formatted payloads into JSON:API documents. These documents are then used by Mirage to update the database accordingly.

There was a gap in the default normalize method for a long time, in that it didn't take REST payloads that included foreign keys and looked like

let payload = {
  contact: {
    id: 1,
    name: 'Link',
    address: 1
  }
};

and turn that address key into a proper JSON:API relationship:

data: {
  type: 'contacts',
  id: 1,
  attributes: {
    name: 'Link'
  },
  relationships: {
    address: {
      data: {
        type: 'address',
        id: 1
      }
    }
  }
}

We added this feature a while ago, and it's controlled with the normalizeIds property on the ActiveModelSerializer and RESTSerializer. (We did this so the feature wouldn't be a breaking change.)

We're now making true the default, which should be the behavior everyone desires (assuming they're using shorthands). This is technically a breaking change, though it's unlikely to affect most people.

All changes

💥 Breaking Changes

#1527 Remove faker.js
#1519 normalizeIds serializer property defaults to true
#1525 drop deprecated forms of create, createList and normalizedRequestAttrs

🚀 Enhancements

#1590 Adds overridable shouldIncludeLinkageData method to JSONAPISerializer docs
#1586 Better logging
#1550 Pass a stack trace for route handler errors

📝 Documentation

#1595 Document JSONAPISerializer
#1600 Document polymorphic hooks
#1587 Fix typo in inline Schema docs
#1578 Add FastBoot notice to docs
#1568 Document keyForForeignKey method
#1559 Fix internal link to Schema docs

🏠 Internal

#1589 Tests coverage for Schema.first() and Schema.findBy()
#1503 remove pretender shim
https://github.com/...

Update notes:

#1466 changed some existing behavior that I expect almost no one to be relying upon, but I could be wrong.

For no particular reason, when we originally coded the Db we had it sort new records by the id field.

This means if you had fixture files like

[
  { id: 2, name: 'Yehuda' },
  { id: 1, name: 'Tom' }
]

they would end up in Mirage's Db as [ { id: 1, name: 'Tom' }, { id: 2, name: 'Yehuda' } ].

We've changed this behavior so records are just added to the Db in the order they were at insertion time.

The only way this could affect your app or tests is if you are doing something like return schema.users.all(), and you're relying on the order of that response, and the source data is unsorted. (In general, if you're relying on an order, it's best practice for your query and/or route handler to specify that sort order with e.g. schema.users.sort((a, b) => b.title < a.title })).

I expect this undocumented behavior to not be something anyone is relying on. Please let me know if I'm wrong!

📝 Documentation

#1377 New AddonDocs site! Check it out at http://www.ember-cli-mirage.com

🚀 Enhancements

#1457 Allow native async functions as route handlers

🏠 Internal

#1466 Db doesn't automatically sort records anymore
#1456 Upgrade Ember CLI

View all commits: v0.4.12...v0.4.13

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Ember CLI Mirage v1.0.0-beta.1

1. Remove Faker.js

2. Remove deprecated forms of `create`, `createList` and `normalizedRequestAttrs`

3. The `normalizeIds` serializer property now defaults to true

All changes

Releases: miragejs/ember-cli-mirage

v1.0.0-beta.3

v1.0.0-beta.2

v1.0.0-beta.1

Ember CLI Mirage v1.0.0-beta.1

1. Remove Faker.js

2. Remove deprecated forms of create, createList and normalizedRequestAttrs

3. The normalizeIds serializer property now defaults to true

All changes

v0.4.15

v0.4.14

v0.4.13

v0.4.12

v0.4.11

v0.4.10

v0.4.9

2. Remove deprecated forms of `create`, `createList` and `normalizedRequestAttrs`

3. The `normalizeIds` serializer property now defaults to true