proposal-import-meta

by tc39

import.meta proposal for JavaScript

130 Stars 13 Forks Last release: Not found MIT License 21 Commits 0 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

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

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:

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

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.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.