Merge pull request #17060 from webpack/thelarkinn/rename-map-helper

refactor(MapHelpers): rename `provide` to `getOrInsert` in MapHelpers and document it better

lib/CodeGenerationResults.js

@@ -5,7 +5,7 @@
 
 "use strict";
 
-const { provide } = require("./util/MapHelpers");
+const { getOrInsert } = require("./util/MapHelpers");
 const { first } = require("./util/SetHelpers");
 const createHash = require("./util/createHash");
 const { runtimeToString, RuntimeSpecMap } = require("./util/runtime");
@@ -147,7 +147,7 @@ Caller might not support runtime-dependent code generation (opt-out via optimiza
 	 * @returns {void}
 	 */
 	add(module, runtime, result) {
-		const map = provide(this.map, module, () => new RuntimeSpecMap());
+		const map = getOrInsert(this.map, module, () => new RuntimeSpecMap());
 		map.set(runtime, result);
 	}
 }

lib/Compilation.js

@@ -61,7 +61,7 @@ const StatsPrinter = require("./stats/StatsPrinter");
 const { equals: arrayEquals } = require("./util/ArrayHelpers");
 const AsyncQueue = require("./util/AsyncQueue");
 const LazySet = require("./util/LazySet");
-const { provide } = require("./util/MapHelpers");
+const { getOrInsert } = require("./util/MapHelpers");
 const WeakTupleMap = require("./util/WeakTupleMap");
 const { cachedCleverMerge } = require("./util/cleverMerge");
 const {
@@ -2618,7 +2618,7 @@ BREAKING CHANGE: Asset processing hooks in Compilation has been merged into a si
 			const logByLoadersSummary = (category, getDuration, getParallelism) => {
 				const map = new Map();
 				for (const [module, profile] of modulesWithProfiles) {
-					const list = provide(
+					const list = getOrInsert(
 						map,
 						module.type + "!" + module.identifier().replace(/(!|^)[^!]*$/, ""),
 						() => []

lib/util/MapHelpers.js

@@ -6,16 +6,30 @@
 "use strict";
 
 /**
+ * getOrInsert is a helper function for maps that allows you to get a value
+ * from a map if it exists, or insert a new value if it doesn't. If it value doesn't
+ * exist, it will be computed by the provided function.
+ *
  * @template K
  * @template V
- * @param {Map<K, V>} map a map
- * @param {K} key the key
- * @param {function(): V} computer compute value
- * @returns {V} value
+ * @param {Map<K, V>} map The map object to check
+ * @param {K} key The key to check
+ * @param {function(): V} computer function which will compute the value if it doesn't exist
+ * @returns {V} The value from the map, or the computed value
+ *
+ * @example
+ * ```js
+ * const map = new Map();
+ * const value = getOrInsert(map, "key", () => "value");
+ * console.log(value); // "value"
+ * ```
  */
-exports.provide = (map, key, computer) => {
+exports.getOrInsert = (map, key, computer) => {
+	// Grab key from map
 	const value = map.get(key);
+	// If the value already exists, return it
 	if (value !== undefined) return value;
+	// Otherwise compute the value, set it in the map, and return it
 	const newValue = computer();
 	map.set(key, newValue);
 	return newValue;