Stage 3 Draft / November 6, 2017

import.meta

Introduction

Background explanatory material for this specification can be found in the tc39/proposal-import-meta repository. See also the issues list and the HTML integration spec that builds on top of the below JavaScript specification.

1Modules

1.1Module Semantics

1.1.1Abstract Module Records

Table 1: Module Record Fields
Field Name Value Type Meaning
[[Realm]] Realm Record | undefined The Realm within which this module was created. undefined if not yet assigned.
[[Environment]] Lexical Environment | undefined The Lexical Environment containing the top level bindings for this module. This field is set when the module is instantiated.
[[Namespace]] Object | undefined The Module Namespace Object (26.3) if one has been created for this module. Otherwise undefined.
[[Status]] String Initially "uninstantiated". Can become "instantiating", "instantiated", "evaluating", "evaluated", or "errored" as the module progresses throughout its lifecycle.
[[ErrorCompletion]] An abrupt completion | undefined A completion of type throw representing the exception that occurred during instantiation or evaluation, if [[Status]] is "errored". Otherwise undefined.
[[Meta]] Object | undefined An object exposed through the import.meta meta property. It is undefined by default, but will become an Object before it is ever accessed by ECMAScript code.
[[HostDefined]] Any, default value is undefined. Field reserved for use by host environments that need to associate additional information with a module.

1.2Left-Hand-Side Expressions

Syntax

MemberExpression[Yield, Await]:PrimaryExpression[?Yield, ?Await] MemberExpression[?Yield, ?Await][Expression[+In, ?Yield, ?Await]] MemberExpression[?Yield, ?Await].IdentifierName MemberExpression[?Yield, ?Await]TemplateLiteral[?Yield, ?Await] SuperProperty[?Yield, ?Await] MetaProperty newMemberExpression[?Yield, ?Await]Arguments[?Yield, ?Await] SuperProperty[Yield, Await]:super[Expression[+In, ?Yield, ?Await]] super.IdentifierName MetaProperty:NewTarget ImportMeta NewTarget:new.target ImportMeta:import.meta NewExpression[Yield, Await]:MemberExpression[?Yield, ?Await] newNewExpression[?Yield, ?Await] CallExpression[Yield, Await]:CoverCallExpressionAndAsyncArrowHead[?Yield, ?Await] SuperCall[?Yield, ?Await] CallExpression[?Yield, ?Await]Arguments[?Yield, ?Await] CallExpression[?Yield, ?Await][Expression[+In, ?Yield, ?Await]] CallExpression[?Yield, ?Await].IdentifierName CallExpression[?Yield, ?Await]TemplateLiteral[?Yield, ?Await] SuperCall[Yield, Await]:superArguments[?Yield, ?Await] Arguments[Yield, Await]:() (ArgumentList[?Yield, ?Await]) (ArgumentList[?Yield, ?Await],) ArgumentList[Yield, Await]:AssignmentExpression[+In, ?Yield, ?Await] ...AssignmentExpression[+In, ?Yield, ?Await] ArgumentList[?Yield, ?Await],AssignmentExpression[+In, ?Yield, ?Await] ArgumentList[?Yield, ?Await],...AssignmentExpression[+In, ?Yield, ?Await] LeftHandSideExpression[Yield, Await]:NewExpression[?Yield, ?Await] CallExpression[?Yield, ?Await]

1.2.1Static Semantics

1.2.1.1Static Semantics: Early Errors

ImportMeta:import.meta

1.2.1.2Static Semantics: IsValidSimpleAssignmentTarget

CallExpression:CallExpression[Expression] CallExpression.IdentifierName MemberExpression:MemberExpression[Expression] MemberExpression.IdentifierName SuperProperty
  1. Return true.
CallExpression:CoverCallExpressionAndAsyncArrowHead SuperCall CallExpressionArguments CallExpressionTemplateLiteral NewExpression:newNewExpression MemberExpression:MemberExpressionTemplateLiteral newMemberExpressionArguments NewTarget:new.target ImportMeta:import.meta
  1. Return false.

1.2.2Meta Properties

1.2.2.1Runtime Semantics: Evaluation

NewTarget:new.target
  1. Return GetNewTarget().
ImportMeta:import.meta
  1. Let module be GetActiveScriptOrModule().
  2. Assert: module is a Module Record (not a Script Record).
  3. Let importMeta be module.[[ImportMeta]].
  4. If importMeta is undefined.
    1. Set importMeta to ObjectCreate(null).
    2. Let importMetaValues be ! HostGetImportMetaProperties(module).
    3. For each Record {[[Key]], [[Value]]} p that is an element of importMetaValues,
    4. Perform ! CreateDataProperty(importMeta, p.[[Key]], p.[[Value]]).
    5. Perform ! HostFinalizeImportMeta(importMeta, module).
    6. Set module.[[ImportMeta]] to importMeta.
    7. Return importMeta.
  5. Else,
    1. Assert: Type(importMeta) is Object.
    2. Return importMeta.

1.2.2.2Runtime Semantics: HostGetImportMetaProperties ( moduleRecord )

HostGetImportMetaProperties is an implementation-defined abstract operation that allows hosts to provide property keys and values for the object returned from import.meta.

The implementation of HostGetImportMetaProperties must conform to the following requirements:

  • It must return a List, whose values are all Records with the two fields [[Key]] and [[Value]].
  • Each such Record's [[Key]] field must be a property key, i.e., IsPropertyKey must return true when applied to it.
  • Each such Record's [[Value]] field must be an ECMAScript value.
  • It must always complete normally (i.e., not return an abrupt completion).

The default implementation of HostGetImportMetaProperties is to return a new empty List.

1.2.2.3Runtime Semantics: HostFinalizeImportMeta ( importMeta, moduleRecord )

HostFinalizeImportMeta is an implementation-defined abstract operation that allows hosts to perform any extraordinary operations to prepare the object returned from import.meta.

Most hosts will be able to simply define HostGetImportMetaProperties, and leave HostFinalizeImportMeta with its default behavior. However, HostFinalizeImportMeta provides an "escape hatch" for hosts which need to directly manipulate the object before it is exposed to ECMAScript code.

The implementation of HostFinalizeImportMeta must conform to the following requirements:

The default implementation of HostFinalizeImportMeta is to do nothing.