From d835b28028a9358b2aacb6645af4fb08d3692371 Mon Sep 17 00:00:00 2001 From: Joshua Chen Date: Fri, 3 Jul 2026 16:46:56 -0400 Subject: [PATCH] Reference for stage 3 source-phase-imports --- .../abstractmodulesource/index.md | 55 +++++++++++++++++++ .../reference/global_objects/index.md | 1 + files/en-us/web/javascript/reference/index.md | 3 + .../reference/operators/import/index.md | 2 + .../operators/import/source/index.md | 47 ++++++++++++++++ .../javascript/reference/operators/index.md | 2 + .../reference/statements/export/index.md | 3 + .../reference/statements/import/index.md | 2 + .../statements/import/source/index.md | 43 +++++++++++++++ .../javascript_interface/module/index.md | 12 ++++ 10 files changed, 170 insertions(+) create mode 100644 files/en-us/web/javascript/reference/global_objects/abstractmodulesource/index.md create mode 100644 files/en-us/web/javascript/reference/operators/import/source/index.md create mode 100644 files/en-us/web/javascript/reference/statements/import/source/index.md diff --git a/files/en-us/web/javascript/reference/global_objects/abstractmodulesource/index.md b/files/en-us/web/javascript/reference/global_objects/abstractmodulesource/index.md new file mode 100644 index 000000000000000..440e41bded91e80 --- /dev/null +++ b/files/en-us/web/javascript/reference/global_objects/abstractmodulesource/index.md @@ -0,0 +1,55 @@ +--- +title: AbstractModuleSource +slug: Web/JavaScript/Reference/Global_Objects/AbstractModuleSource +page-type: javascript-class +browser-compat: javascript.builtins.AbstractModuleSource +sidebar: jsref +--- + +An **_AbstractModuleSource_** object represents the raw module source code accessible with [`import source`](/en-US/docs/Web/JavaScript/Reference/Statements/import/source) or [`import.source()`](/en-US/docs/Web/JavaScript/Reference/Operators/import/source). There is no directly visible `AbstractModuleSource` constructor. + +## Description + +The `AbstractModuleSource` constructor (often referred to as `%AbstractModuleSource%` to indicate its "intrinsicness", since it does not correspond to any global exposed to a JavaScript program) serves as the common superclass of all module source subclasses, providing a common interface of utility methods for all module source subclasses. This constructor is not directly exposed: there is no global `AbstractModuleSource` property. It is only accessible through `Object.getPrototypeOf(moduleSourceObject.constructor)` and similar. + +### AbstractModuleSource objects + +- [`WebAssembly.Module`](/en-US/docs/WebAssembly/Reference/JavaScript_interface/Module) + +JavaScript module source objects will be added by the [ECMAScript Module Phase Imports](https://github.com/tc39/proposal-esm-phase-imports) proposal. + +## Constructor + +This object cannot be instantiated directly — attempting to construct it with `new` throws a {{jsxref("TypeError")}}. + +```js +import source modSource from "./module.wasm"; + +new (Object.getPrototypeOf(modSource.constructor))(); +// TypeError: Abstract class AbstractModuleSource not directly constructable +``` + +You rarely need to construct an `AbstractModuleSource` object directly, since the module source objects are created by the JavaScript engine when you use `import source` or `import.source()`. + +## Instance properties + +These properties are defined on `AbstractModuleSource.prototype` and shared by all `AbstractModuleSource` subclass instances. + +- {{jsxref("Object/constructor", "AbstractModuleSource.prototype.constructor")}} + - : The constructor function that created the instance object. `AbstractModuleSource.prototype.constructor` is the hidden `AbstractModuleSource` constructor function, but each module source subclass also defines its own `constructor` property. +- `AbstractModuleSource.prototype[Symbol.toStringTag]` + - : The initial value of the [`AbstractModuleSource.prototype[Symbol.toStringTag]`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toStringTag) property is a getter that returns the same string as the module source constructor's name. It returns `undefined` if the `this` value is not one of the module source subclasses. This property is used in {{jsxref("Object.prototype.toString()")}}. + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [`WebAssembly.Module`](/en-US/docs/WebAssembly/Reference/JavaScript_interface/Module) +- {{jsxref("Operators/import/source", "import.source()")}} +- {{jsxref("Statements/import/source", "import source")}} diff --git a/files/en-us/web/javascript/reference/global_objects/index.md b/files/en-us/web/javascript/reference/global_objects/index.md index 9da98b04c7266d5..07f44437b64819b 100644 --- a/files/en-us/web/javascript/reference/global_objects/index.md +++ b/files/en-us/web/javascript/reference/global_objects/index.md @@ -145,6 +145,7 @@ Control abstractions can help to structure code, especially async code (without ### Reflection +- {{jsxref("AbstractModuleSource")}} - {{jsxref("Reflect")}} - {{jsxref("Proxy")}} diff --git a/files/en-us/web/javascript/reference/index.md b/files/en-us/web/javascript/reference/index.md index cc87bac39b6306b..55d160e38fa9771 100644 --- a/files/en-us/web/javascript/reference/index.md +++ b/files/en-us/web/javascript/reference/index.md @@ -120,6 +120,7 @@ If you are new to JavaScript, start with the [guide](/en-US/docs/Web/JavaScript/ ### Reflection +- {{jsxref("AbstractModuleSource")}} - {{jsxref("Reflect")}} - {{jsxref("Proxy")}} @@ -184,6 +185,7 @@ If you are new to JavaScript, start with the [guide](/en-US/docs/Web/JavaScript/ - {{jsxref("Statements/debugger", "debugger")}} - {{jsxref("Statements/export", "export")}} - {{jsxref("Statements/import", "import")}} +- {{jsxref("Statements/import/source", "import source")}} - {{jsxref("Statements/label", "label", "", 1)}} - {{jsxref("Statements/with", "with")}} {{deprecated_inline}} @@ -215,6 +217,7 @@ If you are new to JavaScript, start with the [guide](/en-US/docs/Web/JavaScript/ - {{jsxref("Operators/import.meta", "import.meta")}} - {{jsxref("Operators/super", "super")}} - {{jsxref("Operators/import", "import()")}} +- {{jsxref("Operators/import/source", "import.source()")}} ### Increment and decrement diff --git a/files/en-us/web/javascript/reference/operators/import/index.md b/files/en-us/web/javascript/reference/operators/import/index.md index 630921a625ab55e..6f8fc2fbb7e6533 100644 --- a/files/en-us/web/javascript/reference/operators/import/index.md +++ b/files/en-us/web/javascript/reference/operators/import/index.md @@ -30,6 +30,8 @@ The `import()` call is a syntax that closely resembles a function call, but `imp - `with` - : The [import attributes](/en-US/docs/Web/JavaScript/Reference/Statements/import/with). +"Phase modifiers" for `import` statements, such as [`import source`](/en-US/docs/Web/JavaScript/Reference/Statements/import/source), can also be used with dynamic imports, such as `import.source()`. + ### Return value Returns a promise which: diff --git a/files/en-us/web/javascript/reference/operators/import/source/index.md b/files/en-us/web/javascript/reference/operators/import/source/index.md new file mode 100644 index 000000000000000..b8e53905562e8b0 --- /dev/null +++ b/files/en-us/web/javascript/reference/operators/import/source/index.md @@ -0,0 +1,47 @@ +--- +title: import.source() +slug: Web/JavaScript/Reference/Operators/import/source +page-type: javascript-language-feature +browser-compat: javascript.operators.import.source +--- + +{{jsSidebar("Statements")}} + +The **`import.source()`** syntax behaves like regular [`import()`](/en-US/docs/Web/JavaScript/Reference/Operators/import) syntax, but only obtains an object representing the module's unevaluated source code. The module can be imperatively evaluated later using a method provided by the source code object. + +To use `import.source()`, the target module has to support source phase imports. Currently, only WebAssembly modules support source phase imports, which result in [`WebAssembly.Module`](/en-US/docs/WebAssembly/Reference/JavaScript_interface/Module) objects. JavaScript module source objects will be added by the [ECMAScript Module Phase Imports](https://github.com/tc39/proposal-esm-phase-imports) proposal. + +## Syntax + +```js-nolint +import.source(moduleName) +import.source(moduleName, options) +``` + +### Parameters + +See [`import()`](/en-US/docs/Web/JavaScript/Reference/Operators/import#parameters). + +### Return value + +Returns a promise. The rejection conditions are largely similar to [`import()`](/en-US/docs/Web/JavaScript/Reference/Operators/import#return_value), except that `import.source()` does not throw exceptions related to module evaluation, because it does not evaluate the module. + +If the referenced module is loaded successfully, fulfills with an {{jsxref("AbstractModuleSource")}} object representing the module's unevaluated source code. + +## Description + +## Examples + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- {{jsxref("Operators/import", "import()")}} +- {{jsxref("Statements/import/source", "import source")}} +- {{jsxref("AbstractModuleSource")}} diff --git a/files/en-us/web/javascript/reference/operators/index.md b/files/en-us/web/javascript/reference/operators/index.md index d51807bdbe3adfe..2d63643b947a15b 100644 --- a/files/en-us/web/javascript/reference/operators/index.md +++ b/files/en-us/web/javascript/reference/operators/index.md @@ -59,6 +59,8 @@ Left values are the destination of an assignment. - : The `super` keyword calls the parent constructor or allows accessing properties of the parent object. - {{jsxref("Operators/import", "import()")}} - : The `import()` syntax allows loading a module asynchronously and dynamically into a potentially non-module environment. +- {{jsxref("Operators/import/source", "import.source()")}} + - : The `import.source()` syntax only obtains an object representing the module's unevaluated source code. ### Increment and decrement diff --git a/files/en-us/web/javascript/reference/statements/export/index.md b/files/en-us/web/javascript/reference/statements/export/index.md index 705e93eb140f44f..cf4cb78f2fd9ddb 100644 --- a/files/en-us/web/javascript/reference/statements/export/index.md +++ b/files/en-us/web/javascript/reference/statements/export/index.md @@ -213,6 +213,9 @@ The following is syntactically invalid despite its import equivalent: export DefaultExport from "bar.js"; // Invalid ``` +> [!NOTE] +> Due to the lack of this syntax, [`import source`](/en-US/docs/Web/JavaScript/Reference/Statements/import/source) also has no re-exporting counterpart. + The correct way of doing this is to rename the export: ```js diff --git a/files/en-us/web/javascript/reference/statements/import/index.md b/files/en-us/web/javascript/reference/statements/import/index.md index 55facb7cff7ea8a..d5d061b7f979805 100644 --- a/files/en-us/web/javascript/reference/statements/import/index.md +++ b/files/en-us/web/javascript/reference/statements/import/index.md @@ -41,6 +41,8 @@ import "module-name"; The `"module-name"` may be followed by a set of [import attributes](/en-US/docs/Web/JavaScript/Reference/Statements/import/with), starting with the `with` keyword. +The `import` keyword may be followed by a "phase modifier" that pauses the evaluation of the module at one phase of the module loading process. Currently, the only phase modifier is [`source`](/en-US/docs/Web/JavaScript/Reference/Statements/import/source). + ## Description `import` declarations can only be present in modules, and only at the top-level (i.e., not inside blocks, functions, etc.). If an `import` declaration is encountered in non-module contexts (for example, `