webpack 5.76.1 → 5.88.0

package/lib/dependencies/CachedConstDependency.js

@@ -18,9 +18,17 @@ const NullDependency = require("./NullDependency");
 /** @typedef {import("../DependencyTemplates")} DependencyTemplates */
 /** @typedef {import("../ModuleGraph")} ModuleGraph */
 /** @typedef {import("../RuntimeTemplate")} RuntimeTemplate */
+/** @typedef {import("../javascript/JavascriptParser").Range} Range */
+/** @typedef {import("../serialization/ObjectMiddleware").ObjectDeserializerContext} ObjectDeserializerContext */
+/** @typedef {import("../serialization/ObjectMiddleware").ObjectSerializerContext} ObjectSerializerContext */
 /** @typedef {import("../util/Hash")} Hash */
 
 class CachedConstDependency extends NullDependency {
+	/**
+	 * @param {string} expression expression
+	 * @param {Range} range range
+	 * @param {string} identifier identifier
+	 */
 	constructor(expression, range, identifier) {
 		super();
 
@@ -42,6 +50,9 @@ class CachedConstDependency extends NullDependency {
 		hash.update(this._hashUpdate);
 	}
 
+	/**
+	 * @param {ObjectSerializerContext} context context
+	 */
 	serialize(context) {
 		const { write } = context;
 
@@ -52,6 +63,9 @@ class CachedConstDependency extends NullDependency {
 		super.serialize(context);
 	}
 
+	/**
+	 * @param {ObjectDeserializerContext} context context
+	 */
 	deserialize(context) {
 		const { read } = context;
 

package/lib/dependencies/CommonJsDependencyHelpers.js

@@ -7,6 +7,15 @@
 
 const RuntimeGlobals = require("../RuntimeGlobals");
 
+/** @typedef {import("../Module")} Module */
+/** @typedef {"exports" | "module.exports" | "this" | "Object.defineProperty(exports)" | "Object.defineProperty(module.exports)" | "Object.defineProperty(this)"} CommonJSDependencyBaseKeywords */
+
+/**
+ * @param {CommonJSDependencyBaseKeywords} depBase commonjs dependency base
+ * @param {Module} module module
+ * @param {Set<string>} runtimeRequirements runtime requirements
+ * @returns {[string, string]} type and base
+ */
 exports.handleDependencyBase = (depBase, module, runtimeRequirements) => {
 	let base = undefined;
 	let type;

package/lib/dependencies/CommonJsExportRequireDependency.js

@@ -22,13 +22,26 @@ const processExportInfo = require("./processExportInfo");
 /** @typedef {import("../DependencyTemplate").DependencyTemplateContext} DependencyTemplateContext */
 /** @typedef {import("../Module")} Module */
 /** @typedef {import("../ModuleGraph")} ModuleGraph */
+/** @typedef {import("../javascript/JavascriptParser").Range} Range */
+/** @typedef {import("../serialization/ObjectMiddleware").ObjectDeserializerContext} ObjectDeserializerContext */
+/** @typedef {import("../serialization/ObjectMiddleware").ObjectSerializerContext} ObjectSerializerContext */
 /** @typedef {import("../util/runtime").RuntimeSpec} RuntimeSpec */
+/** @typedef {import("./CommonJsDependencyHelpers").CommonJSDependencyBaseKeywords} CommonJSDependencyBaseKeywords */
 
 const idsSymbol = Symbol("CommonJsExportRequireDependency.ids");
 
 const EMPTY_OBJECT = {};
 
 class CommonJsExportRequireDependency extends ModuleDependency {
+	/**
+	 * @param {Range} range range
+	 * @param {Range} valueRange value range
+	 * @param {CommonJSDependencyBaseKeywords} base base
+	 * @param {string[]} names names
+	 * @param {string} request request
+	 * @param {string[]} ids ids
+	 * @param {boolean} resultUsed true, when the result is used
+	 */
 	constructor(range, valueRange, base, names, request, ids, resultUsed) {
 		super(request);
 		this.range = range;
@@ -270,6 +283,9 @@ class CommonJsExportRequireDependency extends ModuleDependency {
 		return { exports, checked };
 	}
 
+	/**
+	 * @param {ObjectSerializerContext} context context
+	 */
 	serialize(context) {
 		const { write } = context;
 		write(this.asiSafe);
@@ -282,6 +298,9 @@ class CommonJsExportRequireDependency extends ModuleDependency {
 		super.serialize(context);
 	}
 
+	/**
+	 * @param {ObjectDeserializerContext} context context
+	 */
 	deserialize(context) {
 		const { read } = context;
 		this.asiSafe = read();

package/lib/dependencies/CommonJsExportsDependency.js

@@ -16,10 +16,20 @@ const NullDependency = require("./NullDependency");
 /** @typedef {import("../Dependency").ExportsSpec} ExportsSpec */
 /** @typedef {import("../DependencyTemplate").DependencyTemplateContext} DependencyTemplateContext */
 /** @typedef {import("../ModuleGraph")} ModuleGraph */
+/** @typedef {import("../javascript/JavascriptParser").Range} Range */
+/** @typedef {import("../serialization/ObjectMiddleware").ObjectDeserializerContext} ObjectDeserializerContext */
+/** @typedef {import("../serialization/ObjectMiddleware").ObjectSerializerContext} ObjectSerializerContext */
+/** @typedef {import("./CommonJsDependencyHelpers").CommonJSDependencyBaseKeywords} CommonJSDependencyBaseKeywords */
 
 const EMPTY_OBJECT = {};
 
 class CommonJsExportsDependency extends NullDependency {
+	/**
+	 * @param {Range} range range
+	 * @param {Range} valueRange value range
+	 * @param {CommonJSDependencyBaseKeywords} base base
+	 * @param {string[]} names names
+	 */
 	constructor(range, valueRange, base, names) {
 		super();
 		this.range = range;
@@ -53,6 +63,9 @@ class CommonJsExportsDependency extends NullDependency {
 		};
 	}
 
+	/**
+	 * @param {ObjectSerializerContext} context context
+	 */
 	serialize(context) {
 		const { write } = context;
 		write(this.range);
@@ -62,6 +75,9 @@ class CommonJsExportsDependency extends NullDependency {
 		super.serialize(context);
 	}
 
+	/**
+	 * @param {ObjectDeserializerContext} context context
+	 */
 	deserialize(context) {
 		const { read } = context;
 		this.range = read();

package/lib/dependencies/CommonJsExportsParserPlugin.js

@@ -16,11 +16,36 @@ const DynamicExports = require("./DynamicExports");
 const HarmonyExports = require("./HarmonyExports");
 const ModuleDecoratorDependency = require("./ModuleDecoratorDependency");
 
-/** @typedef {import("estree").Expression} ExpressionNode */
+/** @typedef {import("estree").AssignmentExpression} AssignmentExpression */
+/** @typedef {import("estree").CallExpression} CallExpression */
+/** @typedef {import("estree").Expression} Expression */
+/** @typedef {import("estree").Super} Super */
+
+/** @typedef {import("../ModuleGraph")} ModuleGraph */
 /** @typedef {import("../NormalModule")} NormalModule */
 /** @typedef {import("../javascript/BasicEvaluatedExpression")} BasicEvaluatedExpression */
 /** @typedef {import("../javascript/JavascriptParser")} JavascriptParser */
+/** @typedef {import("./CommonJsDependencyHelpers").CommonJSDependencyBaseKeywords} CommonJSDependencyBaseKeywords */
 
+/**
+ * This function takes a generic expression and detects whether it is an ObjectExpression.
+ * This is used in the context of parsing CommonJS exports to get the value of the property descriptor
+ * when the `exports` object is assigned to `Object.defineProperty`.
+ *
+ * In CommonJS modules, the `exports` object can be assigned to `Object.defineProperty` and therefore
+ * webpack has to detect this case and get the value key of the property descriptor. See the following example
+ * for more information: https://astexplorer.net/#/gist/83ce51a4e96e59d777df315a6d111da6/8058ead48a1bb53c097738225db0967ef7f70e57
+ *
+ * This would be an example of a CommonJS module that exports an object with a property descriptor:
+ * ```js
+ * Object.defineProperty(exports, "__esModule", { value: true });
+ * exports.foo = void 0;
+ * exports.foo = "bar";
+ * ```
+ *
+ * @param {TODO} expr expression
+ * @returns {Expression | undefined} returns the value of property descriptor
+ */
 const getValueOfPropertyDescription = expr => {
 	if (expr.type !== "ObjectExpression") return;
 	for (const property of expr.properties) {
@@ -31,6 +56,15 @@ const getValueOfPropertyDescription = expr => {
 	}
 };
 
+/**
+ * The purpose of this function is to check whether an expression is a truthy literal or not. This is
+ * useful when parsing CommonJS exports, because CommonJS modules can export any value, including falsy
+ * values like `null` and `false`. However, exports should only be created if the exported value is truthy.
+ *
+ * @param {Expression} expr expression being checked
+ * @returns {boolean} true, when the expression is a truthy literal
+ *
+ */
 const isTruthyLiteral = expr => {
 	switch (expr.type) {
 		case "Literal":
@@ -41,6 +75,14 @@ const isTruthyLiteral = expr => {
 	return false;
 };
 
+/**
+ * The purpose of this function is to check whether an expression is a falsy literal or not. This is
+ * useful when parsing CommonJS exports, because CommonJS modules can export any value, including falsy
+ * values like `null` and `false`. However, exports should only be created if the exported value is truthy.
+ *
+ * @param {Expression} expr expression being checked
+ * @returns {boolean} true, when the expression is a falsy literal
+ */
 const isFalsyLiteral = expr => {
 	switch (expr.type) {
 		case "Literal":
@@ -53,7 +95,7 @@ const isFalsyLiteral = expr => {
 
 /**
  * @param {JavascriptParser} parser the parser
- * @param {ExpressionNode} expr expression
+ * @param {Expression} expr expression
  * @returns {{ argument: BasicEvaluatedExpression, ids: string[] } | undefined} parsed call
  */
 const parseRequireCall = (parser, expr) => {
@@ -86,17 +128,28 @@ const parseRequireCall = (parser, expr) => {
 };
 
 class CommonJsExportsParserPlugin {
+	/**
+	 * @param {ModuleGraph} moduleGraph module graph
+	 */
 	constructor(moduleGraph) {
 		this.moduleGraph = moduleGraph;
 	}
 
 	/**
 	 * @param {JavascriptParser} parser the parser
+	 * @returns {void}
 	 */
 	apply(parser) {
 		const enableStructuredExports = () => {
 			DynamicExports.enable(parser.state);
 		};
+
+		/**
+		 * @param {boolean} topLevel true, when the export is on top level
+		 * @param {string[]} members members of the export
+		 * @param {Expression | undefined} valueExpr expression for the value
+		 * @returns {void}
+		 */
 		const checkNamespace = (topLevel, members, valueExpr) => {
 			if (!DynamicExports.isEnabled(parser.state)) return;
 			if (members.length > 0 && members[0] === "__esModule") {
@@ -107,10 +160,16 @@ class CommonJsExportsParserPlugin {
 				}
 			}
 		};
+		/**
+		 * @param {string=} reason reason
+		 */
 		const bailout = reason => {
 			DynamicExports.bailout(parser.state);
 			if (reason) bailoutHint(reason);
 		};
+		/**
+		 * @param {string} reason reason
+		 */
 		const bailoutHint = reason => {
 			this.moduleGraph
 				.getOptimizationBailout(parser.state.module)
@@ -126,6 +185,13 @@ class CommonJsExportsParserPlugin {
 			.tap("CommonJsPlugin", evaluateToString("object"));
 
 		// exporting //
+
+		/**
+		 * @param {AssignmentExpression} expr expression
+		 * @param {CommonJSDependencyBaseKeywords} base commonjs base keywords
+		 * @param {string[]} members members of the export
+		 * @returns {boolean} true, when the expression was handled
+		 */
 		const handleAssignExport = (expr, base, members) => {
 			if (HarmonyExports.isEnabled(parser.state)) return;
 			// Handle reexporting
@@ -192,9 +258,7 @@ class CommonJsExportsParserPlugin {
 		parser.hooks.call
 			.for("Object.defineProperty")
 			.tap("CommonJsExportsParserPlugin", expression => {
-				const expr = /** @type {import("estree").CallExpression} */ (
-					expression
-				);
+				const expr = /** @type {CallExpression} */ (expression);
 				if (!parser.isStatementLevelExpression(expr)) return;
 				if (expr.arguments.length !== 3) return;
 				if (expr.arguments[0].type === "SpreadElement") return;
@@ -233,6 +297,14 @@ class CommonJsExportsParserPlugin {
 			});
 
 		// Self reference //
+
+		/**
+		 * @param {Expression | Super} expr expression
+		 * @param {CommonJSDependencyBaseKeywords} base commonjs base keywords
+		 * @param {string[]} members members of the export
+		 * @param {CallExpression=} call call expression
+		 * @returns {boolean | void} true, when the expression was handled
+		 */
 		const handleAccessExport = (expr, base, members, call = undefined) => {
 			if (HarmonyExports.isEnabled(parser.state)) return;
 			if (members.length === 0) {

package/lib/dependencies/CommonJsFullRequireDependency.js

@@ -16,12 +16,15 @@ const ModuleDependency = require("./ModuleDependency");
 /** @typedef {import("../Dependency").ReferencedExport} ReferencedExport */
 /** @typedef {import("../DependencyTemplate").DependencyTemplateContext} DependencyTemplateContext */
 /** @typedef {import("../ModuleGraph")} ModuleGraph */
+/** @typedef {import("../javascript/JavascriptParser").Range} Range */
+/** @typedef {import("../serialization/ObjectMiddleware").ObjectDeserializerContext} ObjectDeserializerContext */
+/** @typedef {import("../serialization/ObjectMiddleware").ObjectSerializerContext} ObjectSerializerContext */
 /** @typedef {import("../util/runtime").RuntimeSpec} RuntimeSpec */
 
 class CommonJsFullRequireDependency extends ModuleDependency {
 	/**
 	 * @param {string} request the request string
-	 * @param {[number, number]} range location in source code
+	 * @param {Range} range location in source code
 	 * @param {string[]} names accessed properties on module
 	 */
 	constructor(request, range, names) {
@@ -51,6 +54,9 @@ class CommonJsFullRequireDependency extends ModuleDependency {
 		return [this.names];
 	}
 
+	/**
+	 * @param {ObjectSerializerContext} context context
+	 */
 	serialize(context) {
 		const { write } = context;
 		write(this.names);
@@ -59,6 +65,9 @@ class CommonJsFullRequireDependency extends ModuleDependency {
 		super.serialize(context);
 	}
 
+	/**
+	 * @param {ObjectDeserializerContext} context context
+	 */
 	deserialize(context) {
 		const { read } = context;
 		this.names = read();