spec.html

<pre class="metadata">
title: import()
status: proposal
stage: -1
location: https://domenic.github.io/proposal-import-function/
copyright: false
contributors: Domenic Denicola
</pre>
<script src="https://bterlson.github.io/ecmarkup/ecmarkup.js" defer></script>
<link rel="stylesheet" href="https://bterlson.github.io/ecmarkup/elements.css">
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/8.4/styles/solarized_light.min.css">

<emu-intro id="introduction">
  <h1>Introduction</h1>

  <p>Background explanatory material for this specification can be found in the <a href="https://github.com/domenic/proposal-import-function">domenic/proposal-import-function</a> repository. See also the <a href="https://github.com/tc39/proposal-import-function/issues">issues</a> and the <a href="https://github.com/domenic/proposal-import-function/blob/master/HTML%20Integration.md">HTML integration spec</a> that builds on top of the below JavaScript specification.</p>
</emu-intro>

<emu-clause id="sec-modules">
  <h1>Modules</h1>

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

    <emu-clause id="sec-hostresolveimportedmodule" aoid="HostResolveImportedModule">
      <h1>Runtime Semantics: HostResolveImportedModule ( <del>_referencingModule_</del><ins>_referencingScriptOrModule_</ins>, _specifier_ )</h1>

      <p>HostResolveImportedModule is an implementation defined abstract operation that provides the concrete Module Record subclass instance that corresponds to the |ModuleSpecifier| String, _specifier_, occurring within the context of the <ins>script or </ins>module represented by the <ins>Script Record or </ins>Module Record <del>_referencingModule_</del><ins>_referencingScriptOrModule_</ins>.</p>
      <p>The implementation of HostResolveImportedModule must conform to the following requirements:</p>

      <ul>
        <li>
          The normal return value must be an instance of a concrete subclass of Module Record.
        </li>
        <li>
          If a Module Record corresponding to the pair <del>_referencingModule_</del><ins>_referencingScriptOrModule_</ins>, _specifier_ does not exist or cannot be created, an exception must be thrown.
        </li>
        <li>
          This operation must be idempotent if it completes normally. Each time it is called with a specific <del>_referencingModule_</del><ins>_referencingScriptOrModule_</ins>, _specifier_ pair as arguments it must return the same Module Record instance.
        </li>
      </ul>

      <p>Multiple different <del>_referencingModule_</del><ins>_referencingScriptOrModule_</ins>, _specifier_ pairs may map to the same Module Record instance. The actual mapping semantic is implementation 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 alphabetic case folding and expansion of relative and abbreviated path specifiers.</p>
    </emu-clause>

    <emu-clause id="sec-hostfetchimportedmodule" aoid="HostFetchImportedModule">
      <h1><ins>Runtime Semantics: HostFetchImportedModule ( _referencingScriptOrModule_, _specifier_ )</ins></h1>

      <p>HostFetchImportedModule is an implementation defined abstract operation that asynchronously performs any necessary setup work in order to make available the module corresponding to the |ModuleSpecifier| String, _specifier_, occurring within the context of the script or module represented by the Script Record or Module Record _referencingScriptOrModule_. This prepares the host environment for future calls to HostResolveImportedModule with the same arguments.</p>
      <p>The implementation of HostResolveImportedModule must conform to the following requirements:</p>

      <ul>
        <li>
          The abstract operation must always complete with *undefined*. Success or failure must instead be signaled by using the phrase "asynchronously complete with" and giving a completion record (which may be either an abrupt completion or normal completion).
        </li>
        <li>
          If the operation succeeds, the asynchronous completion value must be a normal completion whose [[Value]] field is *undefined*.
        </li>
        <li>
          If the operation succeeds, a subsequent call to HostResolveImportedModule given the same arguments must complete normally.
        </li>
        <li>
          If the operation fails, the asynchronous completion value must be an abrupt completion.
        </li>
      </ul>

      <p>The actual process performed is implementation defined, but typically consists of performing whatever I/O operations are necessary to allow HostResolveImportedModule to synchronously retrieve the appropriate Module Record. This might require performing similar normalization as HostResolveImportedModule as an initial step.</p>
    </emu-clause>
  </emu-clause>
</emu-clause>

<emu-clause id="sec-left-hand-side-expressions">
  <h1>Left-Hand-Side Expressions</h1>
  <h2>Syntax</h2>
  <emu-grammar>
    CallExpression[Yield] :
      MemberExpression[?Yield] Arguments[?Yield]
      SuperCall[?Yield]
      <ins>ImportCall[?Yield]</ins>
      CallExpression[?Yield] Arguments[?Yield]
      CallExpression[?Yield] `[` Expression[+In, ?Yield] `]`
      CallExpression[?Yield] `.` IdentifierName
      CallExpression[?Yield] TemplateLiteral[?Yield]

    <ins>ImportCall[Yield] :
      `import` Arguments[?Yield]</ins>
  </emu-grammar>

  <p>(Also, many other instances of |CallExpression| need to get |ImportCall| added to them.)</p>

  <emu-clause id="sec-import-calls">
    <h1>Import Calls</h1>

    <emu-clause id="sec-import-call-runtime-semantics-evaluation">
      <h1>Runtime Semantics: Evaluation</h1>

      <emu-grammar>ImportCall : `import` Arguments</emu-grammar>
      <emu-alg>
        1. Let _referencingScriptOrModule_ be ! GetActiveScriptOrModule().
        1. Assert: _referencingScriptOrModule_ is a Script Record or Module Record (i.e. is not *null*).
        1. Let _argList_ be ArgumentListEvaluation of |Arguments|.
        1. ReturnIfAbrupt(_argList_).
        1. Let _specifier_ be the first element of _argList_.
        1. Let _promiseCapability_ be ! NewPromiseCapability(%Promise%).
        1. Return _promiseCapability_.[[Promise]], but continue running the following steps:
          1. Perform ! HostFetchImportedModule(_referencingScriptOrModule_, _specifier_). When it asynchronously completes, let _fetchResult_ be the resulting asynchronous completion value, and continue to the next step.
          1. If _fetchResult_ is an abrupt completion, then perform ! Call(_promiseCapability_.[[Reject]], *undefined*, « _fetchResult_.[[Value]] »).
          1. Otherwise,
            1. Assert: _fetchResult_ is a normal completion and _fetchResult_.[[Value]] is *undefined*.
            1. Let _moduleRecord_ be ! HostResolveImportedModule(_referencingScriptOrModule_, _specifier_).
            1. Perform ! Call(_promiseCapability_.[[Resolve]], *undefined*, « _moduleRecord_.[[Namespace]] »).
      </emu-alg>
    </emu-clause>
  </emu-clause>
</emu-clause>