webpack 5.106.0 → 5.106.2

package/lib/util/StackedMap.js

@@ -9,16 +9,22 @@ const TOMBSTONE = Symbol("tombstone");
 const UNDEFINED_MARKER = Symbol("undefined");
 
 /**
+ * Public cell value exposed by `StackedMap`, where `undefined` is preserved as
+ * a valid stored result.
  * @template T
  * @typedef {T | undefined} Cell<T>
  */
 
 /**
+ * Internal cell value used to distinguish deleted entries and explicit
+ * `undefined` assignments while traversing stacked scopes.
  * @template T
  * @typedef {T | typeof TOMBSTONE | typeof UNDEFINED_MARKER} InternalCell<T>
  */
 
 /**
+ * Converts an internal key/value pair into the external representation returned
+ * by iteration helpers.
  * @template K
  * @template V
  * @param {[K, InternalCell<V>]} pair the internal cell
@@ -34,11 +40,14 @@ const extractPair = (pair) => {
 };
 
 /**
+ * Layered map that supports child scopes while memoizing lookups from parent
+ * scopes into the current layer.
  * @template K
  * @template V
  */
 class StackedMap {
 	/**
+	 * Creates a new map layer on top of an optional parent stack.
 	 * @param {Map<K, InternalCell<V>>[]=} parentStack an optional parent
 	 */
 	constructor(parentStack) {
@@ -50,6 +59,8 @@ class StackedMap {
 	}
 
 	/**
+	 * Stores a value in the current layer, preserving explicit `undefined`
+	 * values with an internal marker.
 	 * @param {K} item the key of the element to add
 	 * @param {V} value the value of the element to add
 	 * @returns {void}
@@ -59,6 +70,8 @@ class StackedMap {
 	}
 
 	/**
+	 * Deletes a key from the current view, either by removing it outright in the
+	 * root layer or by recording a tombstone in child layers.
 	 * @param {K} item the item to delete
 	 * @returns {void}
 	 */
@@ -71,6 +84,8 @@ class StackedMap {
 	}
 
 	/**
+	 * Checks whether a key exists in the current scope chain, caching any parent
+	 * lookup result in the current layer.
 	 * @param {K} item the item to test
 	 * @returns {boolean} true if the item exists in this set
 	 */
@@ -93,6 +108,8 @@ class StackedMap {
 	}
 
 	/**
+	 * Returns the visible value for a key, caching parent hits and misses in the
+	 * current layer.
 	 * @param {K} item the key of the element to return
 	 * @returns {Cell<V>} the value of the element
 	 */
@@ -117,6 +134,9 @@ class StackedMap {
 		}
 	}
 
+	/**
+	 * Collapses the stacked layers into a single concrete map.
+	 */
 	_compress() {
 		if (this.stack.length === 1) return;
 		this.map = new Map();
@@ -132,30 +152,55 @@ class StackedMap {
 		this.stack = [this.map];
 	}
 
+	/**
+	 * Returns the visible keys as an array after collapsing the stack.
+	 * @returns {K[]} array of keys
+	 */
 	asArray() {
 		this._compress();
 		return [...this.map.keys()];
 	}
 
+	/**
+	 * Returns the visible keys as a `Set` after collapsing the stack.
+	 * @returns {Set<K>} set of keys
+	 */
 	asSet() {
 		this._compress();
 		return new Set(this.map.keys());
 	}
 
+	/**
+	 * Returns visible key/value pairs using the external representation.
+	 * @returns {[K, Cell<V>][]} array of key/value pairs
+	 */
 	asPairArray() {
 		this._compress();
 		return Array.from(this.map.entries(), extractPair);
 	}
 
+	/**
+	 * Returns the visible contents as a plain `Map`.
+	 * @returns {Map<K, Cell<V>>} materialized map
+	 */
 	asMap() {
 		return new Map(this.asPairArray());
 	}
 
+	/**
+	 * Returns the number of visible keys after collapsing the stack.
+	 * @returns {number} number of keys
+	 */
 	get size() {
 		this._compress();
 		return this.map.size;
 	}
 
+	/**
+	 * Creates a child `StackedMap` that sees the current layers as its parent
+	 * scope.
+	 * @returns {StackedMap<K, V>} child map
+	 */
 	createChild() {
 		return new StackedMap(this.stack);
 	}

package/lib/util/StringXor.js

@@ -41,7 +41,7 @@ class StringXor {
 	}
 
 	/**
-	 * Adds a string to the current StringXor object.
+	 * Processes the provided str.
 	 * @param {string} str string
 	 * @returns {void}
 	 */

package/lib/util/TupleQueue.js

@@ -8,11 +8,14 @@
 const TupleSet = require("./TupleSet");
 
 /**
+ * FIFO queue for tuples that preserves uniqueness by delegating membership
+ * tracking to `TupleSet`.
  * @template T
  * @template V
  */
 class TupleQueue {
 	/**
+	 * Seeds the queue with an optional iterable of tuples to visit.
 	 * @param {Iterable<[T, V, ...EXPECTED_ANY]>=} items The initial elements.
 	 */
 	constructor(items) {
@@ -29,7 +32,7 @@ class TupleQueue {
 	}
 
 	/**
-	 * Returns the number of elements in this queue.
+	 * Returns the number of distinct tuples currently queued.
 	 * @returns {number} The number of elements in this queue.
 	 */
 	get length() {
@@ -37,7 +40,7 @@ class TupleQueue {
 	}
 
 	/**
-	 * Appends the specified element to this queue.
+	 * Enqueues a tuple if it is not already present in the underlying set.
 	 * @param {[T, V, ...EXPECTED_ANY]} item The element to add.
 	 * @returns {void}
 	 */
@@ -46,7 +49,8 @@ class TupleQueue {
 	}
 
 	/**
-	 * Retrieves and removes the head of this queue.
+	 * Removes and returns the next queued tuple, rebuilding the iterator when
+	 * the underlying tuple set has changed since the last full pass.
 	 * @returns {[T, V, ...EXPECTED_ANY] | undefined} The head of the queue of `undefined` if this queue is empty.
 	 */
 	dequeue() {

package/lib/util/TupleSet.js

@@ -6,17 +6,22 @@
 "use strict";
 
 /**
+ * Nested map structure used to index tuple prefixes until the final tuple
+ * element can be stored in a `Set`.
  * @template K
  * @template V
  * @typedef {Map<K, InnerMap<K, V> | Set<V>>} InnerMap
  */
 
 /**
+ * Stores tuples of arbitrary length while preserving efficient prefix lookups
+ * through a tree of maps that ends in a set of final values.
  * @template T
  * @template V
  */
 class TupleSet {
 	/**
+	 * Seeds the tuple set with an optional iterable of tuples.
 	 * @param {Iterable<[T, V, ...EXPECTED_ANY]>=} init init
 	 */
 	constructor(init) {
@@ -31,6 +36,7 @@ class TupleSet {
 	}
 
 	/**
+	 * Adds a tuple to the set, creating any missing prefix maps along the way.
 	 * @param {[T, V, ...EXPECTED_ANY]} args tuple
 	 * @returns {void}
 	 */
@@ -59,6 +65,7 @@ class TupleSet {
 	}
 
 	/**
+	 * Checks whether the exact tuple is already present in the set.
 	 * @param {[T, V, ...EXPECTED_ANY]} args tuple
 	 * @returns {boolean} true, if the tuple is in the Set
 	 */
@@ -83,6 +90,7 @@ class TupleSet {
 	}
 
 	/**
+	 * Removes a tuple from the set when it is present.
 	 * @param {[T, V, ...EXPECTED_ANY]} args tuple
 	 * @returns {void}
 	 */
@@ -109,10 +117,13 @@ class TupleSet {
 	}
 
 	/**
+	 * Iterates over every stored tuple by walking the nested map structure and
+	 * yielding each complete prefix plus its terminal set value.
 	 * @returns {Iterator<[T, V, ...EXPECTED_ANY]>} iterator
 	 */
 	[Symbol.iterator]() {
 		/**
+		 * Iterator type used while traversing nested tuple-prefix maps.
 		 * @template T, V
 		 * @typedef {MapIterator<[T, InnerMap<T, V> | Set<V>]>} IteratorStack
 		 */
@@ -127,6 +138,8 @@ class TupleSet {
 		let currentSetIterator;
 
 		/**
+		 * Advances through nested maps until a terminal value set is reached or
+		 * every remaining branch has been exhausted.
 		 * @param {IteratorStack<T, V>} it iterator
 		 * @returns {boolean} result
 		 */

package/lib/util/URLAbsoluteSpecifier.js

@@ -74,6 +74,7 @@ function getScheme(specifier) {
 }
 
 /**
+ * Returns protocol if absolute URL specifier provided.
  * @param {string} specifier specifier
  * @returns {string | null | undefined} protocol if absolute URL specifier provided
  */

package/lib/util/WeakTupleMap.js

@@ -6,33 +6,44 @@
 "use strict";
 
 /**
+ * Strong-key child map used for tuple elements that cannot be stored in a
+ * `WeakMap`.
  * @template {EXPECTED_ANY[]} T
  * @template V
  * @typedef {Map<EXPECTED_ANY, WeakTupleMap<T, V>>} M
  */
 
 /**
+ * Weak-key child map used for tuple elements that are objects and can be held
+ * without preventing garbage collection.
  * @template {EXPECTED_ANY[]} T
  * @template V
  * @typedef {WeakMap<EXPECTED_OBJECT, WeakTupleMap<T, V>>} W
  */
 
 /**
+ * Reports whether a tuple element can be stored in a `WeakMap`.
  * @param {EXPECTED_ANY} thing thing
  * @returns {boolean} true if is weak
  */
 const isWeakKey = (thing) => typeof thing === "object" && thing !== null;
 
 /**
+ * Extracts the element type from a tuple-like array.
  * @template {unknown[]} T
  * @typedef {T extends ReadonlyArray<infer ElementType> ? ElementType : never} ArrayElement
  */
 
 /**
+ * Stores values by tuple keys while using `WeakMap` for object elements so the
+ * cache can release entries when those objects are collected.
  * @template {EXPECTED_ANY[]} K
  * @template V
  */
 class WeakTupleMap {
+	/**
+	 * Initializes an empty tuple trie node with optional value and child maps.
+	 */
 	constructor() {
 		/** @private */
 		this.f = 0;
@@ -54,6 +65,7 @@ class WeakTupleMap {
 	}
 
 	/**
+	 * Stores a value at the node identified by the provided tuple key.
 	 * @param {[...K, V]} args tuple
 	 * @returns {void}
 	 */
@@ -67,6 +79,7 @@ class WeakTupleMap {
 	}
 
 	/**
+	 * Checks whether the exact tuple key has a stored value.
 	 * @param {K} args tuple
 	 * @returns {boolean} true, if the tuple is in the Set
 	 */
@@ -81,6 +94,7 @@ class WeakTupleMap {
 	}
 
 	/**
+	 * Returns the value stored for the exact tuple key, if any.
 	 * @param {K} args tuple
 	 * @returns {V | undefined} the value
 	 */
@@ -95,6 +109,8 @@ class WeakTupleMap {
 	}
 
 	/**
+	 * Returns an existing value for the tuple or computes, stores, and returns a
+	 * new one when the tuple is missing.
 	 * @param {[...K, (...args: K) => V]} args tuple
 	 * @returns {V} the value
 	 */
@@ -112,6 +128,7 @@ class WeakTupleMap {
 	}
 
 	/**
+	 * Removes the value stored for the tuple key without pruning the trie.
 	 * @param {K} args tuple
 	 * @returns {void}
 	 */
@@ -126,6 +143,7 @@ class WeakTupleMap {
 	}
 
 	/**
+	 * Clears the stored value and all strong and weak child maps from this node.
 	 * @returns {void}
 	 */
 	clear() {
@@ -135,15 +153,24 @@ class WeakTupleMap {
 		this.m = undefined;
 	}
 
+	/**
+	 * Returns the value stored directly on this trie node.
+	 * @returns {V | undefined} stored value
+	 */
 	_getValue() {
 		return this.v;
 	}
 
+	/**
+	 * Reports whether this trie node currently stores a value.
+	 * @returns {boolean} true when a value is present
+	 */
 	_hasValue() {
 		return (this.f & 1) === 1;
 	}
 
 	/**
+	 * Stores a value directly on this trie node.
 	 * @param {V} v value
 	 * @private
 	 */
@@ -152,12 +179,16 @@ class WeakTupleMap {
 		this.v = v;
 	}
 
+	/**
+	 * Removes the value stored directly on this trie node.
+	 */
 	_deleteValue() {
 		this.f &= 6;
 		this.v = undefined;
 	}
 
 	/**
+	 * Returns the child node for a tuple element without creating one.
 	 * @param {ArrayElement<K>} thing thing
 	 * @returns {WeakTupleMap<K, V> | undefined} thing
 	 * @private
@@ -176,6 +207,8 @@ class WeakTupleMap {
 	}
 
 	/**
+	 * Returns the child node for a tuple element, creating and storing it when
+	 * necessary.
 	 * @private
 	 * @param {ArrayElement<K>} thing thing
 	 * @returns {WeakTupleMap<K, V>} value

package/lib/util/binarySearchBounds.js

@@ -65,6 +65,7 @@ const compileSearch = (funcName, predicate, reversed, extraArgs, earlyOut) => {
 };
 
 /**
+ * Defines the search type used by this module.
  * @template T
  * @typedef {(items: T[], start: number, compareFn?: number | ((item: T, needle: number) => number), l?: number, h?: number) => number} Search
  */

package/lib/util/cleverMerge.js

@@ -51,6 +51,7 @@ const cachedCleverMerge = (first, second) => {
 };
 
 /**
+ * Caches d set property.
  * @template T
  * @param {Partial<T>} obj object
  * @param {string} property property
@@ -86,10 +87,12 @@ const cachedSetProperty = (obj, property, value) => {
 };
 
 /**
+ * Defines the by values type used by this module.
  * @typedef {Map<string, EXPECTED_ANY>} ByValues
  */
 
 /**
+ * Defines the object parsed property entry type used by this module.
  * @template T
  * @typedef {object} ObjectParsedPropertyEntry
  * @property {T[keyof T] | undefined} base base value
@@ -100,16 +103,19 @@ const cachedSetProperty = (obj, property, value) => {
 /** @typedef {(function(...EXPECTED_ANY): object) & { [DYNAMIC_INFO]: [DynamicFunction, object] }} DynamicFunction */
 
 /**
+ * Defines the parsed object static type used by this module.
  * @template {object} T
  * @typedef {Map<keyof T, ObjectParsedPropertyEntry<T>>} ParsedObjectStatic
  */
 
 /**
+ * Defines the parsed object dynamic type used by this module.
  * @template {object} T
  * @typedef {{ byProperty: `by${string}`, fn: DynamicFunction }} ParsedObjectDynamic
  */
 
 /**
+ * Defines the parsed object type used by this module.
  * @template {object} T
  * @typedef {object} ParsedObject
  * @property {ParsedObjectStatic<T>} static static properties (key is property name)
@@ -120,6 +126,7 @@ const cachedSetProperty = (obj, property, value) => {
 const parseCache = new WeakMap();
 
 /**
+ * Caches d parse object.
  * @template {object} T
  * @param {T} obj the object
  * @returns {ParsedObject<T>} parsed object
@@ -135,6 +142,7 @@ const cachedParseObject = (obj) => {
 /** @typedef {{ [p: string]: { [p: string]: EXPECTED_ANY } } | DynamicFunction} ByObject */
 
 /**
+ * Returns parsed object.
  * @template {object} T
  * @param {T} obj the object
  * @returns {ParsedObject<T>} parsed object
@@ -145,6 +153,7 @@ const parseObject = (obj) => {
 	/** @type {ParsedObjectDynamic<T> | undefined} */
 	let dynamicInfo;
 	/**
+	 * Returns object parsed property entry.
 	 * @param {keyof T} p path
 	 * @returns {Partial<ObjectParsedPropertyEntry<T>>} object parsed property entry
 	 */
@@ -221,6 +230,7 @@ const parseObject = (obj) => {
 };
 
 /**
+ * Returns the object.
  * @template {object} T
  * @param {ParsedObjectStatic<T>} info static properties (key is property name)
  * @param {{ byProperty: `by${string}`, fn: DynamicFunction } | undefined} dynamicInfo dynamic part
@@ -269,6 +279,7 @@ const VALUE_TYPE_OBJECT = 3;
 const VALUE_TYPE_DELETE = 4;
 
 /**
+ * Returns value type.
  * @template T
  * @param {T} value a single value
  * @returns {VALUE_TYPE_UNDEFINED | VALUE_TYPE_ATOM | VALUE_TYPE_ARRAY_EXTEND | VALUE_TYPE_OBJECT | VALUE_TYPE_DELETE} value type
@@ -311,6 +322,7 @@ const cleverMerge = (first, second) => {
 };
 
 /**
+ * Returns merged object of first and second object.
  * @template {object} T
  * @template {object} O
  * Merges two objects. Objects are deeply clever merged.
@@ -378,6 +390,7 @@ const _cleverMerge = (first, second, internalCaching = false) => {
 };
 
 /**
+ * Merges the provided values into a single result.
  * @template T, O
  * @param {ObjectParsedPropertyEntry<T>} firstEntry a
  * @param {ObjectParsedPropertyEntry<O>} secondEntry b
@@ -510,6 +523,7 @@ const mergeEntries = (firstEntry, secondEntry, internalCaching) => {
 };
 
 /**
+ * Gets from by values.
  * @template V
  * @param {ByValues} byValues all values
  * @param {string} key value of the selector
@@ -523,6 +537,7 @@ const getFromByValues = (byValues, key) => {
 };
 
 /**
+ * Merges single value.
  * @template A
  * @template B
  * @param {A | A[]} a value
@@ -585,6 +600,7 @@ const mergeSingleValue = (a, b, internalCaching) => {
 };
 
 /**
+ * Removes operations.
  * @template {object} T
  * @param {T} obj the object
  * @param {(keyof T)[]=} keysToKeepOriginalValue keys to keep original value
@@ -632,6 +648,7 @@ const removeOperations = (obj, keysToKeepOriginalValue = []) => {
 };
 
 /**
+ * Resolves by property.
  * @template T
  * @template {keyof T} P
  * @template V