import defer

Syntax

import defer * as name from "module-name";

name

Name, der auf das verzögerte Modul-Namespace-Objekt verweist. Muss ein gültiger JavaScript-Identifier sein.

module-name

Das Modul, aus dem importiert werden soll. Wird auf dieselbe Weise behandelt wie module-name in regulären import-Deklarationen.

Import-Attribute werden ebenfalls unterstützt, indem nach dem Modulspezifizierer eine with-Klausel verwendet wird.

defer ist kein reserviertes Wort. Beispielsweise ist import defer from "./module.js" weiterhin ein regulärer Standardimport, dessen lokale Bindung defer heißt.

Beschreibung

Standardmäßig führt die import-Deklaration viele Aufgaben gleichzeitig aus: das Auflösen des Modulspezifizierers, das Abrufen des Modulquellcodes, das Parsen (wobei möglicherweise transitive Abhängigkeiten entdeckt werden), das Linken und die Auswertung. Diese Form der eager Auswertung ist nicht immer erwünscht: Sie kann zu einem langsameren Start führen, die Umgebung für ihre Auswertung ist möglicherweise noch nicht vollständig vorbereitet, oder das Modul muss möglicherweise gar nicht ausgewertet werden.

Der Importphasen-Modifizierer ermöglicht es, den Modulimportprozess in einer bestimmten Phase anzuhalten. Durch Hinzufügen von defer nach import wird der Quellcode gelinkt, bleibt jedoch unausgewertet, sofern er synchron ausgewertet werden kann (d.h. kein top-level await verwendet). Der Zugriff auf einen Export über den verzögerten Namespace wertet das Modul und alle Abhängigkeiten, die zuvor ausgewertet werden müssen, synchron aus. Der Zugriff gibt den Wert des Exports zurück, nachdem die Auswertung abgeschlossen ist. Dadurch wird der Top-Level-Code des Moduls ausgeführt, nicht nur der Code, der zum Initialisieren des angeforderten Exports benötigt wird. Transitive Abhängigkeiten, die mit eigenen import defer-Deklarationen importiert wurden, können weiterhin verzögert bleiben.

Indem sichergestellt wird, dass der angehaltene Teilgraph synchron ausgewertet werden kann, kann import defer mit nahezu keinen Codeänderungen an den Stellen verwendet werden, die das Modul nutzen:

// Before:
import * as ts from "typescript";
// The full typescript module graph evaluates here

function compileFile(path) {
  const program = ts.createProgram([path], {});
}

// After:
import defer * as ts from "typescript";
// No code is evaluated; potentially faster startup

function compileFile(path) {
  // The typescript module graph evaluates when `ts.createProgram`
  // is accessed, i.e., when `compileFile` is called.
  // If `compileFile` is never called, then the module graph
  // is never evaluated.
  const program = ts.createProgram([path], {});
}

Anders als import source wird ein verzögertes Modul weiterhin vorab gelinkt. Das vorzeitige Linken ermöglicht dem Modullader, Abhängigkeiten aufzulösen und fehlende Abhängigkeiten oder ungültige Imports zu erkennen, bevor das Modul verwendet wird. Wenn das Modul ungelinkt bleibt, werden Abhängigkeiten, die Sie möglicherweise nicht benötigen, nicht geladen, und Sie können steuern, wie es instanziiert wird.

Anders als import() wird das verzögerte Modul weiterhin vorab abgerufen, geparst und gelinkt, wodurch unnötiges Async Coloring vermieden wird (die gesamte Kette von Funktionsaufrufen wird gezwungen, asynchron zu werden). import defer bietet außerdem die meisten Vorteile einer statischen Deklaration, beispielsweise eine bessere statische Analyse.

Beachten Sie, dass nur die Syntax für Namespace-Imports unterstützt wird. Sie können beispielsweise nicht import defer { property } from "./my-module.js" verwenden, da die Ausführung durch den Eigenschaftszugriff auf das Namespace-Objekt ausgelöst wird.

Caching-Semantik

Der Modifizierer wird auf einen Import angewendet, nicht auf das Modul selbst. Wenn ein anderer Teil der Anwendung dasselbe Modul ohne defer importiert, wird das Modul wie üblich ausgewertet. Beide Formen teilen sich denselben Modulzustand, und der Code des Moduls wird höchstens einmal ausgeführt. Das Ändern der Importphase erzeugt kein separates Modul im Cache:

import defer * as ts from "typescript";
// No code is evaluated
import * as ts2 from "typescript";
// The full typescript module graph evaluates here

function compileFile(path) {
  // Accessing `ts.createProgram` no longer evaluates the subgraph
  // because it's already evaluated.
  const program = ts.createProgram([path], {});
}

Im Gegensatz dazu können Import-Attribute die Modulidentität beeinflussen. Beispielsweise fordern diese beiden Deklarationen in einem Host, der Textmodule unterstützt, unterschiedliche Modultypen an:

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

Die beiden Imports gelten als Imports aus unterschiedlichen Modulen, die zufällig denselben String-Spezifizierer teilen (im Web werden sie mit unterschiedlichen HTTP-Headern angefordert). Die unterstützten Attribute und ihre Auswirkungen auf das Laden und die Modulidentität werden durch den Host definiert.

Verzögertes Modul-Namespace-Objekt

Ein verzögertes Modul-Namespace-Objekt verhält sich weitgehend wie ein reguläres Modul-Namespace-Objekt: Es hat einen null-Prototyp, ist nicht erweiterbar und versiegelt und stellt schreibgeschützte Live-Bindings für die Exports des Moduls bereit. Seine String-Schlüssel sind aufzählbar und lexikografisch sortiert. Der Standardexport ist als Eigenschaft mit dem Namen default verfügbar.

Es gibt drei Unterschiede zu einem regulären Namespace:

• Operationen, die Exports untersuchen, können die Auswertung auslösen und Auswertungsfehler werfen, wie unten beschrieben.
• Seine [Symbol.toStringTag]-Eigenschaft ist "Deferred Module" statt "Module". Dies bleibt auch nach der Auswertung so.
• Er stellt keinen Export mit dem Namen then bereit, auch nicht nach der Auswertung. Das Lesen von namespace.then gibt immer undefined zurück. Dadurch wird verhindert, dass die Promise-Auflösung den Namespace als Thenable behandelt und die Auswertung auslöst. Um auf einen solchen Export zuzugreifen, verwenden Sie einen regulären Import oder führen Sie ein Zwischenmodul ein, das then unter einem anderen Namen reexportiert.

Die verzögerten und regulären Namespaces für dasselbe Modul sind unterschiedliche Objekte, auch nach der Auswertung. Wiederholte verzögerte Imports desselben Moduls, ob statisch oder dynamisch, teilen dasselbe verzögerte Namespace-Objekt.

Um das Verhalten „Auslösen der Modulauswertung beim Zugriff auf Schlüssel“ zu implementieren, ist der verzögerte Modul-Namespace im Wesentlichen ein Proxy, der die folgenden Aktionen abfängt, um die Modulauswertung auszulösen:

• defineProperty() für jeden String-Schlüssel außer then: beispielsweise Object.defineProperty(namespace, "value", {}).

  Hinweis: Da das Modul-Namespace-Objekt nicht erweiterbar und versiegelt ist, können Sie keine Eigenschaftsbeschreibung, einschließlich ihres Werts, sinnvoll hinzufügen oder ändern. Dennoch wird die Auswertung ausgelöst, selbst wenn die Operation fehlschlägt.

  Der Proxy fängt set() nicht ab. Das Setzen von Eigenschaften wie namespace.value = 1; schlägt immer fehl.

• deleteProperty() für jeden String-Schlüssel außer then: beispielsweise delete namespace.value.

  Hinweis: Sie können keine Eigenschaft, die der Namespace besitzt, tatsächlich löschen. Dennoch wird die Auswertung ausgelöst, selbst wenn die Operation fehlschlägt.

• get() und getOwnPropertyDescriptor() für jeden String-Schlüssel außer then: beispielsweise namespace.value, namespace["missing"], const { default: value } = namespace, Object.getOwnPropertyDescriptor(namespace, "value").

  Hinweis: Das Destrukturieren eines Exports auf oberster Ebene hebt daher die Verzögerung dieses Moduls auf.

• has() für jeden String-Schlüssel außer then: beispielsweise "value" in namespace, Object.hasOwn(namespace, "missing").

• ownKeys(): beispielsweise Object.keys(namespace), Object.getOwnPropertySymbols(namespace), for (const key in namespace) {}. Selbst das Aufzählen ausschließlich von Symbol-Schlüsseln löst die Auswertung aus.

Das bloße Referenzieren des Namespace, Zuweisen an eine andere Variable, Vergleichen seiner Identität oder Übergeben an eine Funktion löst keine Auswertung aus. Ebenso wenig das Lesen von then oder einer Eigenschaft mit Symbol-Schlüssel wie namespace[Symbol.toStringTag]. Der Aufruf von Object.getPrototypeOf() oder Object.isExtensible() löst ebenfalls keine Auswertung aus. Object.isSealed() und Object.isFrozen() zählen jedoch Schlüssel auf und lösen daher die Auswertung aus.

Top-level await

Das Lesen einer Namespace-Eigenschaft erfolgt synchron und kann daher nicht auf eine asynchrone Modulauswertung warten. Module, die top-level await enthalten, werden zusammen mit den Abhängigkeiten, die zu ihrer Auswertung erforderlich sind, eager ausgewertet. Dies schließt Module ein, die über weitere verzögerte Imports erreicht werden. Das importierende Modul wartet auf diese asynchrone Auswertung, bevor sein eigener Body ausgeführt wird.

Wenn das direkt importierte Modul top-level await enthält, wird seine Auswertung nicht verzögert. Wenn nur einige seiner Abhängigkeiten top-level await enthalten, werden diese Abhängigkeiten eager ausgewertet, aber die synchronen Teile des Graphen, die für ihre Auswertung nicht erforderlich sind, können verzögert bleiben. Siehe Verzögern eines Moduls mit einer asynchronen Abhängigkeit.

Fehler

Fehler beim Laden, Parsen und Linken werden nicht verzögert. Beispielsweise verhindert ein fehlendes Modul, ein Syntaxfehler in einer Abhängigkeit oder ein nicht aufgelöster benannter Import die Ausführung des importierenden Moduls, auch wenn nie auf den verzögerten Namespace zugegriffen wird. Fehler aus eager ausgewerteten asynchronen Abhängigkeiten verhindern ebenfalls die Ausführung des importierenden Moduls.

Während der verzögerten Auswertung geworfene Fehler werden von der Operation, die die Auswertung auslöst, synchron geworfen. Sie können sie mit try...catch um diese Operation herum abfangen. Der Fehler wird zwischengespeichert: Nachfolgende Operationen, die die Auswertung auslösen, werfen denselben Fehler, anstatt den Code des Moduls erneut auszuführen. Dies gilt auch, wenn ein anderer Import zuvor dazu geführt hat, dass die Auswertung des Moduls fehlgeschlagen ist.

Eine Operation, die die Auswertung auslöst, wirft einen TypeError, wenn das Modul oder seine Abhängigkeiten nicht für eine synchrone Auswertung bereit sind. Dies kann bei zyklischen Imports passieren, wenn ein Zugriff ein Modul erfordern würde, das noch ausgewertet wird. Eine import defer-Deklaration macht nicht jede zyklische Abhängigkeit während der Initialisierung sicher zugreifbar. Ein Bereitschaftsfehler selbst markiert das angeforderte Modul nicht als fehlgeschlagen ausgewertet: Ein späterer Zugriff kann erfolgreich sein, sobald seine Abhängigkeiten bereit sind.

Beispiele

Auswertung eines Moduls bei der ersten Verwendung

Das folgende Modul initialisiert eine Lookup-Tabelle, wenn sein Top-Level-Code ausgeführt wird:

// -- squares.js --
console.log("Initializing squares");
const squares = Array.from({ length: 10000 }, (_, index) => index ** 2);

export function getSquare(index) {
  return squares[index];
}

Das importierende Modul kann eine synchrone Funktion bereitstellen, ohne die Tabelle zu initialisieren, bis sie benötigt wird:

// -- main.js --
import defer * as squares from "./squares.js";

console.log("Ready");

export function showSquare(index) {
  console.log(squares.getSquare(index));
}

showSquare(3); // Logs "Initializing squares", then 9
showSquare(4); // Logs 16; initialization is not repeated

"Ready" wird vor "Initializing squares" protokolliert. Wenn showSquare() nie aufgerufen wird und kein anderer Import dazu führt, dass squares.js ausgewertet wird, wird die Lookup-Tabelle nie initialisiert.

Verzögern eines Moduls mit einer asynchronen Abhängigkeit

In diesem Beispiel hängt report.js (das selbst synchron ist) sowohl von einem asynchronen Konfigurationsmodul als auch von einem synchronen Formatierungsmodul ab.

// -- config.js --
export const locale = await Promise.resolve("en-US");
console.log("Configuration ready");

// -- format.js --
console.log("Formatting module evaluated");

export function format(value, locale) {
  return new Intl.NumberFormat(locale).format(value);
}

// -- report.js --
import { locale } from "./config.js";
import { format } from "./format.js";

console.log("Report module evaluated");

export function createReport(value) {
  return format(value, locale);
}

// -- main.js --
import defer * as report from "./report.js";

console.log("Main module evaluated");
console.log(report.createReport(1000));

Die Ausgabe lautet:

Configuration ready
Main module evaluated
Formatting module evaluated
Report module evaluated
1,000

config.js wird vor main.js ausgewertet, weil es top-level await enthält. Weder format.js noch report.js müssen ausgeführt werden, um config.js auszuwerten, daher wird ihre Auswertung verzögert, bis auf report.createReport zugegriffen wird.

Abfangen von Auswertungsfehlern

// -- broken.js --
export const value = 1;
throw new Error("Initialization failed");

// -- main.js --
import defer * as broken from "./broken.js";

for (let attempt = 0; attempt < 2; attempt++) {
  try {
    console.log(broken.value);
  } catch (error) {
    console.log(error.message); // "Initialization failed" on both attempts
  }
}

Auch wenn value initialisiert wurde, bevor die Ausnahme geworfen wurde, führt der Zugriff darauf über den verzögerten Namespace zum Werfen des zwischengespeicherten Auswertungsfehlers.

Exportieren eines verzögerten Namespace

Es gibt keine export defer-Syntax (weitere Informationen finden Sie unter export). Sie können einen verzögerten Namespace importieren und anschließend seine Bindung exportieren, ohne die Auswertung auszulösen:

// -- features.js --
import defer * as report from "./report.js";

export { report };

// -- main.js --
import { report } from "./features.js";

// Accessing an export through report triggers its deferred evaluation.
console.log(report.createReport(1000));

Spezifikationen

Browser-Kompatibilität

Siehe auch

• JavaScript-Module-Leitfaden
• import
• import.defer()