webpack 5.59.0 → 5.94.0

package/lib/stats/StatsFactory.js

@@ -11,83 +11,108 @@ const smartGrouping = require("../util/smartGrouping");
 
 /** @typedef {import("../Chunk")} Chunk */
 /** @typedef {import("../Compilation")} Compilation */
+/** @typedef {import("../Compilation").NormalizedStatsOptions} NormalizedStatsOptions */
 /** @typedef {import("../Module")} Module */
 /** @typedef {import("../WebpackError")} WebpackError */
+/** @typedef {import("../util/comparators").Comparator<any>} Comparator */
 /** @typedef {import("../util/runtime").RuntimeSpec} RuntimeSpec */
-
 /** @typedef {import("../util/smartGrouping").GroupConfig<any, object>} GroupConfig */
 
 /**
- * @typedef {Object} KnownStatsFactoryContext
+ * @typedef {object} KnownStatsFactoryContext
  * @property {string} type
- * @property {function(string): string=} makePathsRelative
- * @property {Compilation=} compilation
- * @property {Set<Module>=} rootModules
- * @property {Map<string,Chunk[]>=} compilationFileToChunks
- * @property {Map<string,Chunk[]>=} compilationAuxiliaryFileToChunks
- * @property {RuntimeSpec=} runtime
- * @property {function(Compilation): WebpackError[]=} cachedGetErrors
- * @property {function(Compilation): WebpackError[]=} cachedGetWarnings
+ * @property {function(string): string} makePathsRelative
+ * @property {Compilation} compilation
+ * @property {Set<Module>} rootModules
+ * @property {Map<string,Chunk[]>} compilationFileToChunks
+ * @property {Map<string,Chunk[]>} compilationAuxiliaryFileToChunks
+ * @property {RuntimeSpec} runtime
+ * @property {function(Compilation): WebpackError[]} cachedGetErrors
+ * @property {function(Compilation): WebpackError[]} cachedGetWarnings
+ */
+
+/** @typedef {Record<string, any> & KnownStatsFactoryContext} StatsFactoryContext */
+
+/** @typedef {any} CreatedObject */
+/** @typedef {any} FactoryData */
+/** @typedef {any} FactoryDataItem */
+/** @typedef {any} Result */
+/** @typedef {Record<string, any>} ObjectForExtract */
+
+/**
+ * @typedef {object} StatsFactoryHooks
+ * @property {HookMap<SyncBailHook<[ObjectForExtract, FactoryData, StatsFactoryContext], undefined>>} extract
+ * @property {HookMap<SyncBailHook<[FactoryDataItem, StatsFactoryContext, number, number], boolean | undefined>>} filter
+ * @property {HookMap<SyncBailHook<[Comparator[], StatsFactoryContext], undefined>>} sort
+ * @property {HookMap<SyncBailHook<[FactoryDataItem, StatsFactoryContext, number, number], boolean | undefined>>} filterSorted
+ * @property {HookMap<SyncBailHook<[GroupConfig[], StatsFactoryContext], undefined>>} groupResults
+ * @property {HookMap<SyncBailHook<[Comparator[], StatsFactoryContext], undefined>>} sortResults
+ * @property {HookMap<SyncBailHook<[FactoryDataItem, StatsFactoryContext, number, number], boolean | undefined>>} filterResults
+ * @property {HookMap<SyncBailHook<[FactoryDataItem[], StatsFactoryContext], Result>>} merge
+ * @property {HookMap<SyncBailHook<[Result, StatsFactoryContext], Result>>} result
+ * @property {HookMap<SyncBailHook<[FactoryDataItem, StatsFactoryContext], string>>} getItemName
+ * @property {HookMap<SyncBailHook<[FactoryDataItem, StatsFactoryContext], StatsFactory | undefined>>} getItemFactory
  */
 
-/** @typedef {KnownStatsFactoryContext & Record<string, any>} StatsFactoryContext */
+/**
+ * @template T
+ * @typedef {Map<string, T[]>} Caches
+ */
 
 class StatsFactory {
 	constructor() {
+		/** @type {StatsFactoryHooks} */
 		this.hooks = Object.freeze({
-			/** @type {HookMap<SyncBailHook<[Object, any, StatsFactoryContext]>>} */
 			extract: new HookMap(
 				() => new SyncBailHook(["object", "data", "context"])
 			),
-			/** @type {HookMap<SyncBailHook<[any, StatsFactoryContext, number, number]>>} */
 			filter: new HookMap(
 				() => new SyncBailHook(["item", "context", "index", "unfilteredIndex"])
 			),
-			/** @type {HookMap<SyncBailHook<[(function(any, any): number)[], StatsFactoryContext]>>} */
 			sort: new HookMap(() => new SyncBailHook(["comparators", "context"])),
-			/** @type {HookMap<SyncBailHook<[any, StatsFactoryContext, number, number]>>} */
 			filterSorted: new HookMap(
 				() => new SyncBailHook(["item", "context", "index", "unfilteredIndex"])
 			),
-			/** @type {HookMap<SyncBailHook<[GroupConfig[], StatsFactoryContext]>>} */
 			groupResults: new HookMap(
 				() => new SyncBailHook(["groupConfigs", "context"])
 			),
-			/** @type {HookMap<SyncBailHook<[(function(any, any): number)[], StatsFactoryContext]>>} */
 			sortResults: new HookMap(
 				() => new SyncBailHook(["comparators", "context"])
 			),
-			/** @type {HookMap<SyncBailHook<[any, StatsFactoryContext, number, number]>>} */
 			filterResults: new HookMap(
 				() => new SyncBailHook(["item", "context", "index", "unfilteredIndex"])
 			),
-			/** @type {HookMap<SyncBailHook<[any[], StatsFactoryContext]>>} */
 			merge: new HookMap(() => new SyncBailHook(["items", "context"])),
-			/** @type {HookMap<SyncBailHook<[any[], StatsFactoryContext]>>} */
 			result: new HookMap(() => new SyncWaterfallHook(["result", "context"])),
-			/** @type {HookMap<SyncBailHook<[any, StatsFactoryContext]>>} */
 			getItemName: new HookMap(() => new SyncBailHook(["item", "context"])),
-			/** @type {HookMap<SyncBailHook<[any, StatsFactoryContext]>>} */
 			getItemFactory: new HookMap(() => new SyncBailHook(["item", "context"]))
 		});
 		const hooks = this.hooks;
-		this._caches =
-			/** @type {Record<keyof typeof hooks, Map<string, SyncBailHook<[any[], StatsFactoryContext]>[]>>} */ ({});
+		this._caches = /** @type {TODO} */ ({});
 		for (const key of Object.keys(hooks)) {
-			this._caches[key] = new Map();
+			this._caches[/** @type {keyof StatsFactoryHooks} */ (key)] = new Map();
 		}
 		this._inCreate = false;
 	}
 
+	/**
+	 * @template {StatsFactoryHooks[keyof StatsFactoryHooks]} HM
+	 * @template {HM extends HookMap<infer H> ? H : never} H
+	 * @param {HM} hookMap hook map
+	 * @param {Caches<H>} cache cache
+	 * @param {string} type type
+	 * @returns {H[]} hooks
+	 * @private
+	 */
 	_getAllLevelHooks(hookMap, cache, type) {
 		const cacheEntry = cache.get(type);
 		if (cacheEntry !== undefined) {
 			return cacheEntry;
 		}
-		const hooks = [];
+		const hooks = /** @type {H[]} */ ([]);
 		const typeParts = type.split(".");
 		for (let i = 0; i < typeParts.length; i++) {
-			const hook = hookMap.get(typeParts.slice(i).join("."));
+			const hook = /** @type {H} */ (hookMap.get(typeParts.slice(i).join(".")));
 			if (hook) {
 				hooks.push(hook);
 			}
@@ -96,27 +121,62 @@ class StatsFactory {
 		return hooks;
 	}
 
+	/**
+	 * @template {StatsFactoryHooks[keyof StatsFactoryHooks]} HM
+	 * @template {HM extends HookMap<infer H> ? H : never} H
+	 * @template {H extends import("tapable").Hook<any, infer R> ? R : never} R
+	 * @param {HM} hookMap hook map
+	 * @param {Caches<H>} cache cache
+	 * @param {string} type type
+	 * @param {function(H): R | undefined} fn fn
+	 * @returns {R | undefined} hook
+	 * @private
+	 */
 	_forEachLevel(hookMap, cache, type, fn) {
 		for (const hook of this._getAllLevelHooks(hookMap, cache, type)) {
-			const result = fn(hook);
+			const result = fn(/** @type {H} */ (hook));
 			if (result !== undefined) return result;
 		}
 	}
 
+	/**
+	 * @template {StatsFactoryHooks[keyof StatsFactoryHooks]} HM
+	 * @template {HM extends HookMap<infer H> ? H : never} H
+	 * @param {HM} hookMap hook map
+	 * @param {Caches<H>} cache cache
+	 * @param {string} type type
+	 * @param {FactoryData} data data
+	 * @param {function(H, FactoryData): FactoryData} fn fn
+	 * @returns {FactoryData} data
+	 * @private
+	 */
 	_forEachLevelWaterfall(hookMap, cache, type, data, fn) {
 		for (const hook of this._getAllLevelHooks(hookMap, cache, type)) {
-			data = fn(hook, data);
+			data = fn(/** @type {H} */ (hook), data);
 		}
 		return data;
 	}
 
+	/**
+	 * @template {StatsFactoryHooks[keyof StatsFactoryHooks]} T
+	 * @template {T extends HookMap<infer H> ? H : never} H
+	 * @template {H extends import("tapable").Hook<any, infer R> ? R : never} R
+	 * @param {T} hookMap hook map
+	 * @param {Caches<H>} cache cache
+	 * @param {string} type type
+	 * @param {Array<FactoryData>} items items
+	 * @param {function(H, R, number, number): R | undefined} fn fn
+	 * @param {boolean} forceClone force clone
+	 * @returns {R[]} result for each level
+	 * @private
+	 */
 	_forEachLevelFilter(hookMap, cache, type, items, fn, forceClone) {
 		const hooks = this._getAllLevelHooks(hookMap, cache, type);
 		if (hooks.length === 0) return forceClone ? items.slice() : items;
 		let i = 0;
 		return items.filter((item, idx) => {
 			for (const hook of hooks) {
-				const r = fn(hook, item, idx, i);
+				const r = fn(/** @type {H} */ (hook), item, idx, i);
 				if (r !== undefined) {
 					if (r) i++;
 					return r;
@@ -129,30 +189,37 @@ class StatsFactory {
 
 	/**
 	 * @param {string} type type
-	 * @param {any} data factory data
+	 * @param {FactoryData} data factory data
 	 * @param {Omit<StatsFactoryContext, "type">} baseContext context used as base
-	 * @returns {any} created object
+	 * @returns {CreatedObject} created object
 	 */
 	create(type, data, baseContext) {
 		if (this._inCreate) {
 			return this._create(type, data, baseContext);
-		} else {
-			try {
-				this._inCreate = true;
-				return this._create(type, data, baseContext);
-			} finally {
-				for (const key of Object.keys(this._caches)) this._caches[key].clear();
-				this._inCreate = false;
-			}
+		}
+		try {
+			this._inCreate = true;
+			return this._create(type, data, baseContext);
+		} finally {
+			for (const key of Object.keys(this._caches))
+				this._caches[/** @type {keyof StatsFactoryHooks} */ (key)].clear();
+			this._inCreate = false;
 		}
 	}
 
+	/**
+	 * @param {string} type type
+	 * @param {FactoryData} data factory data
+	 * @param {Omit<StatsFactoryContext, "type">} baseContext context used as base
+	 * @returns {CreatedObject} created object
+	 * @private
+	 */
 	_create(type, data, baseContext) {
-		const context = {
+		const context = /** @type {StatsFactoryContext} */ ({
 			...baseContext,
 			type,
 			[type]: data
-		};
+		});
 		if (Array.isArray(data)) {
 			// run filter on unsorted items
 			const items = this._forEachLevelFilter(
@@ -165,6 +232,7 @@ class StatsFactory {
 			);
 
 			// sort items
+			/** @type {Comparator[]} */
 			const comparators = [];
 			this._forEachLevel(this.hooks.sort, this._caches.sort, type, h =>
 				h.call(comparators, context)
@@ -188,6 +256,7 @@ class StatsFactory {
 
 			// for each item
 			let resultItems = items2.map((item, i) => {
+				/** @type {StatsFactoryContext} */
 				const itemContext = {
 					...context,
 					_index: i
@@ -217,6 +286,7 @@ class StatsFactory {
 			});
 
 			// sort result items
+			/** @type {Comparator[]} */
 			const comparators2 = [];
 			this._forEachLevel(
 				this.hooks.sortResults,
@@ -232,6 +302,7 @@ class StatsFactory {
 			}
 
 			// group result items
+			/** @type {GroupConfig[]} */
 			const groupConfigs = [];
 			this._forEachLevel(
 				this.hooks.groupResults,
@@ -270,23 +341,23 @@ class StatsFactory {
 				result,
 				(h, r) => h.call(r, context)
 			);
-		} else {
-			const object = {};
+		}
+		/** @type {ObjectForExtract} */
+		const object = {};
 
-			// run extract on value
-			this._forEachLevel(this.hooks.extract, this._caches.extract, type, h =>
-				h.call(object, data, context)
-			);
+		// run extract on value
+		this._forEachLevel(this.hooks.extract, this._caches.extract, type, h =>
+			h.call(object, data, context)
+		);
 
-			// run result on extracted object
-			return this._forEachLevelWaterfall(
-				this.hooks.result,
-				this._caches.result,
-				type,
-				object,
-				(h, r) => h.call(r, context)
-			);
-		}
+		// run result on extracted object
+		return this._forEachLevelWaterfall(
+			this.hooks.result,
+			this._caches.result,
+			type,
+			object,
+			(h, r) => h.call(r, context)
+		);
 	}
 }
 module.exports = StatsFactory;

package/lib/stats/StatsPrinter.js

@@ -7,73 +7,102 @@
 
 const { HookMap, SyncWaterfallHook, SyncBailHook } = require("tapable");
 
-/** @template T @typedef {import("tapable").AsArray<T>} AsArray<T> */
-/** @typedef {import("tapable").Hook} Hook */
 /** @typedef {import("./DefaultStatsFactoryPlugin").StatsAsset} StatsAsset */
 /** @typedef {import("./DefaultStatsFactoryPlugin").StatsChunk} StatsChunk */
 /** @typedef {import("./DefaultStatsFactoryPlugin").StatsChunkGroup} StatsChunkGroup */
 /** @typedef {import("./DefaultStatsFactoryPlugin").StatsCompilation} StatsCompilation */
+/** @typedef {import("./DefaultStatsFactoryPlugin").StatsError} StatsError */
+/** @typedef {import("./DefaultStatsFactoryPlugin").StatsLogging} StatsLogging */
 /** @typedef {import("./DefaultStatsFactoryPlugin").StatsModule} StatsModule */
+/** @typedef {import("./DefaultStatsFactoryPlugin").StatsModuleIssuer} StatsModuleIssuer */
 /** @typedef {import("./DefaultStatsFactoryPlugin").StatsModuleReason} StatsModuleReason */
+/** @typedef {import("./DefaultStatsFactoryPlugin").StatsModuleTraceDependency} StatsModuleTraceDependency */
+/** @typedef {import("./DefaultStatsFactoryPlugin").StatsModuleTraceItem} StatsModuleTraceItem */
+/** @typedef {import("./DefaultStatsFactoryPlugin").StatsProfile} StatsProfile */
 
 /**
- * @typedef {Object} PrintedElement
+ * @typedef {object} PrintedElement
  * @property {string} element
  * @property {string} content
  */
 
 /**
- * @typedef {Object} KnownStatsPrinterContext
+ * @typedef {object} KnownStatsPrinterContext
  * @property {string=} type
  * @property {StatsCompilation=} compilation
  * @property {StatsChunkGroup=} chunkGroup
+ * @property {string=} chunkGroupKind
  * @property {StatsAsset=} asset
  * @property {StatsModule=} module
  * @property {StatsChunk=} chunk
  * @property {StatsModuleReason=} moduleReason
+ * @property {StatsModuleIssuer=} moduleIssuer
+ * @property {StatsError=} error
+ * @property {StatsProfile=} profile
+ * @property {StatsLogging=} logging
+ * @property {StatsModuleTraceItem=} moduleTraceItem
+ * @property {StatsModuleTraceDependency=} moduleTraceDependency
+ */
+
+/**
+ * @typedef {object} KnownStatsPrinterColorFn
  * @property {(str: string) => string=} bold
  * @property {(str: string) => string=} yellow
  * @property {(str: string) => string=} red
  * @property {(str: string) => string=} green
  * @property {(str: string) => string=} magenta
  * @property {(str: string) => string=} cyan
+ */
+
+/**
+ * @typedef {object} KnownStatsPrinterFormaters
  * @property {(file: string, oversize?: boolean) => string=} formatFilename
  * @property {(id: string) => string=} formatModuleId
  * @property {(id: string, direction?: "parent"|"child"|"sibling") => string=} formatChunkId
  * @property {(size: number) => string=} formatSize
+ * @property {(size: string) => string=} formatLayer
  * @property {(dateTime: number) => string=} formatDateTime
  * @property {(flag: string) => string=} formatFlag
  * @property {(time: number, boldQuantity?: boolean) => string=} formatTime
- * @property {string=} chunkGroupKind
+ * @property {(message: string) => string=} formatError
  */
 
-/** @typedef {KnownStatsPrinterContext & Record<string, any>} StatsPrinterContext */
+/** @typedef {Record<string, any> & KnownStatsPrinterColorFn & KnownStatsPrinterFormaters & KnownStatsPrinterContext} StatsPrinterContext */
+/** @typedef {any} PrintObject */
+
+/**
+ * @typedef {object} StatsPrintHooks
+ * @property {HookMap<SyncBailHook<[string[], StatsPrinterContext], void>>} sortElements
+ * @property {HookMap<SyncBailHook<[PrintedElement[], StatsPrinterContext], string | undefined>>} printElements
+ * @property {HookMap<SyncBailHook<[PrintObject[], StatsPrinterContext], true>>} sortItems
+ * @property {HookMap<SyncBailHook<[PrintObject, StatsPrinterContext], string>>} getItemName
+ * @property {HookMap<SyncBailHook<[string[], StatsPrinterContext], string | undefined>>} printItems
+ * @property {HookMap<SyncBailHook<[PrintObject, StatsPrinterContext], string | void>>} print
+ * @property {HookMap<SyncWaterfallHook<[string, StatsPrinterContext]>>} result
+ */
 
 class StatsPrinter {
 	constructor() {
+		/** @type {StatsPrintHooks} */
 		this.hooks = Object.freeze({
-			/** @type {HookMap<SyncBailHook<[string[], StatsPrinterContext], true>>} */
 			sortElements: new HookMap(
 				() => new SyncBailHook(["elements", "context"])
 			),
-			/** @type {HookMap<SyncBailHook<[PrintedElement[], StatsPrinterContext], string>>} */
 			printElements: new HookMap(
 				() => new SyncBailHook(["printedElements", "context"])
 			),
-			/** @type {HookMap<SyncBailHook<[any[], StatsPrinterContext], true>>} */
 			sortItems: new HookMap(() => new SyncBailHook(["items", "context"])),
-			/** @type {HookMap<SyncBailHook<[any, StatsPrinterContext], string>>} */
 			getItemName: new HookMap(() => new SyncBailHook(["item", "context"])),
-			/** @type {HookMap<SyncBailHook<[string[], StatsPrinterContext], string>>} */
 			printItems: new HookMap(
 				() => new SyncBailHook(["printedItems", "context"])
 			),
-			/** @type {HookMap<SyncBailHook<[{}, StatsPrinterContext], string>>} */
 			print: new HookMap(() => new SyncBailHook(["object", "context"])),
 			/** @type {HookMap<SyncWaterfallHook<[string, StatsPrinterContext]>>} */
 			result: new HookMap(() => new SyncWaterfallHook(["result", "context"]))
 		});
-		/** @type {Map<HookMap<Hook>, Map<string, Hook[]>>} */
+		/**
+		 * @type {TODO}
+		 */
 		this._levelHookCache = new Map();
 		this._inPrint = false;
 	}
@@ -81,15 +110,14 @@ class StatsPrinter {
 	/**
 	 * get all level hooks
 	 * @private
-	 * @template {Hook} T
-	 * @param {HookMap<T>} hookMap HookMap
+	 * @template {StatsPrintHooks[keyof StatsPrintHooks]} HM
+	 * @template {HM extends HookMap<infer H> ? H : never} H
+	 * @param {HM} hookMap hook map
 	 * @param {string} type type
-	 * @returns {T[]} hooks
+	 * @returns {H[]} hooks
 	 */
 	_getAllLevelHooks(hookMap, type) {
-		let cache = /** @type {Map<string, T[]>} */ (
-			this._levelHookCache.get(hookMap)
-		);
+		let cache = this._levelHookCache.get(hookMap);
 		if (cache === undefined) {
 			cache = new Map();
 			this._levelHookCache.set(hookMap, cache);
@@ -98,11 +126,11 @@ class StatsPrinter {
 		if (cacheEntry !== undefined) {
 			return cacheEntry;
 		}
-		/** @type {T[]} */
+		/** @type {H[]} */
 		const hooks = [];
 		const typeParts = type.split(".");
 		for (let i = 0; i < typeParts.length; i++) {
-			const hook = hookMap.get(typeParts.slice(i).join("."));
+			const hook = /** @type {H} */ (hookMap.get(typeParts.slice(i).join(".")));
 			if (hook) {
 				hooks.push(hook);
 			}
@@ -114,16 +142,17 @@ class StatsPrinter {
 	/**
 	 * Run `fn` for each level
 	 * @private
-	 * @template T
-	 * @template R
-	 * @param {HookMap<SyncBailHook<T, R>>} hookMap HookMap
+	 * @template {StatsPrintHooks[keyof StatsPrintHooks]} HM
+	 * @template {HM extends HookMap<infer H> ? H : never} H
+	 * @template {H extends import("tapable").Hook<any, infer R> ? R : never} R
+	 * @param {HM} hookMap hook map
 	 * @param {string} type type
-	 * @param {(hook: SyncBailHook<T, R>) => R} fn function
-	 * @returns {R} result of `fn`
+	 * @param {function(H): R | undefined} fn fn
+	 * @returns {R | undefined} hook
 	 */
 	_forEachLevel(hookMap, type, fn) {
 		for (const hook of this._getAllLevelHooks(hookMap, type)) {
-			const result = fn(hook);
+			const result = fn(/** @type {H} */ (hook));
 			if (result !== undefined) return result;
 		}
 	}
@@ -131,48 +160,49 @@ class StatsPrinter {
 	/**
 	 * Run `fn` for each level
 	 * @private
-	 * @template T
-	 * @param {HookMap<SyncWaterfallHook<T>>} hookMap HookMap
+	 * @template {StatsPrintHooks[keyof StatsPrintHooks]} HM
+	 * @template {HM extends HookMap<infer H> ? H : never} H
+	 * @param {HM} hookMap hook map
 	 * @param {string} type type
-	 * @param {AsArray<T>[0]} data data
-	 * @param {(hook: SyncWaterfallHook<T>, data: AsArray<T>[0]) => AsArray<T>[0]} fn function
-	 * @returns {AsArray<T>[0]} result of `fn`
+	 * @param {string} data data
+	 * @param {function(H, string): string} fn fn
+	 * @returns {string} result of `fn`
 	 */
 	_forEachLevelWaterfall(hookMap, type, data, fn) {
 		for (const hook of this._getAllLevelHooks(hookMap, type)) {
-			data = fn(hook, data);
+			data = fn(/** @type {H} */ (hook), data);
 		}
 		return data;
 	}
 
 	/**
 	 * @param {string} type The type
-	 * @param {Object} object Object to print
-	 * @param {Object=} baseContext The base context
+	 * @param {PrintObject} object Object to print
+	 * @param {StatsPrinterContext=} baseContext The base context
 	 * @returns {string} printed result
 	 */
 	print(type, object, baseContext) {
 		if (this._inPrint) {
 			return this._print(type, object, baseContext);
-		} else {
-			try {
-				this._inPrint = true;
-				return this._print(type, object, baseContext);
-			} finally {
-				this._levelHookCache.clear();
-				this._inPrint = false;
-			}
+		}
+		try {
+			this._inPrint = true;
+			return this._print(type, object, baseContext);
+		} finally {
+			this._levelHookCache.clear();
+			this._inPrint = false;
 		}
 	}
 
 	/**
 	 * @private
 	 * @param {string} type type
-	 * @param {Object} object object
-	 * @param {Object=} baseContext context
+	 * @param {PrintObject} object object
+	 * @param {StatsPrinterContext=} baseContext context
 	 * @returns {string} printed result
 	 */
 	_print(type, object, baseContext) {
+		/** @type {StatsPrinterContext} */
 		const context = {
 			...baseContext,
 			type,
@@ -189,6 +219,7 @@ class StatsPrinter {
 					h.call(sortedItems, context)
 				);
 				const printedItems = sortedItems.map((item, i) => {
+					/** @type {StatsPrinterContext} */
 					const itemContext = {
 						...context,
 						_index: i
@@ -241,7 +272,7 @@ class StatsPrinter {
 		return this._forEachLevelWaterfall(
 			this.hooks.result,
 			type,
-			printResult,
+			/** @type {string} */ (printResult),
 			(h, r) => h.call(r, context)
 		);
 	}

package/lib/util/ArrayHelpers.js

@@ -5,10 +5,44 @@
 
 "use strict";
 
-exports.equals = (a, b) => {
+/**
+ * Compare two arrays or strings by performing strict equality check for each value.
+ * @template T [T=any]
+ * @param {ArrayLike<T>} a Array of values to be compared
+ * @param {ArrayLike<T>} b Array of values to be compared
+ * @returns {boolean} returns true if all the elements of passed arrays are strictly equal.
+ */
+
+module.exports.equals = (a, b) => {
 	if (a.length !== b.length) return false;
 	for (let i = 0; i < a.length; i++) {
 		if (a[i] !== b[i]) return false;
 	}
 	return true;
 };
+
+/**
+ * Partition an array by calling a predicate function on each value.
+ * @template T [T=any]
+ * @param {Array<T>} arr Array of values to be partitioned
+ * @param {(value: T) => boolean} fn Partition function which partitions based on truthiness of result.
+ * @returns {[Array<T>, Array<T>]} returns the values of `arr` partitioned into two new arrays based on fn predicate.
+ */
+
+module.exports.groupBy = (
+	// eslint-disable-next-line default-param-last
+	arr = [],
+	fn
+) =>
+	arr.reduce(
+		/**
+		 * @param {[Array<T>, Array<T>]} groups An accumulator storing already partitioned values returned from previous call.
+		 * @param {T} value The value of the current element
+		 * @returns {[Array<T>, Array<T>]} returns an array of partitioned groups accumulator resulting from calling a predicate on the current value.
+		 */
+		(groups, value) => {
+			groups[fn(value) ? 0 : 1].push(value);
+			return groups;
+		},
+		[[], []]
+	);