[Design Spec] ESNext import()

[yuit]

import(specifier) is a newly proposed syntax for dynamically module loading. import(specifier) takes an assignment expression as an input (Note: unlike ES6 static import which only allow string literal as module specifier) and returns a promise of module namespace object.

The full proposal can be found here
Original issue: #12364

This issue will discuss design proposal for implementing import(): parsing, type-checking, and emitting.

The proposal will NOT include "module namespace object" type and expressing the shape of the loaded module (To be able to express such type will allow users to cast the result instead of "any" to be what they expected at runtime)...The issue will be discussed and implemented separately.

Parsing
import(specifier) will be parsed as CallExpression. and specifier will be parsed as AssignmentExpression

Error

• Error if the module flag is ES2015.

• Error if specifier is not assignable to string type

Type-checking

• specifier is type checked as string type. (Clarification: the only limitation for specifier in original proposal is that it can called toString())

• The return of import(specifier) will be as following
  -- if known module can be resolved from specifier, then we return Promise of module namespace object
  -- if not known module, then we return Promise of any. This will give an error in noImplicitAny mode and import() is used as an expression After offline discussion with @mhegazy @bowdenk7 @DanielRosenwasser, we think reporting an error without providing a way to easily get out of it (see [Design] Syntax to represent module namespace object in dynamic import #14844 for more detail) is undesirable. By casting to Promise<any> to satisfy the compiler will not provide users any benefit and arguably is a drawback because if in the future, there is a way to type the module easily, upgrading to use such syntax will not be convenient. Therefore, we will not issue an noImplicitAny error with this feature but with [Design] Syntax to represent module namespace object in dynamic import #14844 instead.

• We will use existed module resolution logic to try to figure out the module of the dynamic import.

Emit
Emit for each different module kind emit is outlined below

import('blah');

• Node

Promise.resolve().then(() => require('blah'));

• AMD

define(["require", "exports"], function (require, exports) {
    "use strict";
    Object.defineProperty(exports, "__esModule", { value: true });
    new Promise(resolve => require(['blah'], resolve));
});

• UMD

(function (factory) {
    if (typeof module === "object" && typeof module.exports === "object") {
        var v = factory(require, exports);
        if (v !== undefined) module.exports = v;
    }
    else if (typeof define === "function" && define.amd) {
        define(["require", "exports"], factory);
    }
})(function (require, exports) {
    "use strict";
    Object.defineProperty(exports, "__esModule", { value: true });
    require.length === 1 ?
        /*CommonJs Require*/ Promise.resolve().then(() => require('blah'));
        /*Amd Require*/ new Promise(resolve => require(['blah'], resolve));
});

• System (Updated from comment)

System.register([], function (_export, _context) {
  return {
    setters: [],
    execute: () => {
      _context.import('dynamic');
    }
  };
});

• ES2018 new value

import('blah')

[mhegazy]

import should not be allowed if --module ES2015.. we have no way of emitting them correctly.

[jods4]

@mhegazy Maybe you should let import() passthrough when --module ES2015.
Likely scenario for me here is using a bundler like Webpack that will take care of it (as of webpack 2.2, import() is supported).

This behavior is useful and we need a way to generate output with import(). If you feel uncomfortable with labeling ES2015 something that really is an extension thereof, maybe we need a new ES201? target.

My interpretation is that ES2015 is the native, standard, ES module system and I'm not shocked to see the newly approved import() inside it, even if it was not strictly speaking in 2015.

[Igorbek]

Shouldn't the 'if not known module' reflect the possibility of missing module and do not expose any?
I'm proposing in this case return Promise<{} | undefined>. Then the caller would be responsible to properly check result of the promise.

[Igorbek]

Ah, sorry, forgot it would go to failure channel of the promise. Then it should be Promise<{}>.

[mhegazy]

@mhegazy Maybe you should let import() passthrough when --module ES2015.
Likely scenario for me here is using a bundler like Webpack that will take care of it (as of webpack 2.2, import() is supported).

this is not valid ES2015 code. even if the engine supports ES2015 modules, import is a keyword and it would be an error.

I guess what you are looking for is a --module ES2018. (or may be --module esnext)

[mhegazy]

Then it should be Promise<{}>.

{} is fairly useless.. it will force users to case. any is more forgiving, and will allow users to proceed without adding a cast. the --noImplicitAny error would help those users interested in stomping out anys.

[Jessidhia]

The argument to import() is something that can be stringified (i.e. anything but symbol), not necessarily string. But allowing only string in the type checker makes sense.

The emit for Node is slightly incorrect. The require should only start after the stack has unwinded, but the example snippet does it synchronously. It should look like:

Promise.resolve().then(() => require('blah'))

This probably also applies to the other emits.

[Jessidhia]

@mhegazy the main (existing) implementer of import() is webpack, so it would be highly desirable to have a passthrough for it. Currently, TypeScript+webpack users are stuck with using the deprecated and, eventually, "worsly typed" System.import() method in webpack.

[mhegazy]

Would --module esNext do? this will pass through import(..) as well as import .. and export ..?

[Jessidhia]

Yeah, that would definitely do.

[mohsen1]

If spec is scheduled for es2018 I think module=es2018 is better than esNext. Next is relative 😀

Also tracked at #12364

[jods4]

@mhegazy I think whether you graft it to --module es2015 or you create a new --module es2018 doesn't matter much (I could argue for both), as long as we can use it. 👍

[bmeck]

Note: import() needs to wait until the stack unwinds prior to doing any eval.

For Node it is also important to note that CJS modules only produce a default export according to the rewritten proposal:

Promise.resolve().then(() => {
  return {default: require('blah')}
});