webpack 5.106.1 → 5.107.0

package/lib/ExternalModule.js

@@ -8,7 +8,6 @@
 const { SyncBailHook } = require("tapable");
 const { OriginalSource, RawSource } = require("webpack-sources");
 const ConcatenationScope = require("./ConcatenationScope");
-const EnvironmentNotSupportAsyncWarning = require("./EnvironmentNotSupportAsyncWarning");
 const { UsageState } = require("./ExportsInfo");
 const InitFragment = require("./InitFragment");
 const Module = require("./Module");
@@ -22,7 +21,9 @@ const { JAVASCRIPT_MODULE_TYPE_DYNAMIC } = require("./ModuleTypeConstants");
 const RuntimeGlobals = require("./RuntimeGlobals");
 const Template = require("./Template");
 const { DEFAULTS } = require("./config/defaults");
+const { ImportPhaseUtils } = require("./dependencies/ImportPhase");
 const StaticExportsDependency = require("./dependencies/StaticExportsDependency");
+const EnvironmentNotSupportAsyncWarning = require("./errors/EnvironmentNotSupportAsyncWarning");
 const createHash = require("./util/createHash");
 const extractUrlAndGlobal = require("./util/extractUrlAndGlobal");
 const makeSerializable = require("./util/makeSerializable");
@@ -62,19 +63,21 @@ const { register } = require("./util/serialization");
 /** @typedef {import("./RuntimeTemplate")} RuntimeTemplate */
 /** @typedef {import("./javascript/JavascriptModulesPlugin").ChunkRenderContext} ChunkRenderContext */
 /** @typedef {import("./javascript/JavascriptParser").ImportAttributes} ImportAttributes */
+/** @typedef {import("./dependencies/ImportPhase").ImportPhaseType} ImportPhaseType */
 /** @typedef {import("./serialization/ObjectMiddleware").ObjectDeserializerContext} ObjectDeserializerContext */
 /** @typedef {import("./serialization/ObjectMiddleware").ObjectSerializerContext} ObjectSerializerContext */
 /** @typedef {import("./util/Hash")} Hash */
 /** @typedef {import("./util/fs").InputFileSystem} InputFileSystem */
 /** @typedef {import("./util/runtime").RuntimeSpec} RuntimeSpec */
 
-/** @typedef {{ attributes?: ImportAttributes, externalType: "import" | "module" | undefined }} ImportDependencyMeta */
+/** @typedef {{ attributes?: ImportAttributes, phase?: ImportPhaseType, externalType: "import" | "module" | undefined }} ImportDependencyMeta */
 /** @typedef {{ layer?: string, supports?: string, media?: string }} CssImportDependencyMeta */
 /** @typedef {{ sourceType: "css-url" }} AssetDependencyMeta */
 
 /** @typedef {ImportDependencyMeta | CssImportDependencyMeta | AssetDependencyMeta} DependencyMeta */
 
 /**
+ * Defines the source data type used by this module.
  * @typedef {object} SourceData
  * @property {boolean=} iife
  * @property {string=} init
@@ -98,6 +101,7 @@ const RUNTIME_REQUIREMENTS_FOR_MODULE = new Set([
 const EMPTY_RUNTIME_REQUIREMENTS = new Set();
 
 /**
+ * Gets source for global variable external.
  * @param {string | string[]} variableName the variable name or path
  * @param {string} type the module system
  * @returns {SourceData} the generated source
@@ -121,6 +125,7 @@ const getSourceForGlobalVariableExternal = (variableName, type) => {
 /** @typedef {string | string[]} ModuleAndSpecifiers */
 
 /**
+ * Gets source for common js external.
  * @param {ModuleAndSpecifiers} moduleAndSpecifiers the module request
  * @returns {SourceData} the generated source
  */
@@ -140,6 +145,7 @@ const getSourceForCommonJsExternal = (moduleAndSpecifiers) => {
 };
 
 /**
+ * Gets external module node commonjs init fragment.
  * @param {RuntimeTemplate} runtimeTemplate the runtime template
  * @returns {InitFragment<ChunkRenderContext>} code
  */
@@ -157,6 +163,7 @@ const getExternalModuleNodeCommonjsInitFragment = (runtimeTemplate) => {
 };
 
 /**
+ * Gets source for common js external in node module.
  * @param {ModuleAndSpecifiers} moduleAndSpecifiers the module request
  * @param {RuntimeTemplate} runtimeTemplate the runtime template
  * @returns {SourceData} the generated source
@@ -186,6 +193,7 @@ const getSourceForCommonJsExternalInNodeModule = (
 };
 
 /**
+ * Gets source for import external.
  * @param {ModuleAndSpecifiers} moduleAndSpecifiers the module request
  * @param {RuntimeTemplate} runtimeTemplate the runtime template
  * @param {ImportDependencyMeta=} dependencyMeta the dependency meta
@@ -196,15 +204,25 @@ const getSourceForImportExternal = (
 	runtimeTemplate,
 	dependencyMeta
 ) => {
-	const importName = runtimeTemplate.outputOptions.importFunctionName;
+	const baseImportName = runtimeTemplate.outputOptions.importFunctionName;
 	if (
 		!runtimeTemplate.supportsDynamicImport() &&
-		(importName === "import" || importName === "module-import")
+		(baseImportName === "import" || baseImportName === "module-import")
 	) {
 		throw new Error(
 			"The target environment doesn't support 'import()' so it's not possible to use external type 'import'"
 		);
 	}
+	const phase = dependencyMeta && dependencyMeta.phase;
+	// `import.defer(…)` and `import.source(…)` are only valid forms of the
+	// native `import(…)` function, so we only emit the phase suffix when the
+	// importFunctionName is the default `"import"`.
+	const importName =
+		baseImportName === "import" && ImportPhaseUtils.isDefer(phase)
+			? "import.defer"
+			: baseImportName === "import" && ImportPhaseUtils.isSource(phase)
+				? "import.source"
+				: baseImportName;
 	const attributes =
 		dependencyMeta && dependencyMeta.attributes
 			? dependencyMeta.attributes._isLegacyAssert
@@ -240,6 +258,7 @@ const getSourceForImportExternal = (
 };
 
 /**
+ * Import assertion replacer.
  * @param {string} key key
  * @param {ImportAttributes | string | boolean | undefined} value value
  * @returns {ImportAttributes | string | boolean | undefined} replaced value
@@ -253,10 +272,12 @@ const importAssertionReplacer = (key, value) => {
 };
 
 /**
+ * Represents ModuleExternalInitFragment.
  * @extends {InitFragment<GenerateContext>}
  */
 class ModuleExternalInitFragment extends InitFragment {
 	/**
+	 * Creates an instance of ModuleExternalInitFragment.
 	 * @param {string} request import source
 	 * @param {Imported} imported the imported specifiers
 	 * @param {string=} ident recomputed ident
@@ -284,7 +305,9 @@ class ModuleExternalInitFragment extends InitFragment {
 			"",
 			InitFragment.STAGE_HARMONY_IMPORTS,
 			0,
-			`external module import ${ident} ${imported === true ? imported : imported.join(" ")}`
+			`external module import ${ident} ${
+				imported === true ? imported : imported.join(" ")
+			}`
 		);
 		this._ident = ident;
 		this._request = request;
@@ -294,6 +317,7 @@ class ModuleExternalInitFragment extends InitFragment {
 	}
 
 	/**
+	 * Returns imported.
 	 * @returns {Imported} imported
 	 */
 	getImported() {
@@ -301,6 +325,7 @@ class ModuleExternalInitFragment extends InitFragment {
 	}
 
 	/**
+	 * Updates imported using the provided imported.
 	 * @param {Imported} imported imported
 	 */
 	setImported(imported) {
@@ -308,6 +333,7 @@ class ModuleExternalInitFragment extends InitFragment {
 	}
 
 	/**
+	 * Returns the source code that will be included as initialization code.
 	 * @param {GenerateContext} context context
 	 * @returns {string | Source | undefined} the source code that will be included as initialization code
 	 */
@@ -320,23 +346,34 @@ class ModuleExternalInitFragment extends InitFragment {
 		} = this;
 		const attributes =
 			dependencyMeta && dependencyMeta.attributes
-				? dependencyMeta.attributes._isLegacyAssert &&
-					dependencyMeta.attributes._isLegacyAssert
+				? dependencyMeta.attributes._isLegacyAssert
 					? ` assert ${JSON.stringify(
 							dependencyMeta.attributes,
 							importAssertionReplacer
 						)}`
 					: ` with ${JSON.stringify(dependencyMeta.attributes)}`
 				: "";
+		const phase = dependencyMeta && dependencyMeta.phase;
 		let content = "";
 		if (imported === true) {
 			// namespace
-			content = `import * as ${identifier} from ${JSON.stringify(request)}${
-				attributes
-			};\n`;
+			const phaseKeyword = ImportPhaseUtils.isDefer(phase) ? "defer " : "";
+			content = `import ${phaseKeyword}* as ${identifier} from ${JSON.stringify(
+				request
+			)}${attributes};\n`;
 		} else if (imported.length === 0) {
 			// just import, no use
 			content = `import ${JSON.stringify(request)}${attributes};\n`;
+		} else if (
+			ImportPhaseUtils.isSource(phase) &&
+			imported.length === 1 &&
+			imported[0][0] === "default"
+		) {
+			// `import source x from "…"` — the source-phase form binds the source
+			// object directly to a single identifier (no namespace, no destructuring).
+			content = `import source ${imported[0][1]} from ${JSON.stringify(
+				request
+			)}${attributes};\n`;
 		} else {
 			content = `import { ${imported
 				.map(([name, finalName]) => {
@@ -355,6 +392,7 @@ class ModuleExternalInitFragment extends InitFragment {
 	}
 
 	/**
+	 * Returns identifier.
 	 * @param {string} ident ident
 	 * @returns {string} identifier
 	 */
@@ -363,6 +401,7 @@ class ModuleExternalInitFragment extends InitFragment {
 	}
 
 	/**
+	 * Returns normalized imported.
 	 * @param {Imported} imported imported
 	 * @returns {Imported} normalized imported
 	 */
@@ -395,6 +434,7 @@ register(
 );
 
 /**
+ * Generates module remapping.
  * @param {string} input input
  * @param {ExportsInfo} exportsInfo the exports info
  * @param {RuntimeSpec=} runtime the runtime
@@ -437,6 +477,7 @@ const generateModuleRemapping = (
 };
 
 /**
+ * Gets source for module external.
  * @param {ModuleAndSpecifiers} moduleAndSpecifiers the module request
  * @param {ExportsInfo} exportsInfo exports info of this module
  * @param {RuntimeSpec} runtime the runtime
@@ -453,6 +494,7 @@ const getSourceForModuleExternal = (
 	dependencyMeta,
 	concatenationScope
 ) => {
+	const phase = dependencyMeta && dependencyMeta.phase;
 	/** @type {Imported} */
 	let imported = true;
 	if (concatenationScope) {
@@ -481,6 +523,14 @@ const getSourceForModuleExternal = (
 		imported = true;
 	}
 
+	// `import defer …` is only valid as `import defer * as ns from "…"`, so
+	// keep the namespace form even if usage analysis would otherwise narrow
+	// the import down to specific names. Defer + concatenation is semantically
+	// at odds (lazy vs. eager), so we preserve the user-written shape here.
+	if (ImportPhaseUtils.isDefer(phase)) {
+		imported = true;
+	}
+
 	const initFragment = new ModuleExternalInitFragment(
 		moduleAndSpecifiers[0],
 		imported,
@@ -530,6 +580,7 @@ const getSourceForModuleExternal = (
 };
 
 /**
+ * Gets source for script external.
  * @param {string | string[]} urlAndGlobal the script request
  * @param {RuntimeTemplate} runtimeTemplate the runtime template
  * @returns {SourceData} the generated source
@@ -567,6 +618,7 @@ const getSourceForScriptExternal = (urlAndGlobal, runtimeTemplate) => {
 };
 
 /**
+ * Checks external variable.
  * @param {string} variableName the variable name to check
  * @param {string} request the request path
  * @param {RuntimeTemplate} runtimeTemplate the runtime template
@@ -578,6 +630,7 @@ const checkExternalVariable = (variableName, request, runtimeTemplate) =>
 	)} }\n`;
 
 /**
+ * Gets source for amd or umd external.
  * @param {ModuleId | string} id the module id
  * @param {boolean} optional true, if the module is optional
  * @param {string | string[]} request the request path
@@ -606,6 +659,7 @@ const getSourceForAmdOrUmdExternal = (
 };
 
 /**
+ * Gets source for default case.
  * @param {boolean} optional true, if the module is optional
  * @param {string | string[]} request the request path
  * @param {RuntimeTemplate} runtimeTemplate the runtime template
@@ -631,6 +685,7 @@ const getSourceForDefaultCase = (optional, request, runtimeTemplate) => {
 /** @typedef {string | string[] | RequestRecord} ExternalModuleRequest */
 
 /**
+ * Defines the external module hooks type used by this module.
  * @typedef {object} ExternalModuleHooks
  * @property {SyncBailHook<[Chunk, Compilation], boolean>} chunkCondition
  */
@@ -640,6 +695,7 @@ const compilationHooksMap = new WeakMap();
 
 class ExternalModule extends Module {
 	/**
+	 * Creates an instance of ExternalModule.
 	 * @param {ExternalModuleRequest} request request
 	 * @param {ExternalsType} type type
 	 * @param {string} userRequest user request
@@ -660,6 +716,7 @@ class ExternalModule extends Module {
 	}
 
 	/**
+	 * Returns the attached hooks.
 	 * @param {Compilation} compilation the compilation
 	 * @returns {ExternalModuleHooks} the attached hooks
 	 */
@@ -675,6 +732,7 @@ class ExternalModule extends Module {
 	}
 
 	/**
+	 * Returns the source types this module can generate.
 	 * @returns {SourceTypes} types available (do not mutate)
 	 */
 	getSourceTypes() {
@@ -693,6 +751,7 @@ class ExternalModule extends Module {
 	}
 
 	/**
+	 * Gets the library identifier.
 	 * @param {LibIdentOptions} options options
 	 * @returns {LibIdent | null} an identifier for library inclusion
 	 */
@@ -701,6 +760,7 @@ class ExternalModule extends Module {
 	}
 
 	/**
+	 * Returns true if the module can be placed in the chunk.
 	 * @param {Chunk} chunk the chunk which condition should be checked
 	 * @param {Compilation} compilation the compilation
 	 * @returns {boolean} true if the module can be placed in the chunk
@@ -721,13 +781,29 @@ class ExternalModule extends Module {
 	}
 
 	/**
+	 * Returns the unique identifier used to reference this module.
 	 * @returns {string} a unique identifier of the module
 	 */
 	identifier() {
-		return `external ${this._resolveExternalType(this.externalType)} ${JSON.stringify(this.request)}`;
+		let id = `external ${this._resolveExternalType(
+			this.externalType
+		)} ${JSON.stringify(this.request)}`;
+		const meta = /** @type {ImportDependencyMeta | undefined} */ (
+			this.dependencyMeta
+		);
+		if (meta) {
+			if (meta.phase) {
+				id += `|phase=${ImportPhaseUtils.stringify(meta.phase)}`;
+			}
+			if (meta.attributes) {
+				id += `|attributes=${JSON.stringify(meta.attributes)}`;
+			}
+		}
+		return id;
 	}
 
 	/**
+	 * Returns a human-readable identifier for this module.
 	 * @param {RequestShortener} requestShortener the request shortener
 	 * @returns {string} a user readable identifier of the module
 	 */
@@ -736,6 +812,7 @@ class ExternalModule extends Module {
 	}
 
 	/**
+	 * Checks whether the module needs to be rebuilt for the current build state.
 	 * @param {NeedBuildContext} context context info
 	 * @param {NeedBuildCallback} callback callback function, returns true, if the module needs a rebuild
 	 * @returns {void}
@@ -745,6 +822,7 @@ class ExternalModule extends Module {
 	}
 
 	/**
+	 * Builds the module using the provided compilation context.
 	 * @param {WebpackOptions} options webpack options
 	 * @param {Compilation} compilation the compilation
 	 * @param {ResolverWithOptions} resolver the resolver
@@ -838,6 +916,7 @@ class ExternalModule extends Module {
 	}
 
 	/**
+	 * Returns the reason this module cannot be concatenated, when one exists.
 	 * @param {ConcatenationBailoutReasonContext} context context
 	 * @returns {string | undefined} reason why this module can't be concatenated, undefined when it can be concatenated
 	 */
@@ -855,6 +934,7 @@ class ExternalModule extends Module {
 	}
 
 	/**
+	 * Get request and external type.
 	 * @private
 	 * @returns {{ request: string | string[], externalType: ExternalsType }} the request and external type
 	 */
@@ -901,6 +981,7 @@ class ExternalModule extends Module {
 	}
 
 	/**
+	 * Returns the source data.
 	 * @private
 	 * @param {string | string[]} request request
 	 * @param {ExternalsType} externalType the external type
@@ -1007,6 +1088,7 @@ class ExternalModule extends Module {
 	}
 
 	/**
+	 * Generates code and runtime requirements for this module.
 	 * @param {CodeGenerationContext} context context for code generation
 	 * @returns {CodeGenerationResult} result
 	 */
@@ -1092,7 +1174,9 @@ class ExternalModule extends Module {
 						scope.registerRawExport(specifier, finalName);
 					}
 				} else if (concatenationScope) {
-					sourceString = `${runtimeTemplate.renderConst()} ${ConcatenationScope.NAMESPACE_OBJECT_EXPORT} = ${sourceString};`;
+					sourceString = `${runtimeTemplate.renderConst()} ${
+						ConcatenationScope.NAMESPACE_OBJECT_EXPORT
+					} = ${sourceString};`;
 					concatenationScope.registerNamespaceExport(
 						ConcatenationScope.NAMESPACE_OBJECT_EXPORT
 					);
@@ -1143,6 +1227,7 @@ class ExternalModule extends Module {
 	}
 
 	/**
+	 * Returns the estimated size for the requested source type.
 	 * @param {string=} type the source type for which the size should be estimated
 	 * @returns {number} the estimated size of the module (must be non-zero)
 	 */
@@ -1151,6 +1236,7 @@ class ExternalModule extends Module {
 	}
 
 	/**
+	 * Updates the hash with the data contributed by this instance.
 	 * @param {Hash} hash the hash used to track dependencies
 	 * @param {UpdateHashContext} context context
 	 * @returns {void}
@@ -1158,14 +1244,26 @@ class ExternalModule extends Module {
 	updateHash(hash, context) {
 		const { chunkGraph } = context;
 		hash.update(
-			`${this._resolveExternalType(this.externalType)}${JSON.stringify(this.request)}${this.isOptional(
-				chunkGraph.moduleGraph
-			)}`
+			`${this._resolveExternalType(this.externalType)}${JSON.stringify(
+				this.request
+			)}${this.isOptional(chunkGraph.moduleGraph)}`
+		);
+		const meta = /** @type {ImportDependencyMeta | undefined} */ (
+			this.dependencyMeta
 		);
+		if (meta) {
+			if (meta.phase) {
+				hash.update(`|phase=${ImportPhaseUtils.stringify(meta.phase)}`);
+			}
+			if (meta.attributes) {
+				hash.update(`|attributes=${JSON.stringify(meta.attributes)}`);
+			}
+		}
 		super.updateHash(hash, context);
 	}
 
 	/**
+	 * Serializes this instance into the provided serializer context.
 	 * @param {ObjectSerializerContext} context context
 	 */
 	serialize(context) {
@@ -1180,6 +1278,7 @@ class ExternalModule extends Module {
 	}
 
 	/**
+	 * Restores this instance from the provided deserializer context.
 	 * @param {ObjectDeserializerContext} context context
 	 */
 	deserialize(context) {

package/lib/ExternalModuleFactoryPlugin.js

@@ -33,6 +33,7 @@ const { cachedSetProperty, resolveByProperty } = require("./util/cleverMerge");
 /** @typedef {(options?: ResolveOptions) => ExternalItemFunctionDataGetResolveCallbackResult | ExternalItemFunctionDataGetResolveResult} ExternalItemFunctionDataGetResolve */
 
 /**
+ * Defines the external item function data type used by this module.
  * @typedef {object} ExternalItemFunctionData
  * @property {string} context the directory in which the request is placed
  * @property {ModuleFactoryCreateDataContextInfo} contextInfo contextual information
@@ -50,6 +51,7 @@ const EMPTY_RESOLVE_OPTIONS = {};
 // TODO webpack 6 remove this
 const callDeprecatedExternals = util.deprecate(
 	/**
+	 * Handles the callback logic for this hook.
 	 * @param {EXPECTED_FUNCTION} externalsFunction externals function
 	 * @param {string} context context
 	 * @param {string} request request
@@ -67,6 +69,7 @@ const callDeprecatedExternals = util.deprecate(
 /** @typedef {ExternalItemObjectKnown & ExternalItemObjectUnknown} ExternalItemObject */
 
 /**
+ * Defines the external weak cache type used by this module.
  * @template {ExternalItemObject} T
  * @typedef {WeakMap<T, Map<IssuerLayer, Omit<T, "byLayer">>>} ExternalWeakCache
  */
@@ -75,6 +78,7 @@ const callDeprecatedExternals = util.deprecate(
 const cache = new WeakMap();
 
 /**
+ * Returns result.
  * @param {ExternalItemObject} obj obj
  * @param {IssuerLayer} layer layer
  * @returns {Omit<ExternalItemObject, "byLayer">} result
@@ -99,6 +103,7 @@ const PLUGIN_NAME = "ExternalModuleFactoryPlugin";
 
 class ExternalModuleFactoryPlugin {
 	/**
+	 * Creates an instance of ExternalModuleFactoryPlugin.
 	 * @param {ExternalsType | ((dependency: Dependency) => ExternalsType)} type default external type
 	 * @param {Externals} externals externals config
 	 */
@@ -108,6 +113,7 @@ class ExternalModuleFactoryPlugin {
 	}
 
 	/**
+	 * Applies the plugin by registering its hooks on the compiler.
 	 * @param {NormalModuleFactory} normalModuleFactory the normal module factory
 	 * @returns {void}
 	 */
@@ -124,6 +130,7 @@ class ExternalModuleFactoryPlugin {
 				/** @typedef {(err?: Error | null, externalModule?: ExternalModule) => void} HandleExternalCallback */
 
 				/**
+				 * Processes the provided value.
 				 * @param {ExternalValue} value the external config
 				 * @param {ExternalsType | undefined} type type of external
 				 * @param {HandleExternalCallback} callback callback
@@ -186,6 +193,11 @@ class ExternalModuleFactoryPlugin {
 
 						dependencyMeta = {
 							attributes: dependency.attributes,
+							phase:
+								dependency instanceof HarmonyImportDependency ||
+								dependency instanceof ImportDependency
+									? dependency.phase
+									: undefined,
 							externalType
 						};
 					} else if (dependency instanceof CssImportDependency) {
@@ -215,6 +227,7 @@ class ExternalModuleFactoryPlugin {
 				};
 
 				/**
+				 * Processes the provided external.
 				 * @param {Externals} externals externals config
 				 * @param {HandleExternalCallback} callback callback
 				 * @returns {void}
@@ -230,6 +243,7 @@ class ExternalModuleFactoryPlugin {
 							/** @type {boolean | undefined} */
 							let asyncFlag;
 							/**
+							 * Handle externals and callback.
 							 * @param {(Error | null)=} err err
 							 * @param {ExternalModule=} module module
 							 * @returns {void}
@@ -262,6 +276,7 @@ class ExternalModuleFactoryPlugin {
 						}
 					} else if (typeof externals === "function") {
 						/**
+						 * Processes the provided err.
 						 * @param {Error | null | undefined} err err
 						 * @param {ExternalValue=} value value
 						 * @param {ExternalsType=} type type

package/lib/ExternalsPlugin.js

@@ -19,6 +19,7 @@ const PLUGIN_NAME = "ExternalsPlugin";
 
 class ExternalsPlugin {
 	/**
+	 * Creates an instance of ExternalsPlugin.
 	 * @param {ExternalsType | ((dependency: Dependency) => ExternalsType)} type default external type
 	 * @param {Externals} externals externals config
 	 */
@@ -28,7 +29,7 @@ class ExternalsPlugin {
 	}
 
 	/**
-	 * Apply the plugin
+	 * Applies the plugin by registering its hooks on the compiler.
 	 * @param {Compiler} compiler the compiler instance
 	 * @returns {void}
 	 */