webpack 5.106.1 → 5.106.2

package/lib/util/AsyncQueue.js

@@ -17,6 +17,7 @@ const DONE_STATE = 2;
 let inHandleResult = 0;
 
 /**
+ * Defines the callback callback.
  * @template T
  * @callback Callback
  * @param {(WebpackError | null)=} err
@@ -25,12 +26,14 @@ let inHandleResult = 0;
  */
 
 /**
+ * Represents AsyncQueueEntry.
  * @template T
  * @template K
  * @template R
  */
 class AsyncQueueEntry {
 	/**
+	 * Creates an instance of AsyncQueueEntry.
 	 * @param {T} item the item
 	 * @param {Callback<R>} callback the callback
 	 */
@@ -50,22 +53,26 @@ class AsyncQueueEntry {
 }
 
 /**
+ * Defines the get key type used by this module.
  * @template T, K
  * @typedef {(item: T) => K} getKey
  */
 
 /**
+ * Defines the processor type used by this module.
  * @template T, R
  * @typedef {(item: T, callback: Callback<R>) => void} Processor
  */
 
 /**
+ * Represents AsyncQueue.
  * @template T
  * @template K
  * @template R
  */
 class AsyncQueue {
 	/**
+	 * Creates an instance of AsyncQueue.
 	 * @param {object} options options object
 	 * @param {string=} options.name name of the queue
 	 * @param {number=} options.parallelism how many items should be processed at once
@@ -119,6 +126,7 @@ class AsyncQueue {
 	}
 
 	/**
+	 * Returns context of execution.
 	 * @returns {string} context of execution
 	 */
 	getContext() {
@@ -126,6 +134,7 @@ class AsyncQueue {
 	}
 
 	/**
+	 * Updates context using the provided value.
 	 * @param {string} value context of execution
 	 */
 	setContext(value) {
@@ -133,6 +142,7 @@ class AsyncQueue {
 	}
 
 	/**
+	 * Processes the provided item.
 	 * @param {T} item an item
 	 * @param {Callback<R>} callback callback function
 	 * @returns {void}
@@ -185,6 +195,7 @@ class AsyncQueue {
 	}
 
 	/**
+	 * Processes the provided item.
 	 * @param {T} item an item
 	 * @returns {void}
 	 */
@@ -225,6 +236,7 @@ class AsyncQueue {
 	}
 
 	/**
+	 * Describes how this stop operation behaves.
 	 * @returns {void}
 	 */
 	stop() {
@@ -245,6 +257,7 @@ class AsyncQueue {
 	}
 
 	/**
+	 * Increase parallelism.
 	 * @returns {void}
 	 */
 	increaseParallelism() {
@@ -258,6 +271,7 @@ class AsyncQueue {
 	}
 
 	/**
+	 * Decrease parallelism.
 	 * @returns {void}
 	 */
 	decreaseParallelism() {
@@ -266,6 +280,7 @@ class AsyncQueue {
 	}
 
 	/**
+	 * Checks whether this async queue is processing.
 	 * @param {T} item an item
 	 * @returns {boolean} true, if the item is currently being processed
 	 */
@@ -276,6 +291,7 @@ class AsyncQueue {
 	}
 
 	/**
+	 * Checks whether this async queue is queued.
 	 * @param {T} item an item
 	 * @returns {boolean} true, if the item is currently queued
 	 */
@@ -286,6 +302,7 @@ class AsyncQueue {
 	}
 
 	/**
+	 * Checks whether this async queue is done.
 	 * @param {T} item an item
 	 * @returns {boolean} true, if the item is currently queued
 	 */
@@ -296,6 +313,7 @@ class AsyncQueue {
 	}
 
 	/**
+	 * Describes how this ensure processing operation behaves.
 	 * @returns {void}
 	 */
 	_ensureProcessing() {
@@ -324,6 +342,7 @@ class AsyncQueue {
 	}
 
 	/**
+	 * Processes the provided entry.
 	 * @param {AsyncQueueEntry<T, K, R>} entry the entry
 	 * @returns {void}
 	 */
@@ -351,6 +370,7 @@ class AsyncQueue {
 	}
 
 	/**
+	 * Processes the provided entry.
 	 * @param {AsyncQueueEntry<T, K, R>} entry the entry
 	 * @param {(WebpackError | null)=} err error, if any
 	 * @param {(R | null)=} result result, if any

package/lib/util/IterableHelpers.js

@@ -6,6 +6,7 @@
 "use strict";
 
 /**
+ * Returns last item.
  * @template T
  * @param {Iterable<T>} set a set
  * @returns {T | undefined} last item
@@ -18,6 +19,7 @@ const last = (set) => {
 };
 
 /**
+ * Returns true, if some items match the filter predicate.
  * @template T
  * @param {Iterable<T>} iterable iterable
  * @param {(value: T) => boolean | null | undefined} filter predicate
@@ -31,6 +33,7 @@ const someInIterable = (iterable, filter) => {
 };
 
 /**
+ * Returns count of items.
  * @template T
  * @param {Iterable<T>} iterable an iterable
  * @returns {number} count of items

package/lib/util/LazyBucketSortedSet.js

@@ -9,23 +9,28 @@ const { first } = require("./SetHelpers");
 const SortableSet = require("./SortableSet");
 
 /**
+ * Callback that extracts the grouping key for an item at one bucket layer.
  * @template T
  * @template K
  * @typedef {(item: T) => K} GetKey
  */
 
 /**
+ * Comparison function used to order keys or leaf items.
  * @template T
  * @typedef {(a: T, n: T) => number} Comparator
  */
 
 /**
+ * Internal bucket entry, either another nested bucket set or a sorted leaf set.
  * @template T
  * @template K
  * @typedef {LazyBucketSortedSet<T, K> | SortableSet<T>} Entry
  */
 
 /**
+ * Constructor argument accepted for nested bucket layers or the final leaf
+ * comparator.
  * @template T
  * @template K
  * @typedef {GetKey<T, K> | Comparator<K> | Comparator<T>} Arg
@@ -45,6 +50,8 @@ const SortableSet = require("./SortableSet");
  */
 class LazyBucketSortedSet {
 	/**
+	 * Creates a lazily sorted, potentially multi-level bucket structure whose
+	 * order is only fully resolved when items are popped.
 	 * @param {GetKey<T, K>} getKey function to get key from item
 	 * @param {Comparator<K>=} comparator comparator to sort keys
 	 * @param {...Arg<T, K>} args more pairs of getKey and comparator plus optional final comparator for the last layer
@@ -62,6 +69,8 @@ class LazyBucketSortedSet {
 	}
 
 	/**
+	 * Adds an item to the unsorted staging area so sorting can be deferred until
+	 * an ordered pop is requested.
 	 * @param {T} item an item
 	 * @returns {void}
 	 */
@@ -71,6 +80,8 @@ class LazyBucketSortedSet {
 	}
 
 	/**
+	 * Inserts an item into the correct nested bucket, creating intermediate
+	 * bucket structures on demand.
 	 * @param {K} key key of item
 	 * @param {T} item the item
 	 * @returns {void}
@@ -95,6 +106,8 @@ class LazyBucketSortedSet {
 	}
 
 	/**
+	 * Removes an item from either the unsorted staging area or its resolved
+	 * bucket and prunes empty buckets as needed.
 	 * @param {T} item an item
 	 * @returns {void}
 	 */
@@ -113,6 +126,7 @@ class LazyBucketSortedSet {
 	}
 
 	/**
+	 * Removes an empty bucket key and its corresponding nested entry.
 	 * @param {K} key key to be removed
 	 * @returns {void}
 	 */
@@ -122,6 +136,8 @@ class LazyBucketSortedSet {
 	}
 
 	/**
+	 * Removes and returns the smallest item according to the configured bucket
+	 * order, sorting only the portions of the structure that are needed.
 	 * @returns {T | undefined} an item
 	 */
 	popFirst() {
@@ -158,6 +174,8 @@ class LazyBucketSortedSet {
 	}
 
 	/**
+	 * Begins an in-place update for an item and returns a completion callback
+	 * that can either reinsert it under a new key or remove it entirely.
 	 * @param {T} item to be updated item
 	 * @returns {(remove?: true) => void} finish update
 	 */
@@ -222,6 +240,8 @@ class LazyBucketSortedSet {
 	}
 
 	/**
+	 * Appends iterators for every stored bucket and leaf to support unordered
+	 * traversal across the entire structure.
 	 * @param {Iterator<T>[]} iterators list of iterators to append to
 	 * @returns {void}
 	 */
@@ -245,6 +265,7 @@ class LazyBucketSortedSet {
 	}
 
 	/**
+	 * Iterates over all stored items without imposing bucket sort order.
 	 * @returns {Iterator<T>} the iterator
 	 */
 	[Symbol.iterator]() {

package/lib/util/LazySet.js

@@ -8,6 +8,7 @@
 const makeSerializable = require("./makeSerializable");
 
 /**
+ * Merges every queued iterable directly into the concrete backing set.
  * @template T
  * @param {Set<T>} targetSet set where items should be added
  * @param {Set<Iterable<T>>} toMerge iterables to be merged
@@ -22,6 +23,8 @@ const merge = (targetSet, toMerge) => {
 };
 
 /**
+ * Flattens nested `LazySet` instances into a single collection of iterables
+ * that can later be merged into the backing set.
  * @template T
  * @param {Set<Iterable<T>>} targetSet set where iterables should be added
  * @param {LazySet<T>[]} toDeepMerge lazy sets to be flattened
@@ -40,6 +43,7 @@ const flatten = (targetSet, toDeepMerge) => {
 };
 
 /**
+ * Defines the set iterator type used by this module.
  * @template T
  * @typedef {import("typescript-iterable").SetIterator<T>} SetIterator
  */
@@ -52,6 +56,8 @@ const flatten = (targetSet, toDeepMerge) => {
  */
 class LazySet {
 	/**
+	 * Seeds the set with an optional iterable while preparing internal queues for
+	 * deferred merges.
 	 * @param {Iterable<T>=} iterable init iterable
 	 */
 	constructor(iterable) {
@@ -65,11 +71,17 @@ class LazySet {
 		this._deopt = false;
 	}
 
+	/**
+	 * Flattens any nested lazy sets that were queued for merging.
+	 */
 	_flatten() {
 		flatten(this._toMerge, this._toDeepMerge);
 		this._toDeepMerge.length = 0;
 	}
 
+	/**
+	 * Materializes all deferred additions into the backing set.
+	 */
 	_merge() {
 		this._flatten();
 		merge(this._set, this._toMerge);
@@ -77,6 +89,10 @@ class LazySet {
 		this._needMerge = false;
 	}
 
+	/**
+	 * Reports whether the set is empty without forcing a full merge.
+	 * @returns {boolean} true when no items have been stored or queued
+	 */
 	_isEmpty() {
 		return (
 			this._set.size === 0 &&
@@ -85,12 +101,17 @@ class LazySet {
 		);
 	}
 
+	/**
+	 * Returns the number of items after applying any deferred merges.
+	 * @returns {number} number of items in the set
+	 */
 	get size() {
 		if (this._needMerge) this._merge();
 		return this._set.size;
 	}
 
 	/**
+	 * Adds a single item immediately to the concrete backing set.
 	 * @param {T} item an item
 	 * @returns {LazySet<T>} itself
 	 */
@@ -100,6 +121,8 @@ class LazySet {
 	}
 
 	/**
+	 * Queues another iterable or lazy set for later merging so large bulk adds
+	 * can stay cheap until the set is read.
 	 * @param {Iterable<T> | LazySet<T>} iterable a immutable iterable or another immutable LazySet which will eventually be merged into the Set
 	 * @returns {LazySet<T>} itself
 	 */
@@ -126,6 +149,9 @@ class LazySet {
 		return this;
 	}
 
+	/**
+	 * Removes all items and clears every deferred merge queue.
+	 */
 	clear() {
 		this._set.clear();
 		this._toMerge.clear();
@@ -135,6 +161,8 @@ class LazySet {
 	}
 
 	/**
+	 * Deletes an item after first materializing any deferred additions that may
+	 * contain it.
 	 * @param {T} value an item
 	 * @returns {boolean} true, if the value was in the Set before
 	 */
@@ -144,6 +172,8 @@ class LazySet {
 	}
 
 	/**
+	 * Returns the set's entry iterator and permanently switches future
+	 * operations to eager merge mode to preserve iterator correctness.
 	 * @returns {SetIterator<[T, T]>} entries
 	 */
 	entries() {
@@ -153,6 +183,8 @@ class LazySet {
 	}
 
 	/**
+	 * Iterates over every item after forcing pending merges and switching to
+	 * eager mode for correctness during iteration.
 	 * @template K
 	 * @param {(value: T, value2: T, set: Set<T>) => void} callbackFn function called for each entry
 	 * @param {K} thisArg this argument for the callbackFn
@@ -166,6 +198,7 @@ class LazySet {
 	}
 
 	/**
+	 * Checks whether an item is present after applying any deferred merges.
 	 * @param {T} item an item
 	 * @returns {boolean} true, when the item is in the Set
 	 */
@@ -175,6 +208,7 @@ class LazySet {
 	}
 
 	/**
+	 * Returns the key iterator, eagerly materializing pending merges first.
 	 * @returns {SetIterator<T>} keys
 	 */
 	keys() {
@@ -184,6 +218,7 @@ class LazySet {
 	}
 
 	/**
+	 * Returns the value iterator, eagerly materializing pending merges first.
 	 * @returns {SetIterator<T>} values
 	 */
 	values() {
@@ -193,6 +228,7 @@ class LazySet {
 	}
 
 	/**
+	 * Returns the default iterator over values after forcing pending merges.
 	 * @returns {SetIterator<T>} iterable iterator
 	 */
 	[Symbol.iterator]() {
@@ -207,6 +243,8 @@ class LazySet {
 	}
 
 	/**
+	 * Serializes the fully materialized set contents into webpack's object
+	 * serialization stream.
 	 * @param {import("../serialization/ObjectMiddleware").ObjectSerializerContext} context context
 	 */
 	serialize({ write }) {
@@ -216,6 +254,7 @@ class LazySet {
 	}
 
 	/**
+	 * Restores a `LazySet` from serialized item data.
 	 * @template T
 	 * @param {import("../serialization/ObjectMiddleware").ObjectDeserializerContext} context context
 	 * @returns {LazySet<T>} lazy set

package/lib/util/ParallelismFactorCalculator.js

@@ -18,6 +18,7 @@ class ParallelismFactorCalculator {
 	}
 
 	/**
+	 * Processes the provided start.
 	 * @param {number} start range start
 	 * @param {number} end range end
 	 * @param {Callback} callback callback

package/lib/util/Queue.js

@@ -6,10 +6,13 @@
 "use strict";
 
 /**
+ * FIFO queue that keeps items unique by storing them in insertion order inside
+ * a `Set`.
  * @template T
  */
 class Queue {
 	/**
+	 * Seeds the queue with an optional iterable of initial unique items.
 	 * @param {Iterable<T>=} items The initial elements.
 	 */
 	constructor(items) {
@@ -21,7 +24,7 @@ class Queue {
 	}
 
 	/**
-	 * Returns the number of elements in this queue.
+	 * Returns the number of unique items currently waiting in the queue.
 	 * @returns {number} The number of elements in this queue.
 	 */
 	get length() {
@@ -29,7 +32,7 @@ class Queue {
 	}
 
 	/**
-	 * Appends the specified element to this queue.
+	 * Enqueues an item, moving nothing if that value is already present.
 	 * @param {T} item The element to add.
 	 * @returns {void}
 	 */
@@ -38,7 +41,7 @@ class Queue {
 	}
 
 	/**
-	 * Retrieves and removes the head of this queue.
+	 * Removes and returns the oldest enqueued item.
 	 * @returns {T | undefined} The head of the queue of `undefined` if this queue is empty.
 	 */
 	dequeue() {

package/lib/util/Semaphore.js

@@ -5,9 +5,14 @@
 
 "use strict";
 
+/**
+ * Simple counting semaphore used to limit how many asynchronous tasks may run
+ * concurrently.
+ */
 class Semaphore {
 	/**
-	 * Creates an instance of Semaphore.
+	 * Initializes the semaphore with the number of permits that may be held at
+	 * the same time.
 	 * @param {number} available the amount available number of "tasks"
 	 * in the Semaphore
 	 */
@@ -20,6 +25,8 @@ class Semaphore {
 	}
 
 	/**
+	 * Acquires a permit for the callback immediately when one is available or
+	 * queues the callback until another task releases its permit.
 	 * @param {() => void} callback function block to capture and run
 	 * @returns {void}
 	 */
@@ -32,6 +39,9 @@ class Semaphore {
 		}
 	}
 
+	/**
+	 * Releases a permit and schedules the next waiting callback, if any.
+	 */
 	release() {
 		this.available++;
 		if (this.waiters.length > 0) {
@@ -39,6 +49,9 @@ class Semaphore {
 		}
 	}
 
+	/**
+	 * Drains the next waiting callback after a permit becomes available.
+	 */
 	_continue() {
 		if (this.available > 0 && this.waiters.length > 0) {
 			this.available--;

package/lib/util/SetHelpers.js

@@ -52,6 +52,7 @@ const isSubset = (bigSet, smallSet) => {
 };
 
 /**
+ * Returns found item.
  * @template T
  * @param {Set<T>} set a set
  * @param {(set: T) => boolean} fn selector function
@@ -64,6 +65,7 @@ const find = (set, fn) => {
 };
 
 /**
+ * Returns first item.
  * @template T
  * @param {Set<T> | ReadonlySet<T>} set a set
  * @returns {T | undefined} first item
@@ -74,6 +76,7 @@ const first = (set) => {
 };
 
 /**
+ * Returns combined set, may be identical to a or b.
  * @template T
  * @param {Set<T>} a first
  * @param {Set<T>} b second

package/lib/util/SortableSet.js

@@ -47,6 +47,7 @@ class SortableSet extends Set {
 	}
 
 	/**
+	 * Returns itself.
 	 * @param {T} value value to add to set
 	 * @returns {this} returns itself
 	 */
@@ -59,6 +60,7 @@ class SortableSet extends Set {
 	}
 
 	/**
+	 * Returns true if value existed in set, false otherwise.
 	 * @param {T} value value to delete
 	 * @returns {boolean} true if value existed in set, false otherwise
 	 */
@@ -69,6 +71,7 @@ class SortableSet extends Set {
 	}
 
 	/**
+	 * Describes how this clear operation behaves.
 	 * @returns {void}
 	 */
 	clear() {
@@ -146,6 +149,7 @@ class SortableSet extends Set {
 	}
 
 	/**
+	 * Invalidates the cached state associated with this value.
 	 * @private
 	 * @returns {void}
 	 */
@@ -156,6 +160,7 @@ class SortableSet extends Set {
 	}
 
 	/**
+	 * Invalidate ordered cache.
 	 * @private
 	 * @returns {void}
 	 */
@@ -166,6 +171,7 @@ class SortableSet extends Set {
 	}
 
 	/**
+	 * Returns the raw array.
 	 * @returns {T[]} the raw array
 	 */
 	toJSON() {

package/lib/util/StackedCacheMap.js

@@ -31,6 +31,10 @@
  * @template V
  */
 class StackedCacheMap {
+	/**
+	 * Initializes the mutable fallback map and the stack of immutable cache
+	 * layers.
+	 */
 	constructor() {
 		/** @type {Map<K, V>} */
 		this.map = new Map();
@@ -39,9 +43,9 @@ class StackedCacheMap {
 	}
 
 	/**
-	 * If `immutable` is true, the map can be referenced by the StackedCacheMap
-	 * and should not be changed afterwards. If the map is mutable, all items
-	 * are copied into a fallback Map.
+	 * Adds another cache layer. Immutable maps are retained by reference and
+	 * reordered so larger layers are checked first, while mutable maps are
+	 * copied into the fallback map.
 	 * @param {ReadonlyMap<K, V>} map map to add
 	 * @param {boolean=} immutable if 'map' is immutable and StackedCacheMap can keep referencing it
 	 */
@@ -64,6 +68,7 @@ class StackedCacheMap {
 	}
 
 	/**
+	 * Stores or overrides a value in the mutable fallback map.
 	 * @param {K} item the key of the element to add
 	 * @param {V} value the value of the element to add
 	 * @returns {void}
@@ -73,6 +78,8 @@ class StackedCacheMap {
 	}
 
 	/**
+	 * Rejects deletions because this data structure is optimized for append-only
+	 * cache layers.
 	 * @param {K} item the item to delete
 	 * @returns {void}
 	 */
@@ -81,6 +88,8 @@ class StackedCacheMap {
 	}
 
 	/**
+	 * Rejects `has` checks because they would force the same layered lookup work
+	 * as `get` without returning the cached value.
 	 * @param {K} item the item to test
 	 * @returns {boolean} true if the item exists in this set
 	 */
@@ -91,6 +100,8 @@ class StackedCacheMap {
 	}
 
 	/**
+	 * Looks up a key by scanning immutable cache layers first and then the
+	 * mutable fallback map.
 	 * @param {K} item the key of the element to return
 	 * @returns {V | undefined} the value of the element
 	 */
@@ -102,12 +113,17 @@ class StackedCacheMap {
 		return this.map.get(item);
 	}
 
+	/**
+	 * Removes every cache layer and clears the mutable fallback map.
+	 */
 	clear() {
 		this.stack.length = 0;
 		this.map.clear();
 	}
 
 	/**
+	 * Returns the total number of entries across the fallback map and all stacked
+	 * cache layers.
 	 * @returns {number} size of the map
 	 */
 	get size() {
@@ -119,6 +135,7 @@ class StackedCacheMap {
 	}
 
 	/**
+	 * Iterates over the fallback map first and then each stacked cache layer.
 	 * @returns {Iterator<[K, V]>} iterator
 	 */
 	[Symbol.iterator]() {