proposal-import-text/spec.emu at main · tc39/proposal-import-text · 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
<!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: Import Text
stage: 2
contributors: Eemeli Aro
</pre>

<emu-clause id="sec-module-semantics" number="16.2.1">
  <h1>Module Semantics</h1>

  <emu-note type="editor">
    <p>See <a href="https://github.com/eemeli/proposal-import-text">the explainer</a> for more information.</p>
    <p>This proposal is modeled after the <a href="https://github.com/tc39/proposal-import-bytes">Import Bytes proposal</a>.</p>
  </emu-note>

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

    <emu-clause id="sec-create-text-module" type="abstract operation" number="5">
      <h1>
        <ins>CreateTextModule (
          _source_: a String,
        ): a normal completion containing a Synthetic Module Record</ins>
      </h1>
      <dl class="header">
        <dt>description</dt>
        <dd>
          It creates a Synthetic Module Record whose default export is _source_,
          a String whose value should represent textual data.
        </dd>
      </dl>

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

  <emu-clause id="sec-HostLoadImportedModule" type="host-defined abstract operation" number="10">
    <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 *"text"*, the host environment must perform FinishLoadingImportedModule(_referrer_, _moduleRequest_, _payload_, _result_), where _result_ is either the Completion Record returned by an invocation of CreateTextModule 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 imported with `type: "json"` (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. <ins>Similarly, hosts are not prohibited from supporting the import of text modules with no type specified.</ins></p>
    </emu-note>

    <emu-note>
      <p>All of the import statements in the module graph that address the same JSON module may evaluate to the same mutable object.</p>
    </emu-note>
  </emu-clause>
</emu-clause>