Explicit JavaScript Compile Hints (File-based)

1. Introduction

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.

2. Additions to Script Records and Source Text Module Records

The Script Record and Source Text Module Record are augmented to contain the following field:

3. Extracting Compile Hint Annotations from JavaScript source text

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.

3.1. ParseScript and ParseModule

ParseScript is modified as follows:

3. Let compileHintAnnotation be true if sourceText contains the Compile Hint Annotation, false otherwise.

4. If compileHintAnnotation is true, return Script Record { existing Script Record fields, [[CompileHintAnnotation]]: "all" } .

5. Otherwise, return Script Record { existing Script Record fields } .

ParseModule is modified as follows:

11. Let compileHintAnnotation be true if sourceText contains the Compile Hint Annotation, false otherwise.

12. If compileHintAnnotation is true, return Source Text Module Record { existing Source Text Module Record fields, [[CompileHintAnnotation]]: "all" }.

13. Otherwise, return Source Text Module Record { existing Source Text Module Record fields }.

3.2. Checking whether a source string contains the Compile Hint Annotation

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

1. If extracting a Compile Hint Annotation from source returns the String "all", return true.

2. Return false.

3.3. Extracting a Compile Hint Annotation from a JavaScript source string

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

1. Let tokens be the List of tokens obtained from parsing source according to [ECMASCRIPT].

2. For each token in tokens:

   1. If token is not a single line comment or a multi-line comment, return.

   2. Let comment be the content of token.

   3. If matching a Compile Hint Annotation in comment returns a String, return it.

3. Return null.

3.4. Matching a Compile Hint Annotation in a String

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(pattern, comment).

3. Is match is not null, return match.

4. Return null.

4. Using the [[CompileHintAnnotation]] internal field

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.

The user agent might compile the functions earlier than it otherwise would.

Example: The user agent might compile the functions in the script with a higher tier compiler than it otherwise would.

Example: The user agent might cache the compilation results more eagerly than it otherwise would.

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