import source

Syntax

import source x from "module-name";

x

Name, der sich auf das Modulquellobjekt bezieht. Muss ein gltiger JavaScript-Identifier sein.

module-name

Das Modul, aus dem importiert werden soll. Wird genauso behandelt wie der module-name in regulren import-Deklarationen.

Importattribute werden ebenfalls untersttzt, indem nach dem Modulspezifizierer eine with-Klausel verwendet wird.

source ist kein reserviertes Wort. Beispielsweise ist import source from "./module.js" weiterhin ein regulrer Standardimport, dessen lokale Bindung source heit.

Ausnahmen

SyntaxError

Wird ausgelst, wenn das Zielmodul keine Quellphasenimporte untersttzt.

Beschreibung

Standardmig fhrt die import-Deklaration viele Aufgaben gleichzeitig aus: das Auflsen des Modulspezifizierers, das Abrufen des Modulquellcodes, das Parsen (wobei mglicherweise transitive Abhngigkeiten entdeckt werden), das Verknpfen und das Auswerten. Diese Form der sofortigen Auswertung ist nicht immer wnschenswert, insbesondere wenn der Modulquellcode in einem anderen Kontext ausgewertet werden soll, beispielsweise in einem Worker-Thread.

Der Importphasenmodifikator ermglicht es, den Modulimportprozess in einer bestimmten Phase anzuhalten. Durch das Hinzufgen von source nach import wird der Quellcode geparst und kompiliert, bleibt jedoch unverknpft und nicht ausgewertet. Der Quellimport ldt die transitiven Abhngigkeiten des Moduls nicht.

Traditionell bestand die einzige Mglichkeit, einen Teil der Pipeline auszufhren, darin, sie vollstndig manuell zu implementieren. Bei WebAssembly verwenden Sie beispielsweise zunchst fetch(), um die binren Bytes des Moduls abzurufen, und kompilieren diese spter mit WebAssembly.compile() oder kompilieren den Antwortstream mit WebAssembly.compileStreaming() zu einem WebAssembly.Module-Objekt.

const myModuleSource = await WebAssembly.compileStreaming(
  fetch("./my-module.wasm"),
);

Diese Art manueller Arbeitsablauf ist aus mehreren Grnden problematisch:

• Sie erfordert zu viele Manipulationen auf niedriger Ebene, die mglicherweise nicht mit dem Verhalten des Standardmodulladers bereinstimmen, etwa beim Caching, bei HTTP-Header-Einstellungen und bei der Auflsung von Modulspezifizierern.
• Sie ist imperativ, wodurch es schwierig wird, die Abhngigkeiten des Moduls und ihre Auswertungsreihenfolge nachzuvollziehen, insbesondere fr Bundler oder andere Analysewerkzeuge.
• Die Auswertung des rohen Quellcodes im Userland ist mit strikten CSP-Einstellungen nicht kompatibel.

Die Verwendung von Quellphasenimporten vermeidet diese Probleme.

import source myModuleSource from "./my-module.wasm";

Das aus diesem Import erhaltene Objekt ist eine Instanz einer Unterklasse von AbstractModuleSource. Jeder Modultyp, der Quellphasenimporte untersttzt, definiert seine eigene Unterklasse. Fr WebAssembly ist die Unterklasse WebAssembly.Module. Dieses Objekt wird fr das jeweilige Modul zwischengespeichert, sodass sptere Quellimporte desselben Spezifizierers exakt dasselbe Objekt zurckgeben.

Anders als bei import defer wird bei einem Quellimport auch das Verknpfen aufgeschoben. Ein vorheriges Verknpfen ermglicht dem Modullader, Abhngigkeiten aufzulsen und fehlende Abhngigkeiten oder ungltige Importe zu erkennen, bevor das Modul verwendet wird. Das Modul unverknpft zu lassen, vermeidet das Laden von Abhngigkeiten, die Sie mglicherweise nicht bentigen, und ermglicht es Ihnen, seine Instanziierung zu steuern. Beispielsweise knnen Sie ein per Quellimport importiertes WebAssembly-Modul mehrfach mit unterschiedlichen Importen instanziieren oder es zur dortigen Instanziierung an einen Worker senden.

Anders als bei import() wird das per Quellimport importierte Modul im Voraus abgerufen und kompiliert, ohne ausgewertet zu werden. import source bietet auerdem die meisten Vorteile einer statischen Deklaration, etwa eine bessere statische Analyse.

Beachten Sie, dass nur die Syntax fr den Standardimport untersttzt wird. Sie knnen beispielsweise nicht import source { property } from "./my-module.wasm" verwenden.

Importieren von WebAssembly-Quellcode

Fr WebAssembly stellen Sie die importierten Werte bei der Instanziierung des Moduls bereit:

import source myModuleSource from "./my-module.wasm";

const instance = await WebAssembly.instantiate(myModuleSource, {
  env: { log: console.log },
});
const { exports } = instance;

Anders als bei einem gewhnlichen WebAssembly-Modulimport wird dadurch eine neue Instanz mit den von Ihnen bereitgestellten Importen erstellt, statt die vom Modullader verknpfte zwischengespeicherte Instanz zu verwenden. Ihr exports-Objekt ist kein JavaScript-Modul-Namespace-Objekt. Beispielsweise werden WebAssembly-Globals ber instance.exports als WebAssembly.Global-Objekte verfgbar gemacht, whrend die ESM-Integration ihre Werte fr JavaScript-Importierende verfgbar macht.

Quellimporte verwenden den Modullader des Hosts, einschlielich seiner Kompilierungseinstellungen. Sie entsprechen nicht unbedingt einem Aufruf von WebAssembly.compileStreaming() mit Standardoptionen. Beispielsweise aktiviert Node.js JavaScript-String-Built-ins fr Wasm-Importe und lehnt reservierte Import- und Exportnamen ab. Verwenden Sie die direkten WebAssembly-Kompilierungs-APIs, wenn Sie benutzerdefinierte Kompilierungsoptionen bentigen.

Importieren von JavaScript-Quellcode

Fr JavaScript (unter der Annahme der vorgeschlagenen Untersttzung fr import(moduleSource), ebenfalls in ECMAScript Module Phase Imports):

import * as namespace from "./my-module.js";

// Is equivalent to:

import source myModuleSource from "./my-module.js";

const namespace = await import(myModuleSource);

Caching-Semantik

Der Modifikator gilt fr einen Import, nicht fr das Modul selbst. Wenn ein anderer Teil der Anwendung dasselbe Modul ohne source importiert, wird das Modul wie gewohnt ausgewertet. Beide Formen teilen denselben Modulzustand, und der Code des Moduls wird hchstens einmal ausgefhrt. Das ndern der Importphase erstellt kein separates Modul im Cache:

import * as x from "foo";
import source xSource from "foo";

console.log((await import(xSource)) === x); // true

Im Gegensatz dazu knnen Importattribute die Modulidentitt beeinflussen. Beispielsweise fordern diese beiden Deklarationen auf einem Host, der Textmodule untersttzt, unterschiedliche Modultypen an:

import * as mod from "./module.js";
import text from "./module.js" with { type: "text" };

Die beiden Importe gelten als Importe aus unterschiedlichen Modulen, die zufllig denselben String-Spezifizierer teilen (im Web werden sie mit unterschiedlichen HTTP-Headern angefordert). Die untersttzten Attribute und ihre Auswirkungen auf das Laden und die Modulidentitt werden vom Host definiert.

Beispiele

Instanziieren eines Moduls mit unterschiedlichen Importen

Angenommen, counter.wasm importiert aus env ein unvernderliches i32-Global namens initial, initialisiert daraus einen internen Zhler und exportiert eine Funktion namens increment. Sie knnen den kompilierten Quellcode mit unterschiedlichen Importen und unabhngigen internen Zhlern wiederverwenden:

import source counterSource from "./counter.wasm";

const first = await WebAssembly.instantiate(counterSource, {
  env: { initial: 0 },
});
const second = await WebAssembly.instantiate(counterSource, {
  env: { initial: 100 },
});

console.log(first.exports.increment()); // 1
console.log(first.exports.increment()); // 2
console.log(second.exports.increment()); // 101

Jede Instanz hat ihren eigenen internen Zustand, obwohl explizit importierte Speicher, Tabellen oder andere vernderliche Objekte zwischen Instanzen geteilt werden knnen. Sie knnen den kompilierten Quellcode auch an einen Worker senden, um ihn dort zu instanziieren.

Exportieren eines Modulquellcodes

Es gibt keine Syntax export source (weitere Informationen finden Sie unter export). Sie knnen einen Modulquellcode importieren und anschlieend seine Bindung exportieren, ohne das Modul zu instanziieren oder auszuwerten:

// -- sources.js --
import source counterSource from "./counter.wasm";

export { counterSource };

// -- main.js --
import { counterSource } from "./sources.js";

const instance = new WebAssembly.Instance(counterSource, {
  env: { initial: 0 },
});

Spezifikationen

Browser-Kompatibilitt

Siehe auch

• Leitfaden zu JavaScript-Modulen
• import
• import.source()
• AbstractModuleSource