Skip to content

Normative: Add JSON modules #3391

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Feb 19, 2025
Merged

Normative: Add JSON modules #3391

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
193 changes: 193 additions & 0 deletions spec.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28527,6 +28527,192 @@ <h1>
</emu-clause>
</emu-clause>

<emu-clause id="sec-synthetic-module-records">
<h1>Synthetic Module Records</h1>

<p>A <dfn variants="Synthetic Module Records">Synthetic Module Record</dfn> is used to represent information about a module that is defined by specifications. Its exported names are statically defined at creation, while their corresponding values can change over time using SetSyntheticModuleExport. It has no imports or dependencies.</p>

<emu-note>A Synthetic Module Record could be used for defining a variety of module types: for example, JSON modules or CSS modules.</emu-note>

<p>In addition to the fields defined in <emu-xref href="#table-module-record-fields"></emu-xref> Synthetic Module Records have the additional fields listed in <emu-xref href="#table-synthetic-module-record-fields"></emu-xref>.</p>

<emu-table id="table-synthetic-module-record-fields" caption="Additional Fields of Synthetic Module Records">
<table>
<thead>
<tr>
<th>Field Name</th>
<th>Value Type</th>
<th>Meaning</th>
</tr>
</thead>
<tr>
<td>[[ExportNames]]</td>
<td>a List of Strings</td>
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Quoting a note from the original authors of the proposal:

I find having this wrapping sub-clause cleaner and suggest we do the same for Source Text Module Records in the main spec.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sure, they should match.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm going to open a PR to align Source Text Module Record to this, but I'll do it after that the import attributes PR is merged to avoid indentation conflicts.

<td>The names of the exports of the module. This list does not contain duplicates.</td>
</tr>
<tr>
<td>[[EvaluationSteps]]</td>
<td>an Abstract Closure</td>
<td>The initialization logic to perform upon evaluation of the module, taking the Synthetic Module Record as its sole argument. It must not modify [[ExportNames]]. It may return an abrupt completion.</td>
</tr>
</table>
</emu-table>

<emu-clause id="sec-create-default-export-synthetic-module" type="abstract operation">
<h1>
CreateDefaultExportSyntheticModule (
_defaultExport_: an ECMAScript language value,
): a Synthetic Module Record
</h1>
<dl class="header">
<dt>description</dt>
<dd>It creates a Synthetic Module Record whose default export is _defaultExport_.</dd>
</dl>
<emu-alg>
1. Let _realm_ be the current Realm Record.
1. Let _setDefaultExport_ be a new Abstract Closure with parameters (_module_) that captures _defaultExport_ and performs the following steps when called:
1. Perform SetSyntheticModuleExport(_module_, *"default"*, _defaultExport_).
1. Return NormalCompletion(~unused~).
1. Return the Synthetic Module Record { [[Realm]]: _realm_, [[Environment]]: ~empty~, [[Namespace]]: ~empty~, [[HostDefined]]: *undefined*, [[ExportNames]]: « *"default"* », [[EvaluationSteps]]: _setDefaultExport_ }.
</emu-alg>
</emu-clause>

<emu-clause id="sec-parse-json-module" type="abstract operation">
<h1>
ParseJSONModule (
_source_: a String,
): either a normal completion containing a Synthetic Module Record, or a throw completion
</h1>
<dl class="header">
<dt>description</dt>
<dd></dd>
</dl>

<emu-alg>
1. Let _json_ be ? Call(%JSON.parse%, *undefined*, « _source_ »).
1. Return CreateDefaultExportSyntheticModule(_json_).
</emu-alg>
</emu-clause>

<emu-clause id="sec-setsyntheticmoduleexport" type="abstract operation">
<h1>
SetSyntheticModuleExport (
_module_: a Synthetic Module Record,
_exportName_: a String,
_exportValue_: an ECMAScript language value,
): ~unused~
</h1>
<dl class="header">
<dt>description</dt>
<dd>It can be used to set or change the exported value for an existing export of a Synthetic Module Record.</dd>
</dl>

<emu-alg>
1. Assert: _module_.[[ExportNames]] contains _exportName_.
1. Let _envRec_ be _module_.[[Environment]].
1. Assert: _envRec_ is not ~empty~.
1. Perform _envRec_.SetMutableBinding(_exportName_, _exportValue_, *true*).
1. Return ~unused~.
</emu-alg>
</emu-clause>

<emu-clause id="sec-smr-module-record-methods">
<h1>Implementation of Module Record Abstract Methods</h1>

<p>The following are the concrete methods for Synthetic Module Record that implement the corresponding Module Record abstract methods defined in <emu-xref href="#table-abstract-methods-of-module-records"></emu-xref>.</p>

<emu-clause id="sec-smr-LoadRequestedModules" type="concrete method">
<h1>LoadRequestedModules ( ): a Promise</h1>
<dl class="header">
<dt>for</dt>
<dd>a Synthetic Module Record _module_</dd>
</dl>

<emu-alg>
1. Return ! PromiseResolve(%Promise%, *undefined*).
</emu-alg>

<emu-note>
Synthetic Module Records have no dependencies.
</emu-note>
</emu-clause>

<emu-clause id="sec-smr-getexportednames" type="concrete method">
<h1>GetExportedNames ( ): a List of Strings</h1>
<dl class="header">
<dt>for</dt>
<dd>a Synthetic Module Record _module_</dd>
</dl>

<emu-alg>
1. Return _module_.[[ExportNames]].
</emu-alg>
</emu-clause>

<emu-clause id="sec-smr-resolveexport" type="concrete method">
<h1>
ResolveExport (
_exportName_: a String,
): a ResolvedBinding Record or *null*
</h1>
<dl class="header">
<dt>for</dt>
<dd>a Synthetic Module Record _module_</dd>
</dl>

<emu-alg>
1. If _module_.[[ExportNames]] does not contain _exportName_, return *null*.
1. Return ResolvedBinding Record { [[Module]]: _module_, [[BindingName]]: _exportName_ }.
</emu-alg>
</emu-clause>

<emu-clause id="sec-smr-Link" type="concrete method">
<h1>Link ( ): a normal completion containing ~unused~</h1>
<dl class="header">
<dt>for</dt>
<dd>a Synthetic Module Record _module_</dd>
</dl>

<emu-alg>
1. Let _realm_ be _module_.[[Realm]].
1. Let _env_ be NewModuleEnvironment(_realm_.[[GlobalEnv]]).
1. Set _module_.[[Environment]] to _env_.
1. For each String _exportName_ of _module_.[[ExportNames]], do
1. Perform ! _env_.CreateMutableBinding(_exportName_, *false*).
1. Perform ! _env_.InitializeBinding(_exportName_, *undefined*).
1. Return NormalCompletion(~unused~).
</emu-alg>
</emu-clause>

<emu-clause id="sec-smr-Evaluate" type="concrete method">
<h1>Evaluate ( ): a Promise</h1>
<dl class="header">
<dt>for</dt>
<dd>a Synthetic Module Record _module_</dd>
</dl>

<emu-alg>
1. Let _moduleContext_ be a new ECMAScript code execution context.
1. Set the Function of _moduleContext_ to *null*.
1. Set the Realm of _moduleContext_ to _module_.[[Realm]].
1. Set the ScriptOrModule of _moduleContext_ to _module_.
1. Set the VariableEnvironment of _moduleContext_ to _module_.[[Environment]].
1. Set the LexicalEnvironment of _moduleContext_ to _module_.[[Environment]].
1. Suspend the running execution context.
1. Push _moduleContext_ onto the execution context stack; _moduleContext_ is now the running execution context.
1. Let _steps_ be _module_.[[EvaluationSteps]].
1. Let _result_ be Completion(_steps_(_module_)).
1. Suspend _moduleContext_ and remove it from the execution context stack.
1. Resume the context that is now on the top of the execution context stack as the running execution context.
1. Let _pc_ be ! NewPromiseCapability(%Promise%).
1. IfAbruptRejectPromise(_result_, _pc_).
1. Perform ! Call(_pc_.[[Resolve]], *undefined*, « *undefined* »).
1. Return _pc_.[[Promise]].
</emu-alg>
</emu-clause>
</emu-clause>
</emu-clause>

<emu-clause id="sec-GetImportedModule" type="abstract operation">
<h1>
GetImportedModule (
Expand Down Expand Up @@ -28582,12 +28768,19 @@ <h1>
</ul>
<p>and it performs FinishLoadingImportedModule(_referrer_, _moduleRequest_, _payload_, _result_) where _result_ is a normal completion, then it must perform FinishLoadingImportedModule(_referrer_, _moduleRequest_, _payload_, _result_) with the same _result_ each time.</p>
</li>
<li>
<p>If _moduleRequest_.[[Attributes]] has an entry _entry_ such that _entry_.[[Key]] is *"type"* and _entry_.[[Value]] is *"json"*, when the host environment performs FinishLoadingImportedModule(_referrer_, _moduleRequest_, _payload_, _result_), _result_ must either be the Completion Record returned by an invocation of ParseJSONModule or a throw completion.</p>
</li>
<li>
The operation must treat _payload_ as an opaque value to be passed through to FinishLoadingImportedModule.
</li>
</ul>

<p>The actual process performed is host-defined, but typically consists of performing whatever I/O operations are necessary to load the appropriate Module Record. Multiple different (_referrer_, _moduleRequest_.[[Specifier]], _moduleRequest_.[[Attributes]]) triples may map to the same Module Record instance. The actual mapping semantics is host-defined but typically a normalization process is applied to _specifier_ as part of the mapping process. A typical normalization process would include actions such as expansion of relative and abbreviated path specifiers.</p>

<emu-note>
<p>The above text requires that hosts support JSON modules when imported with `type: "json"` (and HostLoadImportedModule completes normally), but it does not prohibit hosts from supporting JSON modules when imported without `type: "json"`.</p>
</emu-note>
</emu-clause>

<emu-clause id="sec-FinishLoadingImportedModule" type="abstract operation" oldids="sec-finishdynamicimport">
Expand Down
Loading