• This repository has been archived on 01/May/2020
  • Stars
    star
    145
  • Rank 244,999 (Top 5 %)
  • Language
    HTML
  • License
    MIT License
  • Created almost 7 years ago
  • Updated almost 4 years ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

import.meta proposal for JavaScript

import.meta

This repository contains a proposal for adding an import.meta metaproperty to JavaScript, for holding host-specific metadata about the current module. It is currently in stage 4 of the TC39 process.

Previously this problem space was discussed with the module-loading community in whatwg/html#1013. The result was a presentation at the May 2017 TC39 meeting of these slides. The committee's feedback about the options presented there led to the particular form chosen in this proposal; these discussions are summarized in the rest of this README.

You can view the in-progress spec draft and take part in the discussions on the issue tracker.

Motivation and use cases

It is often the case that a host environment can provide useful module-specific information, to code evaluating within a module. Several examples follow:

The module's URL or filename

This is provided in Node.js's CommonJS module system via the in-scope __filename variable (and its counterpart __dirname). This allows easy resolution of resources relative to the module file, via code such as

const fs = require("fs");
const path = require("path");
const bytes = fs.readFileSync(path.resolve(__dirname, "data.bin"));

Without __dirname available, code like fs.readFileSync("data.bin") would resolve data.bin relative to the current working directory. This is generally not useful for library authors, which bundle their resources with their modules which could be located anywhere relative to the CWD.

Very similar use cases exist in browsers, where the URL would stand in place of the filename.

The initiating <script>

This is provided in browsers for classic scripts (i.e. non-module scripts) via the global document.currentScript property. It is often used for configuration of an included library. The page writes code such as:

<script data-option="value" src="library.js"></script>

and the library then looks up the value of data-option via code like

const theOption = document.currentScript.dataset.option;

As an aside, the mechanism of using an (effectively) global variable for this, instead of a lexically-scoped value, is problematic, as it means the value is only set at top-level, and must be saved there if it is to be used in any asynchronous code.

Am I the "main" module?

In Node.js, it is common practice to branch on whether you are the "main" or "entry" module for a program, via code such as:

if (module === process.mainModule) {
  // run tests for this library, or provide a CLI interface, or similar
}

That is, it allows a single file to serve as a library when imported, or as a side-effecting program when run directly.

Note how this particular formulation relies on comparing the host-provided scoped value module with the host-provided global value process.mainModule.

Other miscellaneous use cases

Other cases that can be envisioned include:

  • Other Node.js utilities, such as module.children or require.resolve()
  • Information on the "package" a module belongs to, either via Node.js's package.json or a web package
  • A pointer to the containing DocumentFragment for JavaScript modules embedded inside HTML modules.

Constraints

Given that this information is so often host-specific, we want JavaScript to provide a general extensibility mechanism that hosts can use, instead of requiring standardization in JavaScript for every piece of metadata.

Also, as alluded to above, this is information is best provided lexically, instead of via e.g. a temporarily-set global variable.

Proposed solution

This proposal adds an import.meta meta-property, which is itself an object. It is created by the ECMAScript implementation, with a null prototype. The host environment can return a set of properties (as key/value pairs) that will be added to the object. Finally, as an escape hatch, the object can be modified arbitrarily by the host if necessary.

The import.meta meta-property is only syntactically valid in modules, as it is meant for meta-information about the currently running module, and should not be repurposed for information about the currently-running classic script.

Example

The following code uses a couple properties that we anticipate adding to import.meta in browsers:

(async () => {
  const response = await fetch(new URL("../hamsters.jpg", import.meta.url));
  const blob = await response.blob();

  const size = import.meta.scriptElement.dataset.size || 300;

  const image = new Image();
  image.src = URL.createObjectURL(blob);
  image.width = image.height = size;

  document.body.appendChild(image);
})();

When this module is loaded, no matter its location, it will load a sibling file hamsters.jpg, and display the image. The size of the image can be configured using the script element used to import it, such as with

<script type="module" src="path/to/hamster-displayer.mjs" data-size="500"></script>

Alternative solutions explored

There are a number of other ways of potentially supplying host-specific metadata. The main other avenues explored were:

Using a particular module specifier

The idea here is that we already have a mechanism for obtaining context-specific values from the module system: importing them! In this case the syntax for obtaining these properties would be via top-level importing of some particular module specifier, such as

import { url, scriptElement } from "js:context";

This fits well with the existing framework, and can be taken care of entirely on the host side, requiring no new ECMAScript proposals (since hosts have control over how module specifiers are interpreted). However, on the web, it saw opposition from WebKit, and given TC39 was not unamimously united behind this idea, it was deemed not worthwhile trying to overcome WebKit's objection. Node.js may still implement this, especially if import.meta is not available soon enough for their needs.

Introducing lexical variables in another way

This possibility would introduce the appropriate information as variables somehow injected into the scope of the module, similar to how Node.js currently injects __dirname, __filename, and module. Then they would just be used as normal in-scope variables:

console.log(moduleURL);
console.log(moduleScriptElement);

From an implementation and spec perspective, this could be done with no ECMAScript spec changes by, for example, the host prepending appropriate variable declarations to every module source text before handing it off to the ECMAScript spec mechanisms. Alternately, the host could introduce a new type of module record that has a slightly different scope for its [[Environment]] field. (Or ECMASCript could be modified to allow hosts to intervene in setting up the [[Environment]] of a source text module record.)

The committee was generally against handling this idea in ECMAScript as several members were not a fan of "polluting" module scopes with new variables. It remains a fallback option for web hosts if import.meta fails to advance quickly enough.

FAQs

Will this object be locked down in any way?

The committee's tentative decision was no: by default the import.meta object will be extensible, and its properties will be writable, configurable, and enumerable.

There is no real benefit to locking down the object, as it is local to the module, and can only be shared explicitly by passing it around. It does not represent "global state" or anything of the sort.

Additionally, leaving it mutable allows module-to-module transpilers to "polyfill" future features by inserting a few extra lines at the top of each module, adding or modifying import.meta properties. For example, if in a few years HTML adds an additional property, it would be possible to write a transpiler that adds that property, when targeting older browsers.

Finally, the escape hatch provided by HostFinalizeImportMeta allows hosts which prefer a more locked-down import.meta object to take that route.

More Repositories

1

proposals

Tracking ECMAScript Proposals
17,177
star
2

ecma262

Status, process, and documents for ECMA-262
HTML
14,437
star
3

proposal-pipeline-operator

A proposal for adding a useful pipe operator to JavaScript.
HTML
7,380
star
4

proposal-pattern-matching

Pattern matching syntax for ECMAScript
HTML
5,341
star
5

proposal-optional-chaining

HTML
4,952
star
6

proposal-type-annotations

ECMAScript proposal for type syntax that is erased - Stage 1
JavaScript
4,090
star
7

proposal-temporal

Provides standard objects and functions for working with dates and times.
HTML
3,135
star
8

proposal-observable

Observables for ECMAScript
JavaScript
3,032
star
9

proposal-signals

A proposal to add signals to JavaScript.
TypeScript
2,668
star
10

proposal-decorators

Decorators for ES6 classes
2,640
star
11

proposal-record-tuple

ECMAScript proposal for the Record and Tuple value types. | Stage 2: it will change!
HTML
2,423
star
12

test262

Official ECMAScript Conformance Test Suite
JavaScript
2,073
star
13

proposal-dynamic-import

import() proposal for JavaScript
HTML
1,859
star
14

proposal-bind-operator

This-Binding Syntax for ECMAScript
1,736
star
15

proposal-class-fields

Orthogonally-informed combination of public and private fields proposals
HTML
1,720
star
16

proposal-async-await

Async/await for ECMAScript
HTML
1,577
star
17

proposal-object-rest-spread

Rest/Spread Properties for ECMAScript
HTML
1,496
star
18

proposal-shadowrealm

ECMAScript Proposal, specs, and reference implementation for Realms
HTML
1,365
star
19

proposal-nullish-coalescing

Nullish coalescing proposal x ?? y
HTML
1,233
star
20

proposal-iterator-helpers

Methods for working with iterators in ECMAScript
HTML
1,220
star
21

proposal-top-level-await

top-level `await` proposal for ECMAScript (stage 4)
HTML
1,082
star
22

proposal-partial-application

Proposal to add partial application to ECMAScript
HTML
1,002
star
23

proposal-do-expressions

Proposal for `do` expressions
HTML
990
star
24

agendas

TC39 meeting agendas
JavaScript
952
star
25

proposal-binary-ast

Binary AST proposal for ECMAScript
945
star
26

proposal-built-in-modules

HTML
886
star
27

proposal-async-iteration

Asynchronous iteration for JavaScript
HTML
854
star
28

proposal-explicit-resource-management

ECMAScript Explicit Resource Management
JavaScript
671
star
29

proposal-operator-overloading

JavaScript
610
star
30

proposal-string-dedent

TC39 Proposal to remove common leading indentation from multiline template strings
HTML
588
star
31

proposal-bigint

Arbitrary precision integers in JavaScript
HTML
560
star
32

proposal-set-methods

Proposal for new Set methods in JS
HTML
557
star
33

proposal-import-attributes

Proposal for syntax to import ES modules with assertions
HTML
538
star
34

ecmascript_simd

SIMD numeric type for EcmaScript
JavaScript
536
star
35

proposal-slice-notation

HTML
515
star
36

proposal-change-array-by-copy

Provides additional methods on Array.prototype and TypedArray.prototype to enable changes on the array by returning a new copy of it with the change.
HTML
509
star
37

ecma402

Status, process, and documents for ECMA 402
HTML
506
star
38

notes

TC39 meeting notes
JavaScript
496
star
39

proposal-class-public-fields

Stage 2 proposal for public class fields in ECMAScript
HTML
489
star
40

proposal-iterator.range

A proposal for ECMAScript to add a built-in Iterator.range()
HTML
464
star
41

proposal-uuid

UUID proposal for ECMAScript (Stage 1)
JavaScript
462
star
42

proposal-throw-expressions

Proposal for ECMAScript 'throw' expressions
JavaScript
425
star
43

proposal-module-expressions

HTML
424
star
44

proposal-UnambiguousJavaScriptGrammar

413
star
45

proposal-decimal

Built-in decimal datatype in JavaScript
HTML
408
star
46

proposal-array-grouping

A proposal to make grouping of array items easier
HTML
407
star
47

proposal-async-context

Async Context for JavaScript
HTML
406
star
48

proposal-weakrefs

WeakRefs
HTML
404
star
49

proposal-error-cause

TC39 proposal for accumulating errors
HTML
378
star
50

proposal-ecmascript-sharedmem

Shared memory and atomics for ECMAscript
HTML
376
star
51

proposal-cancelable-promises

Former home of the now-withdrawn cancelable promises proposal for JavaScript
Shell
376
star
52

proposal-relative-indexing-method

A TC39 proposal to add an .at() method to all the basic indexable classes (Array, String, TypedArray)
HTML
351
star
53

proposal-first-class-protocols

a proposal to bring protocol-based interfaces to ECMAScript users
350
star
54

proposal-global

ECMAScript Proposal, specs, and reference implementation for `global`
HTML
346
star
55

proposal-private-methods

Private methods and getter/setters for ES6 classes
HTML
344
star
56

proposal-numeric-separator

A proposal to add numeric literal separators in JavaScript.
HTML
327
star
57

proposal-private-fields

A Private Fields Proposal for ECMAScript
HTML
320
star
58

proposal-object-from-entries

TC39 proposal for Object.fromEntries
HTML
317
star
59

proposal-module-declarations

JavaScript Module Declarations
HTML
314
star
60

proposal-promise-allSettled

ECMAScript Proposal, specs, and reference implementation for Promise.allSettled
HTML
314
star
61

tc39.github.io

Get involved in specifying JavaScript
HTML
313
star
62

proposal-regex-escaping

Proposal for investigating RegExp escaping for the ECMAScript standard
JavaScript
309
star
63

proposal-await.ops

Introduce await.all / await.race / await.allSettled / await.any to simplify the usage of Promises
HTML
308
star
64

proposal-logical-assignment

A proposal to combine Logical Operators and Assignment Expressions
HTML
302
star
65

proposal-export-default-from

Proposal to add `export v from "mod";` to ECMAScript.
HTML
297
star
66

proposal-promise-finally

ECMAScript Proposal, specs, and reference implementation for Promise.prototype.finally
HTML
278
star
67

proposal-asset-references

Proposal to ECMAScript to add first-class location references relative to a module
268
star
68

proposal-cancellation

Proposal for a Cancellation API for ECMAScript
HTML
262
star
69

proposal-json-modules

Proposal to import JSON files as modules
HTML
259
star
70

proposal-promise-with-resolvers

HTML
255
star
71

proposal-string-replaceall

ECMAScript proposal: String.prototype.replaceAll
HTML
254
star
72

proposal-export-ns-from

Proposal to add `export * as ns from "mod";` to ECMAScript.
HTML
241
star
73

proposal-ses

Draft proposal for SES (Secure EcmaScript)
HTML
217
star
74

proposal-structs

JavaScript Structs: Fixed Layout Objects
216
star
75

proposal-intl-relative-time

`Intl.RelativeTimeFormat` specification [draft]
HTML
215
star
76

proposal-flatMap

proposal for flatten and flatMap on arrays
HTML
215
star
77

proposal-json-parse-with-source

Proposal for extending JSON.parse to expose input source text.
HTML
204
star
78

ecmarkup

An HTML superset/Markdown subset source format for ECMAScript and related specifications
TypeScript
201
star
79

proposal-promise-any

ECMAScript proposal: Promise.any
HTML
198
star
80

proposal-decorators-previous

Decorators for ECMAScript
HTML
184
star
81

proposal-smart-pipelines

Old archived draft proposal for smart pipelines. Go to the new Hack-pipes proposal at js-choi/proposal-hack-pipes.
HTML
181
star
82

proposal-defer-import-eval

A proposal for introducing a way to defer evaluate of a module
HTML
174
star
83

proposal-array-filtering

A proposal to make filtering arrays easier
HTML
171
star
84

proposal-optional-chaining-assignment

`a?.b = c` proposal
168
star
85

proposal-array-from-async

Draft specification for a proposed Array.fromAsync method in JavaScript.
HTML
167
star
86

proposal-extractors

Extractors for ECMAScript
JavaScript
166
star
87

proposal-upsert

ECMAScript Proposal, specs, and reference implementation for Map.prototype.upsert
HTML
165
star
88

proposal-ptc-syntax

Discussion and specification for an explicit syntactic opt-in for Tail Calls.
HTML
165
star
89

how-we-work

Documentation of how TC39 operates and how to participate
161
star
90

proposal-collection-methods

HTML
160
star
91

proposal-Array.prototype.includes

Spec, tests, reference implementation, and docs for ESnext-track Array.prototype.includes
HTML
157
star
92

proposal-error-stacks

ECMAScript Proposal, specs, and reference implementation for Error.prototype.stack / System.getStack
HTML
156
star
93

proposal-promise-try

ECMAScript Proposal, specs, and reference implementation for Promise.try
HTML
154
star
94

proposal-hashbang

#! for JS
HTML
148
star
95

proposal-resizablearraybuffer

Proposal for resizable array buffers
HTML
145
star
96

proposal-intl-segmenter

Unicode text segmentation for ECMAScript
HTML
145
star
97

proposal-extensions

Extensions proposal for ECMAScript
HTML
143
star
98

proposal-seeded-random

Proposal for an options argument to be added to JS's Math.random() function, and some options to start it with.
HTML
143
star
99

proposal-intl-duration-format

141
star
100

proposal-regexp-unicode-property-escapes

Proposal to add Unicode property escapes `\p{…}` and `\P{…}` to regular expressions in ECMAScript.
HTML
134
star