webpack 5.106.1 → 5.107.0

package/README.md

@@ -302,12 +302,12 @@ For information about the governance of the webpack project, see [GOVERNANCE.md]
 
 - [alexander-akait](https://github.com/alexander-akait) -
   **Alexander Akait** <<sheo13666q@gmail.com>> (he/him)
+- [avivkeller](https://github.com/avivkeller) -
+  **Aviv Keller** <<me@aviv.sh>> (he/him)
 - [evenstensberg](https://github.com/evenstensberg) -
   **Even Stensberg** <<evenstensberg@gmail.com>> (he/him)
 - [ovflowd](https://github.com/ovflowd) -
   **Claudio Wunder** <<cwunder@gnome.org>> (he/they)
-- [snitin315](https://github.com/snitin315) -
-  **Nitin Kumar** <<snitin315@gmail.com>> (he/him)
 - [thelarkinn](https://github.com/thelarkinn) -
   **Sean Larkin** <<selarkin@microsoft.com>> (he/him)
 

package/lib/APIPlugin.js

@@ -14,10 +14,10 @@ const {
 	JAVASCRIPT_MODULE_TYPE_ESM
 } = require("./ModuleTypeConstants");
 const RuntimeGlobals = require("./RuntimeGlobals");
-const WebpackError = require("./WebpackError");
 const ConstDependency = require("./dependencies/ConstDependency");
 const ModuleInitFragmentDependency = require("./dependencies/ModuleInitFragmentDependency");
 const RuntimeRequirementsDependency = require("./dependencies/RuntimeRequirementsDependency");
+const WebpackError = require("./errors/WebpackError");
 const BasicEvaluatedExpression = require("./javascript/BasicEvaluatedExpression");
 const JavascriptModulesPlugin = require("./javascript/JavascriptModulesPlugin");
 const {
@@ -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/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/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

@@ -9,19 +9,20 @@ const { AsyncParallelHook, AsyncSeriesBailHook, SyncHook } = require("tapable");
 const {
 	makeWebpackError,
 	makeWebpackErrorCallback
-} = require("./HookWebpackError");
-
-/** @typedef {import("./WebpackError")} WebpackError */
+} = require("./errors/HookWebpackError");
 
 /**
+ * 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 `Error` or resolve with a typed result.
  * @template T
  * @callback CallbackCache
- * @param {WebpackError | null} err
+ * @param {Error | null} err
  * @param {T=} result
  * @returns {void}
  */
@@ -29,6 +30,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 +40,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 +56,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 +82,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 +117,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 +136,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 +150,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 +159,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 +171,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