Document mappings.json format.

[rwjblue]

• This properly documents the existing mappings.json format
• Ensures that all properties (other than replacement) are present on all entries
• Updates the README with the interface:
• Creates a new script that will allow easier formatting of the mappings.json (not terribly important, but it was nice to have as I made these changes)
• Added tests to ensure that the interface is satisfied

---

interface Mapping {
    /**
      The globals based API that this module and export replace.
     */
    global: string;

    /**
      The module to import.
     */
    module: string;

    /**
      The export name from the module.
     */
    export: string;

    /**
      `true` if this module / export combination has been deprecated.
     */
    deprecated: boolean;

    /**
      The recommended `localName` to use for a given module/export.

      This is useful for things like ember-modules-codemod or eslint-plugin-ember
      so that they can provide a nice suggested import for a given global path usage.
     */
    localName: string;

    replacement?: {
        module: string;
        export: string;
    }
}

[Turbo87]

what's the reason for making localName required?

[rwjblue]

1. it’s really just “suggested local name”, obviously anyone can use whatever they want (and when I do an update for 0.4.0 with the getter / setter stuff I was going to change it to recommendedLocalName to make that even clearer)
2. calculating and curating the default here prevents every downstream tool from having to deal with the reserved names manually (and possibly incorrectly). For example, eslint-plugin-ember does not seem to take reserved words into account at all when providing its suggestion.

tldr; it’s “free” to add and centralizing makes life a tad bit easier for downstreams.

[Turbo87]

it’s really just “suggested local name”, obviously anyone can use whatever they want (and when I do an update for 0.4.0 with the getter / setter stuff I was going to change it to recommendedLocalName to make that even clearer)

renaming seems fine to me

calculating and curating the default here prevents every downstream tool from having to deal with the reserved names manually (and possibly incorrectly). For example, eslint-plugin-ember does not seem to take reserved words into account at all when providing its suggestion.

If we use e.g. localName: Object we should change to localName: EmberObject so that downstream projects don't have that problem, but I don't see how that relates to making localName a required key 🤔

I'm not hard blocking on this, just interested what the reasons are.

[rwjblue]

I don't feel super strongly. I mostly auto-populated it because it seemed easier to define a consistent interface (vs making localName optional) and it removes the extra "local building" logic from downstream projects.

If we use e.g. localName: Object we should change to localName: EmberObject so that downstream projects don't have that problem, but I don't see how that relates to making localName a required key

So you are suggesting to only have localName set when it would differ from export? I think that is fine, it just means that all downstream consumers will have to handle the mapping.localName || mapping.export logic themselves if they need to come up with a local name.

[Turbo87]

So you are suggesting to only have localName set when it would differ from export?

yep, I think that was the logic until now, right?

[rwjblue]

yep, I think that was the logic until now, right?

We had a few other scenarios (e.g. #45) where we have customized the localName other than just reserved words. Another example is emberjs/rfcs#273 (comment), where we would have a localName of injectService for import { inject } from '@ember/service'.

However, as long as the guidance for downstream projects is to always do m.localName || m.export to decide a suggested local name, we have no issues with leaving localName out when it wouldn't differ from export.

[Turbo87]

are we sure about this? I've always used Promise instead, because I never wanted the native Promise and it's essentially a polyfill too 🤔

and if we want to use a different name, why not RSVPPromise or RSVPromise? 😉

[rwjblue]

Updated. I agree, I want to name it Promise for exactly the same reason.

[rwjblue]

Updated to remove localName when it is the same as export, were the rest of the changes reasonable?

[Turbo87]

see above :P