Skip to content
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

Jump to bottom

Normative: Add JSON modules #3391

Open
wants to merge 1 commit into
base: import-attributes
Choose a base branch
from
Open

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
210 changes: 210 additions & 0 deletions spec.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28440,6 +28440,209 @@
</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 as an argument to CreateSyntheticModule, 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, built-in modules, or 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>. Each of these fields is initially set in CreateSyntheticModule.</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>
<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. These will usually set up the exported values, by using SetSyntheticModuleExport. It must not modify [[ExportNames]]. It may return an abrupt completion.</td>
</tr>
</table>
</emu-table>

<emu-clause id="sec-createsyntheticmodule" type="abstract operation">
<h1>
CreateSyntheticModule (
Copy link
Member Author

Choose a reason for hiding this comment

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

This AO is only used once, it's not used in any host spec, and its implementation is a single line. Can we inline it?

It seems like V8 has an API based on this AO (https://v8docs.nodesource.com/node-13.2/df/d74/classv8_1_1_module.html#aeaa8c3cfb75478b9403be3d3955bb338), but nothing prevents implementations to keep providing this sort of constructor for Synthetic Module Records.

Copy link
Member

Choose a reason for hiding this comment

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

Yeah I would inline this and remove the references to it.

_exportNames_: a List of Strings without duplicates,
_evaluationSteps_: an Abstract Closure,
_realm_: a Realm Record,
): a Synthetic Module Record
</h1>
<dl class="header">
<dt>description</dt>
<dd></dd>
</dl>

<emu-alg>
1. Return the Synthetic Module Record { [[Realm]]: _realm_, [[Environment]]: ~empty~, [[Namespace]]: ~empty~, [[HostDefined]]: *undefined*, [[ExportNames]]: _exportNames_, [[EvaluationSteps]]: _evaluationSteps_ }.
</emu-alg>
</emu-clause>

<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 CreateSyntheticModule(« *"default"* », _setDefaultExport_, _realm_).
</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_ »).
Copy link
Member Author

@nicolo-ribaudo nicolo-ribaudo Aug 14, 2024 •
edited
Loading

Choose a reason for hiding this comment

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

Should steps 2-9 of JSON.parse be extracted to a new AO that we can call here, or is this ok?

Related: #1012 and https://infra.spec.whatwg.org/#parse-a-json-string-to-a-javascript-value

Copy link
Member

Choose a reason for hiding this comment

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

I'm fine with either way.

Copy link
Contributor

Choose a reason for hiding this comment

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

I mildly prefer the AO (after #3394 lands), but that refactoring can happen after this PR.

1. Return CreateDefaultExportSyntheticModule(_json_).
</emu-alg>
</emu-clause>

<emu-clause id="sec-setsyntheticmoduleexport" type="abstract operation">
<h1>
SetSyntheticModuleExport (
nicolo-ribaudo marked this conversation as resolved.
Show resolved Hide resolved
_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 a pre-established 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>
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.


<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">
Copy link
Member Author

Choose a reason for hiding this comment

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

There is an open PR in the proposal changing these smr shorthands to the longer sec-synthetic-module-record-LoadRequestedModules. What is the editorial preference?

Copy link
Member

Choose a reason for hiding this comment

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

I am completely unopinionated on IDs. This ID is fine.

<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 ( ): ~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_ in _module_.[[ExportNames]], do
1. Perform ! _env_.CreateMutableBinding(_exportName_, *false*).
1. Perform ! _env_.InitializeBinding(_exportName_, *undefined*).
1. Return ~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 currently running execution context.
1. Push _moduleContext_ on to 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 ! _pc_.[[Resolve]](_result_).
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 @@ -28495,12 +28698,19 @@
</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"*, the host environment must perform FinishLoadingImportedModule(_referrer_, _moduleRequest_, _payload_, _result_), where _result_ is either the Completion Record returned by an invokation of ParseJSONModule or a throw completion.</p>

Check warning on line 28702 in spec.html

View workflow job for this annotation

GitHub Actions / check for newly-introduced spelling errors

Potential Typo 

"invokation" is not a previously used word or composed of previously used words. Perhaps it is a typo?
Copy link
Member

Choose a reason for hiding this comment

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

Suggested change
<p>If _moduleRequest_.[[Attributes]] has an entry _entry_ such that _entry_.[[Key]] is *"type"* and _entry_.[[Value]] is *"json"*, the host environment must perform FinishLoadingImportedModule(_referrer_, _moduleRequest_, _payload_, _result_), where _result_ is either the Completion Record returned by an invokation of ParseJSONModule or a throw completion.</p>
<p>If _moduleRequest_.[[Attributes]] has an entry _entry_ such that _entry_.[[Key]] is *"type"* and _entry_.[[Value]] is *"json"*, the host environment must perform FinishLoadingImportedModule(_referrer_, _moduleRequest_, _payload_, _result_), where _result_ is either 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 implies that hosts *must* support JSON modules imported with `type: "json"` (if it completes normally), but it doesn't prohibit hosts from supporting JSON modules imported with no type specified.</p>
Copy link
Member

Choose a reason for hiding this comment

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

Suggested change
<p>The above text implies that hosts *must* support JSON modules imported with `type: "json"` (if it completes normally), but it doesn't prohibit hosts from supporting JSON modules imported with no type specified.</p>
<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