Skip to content
Pre-release
Pre-release

@samselikoff samselikoff released this Apr 24, 2019 · 27 commits to master since this release

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:

  1. Remove Faker.js
  2. Remove deprecated forms of create, createList and normalizedRequestAttrs
  3. 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:

  1. Install Ember Auto Import (if it's not already installed)
ember install ember-auto-import
  1. Install Faker.js directly from npm:
yarn add -D faker

# or npm install --save-dev faker
  1. 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
  • #1562 Remove duplicated dependencies
  • #1561 Save over 500KB with one weird trick
  • #1526 Remove skipped tests
  • Dependency updates
Assets 2
You can’t perform that action at this time.