index.bs

<pre class='metadata'>
Title: Explicit JavaScript Compile Hints (File-based)
Shortname: explicit-js-compile-hints
Level: None
Status: LD
Repository: explainers-by-googlers/explicit-javascript-compile-hints-file-based
URL: https://explainers-by-googlers.github.io/explicit-javascript-compile-hints-file-based/
Editor: Marja Hölttä, Google, https://google.com, marja@google.com
Abstract: A magic comment in JavaScript for signaling certain scripts / functions should be prioritized.
Markup Shorthands: markdown yes, css no
Complain About: accidental-2119 yes, missing-example-ids yes
Assume Explicit For: yes
Die On: warning
WPT Path Prefix: TODO-API-LABEL
WPT Display: closed
Include MDN Panels: if possible
Include Can I Use Panels: yes
Boilerplate: omit conformance
</pre>

Introduction {#intro}
=====================

This proposal introduces a new magic comment that signals to browsers that the functions in a JavaScript script are likely to be needed by the website. This allows the browser to parse, compile and/or cache them eagerly, which can improve page load times.

In its current form, it’s not a defined standard and is subject to modifications.

Additions to Script Records and Source Text Module Records {#additions}
=======================================================================

The [Script Record](https://tc39.es/ecma262/#sec-script-records) and [Source Text Module Record](https://tc39.es/ecma262/#sec-source-text-module-records) are augmented to contain the following field:

<table class="data">
    <tr>
        <td>Field name</td>
        <td>Value type</td>
        <td>Meaning</td>
    </tr>
    <tr>
        <td>\[\[CompileHintAnnotation]]</td>
        <td>anything (default value is EMPTY)</td>
        <td>Contains information about the Compile Hint Annotation associated with the script / module.</td>
    </tr>
</table>


Extracting Compile Hint Annotations from JavaScript source text {#extract}
==========================================================================

This section explains how the user agent may determine whether a JavaScript source text contains the Compile Hint Annotation and store the information in [[!ECMASCRIPT]] Script Records and Source Text Module Records.

<h3 id="parsescript-and-parsemodule"> ParseScript and ParseModule</h3>

[ParseScript](https://tc39.es/ecma262/#sec-parse-script) is modified as follows:

3. Let *compileHintAnnotation* be **true** if *sourceText* [contains the Compile Hint Annotation](#check-string-contains), **false** otherwise.
4. If *compileHintAnnotation* is **true**, return [Script Record](https://tc39.es/ecma262/#sec-script-records) { existing Script Record fields, \[\[CompileHintAnnotation]]: **"all"** } .
5. Otherwise, return [Script Record](https://tc39.es/ecma262/#sec-script-records) { existing Script Record fields } .

[ParseModule](https://tc39.es/ecma262/#sec-parsemodule) is modified as follows:

11. Let *compileHintAnnotation* be **true** if *sourceText* [contains the Compile Hint Annotation](#check-string-contains), **false** otherwise.
12. If *compileHintAnnotation* is **true**, return [Source Text Module Record](https://tc39.es/ecma262/#sec-source-text-module-records) { existing Source Text Module Record fields, \[\[CompileHintAnnotation]]: **"all"**  }.
13. Otherwise, return [Source Text Module Record](https://tc39.es/ecma262/#sec-source-text-module-records) { existing Source Text Module Record fields }.

<h3 id="check-string-contains">Checking whether a source string contains the Compile Hint Annotation</h3>

To check whether a JavaScript source string *source* contains the Compile Hint Annotation, run the following steps:

1. If [extracting a Compile Hint Annotation](#extract-compile-hint-annotation) from *source* returns the String **"all"**, return **true**.
2. Return **false**.

<h3 id="extract-compile-hint-annotation">Extracting a Compile Hint Annotation from a JavaScript source string</h3>

To extract a Compile Hint Annotation from a JavaScript source string *source*, run the following steps:

1. Let *tokens* be the [List](https://tc39.es/ecma262/#sec-list-and-record-specification-type) of tokens obtained from parsing *source* according to [[!ECMASCRIPT]].
2. For each *token* in *tokens*:
    1. If *token* is not a [single line comment](https://tc39.es/ecma262/#prod-SingleLineComment) or a [multi-line comment](https://tc39.es/ecma262/#prod-MultiLineComment), return.
    2. Let *comment* be the content of *token*.
    3. If [matching a Compile Hint Annotation](#matching-compile-hint-annotation) in *comment* returns a String, return it.
4. Return **null**.

<h3 id="matching-compile-hint-annotation">Matching a Compile Hint Annotation in a String</h3>

To match a Compile Hint Annotation in a String *comment*, run the following steps:
1. Let *pattern* be the regular expression **/^#\s*eagerCompilation=(\S*?)\s*$/**.
2. Let *match* be ! [RegExpBuiltinExec](https://tc39.es/ecma262/#sec-regexpbuiltinexec)(*pattern*, *comment*).
3. Is *match* is not **null**, return *match*.
4. Return **null**.

Using the \[\[CompileHintAnnotation]] internal field {#using}
=============================================================

This non-normative section describes how the user agent may use the Compile Hint Annotation.

If a script or module record contains the \[\[CompileHintAnnotation]] internal field, the user agent may prioritize parsing and compiling the script and the functions within.

<p class="example" id="might-compile-eagerly">The user agent might compile the functions earlier than it otherwise would.</p>

<p class="example" id="might-compile-higher-tier">Example: The user agent might compile the functions in the script with a higher tier compiler than it otherwise would.</p>

<p class="example" id="might-cache-eagerly">Example: The user agent might cache the compilation results more eagerly than it otherwise would.</p>

The user agent may also completely ignore the \[\[CompileHintAnnotation]] internal field.