4.1.1 Implicit Completions

All abstract operations declared in this specification are implicitly assumed to either return a normal completion containing the algorithm's declared return type, or a throw completion. For example, an abstract operation declared as

4.1.1.1 GetTheAnswer ( input )

The abstract operation GetTheAnswer takes argument input (an integer) and returns an integer.

is equivalent to:

4.1.1.2 GetTheAnswer2 ( input )

The abstract operation GetTheAnswer2 takes argument input (an integer) and returns either a normal completion containing an integer or a throw completion.

All calls to abstract operations that return completion records are implicitly assumed to be wrapped by a ReturnIfAbrupt macro, unless they are explicitly wrapped by an explicit Completion call. For example:

is equivalent to:

4.1.2 Optional Errors

Whenever an algorithm is to optionally report an error, an implementation may choose one of the following behaviours:

• Continue executing the rest of the algorithm.
• Report an error to the user (for example, in the browser console), and continue executing the rest of the algorithm.
• Return a ThrowCompletion.

An implementation can choose different behaviours for different optional errors.

9.1.1 ParseSourceMap ( string, baseURL )

The abstract operation ParseSourceMap takes arguments string (a String) and baseURL (an URL) and returns a Decoded Source Map Record. It performs the following steps when called:

9.1.2 DecodeSourceMap ( json, baseURL )

The abstract operation DecodeSourceMap takes arguments json (a JSON object) and baseURL (an URL) and returns a Decoded Source Map Record. It performs the following steps when called:

9.2.1 Mappings grammar

The mappings String must adhere to the following grammar:

A Decode Mapping State Record has the following fields:

9.2.2 DecodeMappings ( rawMappings, names, sources )

The abstract operation DecodeMappings takes arguments rawMappings (a String), names (a List of Strings), and sources (a List of Decoded Source Records) and returns a List of Decoded Mapping Record. It performs the following steps when called:

9.2.3 Mappings for generated JavaScript code

Generated code positions that may have mapping entries are defined in terms of input elements, as per the ECMAScript Lexical Grammar. Mapping entries shall point to either:

• the first code point of the source text matched by IdentifierName, PrivateIdentifier, Punctuator, DivPunctuator, RightBracePunctuator, NumericLiteral and RegularExpressionLiteral.
• any code point of the source text matched by Comment, HashbangComment, StringLiteral, Template, TemplateSubstitutionTail, WhiteSpace and LineTerminator.

9.2.4 Names for generated JavaScript code

Source map generators should create a mapping entry with a [[Name]] field for a JavaScript token, if:

• The original source language construct maps semantically to the generated JavaScript code.
• The original source language construct has a name.

Then the [[Name]] of the mapping entry should be the name of the original source language construct. A mapping with a non-null [[Name]] is called a named mapping.

The following enumeration lists productions of the ECMAScript Syntactic Grammar and the respective token or non-terminal (on the right-hand side of the production) for which source map generators should emit a named mapping. The mapping entry created for such tokens shall follow section 9.2.3.

The enumeration should be understood as the "minimum". In general, source map generators are free to emit any additional named mappings.

• The BindingIdentifier(s) for LexicalDeclaration, VariableStatement and FormalParameterList.

• The BindingIdentifier for FunctionDeclaration, FunctionExpression, AsyncFunctionDeclaration, AsyncFunctionExpression, GeneratorDeclaration, GeneratorExpression, AsyncGeneratorDeclaration, and AsyncGeneratorExpression if it exists, or the opening parenthesis ( preceding the FormalParameters otherwise.

  Source map generators may chose to emit a named mapping on the opening parenthesis regardless of the presence of the BindingIdentifier.

• For an ArrowFunction or AsyncArrowFunction:

  • The => token where ArrowFunction is produced with a single BindingIdentifier for ArrowParameters or AsyncArrowFunction is produced with an AsyncArrowBindingIdentifier.

    Note 3
    This describes the case of (async) arrow functions with a single parameter, where that single parameter is not wrapped in parenthesis.

  • The opening parenthesis ( where ArrowFunction or AsyncArrowFunction is produced with ArrowFormalParameters.

    Source map generators may chose to additionally emit a named mapping on the => token for consistency with the previous case.

• The ClassElementName for MethodDefinition. This includes generators, async methods, async generators and accessors. For MethodDefinition where ClassElementName is "constructor", the [[Name]] should be the original class name if applicable.

  Source map generators may chose to additionally emit a named mapping on the opening parenthesis (.

• Source map generators may emit named mapping for IdentifierReference| in |Expression|.

9.3.1 Original Scope Record

A original scope is described by a Original Scope Record:

A root Original Scope Record describes the lexical scope tree of a original source file.

9.3.2 Generated Range Record

A generated range is described by a Generated Range Record:

A root Decoded Generated Record describes a distinct part of the generated code. Each Generated Range Record may be associated with a Original Scope Record as indicated by the presence of the [[Definition]] field.

[[Bindings]] are intended for debuggers to retrieve the values of original variables. The length of [[Bindings]] must be equal to [[Variables]] of the corresponding Original Scope Record. Given an index i, the JavaScript expression [[Binding]][i], when evaluated inside the generated range, retrieves the value for the original variable [[Variables]][i].

If a variable requires different expressions across a generated range, then [[SubRangeBindings]] can be used. [[SubRangeBinding]] splits the generated range into multiple sub-ranges, but just for a specific variable. Note that the same can be achieved with splitting the whole generated range, but at the cost of duplicating all of the information.

If a variable utilizes [[SubRangeBindings]] then the expression for the first sub-range is found in [[Bindings]] and the rest in [[SubRangeBindings]].

          {
            [[Start]]: { [[Line]]: 0, [[Column]]: 0 },
            [[End]]: { [[Line]]: 0, [[Column]]: 30 },
            [[Definition]]: { ... }
            [[Bindings]]: ["a"]
            [[SubRangeBindings]]: [
              {
                [[From]]: { [[Line]]: 0, [[Column]]: 10 },
                [[Binding]]: *null*,
              },
              {
                [[From]]: { [[Line]]: 0, [[Column]]: 20 },
                [[Binding]]: "b",
              },
            ],
          }
        

A non-null [[CallSite]] field marks the generated range as an inlined scope. If the [[CallSite]] field of a generated range is not null, then:

• [[Definition]] must not be null.
• [[Definition]].[[IsStackFrame]] must be true.
• [[IsStackFrame]] must be false.

9.3.3 Scopes grammar

The scopes field is described by the following context-sensitive grammar starting at the Scopes goal symbol:

The number of OriginalScopeTreeItems in the OriginalScopeTreeList is expected to match the length of the sources field. The n-th OriginalScopeTreeItem describes the scope tree of the n-th authored source file in the sources field. If no scope information is available for a particular source URL, an empty item can be used.

          "scopes": "<OriginalScopeTree>,,<OriginalScopeTree>,<GeneratedRangeTree>"
        

9.3.4 Decoding scopes

The scopes grammar defined in 9.3.3 is context-sensitive and heavily utilizes relative numbers to reduce the bytes required for the encoded scope information. As such, the grammar alone is not enough to describe how a Scopes parse node is turned into Original Scope Records and Generated Range Records.

9.4.1 DecodeSourceMapSources ( baseURL, sourceRoot, sources, sourcesContent, ignoreList, scopes )

The abstract operation DecodeSourceMapSources takes arguments baseURL (an URL), sourceRoot (a String or null), sources (a List of either Strings or null), sourcesContent (a List of either Strings or null), ignoreList (a List of non-negative integers), and scopes (a List of either Original Scope Records or null) and returns a Decoded Source Record. It performs the following steps when called:

11.1.1 Linking through HTTP headers

If a file is served through HTTP(S) with a sourcemap header, the value of the header is the URL of the linked source map.

sourcemap: <url>

11.1.2 Linking through inline annotations

The generated code should include a comment, or the equivalent construct depending on its language or format, named sourceMappingURL and that contains the URL of the source map. This specification defines how the comment should look like for JavaScript, CSS, and WebAssembly. Other languages should follow a similar convention.

For a given language there can be multiple ways of detecting the sourceMappingURL comment, to allow for different implementations to choose what is less complex for them. The generated code unambiguously links to a source map if the result of all the extraction methods is the same.

If a tool consumes one or more source files that unambiguously links to a source map and it produces an output file that links to a source map, it shall do so unambiguously.

let a = `
//# sourceMappingURL=foo.js.map
//`

const JS_NEWLINE = /^/m;

// This RegExp will always match one of the following:
// - single-line comments
// - "single-line" multi-line comments
// - unclosed multi-line comments
// - just trailing whitespaces
// - a code character
// The loop below differentiates between all these cases.
const JS_COMMENT =
  /\s*(?:\/\/(?<single>.*)|\/\*(?<multi>.*?)\*\/|\/\*.*|$|(?<code>[^\/]+))/uym;

const PATTERN = /^[@#]\s*sourceMappingURL=(\S*?)\s*$/;

let lastURL = null;
for (const line of source.split(JS_NEWLINE)) {
  JS_COMMENT.lastIndex = 0;
  while (JS_COMMENT.lastIndex < line.length) {
    let commentMatch = JS_COMMENT.exec(line).groups;
    let comment = commentMatch.single ?? commentMatch.multi;
    if (comment != null) {
      let match = PATTERN.exec(comment);
      if (match !== null) lastURL = match[1];
    } else if (commentMatch.code != null) {
      lastURL = null;
    } else {
      // We found either trailing whitespaces or an unclosed comment.
      // Assert: JS_COMMENT.lastIndex === line.length
    }
  }
}
return lastURL;

Since WebAssembly is not a textual format and it does not support comments, it supports a single unambiguous extraction method. The URL is encoded as a WebAssembly name, and it's placed as the content of the custom section. It is invalid for tools that generate WebAssembly code to generate two or more custom sections with the sourceMappingURL name.

11.2.1 FetchSourceMap ( url )

The abstract operation FetchSourceMap takes argument url (an URL) and returns a Promise. It performs the following steps when called:

)]}'garbage here
{"version": 3, ...}

{"version": 3, ...}