webpack 5.106.0 → 5.106.2

package/lib/APIPlugin.js

@@ -34,6 +34,7 @@ const GetFullHashRuntimeModule = require("./runtime/GetFullHashRuntimeModule");
 /** @typedef {import("./javascript/JavascriptParser").Range} Range */
 
 /**
+ * Returns the replacement definitions used for webpack API identifiers.
  * @returns {Record<string, { expr: string, req: string[] | null, type?: string, assign: boolean }>} replacements
  */
 function getReplacements() {
@@ -140,7 +141,7 @@ const PLUGIN_NAME = "APIPlugin";
 
 class APIPlugin {
 	/**
-	 * Apply the plugin
+	 * Applies the plugin by registering its hooks on the compiler.
 	 * @param {Compiler} compiler the compiler instance
 	 * @returns {void}
 	 */
@@ -204,6 +205,7 @@ class APIPlugin {
 				);
 
 				/**
+				 * Handles the hook callback for this code path.
 				 * @param {JavascriptParser} parser the parser
 				 */
 				const handler = (parser) => {

package/lib/AbstractMethodError.js

@@ -10,6 +10,8 @@ const WebpackError = require("./WebpackError");
 const CURRENT_METHOD_REGEXP = /at ([a-zA-Z0-9_.]*)/;
 
 /**
+ * Creates the error message shown when an abstract API is called without
+ * being implemented by a subclass.
  * @param {string=} method method name
  * @returns {string} message
  */
@@ -18,6 +20,8 @@ function createMessage(method) {
 }
 
 /**
+ * Captures a stack trace so the calling method name can be folded into the
+ * final abstract-method error message.
  * @constructor
  */
 function Message() {
@@ -35,7 +39,8 @@ function Message() {
 }
 
 /**
- * Error for abstract method
+ * Error thrown when code reaches a method that is intended to be overridden by
+ * a subclass.
  * @example
  * ```js
  * class FooClass {
@@ -46,6 +51,10 @@ function Message() {
  * ```
  */
 class AbstractMethodError extends WebpackError {
+	/**
+	 * Creates an error whose message points at the abstract method that was
+	 * invoked.
+	 */
 	constructor() {
 		super(new Message().message);
 		/** @type {string} */

package/lib/AsyncDependenciesBlock.js

@@ -71,6 +71,7 @@ class AsyncDependenciesBlock extends DependenciesBlock {
 	}
 
 	/**
+	 * 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}
@@ -88,6 +89,7 @@ class AsyncDependenciesBlock extends DependenciesBlock {
 	}
 
 	/**
+	 * Serializes this instance into the provided serializer context.
 	 * @param {ObjectSerializerContext} context context
 	 */
 	serialize(context) {
@@ -99,6 +101,7 @@ class AsyncDependenciesBlock extends DependenciesBlock {
 	}
 
 	/**
+	 * Restores this instance from the provided deserializer context.
 	 * @param {ObjectDeserializerContext} context context
 	 */
 	deserialize(context) {

package/lib/AsyncDependencyToInitialChunkError.js

@@ -10,9 +10,14 @@ const WebpackError = require("./WebpackError");
 /** @typedef {import("./Dependency").DependencyLocation} DependencyLocation */
 /** @typedef {import("./Module")} Module */
 
+/**
+ * Error raised when webpack detects an attempt to lazy-load a chunk name that
+ * is already claimed by an entrypoint's initial chunk.
+ */
 class AsyncDependencyToInitialChunkError extends WebpackError {
 	/**
-	 * Creates an instance of AsyncDependencyToInitialChunkError.
+	 * Captures the chunk name, originating module, and source location for an
+	 * invalid async dependency targeting an initial chunk.
 	 * @param {string} chunkName Name of Chunk
 	 * @param {Module} module module tied to dependency
 	 * @param {DependencyLocation} loc location of dependency

package/lib/AutomaticPrefetchPlugin.js

@@ -13,9 +13,14 @@ const PrefetchDependency = require("./dependencies/PrefetchDependency");
 
 const PLUGIN_NAME = "AutomaticPrefetchPlugin";
 
+/**
+ * Records modules from one compilation and adds them back as prefetch
+ * dependencies in the next compilation.
+ */
 class AutomaticPrefetchPlugin {
 	/**
-	 * Apply the plugin
+	 * Registers hooks that remember previously built normal modules and enqueue
+	 * them as `PrefetchDependency` requests during the next make phase.
 	 * @param {Compiler} compiler the compiler instance
 	 * @returns {void}
 	 */

package/lib/BannerPlugin.js

@@ -21,6 +21,8 @@ const Template = require("./Template");
 /** @typedef {(data: { hash?: string, chunk: Chunk, filename: string }) => string} BannerFunction */
 
 /**
+ * Wraps banner text in a JavaScript block comment, preserving multi-line
+ * formatting and escaping accidental comment terminators.
  * @param {string} str string to wrap
  * @returns {string} wrapped string
  */
@@ -38,8 +40,14 @@ const wrapComment = (str) => {
 
 const PLUGIN_NAME = "BannerPlugin";
 
+/**
+ * Prepends or appends banner text to emitted assets that match the configured
+ * file filters.
+ */
 class BannerPlugin {
 	/**
+	 * Normalizes banner options and compiles the configured banner source into a
+	 * function that can render per-asset banner text.
 	 * @param {BannerPluginArgument} options options object
 	 */
 	constructor(options) {
@@ -69,7 +77,8 @@ class BannerPlugin {
 	}
 
 	/**
-	 * Apply the plugin
+	 * Validates the configured options and injects rendered banner comments into
+	 * matching compilation assets at the configured process-assets stage.
 	 * @param {Compiler} compiler the compiler instance
 	 * @returns {void}
 	 */

package/lib/Cache.js

@@ -14,11 +14,15 @@ const {
 /** @typedef {import("./WebpackError")} WebpackError */
 
 /**
+ * Cache validation token whose string representation identifies the build
+ * inputs associated with a cached value.
  * @typedef {object} Etag
  * @property {() => string} toString
  */
 
 /**
+ * Completion callback used by cache operations that either fail with a
+ * `WebpackError` or resolve with a typed result.
  * @template T
  * @callback CallbackCache
  * @param {WebpackError | null} err
@@ -29,6 +33,8 @@ const {
 /** @typedef {EXPECTED_ANY} Data */
 
 /**
+ * Handler invoked after a cache read succeeds so additional cache layers can
+ * react to the retrieved value.
  * @template T
  * @callback GotHandler
  * @param {T} result
@@ -37,6 +43,8 @@ const {
  */
 
 /**
+ * Creates a callback wrapper that waits for a fixed number of completions and
+ * forwards the first error immediately.
  * @param {number} times times
  * @param {(err?: Error | null) => void} callback callback
  * @returns {(err?: Error | null) => void} callback
@@ -51,7 +59,14 @@ const needCalls = (times, callback) => (err) => {
 	}
 };
 
+/**
+ * Abstract cache interface backed by tapable hooks for reading, writing, idle
+ * transitions, and shutdown across webpack cache implementations.
+ */
 class Cache {
+	/**
+	 * Initializes the cache lifecycle hooks implemented by cache backends.
+	 */
 	constructor() {
 		this.hooks = {
 			/** @type {AsyncSeriesBailHook<[string, Etag | null, GotHandler<EXPECTED_ANY>[]], Data>} */
@@ -70,6 +85,8 @@ class Cache {
 	}
 
 	/**
+	 * Retrieves a cached value and lets registered `gotHandlers` observe the
+	 * result before the caller receives it.
 	 * @template T
 	 * @param {string} identifier the cache identifier
 	 * @param {Etag | null} etag the etag
@@ -103,6 +120,8 @@ class Cache {
 	}
 
 	/**
+	 * Stores a cache entry for the identifier and etag through the registered
+	 * cache backend hooks.
 	 * @template T
 	 * @param {string} identifier the cache identifier
 	 * @param {Etag | null} etag the etag
@@ -120,7 +139,8 @@ class Cache {
 	}
 
 	/**
-	 * After this method has succeeded the cache can only be restored when build dependencies are
+	 * Persists the set of build dependencies required to determine whether the
+	 * cache can be restored in a future compilation.
 	 * @param {Iterable<string>} dependencies list of all build dependencies
 	 * @param {CallbackCache<void>} callback signals when the dependencies are stored
 	 * @returns {void}
@@ -133,6 +153,8 @@ class Cache {
 	}
 
 	/**
+	 * Signals that webpack is entering an idle phase and cache backends may flush
+	 * or compact pending work.
 	 * @returns {void}
 	 */
 	beginIdle() {
@@ -140,6 +162,8 @@ class Cache {
 	}
 
 	/**
+	 * Signals that webpack is leaving the idle phase and waits for cache
+	 * backends to finish any asynchronous resume work.
 	 * @param {CallbackCache<void>} callback signals when the call finishes
 	 * @returns {void}
 	 */
@@ -150,6 +174,7 @@ class Cache {
 	}
 
 	/**
+	 * Shuts down every registered cache backend and waits for cleanup to finish.
 	 * @param {CallbackCache<void>} callback signals when the call finishes
 	 * @returns {void}
 	 */

package/lib/CacheFacade.js

@@ -16,6 +16,7 @@ const mergeEtags = require("./cache/mergeEtags");
 /** @typedef {import("./util/Hash").HashFunction} HashFunction */
 
 /**
+ * Defines the callback cache callback.
  * @template T
  * @callback CallbackCache
  * @param {(Error | null)=} err
@@ -24,6 +25,7 @@ const mergeEtags = require("./cache/mergeEtags");
  */
 
 /**
+ * Defines the callback normal error cache callback.
  * @template T
  * @callback CallbackNormalErrorCache
  * @param {(Error | null)=} err
@@ -33,6 +35,7 @@ const mergeEtags = require("./cache/mergeEtags");
 
 class MultiItemCache {
 	/**
+	 * Creates an instance of MultiItemCache.
 	 * @param {ItemCacheFacade[]} items item caches
 	 */
 	constructor(items) {
@@ -43,6 +46,7 @@ class MultiItemCache {
 	}
 
 	/**
+	 * Returns value.
 	 * @template T
 	 * @param {CallbackCache<T>} callback signals when the value is retrieved
 	 * @returns {void}
@@ -52,11 +56,13 @@ class MultiItemCache {
 	}
 
 	/**
+	 * Returns promise with the data.
 	 * @template T
 	 * @returns {Promise<T>} promise with the data
 	 */
 	getPromise() {
 		/**
+		 * Returns promise with the data.
 		 * @param {number} i index
 		 * @returns {Promise<T>} promise with the data
 		 */
@@ -69,6 +75,7 @@ class MultiItemCache {
 	}
 
 	/**
+	 * Processes the provided data.
 	 * @template T
 	 * @param {T} data the value to store
 	 * @param {CallbackCache<void>} callback signals when the value is stored
@@ -83,6 +90,7 @@ class MultiItemCache {
 	}
 
 	/**
+	 * Stores the provided data.
 	 * @template T
 	 * @param {T} data the value to store
 	 * @returns {Promise<void>} promise signals when the value is stored
@@ -96,6 +104,7 @@ class MultiItemCache {
 
 class ItemCacheFacade {
 	/**
+	 * Creates an instance of ItemCacheFacade.
 	 * @param {Cache} cache the root cache
 	 * @param {string} name the child cache item name
 	 * @param {Etag | null} etag the etag
@@ -107,6 +116,7 @@ class ItemCacheFacade {
 	}
 
 	/**
+	 * Returns value.
 	 * @template T
 	 * @param {CallbackCache<T>} callback signals when the value is retrieved
 	 * @returns {void}
@@ -116,6 +126,7 @@ class ItemCacheFacade {
 	}
 
 	/**
+	 * Returns promise with the data.
 	 * @template T
 	 * @returns {Promise<T>} promise with the data
 	 */
@@ -132,6 +143,7 @@ class ItemCacheFacade {
 	}
 
 	/**
+	 * Processes the provided data.
 	 * @template T
 	 * @param {T} data the value to store
 	 * @param {CallbackCache<void>} callback signals when the value is stored
@@ -142,6 +154,7 @@ class ItemCacheFacade {
 	}
 
 	/**
+	 * Stores the provided data.
 	 * @template T
 	 * @param {T} data the value to store
 	 * @returns {Promise<void>} promise signals when the value is stored
@@ -159,6 +172,7 @@ class ItemCacheFacade {
 	}
 
 	/**
+	 * Processes the provided computer.
 	 * @template T
 	 * @param {(callback: CallbackNormalErrorCache<T>) => void} computer function to compute the value if not cached
 	 * @param {CallbackNormalErrorCache<T>} callback signals when the value is retrieved
@@ -179,6 +193,7 @@ class ItemCacheFacade {
 	}
 
 	/**
+	 * Returns promise with the data.
 	 * @template T
 	 * @param {() => Promise<T> | T} computer function to compute the value if not cached
 	 * @returns {Promise<T>} promise with the data
@@ -194,6 +209,7 @@ class ItemCacheFacade {
 
 class CacheFacade {
 	/**
+	 * Creates an instance of CacheFacade.
 	 * @param {Cache} cache the root cache
 	 * @param {string} name the child cache name
 	 * @param {HashFunction=} hashFunction the hash function to use
@@ -205,6 +221,7 @@ class CacheFacade {
 	}
 
 	/**
+	 * Returns child cache.
 	 * @param {string} name the child cache name#
 	 * @returns {CacheFacade} child cache
 	 */
@@ -217,6 +234,7 @@ class CacheFacade {
 	}
 
 	/**
+	 * Returns item cache.
 	 * @param {string} identifier the cache identifier
 	 * @param {Etag | null} etag the etag
 	 * @returns {ItemCacheFacade} item cache
@@ -230,6 +248,7 @@ class CacheFacade {
 	}
 
 	/**
+	 * Gets lazy hashed etag.
 	 * @param {HashableObject} obj an hashable object
 	 * @returns {Etag} an etag that is lazy hashed
 	 */
@@ -238,6 +257,7 @@ class CacheFacade {
 	}
 
 	/**
+	 * Merges the provided values into a single result.
 	 * @param {Etag} a an etag
 	 * @param {Etag} b another etag
 	 * @returns {Etag} an etag that represents both
@@ -247,6 +267,7 @@ class CacheFacade {
 	}
 
 	/**
+	 * Returns value.
 	 * @template T
 	 * @param {string} identifier the cache identifier
 	 * @param {Etag | null} etag the etag
@@ -258,6 +279,7 @@ class CacheFacade {
 	}
 
 	/**
+	 * Returns promise with the data.
 	 * @template T
 	 * @param {string} identifier the cache identifier
 	 * @param {Etag | null} etag the etag
@@ -276,6 +298,7 @@ class CacheFacade {
 	}
 
 	/**
+	 * Processes the provided identifier.
 	 * @template T
 	 * @param {string} identifier the cache identifier
 	 * @param {Etag | null} etag the etag
@@ -288,6 +311,7 @@ class CacheFacade {
 	}
 
 	/**
+	 * Stores the provided identifier.
 	 * @template T
 	 * @param {string} identifier the cache identifier
 	 * @param {Etag | null} etag the etag
@@ -307,6 +331,7 @@ class CacheFacade {
 	}
 
 	/**
+	 * Processes the provided identifier.
 	 * @template T
 	 * @param {string} identifier the cache identifier
 	 * @param {Etag | null} etag the etag
@@ -329,6 +354,7 @@ class CacheFacade {
 	}
 
 	/**
+	 * Returns promise with the data.
 	 * @template T
 	 * @param {string} identifier the cache identifier
 	 * @param {Etag | null} etag the etag

package/lib/CaseSensitiveModulesWarning.js

@@ -11,6 +11,7 @@ const WebpackError = require("./WebpackError");
 /** @typedef {import("./ModuleGraph")} ModuleGraph */
 
 /**
+ * Sorts the conflicting modules by identifier to keep warning output stable.
  * @param {Module[]} modules the modules to be sorted
  * @returns {Module[]} sorted version of original modules
  */
@@ -27,6 +28,8 @@ const sortModules = (modules) =>
 	});
 
 /**
+ * Formats the conflicting modules and one representative incoming reason for
+ * each module into the warning body.
  * @param {Module[]} modules each module from throw
  * @param {ModuleGraph} moduleGraph the module graph
  * @returns {string} each message from provided modules
@@ -49,9 +52,14 @@ const createModulesListMessage = (modules, moduleGraph) =>
 		})
 		.join("\n");
 
+/**
+ * Warning emitted when webpack finds modules whose identifiers differ only by
+ * letter casing, which can behave inconsistently across filesystems.
+ */
 class CaseSensitiveModulesWarning extends WebpackError {
 	/**
-	 * Creates an instance of CaseSensitiveModulesWarning.
+	 * Builds a warning message that lists the case-conflicting modules and
+	 * representative importers that caused them to be included.
 	 * @param {Iterable<Module>} modules modules that were detected
 	 * @param {ModuleGraph} moduleGraph the module graph
 	 */