Migrating from JSM to ES6 modules

migration.md

This document shows a possible migration path from Cu.import() to ES modules for the code of Firefox.

Requirements:

1. Preserve current JSM semantics where multiple imports of a single module from different globals results in a single module instance that lives in a separate global to the importer.
2. Add-ons and Thunderbird should not be affected by the migration.
3. Memory usage should not be adversly affected.

1. Allow Cu.import() to load ES6 modules with detction based on file extension

1. Optionally, transition all JSMs to use a single global (bug 1186409) ahead of time to flush out any issues.
2. Implement an internal API to synchronously load an ES module into a specified global.
3. Make Cu.import() use the above to optionally load an ES module based on the file extension.
4. Inform developers that they should now use ES6 modules instead of jsm for their new code.
5. Reject patches that introduce new jsm modules. Optionally, patch mozReview to do this automatically.

2. Migrate Cu.import(foo) to import foo for module imports

This section refers to imports inside a module, not at top-level. Top-level imports must continue to use Cu.import() to get the module imported into the special shared global as per requirement 1. We might want to disable loading top-level modules in chrome altogether.

1. Inform developers that they should now use import foo inside modules, rather than Cu.import().
2. Reject patches that introduce new instances of Cu.import() inside modules. Optionally, patch mozReview to do this automatically.
3. Start migrating use of Cu.import('foo') in modules to import foo. Add shim foo.jsm to allow existing cases to continue to work. It should be possible to automate this.

3. Remaining cases

At this stage, we will still have the following cases to contend with:

1. conditional imports;
2. scoped imports and imports from within a function.
3. uses of XPCOM.defineLazyModuleGetter;

We probably want to wait until there is a programmatic way of loading ES modules added to the spec and then implement that.

@Jonco I don't think we should

Optionally, transition all JSMs to use a single global (bug 1186409) ahead of time to flush out any issues.

This would essentially require us to debug all of Firefox at once, rather than one-step-at-a-time.