spec.bs

<pre class="metadata">
Title: Import Maps
Shortname: import-maps
Repository: WICG/import-maps
Inline Github Issues: true
Group: WICG
Status: CG-DRAFT
Level: 1
URL: https://wicg.github.io/import-maps/
Boilerplate: omit conformance, omit feedback-header
Editor: Domenic Denicola, Google https://www.google.com/, d@domenic.me, https://domenic.me/
Abstract: Import maps allow web pages to control the behavior of JavaScript imports.
!Participate: <a href="https://github.com/WICG/import-maps">GitHub WICG/import-maps</a> (<a href="https://github.com/WICG/import-maps/issues/new">new issue</a>, <a href="https://github.com/WICG/import-maps/issues?state=open">open issues</a>)
!Commits: <a href="https://github.com/WICG/import-maps/commits/master/spec.bs">GitHub spec.bs commits</a>
Complain About: accidental-2119 yes, missing-example-ids yes
Indent: 2
Default Biblio Status: current
Markup Shorthands: markdown yes
</pre>
<pre class="link-defaults">
spec: infra; type: dfn
  text: string
  text: list
spec: url; type: dfn; for: /; text: url
spec: html; type: element; text: script
</pre>
<pre class="anchors">
spec: html; type: dfn; urlPrefix: https://html.spec.whatwg.org/multipage/
  text: module map; for: /; url: webappapis.html#module-map
  text: fetch an import() module script graph; url: webappapis.html#fetch-an-import()-module-script-graph
  text: fetch a modulepreload module script graph; url: webappapis.html#fetch-a-modulepreload-module-script-graph
  text: fetch an inline module script graph; url: webappapis.html#fetch-an-inline-module-script-graph
  text: fetch a single module script; url: webappapis.html#fetch-a-single-module-script
  text: script; url: webappapis.html#concept-script

urlPrefix: https://tc39.github.io/ecma262/#; spec: ECMA-262; type: abstract-op;
  text: IsArray; url: sec-isarray
</pre>

<style>
.selected-text-file-an-issue {
  position: fixed;
  bottom: 0;
  right: 0;
  background: rgba(255, 255, 255, 0.8);
  font-size: smaller;
  padding: 4px 10px;
  z-index: 4;
}

summary {
  cursor: pointer;
}
</style>

<script src="https://resources.whatwg.org/file-issue.js" async></script>

<h2 id="definitions">Definitions</h2>

A <dfn>resolution result</dfn> is either a [=URL=] or null.

A <dfn>specifier map</dfn> is an [=ordered map=] from [=strings=] to [=resolution results=].

A <dfn>dependency cache list</dfn> is a optimization cache [=list=] of the dependency [=strings=] of a module.

A <dfn>import map</dfn> is a [=struct=] with three [=struct/items=]:

* <dfn for="import map">imports</dfn>, a [=specifier map=], and
* <dfn for="import map">scopes</dfn>, an [=ordered map=] of [=URLs=] to [=specifier maps=].
* <dfn for="import map">depcache</dfn>, an [=ordered map=] of [=URLs=] to [=dependency cache lists=].

An <dfn>empty import map</dfn> is an [=/import map=] with its [=import map/imports=], [=import map/scopes=] and [=import map/depcache=] all being empty maps.

<h2 id="acquiring">Acquiring import maps</h2>

<h3 id="integration-environment-settings-object">New members of environment settings objects</h3>

Each [=environment settings object=] will get an <dfn for="environment settings object">import map</dfn> algorithm, which returns an [=/import map=] created by the first `<script type="importmap">` element that is encountered (before the cutoff).

A {{Document}} has an [=/import map=] <dfn for="Document">import map</dfn>. It is initially a new [=/empty import map=].

In <a spec="html">set up a window environment settings object</a>, <var ignore>settings object</var>'s [=environment settings object/import map=] returns the [=Document/import map=] of <var ignore>window</var>'s <a>associated <code>Document</code></a>.

A {{WorkerGlobalScope}} has an [=/import map=] <dfn for="WorkerGlobalScope">import map</dfn>. It is initially a new [=/empty import map=].

ISSUE: Specify a way to set {{WorkerGlobalScope}}'s [=WorkerGlobalScope/import map=]. We might want to inherit parent context's import maps, or provide APIs on {{WorkerGlobalScope}}, but we are not sure. Currently it is always an [=/empty import map=]. See <a href="https://github.com/WICG/import-maps/issues/2">#2</a>.</p>

In <a spec="html">set up a worker environment settings object</a>, <var ignore>settings object</var>'s [=environment settings object/import map=] returns <var ignore>worker global scope</var>'s [=WorkerGlobalScope/import map=].

<p class="note">
  This infrastructure is very similar to the existing specification for module maps.
</p>

A {{Document}} has a <dfn for="Document">pending import map script</dfn>, which is a {{HTMLScriptElement}} or null, initially null.

<p class="note">This is modified by [[#integration-prepare-a-script]].</p>

Each {{Document}} has an <dfn for="Document">acquiring import maps</dfn> boolean. It is initially true.

<div class="note">
  These two pieces of state are used to achieve the following behavior:

  <ul>
    <li>An import map is accepted if and only if it is added (i.e., its corresponding <{script}> element is added) before the first module load is started, even if the loading of the import map file doesn't finish before the first module load is started.
    <li>Module loading waits for any import map that has already started loading.
  </ul>
</div>

<h3 id="integration-script-type">Script type</h3>

To process import maps in the <a spec="html">prepare a script</a> algorithm consistently with existing script types (i.e. classic or module), we make the following changes:

- Introduce <dfn>import map parse result</dfn>, which is a [=struct=] with three [=struct/items=]:
  - a <dfn for="import map parse result">settings object</dfn>, an [=environment settings object=];
  - an <dfn for="import map parse result">import map</dfn>, an [=/import map=]; and
  - an <dfn for="import map parse result">error to rethrow</dfn>, a JavaScript value representing a parse error when non-null.
- <a spec="html">the script's type</a> should be either "`classic`", "`module`", or "`importmap`".
- Rename <a spec="html">the script's script</a> to <dfn>the script's result</dfn>, which can be either a <a spec="html">script</a> or an [=import map parse result=].

The following algorithms are updated accordingly:

- <a spec="html">prepare a script</a>: see [[#integration-prepare-a-script]].
- <a spec="html">execute a script block</a> Step 4: add the following case.
  <dl>
    <dt>"`importmap`"</dt>
    <dd>
      1. Assert: Never reached.
         <p class="note">Import maps are processed by [=/register an import map=] instead of <a spec="html">execute a script block</a>.</p>
    </dd>
  </dl>

<p class="note">Because we don't make [=import map parse result=] the new subclass of [=script=], other script execution-related specs are left unaffected.</p>

<h3 id="integration-prepare-a-script">Prepare a script</h3>

Inside the <a spec="html">prepare a script</a> algorithm, we make the following changes:

- Insert the following step to [=prepare a script=] step 7, under "Determine the script's type as follows:":
  - If the script block's type string is an [=ASCII case-insensitive=] match for the string "`importmap`", <a spec="html">the script's type</a> is "`importmap`".
- Insert the following step before <a spec="html">prepare a script</a> step 24:
  - If <a spec="html">the script's type</a> is "`importmap`", and either the element's [=node document=]'s [=Document/acquiring import maps=] is false or the element's [=node document=]'s [=pending import map script=] is non-null, then <a spec="html">queue a task</a> to <a spec="html">fire an event</a> named `error` at the element, and return.
    <p class="note">In the future we could losen the constrain of erroring when the [=pending import map script=] is non-null, to allow multiple import maps.</p>
- Insert the following case to <a spec="html">prepare a script</a> step 24.6:
  <dl>
    <dt>"`importmap`"</dt>
    <dd>
      [=Fetch an import map=] given <var ignore>url</var>, |settings object|, and <var ignore>options</var>.
    </dd>
  </dl>
- Insert the following case to <a spec="html">prepare a script</a> step 25.2:
  <dl>
    <dt>"`importmap`"</dt>
    <dd>
      1. Let |import map parse result| be the result of [=create an import map parse result=], given <var ignore>source text</var>, <var ignore>base URL</var> and |settings object|.
      1. Set [=the script's result=] to |import map parse result|.
      1. <a spec="html">The script is ready</a>.
    </dd>
  </dl>
- Insert the following case to <a spec="html">prepare a script</a> step 26:
  <dl>
    <dt>If <a spec="html">the script's type</a> is "`importmap`"</dt>
    <dd>
      Set the element's [=node document=]'s [=Document/pending import map script=] to the element.
      When <a spec="html">the script is ready</a>, run the following steps:
        1. [=/Register an import map=] given the [=Document/pending import map script=].
        1. Set the [=Document/pending import map script=] to null.
           <p class="note">This will (asynchronously) unblock any [=wait for import maps=] algorithm instances.</p>
    </dd>
  </dl>

<p class="note">
  This is specified similar to the <a spec="html">list of scripts that will execute in order as soon as possible</a>.
</p>

<p class="note">
  CSPs are applied to inline import maps at Step 13 of <a spec="html">prepare a script</a>, and to external import maps in [=fetch an import map=], just like applied to classic/module scripts.
</p>

</div>

<div algorithm>
  To <dfn export>fetch an import map</dfn> given |url|, |settings object|, and |options|, run the following steps. This algorithm asynchronously returns an [=/import map=] or null.
  <p class="note">This algorithm is specified consistently with [=fetch a single module script=] steps 5, 7, 8, 9, 10, and 12.1. Particularly, we enforce CORS to avoid leaking the import map contents that shouldn't be accessed.</p>

  1. Let |request| be a new [=/request=] whose [=request/url=] is |url|, [=request/destination=] is "`script`", [=request/mode=] is "`cors`", [=request/referrer=] is "`client`", and [=request/client=] is |settings object|.
     <p class="note">Here we use "`script`" as the [=request/destination=], which means the `script-src-elem` CSP directive applies.</p>
  1. <a spec="html">Set up the module script request</a> given |request| and |options|.
  1. [=/Fetch=] |request|. Return from this algorithm, and run the remaining steps as part of the fetch's [=/process response=] for the [=/response=] |response|.
     <p class="note">|response| is always [=CORS-same-origin=].</p>
  1. If any of the following conditions are met, asynchronously complete this algorithm with null, and abort these steps:
    - |response|'s [=response/type=] is "`error`"
    - |response|'s [=response/status=] is not an [=ok status=]
    - The result of [=extracting a MIME type=] from |response|'s [=response/header list=] is not `"application/importmap+json"`
      <p class="note">For more context on MIME type checking, see <a href="https://github.com/WICG/import-maps/issues/105">#105</a> and <a href="https://github.com/WICG/import-maps/pull/119">#119</a>.</p>
  1. Let |source text| be the result of [=UTF-8 decoding=] response's [=response/body=].
  1. Asynchronously complete this algorithm with the result of [=create an import map parse result=], given |source text|, |response|'s [=response/url=], and |settings object|.

</div>

<h3 id="integration-wait-for-import-maps">Wait for import maps</h3>

<div algorithm>
  To <dfn export>wait for import maps</dfn> given |settings object|:

  1. If |settings object|'s [=environment settings object/global object=] is a {{Window}} object:
    1. Let |document| be |settings object|'s [=environment settings object/global object=]'s <a>associated <code>Document</code></a>.
    1. Set |document|'s [=Document/acquiring import maps=] to false.
    1. <a spec="html">Spin the event loop</a> until |document|'s [=Document/pending import map script=] is null.
  1. Asynchronously complete this algorithm.

<p class="note">No actions are specified for {{WorkerGlobalScope}} because for now there are no mechanisms for adding import maps to {{WorkerGlobalScope}}.</p>

</div>

Insert a call to [=wait for import maps=] at the beginning of the following HTML spec concepts.

- [=fetch an external module script graph=]
- [=fetch an import() module script graph=]
- [=fetch a modulepreload module script graph=]
- [=fetch an inline module script graph=]
- [=fetch a module worker script graph=] (using <var ignore>module map settings object</var>)

<div class="advisement">
  In this draft of the spec, which inserts itself into these HTML concepts, the settings object used here is the |module map settings object|, not |fetch client settings object|, because [=resolve a module specifier=] uses the import map of |module map settings object|. In a potential future version of the import maps infrastructure, which interjects itself at the layer of the Fetch spec in order to support `import:` URLs, we would instead use |fetch client settings object|.

  This only affects [=fetch a module worker script graph=], where these two settings objects are different. And, given that the import maps for {{WorkerGlobalScope}}s are currently always empty, the only fetch that could be impacted is that of the initial module. But even that would not be impacted, because that fetch is done using URLs, not specifiers. So this is not a future compatibility hazard, just something to keep in mind as we develop import maps in module workers.
</div>

<div class="advisement">
  Depending on the exact location of [=wait for import maps=], `import(unresolvableSpecifier)` might behave differently between a HTML-spec- and Fetch-spec-based import maps. In particular, in the current draft, [=acquiring import maps=] is set to false after an `import()`-initiated failure to [=resolve a module specifier=], thus causing any later-encountered import maps to cause an `error` event instead of being processed. Whereas, if [=wait for import maps=] was called as part of the Fetch spec, it's possible it would be natural to specify things such that [=acquiring import maps=] remains true (as it does for cases like `<script type="module" src="http://:invalidurl">`).

  This should not be much of a compatibility hazard, as it only makes esoteric error cases into successes. And we can always preserve the behavior as specced here if necessary, with some potential additional complexity.
</div>

<h3 id="integration-register-an-import-map">Registering an import map</h3>

<div algorithm>
To <dfn>register an import map</dfn> given an {{HTMLScriptElement}} |element|:

1. If |element|'s [=the script's result=] is null, then [=fire an event=] named `error` at |element|, and return.
1. Let |import map parse result| be |element|'s [=the script's result=].
1. Assert: |element|'s <a spec="html">the script's type</a> is "`importmap`".
1. Assert: |import map parse result| is an [=import map parse result=].
1. Let |settings object| be |import map parse result|'s [=import map parse result/settings object=].
1. If |element|'s <a spec="html">node document</a>'s <a spec="html">relevant settings object</a> is not equal to |settings object|, then return.
   <p class="note">This is spec'ed consistently with <a href="https://github.com/whatwg/html/pull/2673">whatwg/html#2673</a>.</p>
   <p class="advisement">Currently we don't fire `error` events in this case. If we change the decision at <a href="https://github.com/whatwg/html/pull/2673">whatwg/html#2673</a> to fire `error` events, then we should change this step accordingly.</p>
1. If |import map parse result|'s [=import map parse result/error to rethrow=] is not null, then:
  1. <a spec="html">Report the exception</a> given |import map parse result|'s [=import map parse result/error to rethrow=].
     <p class="issue">There are no relevant [=script=], because [=import map parse result=] isn't a [=script=]. This needs to wait for <a href="https://github.com/whatwg/html/issues/958">whatwg/html#958</a> before it is fixable.</p>
  1. Return.
1. Set |element|'s [=node document=]'s [=Document/import map=] to |import map parse result|'s [=import map parse result/import map=].
1. If |element| is <a spec="html">from an external file</a>, then [=fire an event=] named `load` at |element|.

<p class="note">
  The timing of [=/register an import map=] is observable by possible `error` and `load` events, or by the fact that after [=/register an import map=] an import map <{script}> can be moved to another {{Document}}. On the other hand, the updated [=Document/import map=] is not observable until [=/wait for import maps=] completes.
</p>

</div>

<h2 id="parsing">Parsing import maps</h2>

<div algorithm>
  To <dfn lt="parse an import map string|parsing an import map string">parse an import map string</dfn>, given a [=string=] |input| and a [=URL=] |baseURL|:

  1. Let |parsed| be the result of [=parse JSON into Infra values|parsing JSON into Infra values=] given |input|.
  1. If |parsed| is not a [=map=], then throw a {{TypeError}} indicating that the top-level value must be a JSON object.
  1. Let |sortedAndNormalizedImports| be an empty [=map=].
  1. If |parsed|["`imports`"] [=map/exists=], then:
    1. If |parsed|["`imports`"] is not a [=map=], then throw a {{TypeError}} indicating that the "`imports`" top-level key must be a JSON object.
    1. Set |sortedAndNormalizedImports| to the result of [=sorting and normalizing a specifier map=] given |parsed|["`imports`"] and |baseURL|.
  1. Let |sortedAndNormalizedScopes| be an empty [=map=].
  1. If |parsed|["`scopes`"] [=map/exists=], then:
    1. If |parsed|["`scopes`"] is not a [=map=], then throw a {{TypeError}} indicating that the "`scopes`" top-level key must be a JSON object.
    1. Set |sortedAndNormalizedScopes| to the result of [=sorting and normalizing scopes=] given |parsed|["`scopes`"] and |baseURL|.
  1. If |parsed|["`depcache`"] [=map/exists=], then:
    1. If |parsed|["`depcache`"] is not a [=map=], then throw a {{TypeError}} indicating that the "`depcache`" top-level key must be a JSON object.
    1. Set |normalizedDepcache| to the result of [=normalizing depcache=] given |parsed|["`depcache`"] and |baseURL|.
  1. If |parsed|'s [=map/get the keys|keys=] [=set/contains=] any items besides "`imports`", "`scopes`" or "`depcache`", [=report a warning to the console=] that an invalid top-level key was present in the import map.
     <p class="note">This can help detect typos. It is not an error, because that would prevent any future extensions from being added backward-compatibly.</p>
  1. Return the [=/import map=] whose [=import map/imports=] are |sortedAndNormalizedImports|, [=import map/scopes=] scopes are |sortedAndNormalizedScopes| and [=import map/depcache=] depcache are |normalizedDepcache|.
</div>

<div algorithm>
  To <dfn>create an import map parse result</dfn>, given a [=string=] |input|, a [=URL=] |baseURL|, and an [=environment settings object=] |settings object|:

  1. Let |import map| be the result of [=parse an import map string=] given |input| and |baseURL|. If this throws an exception, let |error to rethrow| be the exception. Otherwise, let |error to rethrow| be null.
  1. Return an [=import map parse result=] with [=import map parse result/settings object=] is |settings object|, [=import map parse result/import map=] is |import map|, and [=import map parse result/error to rethrow=] is |error to rethrow|.
</div>


<div class="example" id="parsing-example">
  The [=/import map=] is a highly normalized structure. For example, given a base URL of `<https://example.com/base/page.html>`, the input

  <xmp highlight="json">
    {
      "imports": {
        "/app/helper": "node_modules/helper/index.mjs",
        "lodash": "/node_modules/lodash-es/lodash.js"
      }
    }
  </xmp>

  will generate an [=/import map=] with [=import map/imports=] of

  <xmp>
  «[
    "https://example.com/app/helper" → <https://example.com/base/node_modules/helper/index.mjs>
    "lodash" → <https://example.com/node_modules/lodash-es/lodash.js>
  ]»
  </xmp>

  and (despite nothing being present in the input) empty [=map=] entries for its [=import map/scopes=] and [=import map/depcache=].
</div>

<div algorithm>
  To <dfn lt="sort and normalize a specifier map|sorting and normalizing a specifier map">sort and normalize a specifier map</dfn>, given a [=map=] |originalMap| and a [=URL=] |baseURL|:

  1. Let |normalized| be an empty [=map=].
  1. [=map/For each=] |specifierKey| → |value| of |originalMap|,
    1. Let |normalizedSpecifierKey| be the result of [=normalizing a specifier key=] given |specifierKey| and |baseURL|.
    1. If |normalizedSpecifierKey| is null, then [=continue=].
    1. If |value| is not a [=string=], then:
      1. [=Report a warning to the console=] that addresses must be strings.
      1. Set |normalized|[|specifierKey|] to null.
      1. [=Continue=].
    1. Let |addressURL| be the result of [=parsing a URL-like import specifier=] given |value| and |baseURL|.
    1. If |addressURL| is null, then:
      1. [=Report a warning to the console=] that the address was invalid.
      1. Set |normalized|[|specifierKey|] to null.
      1. [=Continue=].
    1. If |specifierKey| ends with U+002F (/), and the [=URL serializer|serialization=] of |addressURL| does not end with U+002F (/), then:
      1. [=Report a warning to the console=] that an invalid address was given for the specifier key |specifierKey|; since |specifierKey| ended in a slash, so must the address.
      1. Set |normalized|[|specifierKey|] to null.
      1. [=Continue=].
    1. Set |normalized|[|specifierKey|] to |addressURL|.
  1. Return the result of [=map/sorting=] |normalized|, with an entry |a| being less than an entry |b| if |b|'s [=map/key=] is [=code unit less than=] |a|'s [=map/key=].
</div>

<div algorithm>
  To <dfn lt="sort and normalize scopes|sorting and normalizing scopes">sort and normalize scopes</dfn>, given a [=map=] |originalMap| and a [=URL=] |baseURL|:

  1. Let |normalized| be an empty [=map=].
  1. [=map/For each=] |scopePrefix| → |potentialSpecifierMap| of |originalMap|,
    1. If |potentialSpecifierMap| is not a [=map=], then throw a {{TypeError}} indicating that the value of the scope with prefix |scopePrefix| must be a JSON object.
    1. Let |scopePrefixURL| be the result of [=URL parser|parsing=] |scopePrefix| with |baseURL| as the base URL.
    1. If |scopePrefixURL| is failure, then:
      1. [=Report a warning to the console=] that the scope prefix URL was not parseable.
      1. [=Continue=].
    1. Let |normalizedScopePrefix| be the [=URL serializer|serialization=] of |scopePrefixURL|.
    1. Set |normalized|[|normalizedScopePrefix|] to the result of [=sorting and normalizing a specifier map=] given |potentialSpecifierMap| and |baseURL|.
  1. Return the result of [=map/sorting=] |normalized|, with an entry |a| being less than an entry |b| if |b|'s [=map/key=] is [=code unit less than=] |a|'s [=map/key=].
</div>

<div algorithm>
  To <dfn lt="normalize depcache|normalizing depcache">normalize depcache</dfn>, given a [=map=] |originalMap| and a [=URL=] |baseURL|:

  1. Let |normalized| be an empty [=map=].
  1. [=map/For each=] |module| → |dependencies| of |originalMap|,
    1. Let |moduleURL| be the result of [=URL parser|parsing=] |module| with |baseURL| as the base URL.
    1. If |moduleURL| is failure, then:
      1. [=Report a warning to the console=] that the depcache URL was not parseable.
      1. [=Continue=].
    1. If ![$IsArray$](dependencies), then:
      1. [=Report a warning to the console=] that the value of the depcache for module |module| must be a JSON array.
      1. [=Continue=].
    1. Let |validDependencies| be true.
    1. [=list/For each=] |dependency| of |dependencies|,
      1. If |dependency| is not a Javascript [=string=], then:
        1. [=Report a warning to the console=] that the depcache list for |moduleURL| is invalid.
        1. Set _validDependencies_ to false.
        1. [=Break=].
    1. If |dependencies| is not [=list/empty=] and |validDependencies| is true, then:
      1. Let |normalizedModule| be the [=URL serializer|serialization=] of |moduleURL|.
      1. Set |normalized|[|normalizedModule|] to |dependencies|.
  1. Return |normalized|.
</div>

<p class="note">We sort keys/scopes in reverse order, to put `"foo/bar/"` before `"foo/"` so that `"foo/bar/"` has a higher priority than `"foo/"`.</p>

<div algorithm>
  To <dfn lt="normalize a specifier key|normalizing a specifier key">normalize a specifier key</dfn>, given a [=string=] |specifierKey| and a [=URL=] |baseURL|:

  1. If |specifierKey| is the empty string, then:
    1. [=Report a warning to the console=] that specifier keys cannot be the empty string.
    1. Return null.
  1. Let |url| be the result of [=parsing a URL-like import specifier=], given |specifierKey| and |baseURL|.
  1. If |url| is not null, then return the [=URL serializer|serialization=] of |url|.
  1. Return |specifierKey|.
</div>

<div algorithm>
  To <dfn lt="parse a URL-like import specifier|parsing a URL-like import specifier">parse a URL-like import specifier</dfn>, given a [=string=] |specifier| and a [=URL=] |baseURL|:

  1. If |specifier| [=/starts with=] "`/`", "`./`", or "`../`", then:
    1. Let |url| be the result of [=URL parser|parsing=] |specifier| with |baseURL| as the base URL.
    1. If |url| is failure, then return null.
       <p class="example" id="example-bad-urllike-import-specifier">One way this could happen is if |specifier| is "`../foo`" and |baseURL| is a `data:` URL.</p>
    1. Return |url|.
  1. Let |url| be the result of [=URL parser|parsing=] |specifier| (with no base URL).
  1. If |url| is failure, then return null.
  1. Return |url|.
</div>

<h2 id="resolving">Resolving module specifiers</h2>

<div class="note">
  During [=resolve a module specifier|resolving a module specifier=], the following algorithms check candidate entries of [=specifier maps=], from most-specific to least-specific scopes (falling back to top-level "`imports`"), and from most-specific to least-specific prefixes. For each candidate, the result is one of the following:

  - Successfully resolves a specifier to a [=URL=]. This makes the [=resolve a module specifier=] algorithm immediately return that [=URL=].
  - Throws an error. This makes the [=resolve a module specifier=] algorithm rethrow the error, without any further fallbacks.
  - Fails to resolve, without an error. In this case the algorithm moves on to the next candidate.
</div>

<h3 id="new-resolve-algorithm">New "resolve a module specifier"</h3>

<div algorithm>
  HTML already has a <a spec="html">resolve a module specifier</a> algorithm. We replace it with the following <dfn export>resolve a module specifier</dfn> algorithm, given a [=script=] |referringScript| and a [=JavaScript string=] |specifier|:

  1. Let |settingsObject| be the [=current settings object=].
  1. Let |baseURL| be |settingsObject|'s [=environment settings object/API base URL=].
  1. If |referringScript| is not null, then:
    1. Set |settingsObject| to |referringScript|'s [=script/settings object=].
    1. Set |baseURL| to |referringScript|'s [=script/base URL=].
  1. Let |importMap| be |settingsObject|'s [=environment settings object/import map=].
  1. Return the result of [=resolve an import map=] given |specifier|, |importMap| and |baseURL|.

</div>

<div algorithm>
  To <dfn lt="resolve an import map|resolve an import map">resolve an import map</dfn>, given a [=string=] |specifier|, an [=/import map=] |importMap| and a [=URL=] |baseURL|:
  1. Let |baseURLString| be |baseURL|, [=URL serializer|serialized=].
  1. Let |asURL| be the result of [=parsing a URL-like import specifier=] given |specifier| and |baseURL|.
  1. Let |normalizedSpecifier| be the [=URL serializer|serialization=] of |asURL|, if |asURL| is non-null; otherwise, |specifier|.
  1. [=map/For each=] |scopePrefix| → |scopeImports| of |importMap|'s [=import map/scopes=],
    1. If |scopePrefix| is |baseURLString|, or if |scopePrefix| ends with U+002F (/) and |baseURLString| [=/starts with=] |scopePrefix|, then:
      1. Let |scopeImportsMatch| be the result of [=resolving an imports match=] given |normalizedSpecifier| and |scopeImports|.
      1. If |scopeImportsMatch| is not null, then return |scopeImportsMatch|.
  1. Let |topLevelImportsMatch| be the result of [=resolving an imports match=] given |normalizedSpecifier| and |importMap|'s [=import map/imports=].
  1. If |topLevelImportsMatch| is not null, then return |topLevelImportsMatch|.
  1. <p class="note">At this point, the specifier was able to be turned in to a URL, but it wasn't remapped to anything by |importMap|.</p>
    If |asURL| is not null, then return |asURL|.
  1. Throw a {{TypeError}} indicating that |specifier| was a bare specifier, but was not remapped to anything by |importMap|.
</div>

<div algorithm>
  To <dfn lt="resolve an imports match|resolving an imports match">resolve an imports match</dfn>, given a [=string=] |normalizedSpecifier| and a [=specifier map=] |specifierMap|:

  1. For each |specifierKey| → |resolutionResult| of |specifierMap|,
    1. If |specifierKey| is |normalizedSpecifier|, then:
      1. If |resolutionResult| is null, then throw a {{TypeError}} indicating that resolution of |specifierKey| was blocked by a null entry.
        <p class="note">This will terminate the entire [=resolve a module specifier=] algorithm, without any further fallbacks.</p>
      1. Assert: |resolutionResult| is a [=URL=].
      1. Return |resolutionResult|.
    1. If |specifierKey| ends with U+002F (/) and |normalizedSpecifier| [=/starts with=] |specifierKey|, then:
      1. If |resolutionResult| is null, then throw a {{TypeError}} indicating that resolution of |specifierKey| was blocked by a null entry.
        <p class="note">This will terminate the entire [=resolve a module specifier=] algorithm, without any further fallbacks.</p>
      1. Assert: |resolutionResult| is a [=URL=].
      1. Let |afterPrefix| be the portion of |normalizedSpecifier| after the initial |specifierKey| prefix.
      1. Assert: |resolutionResult|, [=URL serializer|serialized=], ends with "`/`", as enforced during [=parse an import map string|parsing=].
      1. Let |url| be the result of [=URL parser|parsing=] |afterPrefix| relative to the base URL |resolutionResult|.
      1. If |url| is failure, then throw a {{TypeError}} indicating that resolution of |specifierKey| was blocked due to a URL parse failure.
        <p class="note">This will terminate the entire [=resolve a module specifier=] algorithm, without any further fallbacks.</p>
      1. Assert: |url| is a [=URL=].
      1. Return |url|.
  1. Return null.
     <p class="note">The [=resolve a module specifier=] algorithm will fallback to a less specific scope or to "`imports`", if possible.</p>
</div>

<h3 id="resolving-updates">Updates to other algorithms</h3>

All call sites of HTML's existing <a spec="html">resolve a module specifier</a> will need to be updated to pass the appropriate [=script=], not just its [=script/base URL=]. Some particular interesting cases:

* <a spec="html">HostResolveImportedModule</a> and <a spec="html">HostImportModuleDynamically</a> no longer need to compute the base URL themselves, as [=resolve a module specifier=] now handles that.
* [=Fetch an import() module script graph=] will also need to take a [=script=] instead of a base URL.

Call sites will also need to be updated to account for [=resolve a module specifier=] now throwing exceptions, instead of returning failure. (Previously most call sites just turned failures into {{TypeError}}s manually, so this is straightforward.)

<h2 id="parallelizing">Parallelizing module graphs</h2>

  To parallelize the loading of modules in the import map, a module graph [=dependency cache list=] can be used to provide upfront a cache of module dependencies so they can be loaded in parallel when lazily loaded, without unnecessary requests or extra round trips.

  When this list of dependency hints is provided for a module [=URL=] the algorithm will, on resolution for that module [=URL=], immediately trigger resolution and preloading for each dependency hint provided.

  The behavior of the dependency cache preloader is distinct from the [=fetch a modulepreload module script graph=] preloader in that it immediately iterates all dependency preloads, and does not trigger instantiation since the top-level module instantiation would already be queued.

<h3 id="preloading-dependency-graphs">Preloading dependency graphs</h3>

  The [=preload depcache=] steps below should be included in [=fetch a single module script=], right after step 4 setting moduleMap[url] to "fetching" combining to form an optimizally-terminating graph fetch parallelizing operation, with minimum complexity. Alternatively these steps can be inlined into [=fetch a single module script=] directly. The rationale of this ordering being that dependencies should be triggered for fetching before their parents, even when fetching in parallel.

<div algorithm>
  To <dfn lt="preload a dependency graph cache|preload depcache">preload a dependency graph cache</dfn>, given a |url|, a |fetch client settings object|, a |destination|, some |options| and a |module map settings object|, run these steps:

  1. Let |urlString| be |url|, [=URL serializer|serialized=].
  1. Let |moduleMap| be |module map settings object|'s [=module map=].
  1. If |moduleMap|[|urlString|] is not undefined, return null.
    <p class="note">null entries in the |moduleMap| for errored modules will also return here.</p>
  1. Let |importMap| be |module map settings object|'s [=environment settings object/import map=].
  1. Let |depcache| be |importMap|'s [=import map/depcache=],
  1. If |depcache| contains an entry for |urlString|, then:
    1. Let |dependencies| be the [=list=] |depcache|[|urlString|].
    1. For each |dependency| of |dependencies|,
      1. Let |resolvedDependencyURL| be the result of [=resolve an import map=] called with |dependency|, |importMap| and |url|.
      1. If |resolvedDependencyURL| is null, then:
        1. Throw a {{TypeError}} indicating that |dependency| was a specifier preloaded by the depcache for |urlString|, but was not resolved by |importMap|.
      1. Perfom the steps of HTML's [=fetch a single module script] with |resolvedDependencyURL|, |fetch client settings object|, |destination|, |options|, |module map settings object|, |url|, and with the top-level module fetch flag unset, without waiting for asynchronous completion.
        <p class="note">This triggers the recursive fetch preload operations in turn, since this algorithm is in turn called by [=fetch a single module script=].</p>
</div>

<p class="note">Only dependency preload resolution errors are thrown, not dependency preload instantiation errors. These can be ignored as they will be rethrown appropriately by the top-level module load operation.</p>

<h2 id="security-and-privacy">Security and Privacy</h2>

<h3 id="threat-models">Threat models</h3>

<h4 id="comparison-with-first-party-scripts">Comparison with first-party scripts</h4>

Import maps are explicitly designed to be installed by page authors, i.e. those who have the ability to run first-party scripts. (See the explainer's ["Scope" section](https://github.com/WICG/import-maps/blob/master/README.md#scope).)

Although it may seem that the ability to change how resources are imported from JavaScript and the capability of rewriting rules are powerful, there is no extra power really granted here, compared with first-party scripts. That is, they only change things which the page author could change already, by manually editing their code to use different URLs.

We do still need to apply the traditional protections against first-party malicious actors, for example:

- CSP to protect against injection vulnerabilities. (See [#105](https://github.com/WICG/import-maps/issues/105) for further discussion.)
- CORS and strict MIME type checking (with a new MIME type, "`application/importmap+json`") for external import maps.

But there is no fundamentally new capability introduced here, that needs new consideration.

<h4 id="comparison-with-service-workers">Comparison with Service Workers</h4>

On one hand, the ability of import maps to change how resources are imported looks similar to the ability of Service Workers to intercept and rewrite fetch requests.

On the other hand, import maps have a much more restricted scope than Service Workers. Import maps are not persistent, and an import map only affects the document that installs the import map via `<script type="importmap">`.

Therefore, the security restrictions applied to Service Workers (beyond those applied to first-party scripts), e.g. the same-origin/secure contexts requirements, are not applied to import maps.

<h4 id="complexity">Time/memory complexity</h4>

To avoid denial of service attacks, explosive memory usage, and the like, import maps are designed to have reasonably bounded time and memory complexity in the worst cases, and to not be Turing complete.

<h3 id="note-on-import-specifiers">A note on import specifiers</h3>

The import specifiers that appear in `import` statements and `import()` expressions are not [=URLs=], and should not be thought of as such.

To date, there has been a <a spec="html" data-lt="resolve a module specifier">default mechanism</a> for translating those strings into URLs. And indeed, some of the strings, such as `"https://example.com/foo.mjs"`, or `"./bar.mjs"`, might look URL-like; for those, the default translation does what you would expect.

But overall, one should not think of `import(x)` as corresponding to `fetch(x)`. Instead, the correspondence is to `fetch(translate(x))`, where the translation algorithm produces the actual URL to be fetched. In this framing, the way to think about import maps is as providing a mechanism for overriding the default mechanism, i.e. customizing the `translate()` function.

This brings some clarity to some common security questions. For example: given an import map which maps the specifier `"https://1.example.com/foo.mjs"` to the URL `<https://2.example.com/bar.mjs>`, should we apply CSP checks to `<https://1.example.com/foo.mjs>` or to `<https://2.example.com/bar.mjs>`? With this framing we can see that we should apply the checks to the post-translation URL `<https://2.example.com/bar.mjs>` which is actually fetched, and not to the pre-translation `"https://1.example.com/foo.mjs"` module specifier.