proposal-import-bytes/spec.emu at main · tc39/proposal-import-bytes · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
<!doctype html>
<meta charset="utf8">
<link rel="stylesheet" href="./spec.css">
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/8.4/styles/github.min.css">
<script src="./spec.js"></script>
<pre class="metadata">
title: Proposal Import Bytes
stage: 2.7
contributors: Steven, Guy Bedford
</pre>
<emu-intro id="intro">
  <h1>Proposal Import Bytes</h1>
  <p>See <a href="https://github.com/styfle/proposal-import-bytes/blob/main/README.md">the explainer</a> for information.</p>
  <emu-note type="editor">
    <p>This proposal is built on top of the <a href="https://github.com/tc39/proposal-json-modules">JSON Modules</a> and <a href="https://github.com/tc39/proposal-immutable-arraybuffer">Immutable Array Buffer</a> proposals.</p>
  </emu-note>
</emu-intro>

<emu-clause id="sec-semantics">
  <h1>Semantics</h1>

  <emu-clause id="sec-HostLoadImportedModule" type="host-defined abstract operation">
    <h1>
      HostLoadImportedModule (
        _referrer_: a Script Record, a Cyclic Module Record, or a Realm Record,
        _moduleRequest_: a ModuleRequest Record,
        _hostDefined_: anything,
        _payload_: a GraphLoadingState Record or a PromiseCapability Record,
      ): ~unused~
    </h1>
    <dl class="header">
      <dt>description</dt>
      <dd></dd>
    </dl>

    <emu-note id="note-HostLoadImportedModule-referrer-Realm-Record">
      <p>An example of when _referrer_ can be a Realm Record is in a web browser host. There, if a user clicks on a control given by</p>

      <pre><code class="html">&lt;button type="button" onclick="import('./foo.mjs')"&gt;Click me&lt;/button&gt;</code></pre>

      <p>there will be no active script or module at the time the <emu-xref href="#sec-import-calls">`import()`</emu-xref> expression runs. More generally, this can happen in any situation where the host pushes execution contexts with *null* ScriptOrModule components onto the execution context stack.</p>
    </emu-note>

    <p>An implementation of HostLoadImportedModule must conform to the following requirements:</p>
    <ul>
      <li>
        The host environment must perform FinishLoadingImportedModule(_referrer_, _moduleRequest_, _payload_, _result_), where _result_ is either a normal completion containing the loaded Module Record or a throw completion, either synchronously or asynchronously.
      </li>
      <li>
        <p>If this operation is called multiple times with two (_referrer_, _moduleRequest_) pairs such that:</p>
        <ul>
          <li>the first _referrer_ is the same as the second _referrer_;</li>
          <li>the first _moduleRequest_.[[Specifier]] is the same as the second _moduleRequest_.[[Specifier]];</li>
          <li>ImportAttributesEqual(the first _moduleRequest_.[[Attributes]], the second _moduleRequest_.[[Attributes]]) is *true*;</li>
          <li>it performs FinishLoadingImportedModule(_referrer_, _moduleRequest_, _payload_, _result_) where _result_ is a normal completion,</li>
        </ul>
        <p>then it must perform FinishLoadingImportedModule(_referrer_, _moduleRequest_, _payload_, _result_) with the same _result_ each time.</p>
      </li>
      <li><p><del>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.</del></p></li>
      <li><p><ins>If _moduleRequest_.[[Attributes]] has an entry _entry_ such that _entry_.[[Key]] is *"type"*, then</ins></p></li>
      <ol>
        <li><p><ins>Let _type_ be _entry_.[[Value]].</ins></p></li>
        <li><p><ins>If _type_ 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.</ins></p></li>
        <li><p><ins>If _type_ is *"bytes"*, the host environment must perform FinishLoadingImportedModule(_referrer_, _moduleRequest_, _payload_, _result_), where _result_ is either the Completion Record returned by an invocation of CreateBytesModule or a throw completion.</ins></p></li>
      </ol>
      <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_.[[Specifer]], _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 <ins>and bytes modules</ins> imported with `type: "json"` <ins>and `type: "bytes"` respectively </ins>(if it completes normally), but it doesn't prohibit hosts from supporting JSON modules imported with no type specified. Some environments (for example, web browsers) plan to require `with { type: "json" }`, and environments which want to restrict themselves to a compatible subset would do so as well.</p>
    </emu-note>

    <emu-note>
      <p>All of the import statements in the module graph that address the same JSON <ins>or bytes </ins>module may evaluate to the same <del>mutable </del>object.</p>
    </emu-note>
  </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 exports are derived from a pair of lists, of string keys and of ECMAScript values. The set of exported names is static, and determined at creation time (as an argument to CreateSyntheticModule), while the set of exported values can be changed 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, <ins>or bytes modules, </ins>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>
          <th>Field Name</th>
          <th>Value Type</th>
          <th>Meaning</th>
        </thead>
        <tbody>
          <tr>
            <td>[[ExportNames]]</td>
            <td>List of String</td>
            <td>A List of all names that are exported.</td>
          </tr>
          <tr>
            <td>[[EvaluationSteps]]</td>
            <td>An Abstract Closure</td>
            <td>An Abstract Closure that will be performed 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. They must not modify [[ExportNames]]. They may return an abrupt completion.</td>
          </tr>
        </tbody>
      </table>
    </emu-table>

    <emu-clause id="sec-create-bytes-module" type="abstract operation">
      <h1>
        <ins>
          CreateBytesModule (
            _arrayBuffer_: an immutable ArrayBuffer
          ): a Synthetic Module Record
        </ins>
      </h1>
      <dl class="header">
        <dt>description</dt>
        <dd></dd>
      </dl>

      <emu-alg>
        1. Assert: IsImmutableBuffer(_arrayBuffer_) is *true*.
        1. Let _uint8Array_ be ! Construct(%Uint8Array%, « _arrayBuffer_ »).
        1. Return CreateDefaultExportSyntheticModule(_uint8Array_).
      </emu-alg>
    </emu-clause>
  </emu-clause>
  </emu-clause>