Skip to content

Commit 70abaa5

Browse files
refactor(types): type webpack's own stats taps from the key registries
1 parent aabeb3e commit 70abaa5

2 files changed

Lines changed: 83 additions & 134 deletions

File tree

‎lib/stats/DefaultStatsFactoryPlugin.js‎

Lines changed: 74 additions & 130 deletions
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,15 @@ const { makePathsRelative, parseResource } = require("../util/identifier");
3030

3131
/** @import { Source } from "webpack-sources" */
3232
/** @import { StatsValue } from "../../declarations/WebpackOptions" */
33-
/** @import StatsFactory, { StatsFactoryContext } from "./StatsFactory" */
33+
/**
34+
* @import StatsFactory, {
35+
* StatsFactoryContext,
36+
* StatsFactoryExtractKeys,
37+
* StatsFactoryItemKeys,
38+
* StatsFactoryItemNameKeys,
39+
* StatsFactoryMergedItems
40+
* } from "./StatsFactory"
41+
*/
3442
/** @import Chunk, { ChunkId, ChunkName } from "../graph/Chunk" */
3543
/** @import { ModuleId } from "../graph/ChunkGraph" */
3644
/** @import ChunkGroup, { OriginRecord } from "../graph/ChunkGroup" */
@@ -52,7 +60,6 @@ const { makePathsRelative, parseResource } = require("../util/identifier");
5260
/** @import Module, { NameForCondition, BuildInfo } from "../module/Module" */
5361
/** @import ModuleGraph from "../graph/ModuleGraph" */
5462
/** @import ModuleGraphConnection from "../graph/ModuleGraphConnection" */
55-
/** @import ModuleProfile from "../module/ModuleProfile" */
5663
/** @import WebpackError from "../errors/WebpackError" */
5764
/**
5865
* @import {
@@ -360,24 +367,26 @@ const { makePathsRelative, parseResource } = require("../util/identifier");
360367
/** @typedef {{ origin: Module, module: Module }} ModuleTrace */
361368

362369
/**
363-
* Defines the simple extractors type used by this module.
364-
* @typedef {object} SimpleExtractors
365-
* @property {ExtractorsByOption<Compilation, StatsCompilation>} compilation
366-
* @property {ExtractorsByOption<PreprocessedAsset, StatsAsset>} asset
367-
* @property {ExtractorsByOption<PreprocessedAsset, StatsAsset>} asset$visible
368-
* @property {ExtractorsByOption<ChunkGroupInfoWithName, StatsChunkGroup>} chunkGroup
369-
* @property {ExtractorsByOption<Module, StatsModule>} module
370-
* @property {ExtractorsByOption<Module, StatsModule>} module$visible
371-
* @property {ExtractorsByOption<Module, StatsModuleIssuer>} moduleIssuer
372-
* @property {ExtractorsByOption<ModuleProfile, StatsProfile>} profile
373-
* @property {ExtractorsByOption<ModuleGraphConnection, StatsModuleReason>} moduleReason
374-
* @property {ExtractorsByOption<Chunk, StatsChunk>} chunk
375-
* @property {ExtractorsByOption<OriginRecord, StatsChunkOrigin>} chunkOrigin
376-
* @property {ExtractorsByOption<WebpackError, StatsError>} error
377-
* @property {ExtractorsByOption<WebpackError, StatsError>} warning
378-
* @property {ExtractorsByOption<WebpackError, StatsError>} cause
379-
* @property {ExtractorsByOption<ModuleTrace, StatsModuleTraceItem>} moduleTraceItem
380-
* @property {ExtractorsByOption<Dependency, StatsModuleTraceDependency>} moduleTraceDependency
370+
* The `extract` taps of every key in `StatsFactoryExtractKeys`, by option, typed from that key's entry.
371+
* @typedef {{ [K in keyof StatsFactoryExtractKeys]: ExtractorsByOption<StatsFactoryExtractKeys[K][1], StatsFactoryExtractKeys[K][0]> }} SimpleExtractors
372+
*/
373+
374+
/**
375+
* The `filter` or `filterResults` taps of one array path, by option, over its item or created item.
376+
* @template I
377+
* @typedef {Record<string, (item: I, context: StatsFactoryContext, options: NormalizedStatsOptions, idx: number, i: number) => boolean | undefined>} FiltersByOption
378+
*/
379+
380+
/**
381+
* The `sort` or `sortResults` taps of one array path, by option, over its item or created item.
382+
* @template I
383+
* @typedef {Record<string, (comparators: Comparator<I>[], context: StatsFactoryContext, options: NormalizedStatsOptions) => void>} SortersByOption
384+
*/
385+
386+
/**
387+
* The `groupResults` taps of one array path, by option, over its created item; the group type is the hook's default.
388+
* @template I
389+
* @typedef {Record<string, (groupConfigs: GroupConfig<I, EXPECTED_OBJECT>[], context: StatsFactoryContext, options: NormalizedStatsOptions) => void>} GroupersByOption
381390
*/
382391

383392
/**
@@ -1726,7 +1735,7 @@ const SIMPLE_EXTRACTORS = {
17261735
}
17271736
};
17281737

1729-
/** @type {Record<string, Record<string, (thing: ModuleGraphConnection, context: StatsFactoryContext, options: NormalizedStatsOptions, idx: number, i: number) => boolean | undefined>>} */
1738+
/** @type {{ [K in "module.reasons"]: FiltersByOption<StatsFactoryItemKeys[K][0]> }} */
17301739
const FILTER = {
17311740
"module.reasons": {
17321741
"!orphanModules": (reason, { compilation: { chunkGraph } }) => {
@@ -1740,7 +1749,7 @@ const FILTER = {
17401749
}
17411750
};
17421751

1743-
/** @type {Record<string, Record<string, (thing: KnownStatsError, context: StatsFactoryContext, options: NormalizedStatsOptions, idx: number, i: number) => boolean | undefined>>} */
1752+
/** @type {{ [K in "compilation.warnings"]: FiltersByOption<StatsFactoryItemKeys[K][1]> }} */
17441753
const FILTER_RESULTS = {
17451754
"compilation.warnings": {
17461755
warningsFilter: util.deprecate(
@@ -1802,17 +1811,7 @@ const MODULE_REASONS_COMPARATORS = [
18021811
)
18031812
];
18041813

1805-
/**
1806-
* @type {{
1807-
* "compilation.chunks": Record<string, (comparators: Comparator<Chunk>[], context: StatsFactoryContext, options: NormalizedStatsOptions) => void>,
1808-
* "compilation.modules": Record<string, (comparators: Comparator<Module>[], context: StatsFactoryContext, options: NormalizedStatsOptions) => void>,
1809-
* "chunk.rootModules": Record<string, (comparators: Comparator<Module>[], context: StatsFactoryContext, options: NormalizedStatsOptions) => void>,
1810-
* "chunk.modules": Record<string, (comparators: Comparator<Module>[], context: StatsFactoryContext, options: NormalizedStatsOptions) => void>,
1811-
* "module.modules": Record<string, (comparators: Comparator<Module>[], context: StatsFactoryContext, options: NormalizedStatsOptions) => void>,
1812-
* "module.reasons": Record<string, (comparators: Comparator<ModuleGraphConnection>[], context: StatsFactoryContext, options: NormalizedStatsOptions) => void>,
1813-
* "chunk.origins": Record<string, (comparators: Comparator<OriginRecord>[], context: StatsFactoryContext, options: NormalizedStatsOptions) => void>,
1814-
* }}
1815-
*/
1814+
/** @type {{ [K in "compilation.chunks" | "compilation.modules" | "chunk.rootModules" | "chunk.modules" | "module.modules" | "module.reasons" | "chunk.origins"]: SortersByOption<StatsFactoryItemKeys[K][0]> }} */
18161815
const SORTERS = {
18171816
"compilation.chunks": {
18181817
_: (comparators) => {
@@ -2178,27 +2177,9 @@ const reasonGroup = (children, reasons) => {
21782177
const GROUP_EXTENSION_REGEXP = /(\.[^.]+?)(?:\?|(?: \+ \d+ modules?)?$)/;
21792178
const GROUP_PATH_REGEXP = /(.+)[/\\][^/\\]+?(?:\?|(?: \+ \d+ modules?)?$)/;
21802179

2181-
/** @typedef {{ type: string }} BaseGroup */
2182-
2183-
/**
2184-
* Defines the base group with children type used by this module.
2185-
* @template T
2186-
* @typedef {BaseGroup & { children: T[], size: number }} BaseGroupWithChildren
2187-
*/
2188-
21892180
/** @typedef {(name: string, asset: StatsAsset) => boolean} AssetFilterItemFn */
21902181

2191-
/**
2192-
* Describes the assets groupers shape.
2193-
* @typedef {{
2194-
* _: (groupConfigs: GroupConfig<KnownStatsAsset, BaseGroup & { filteredChildren: number, size: number } | BaseGroupWithChildren<KnownStatsAsset>>[], context: StatsFactoryContext, options: NormalizedStatsOptions) => void,
2195-
* groupAssetsByInfo: (groupConfigs: GroupConfig<KnownStatsAsset, BaseGroupWithChildren<KnownStatsAsset>>[], context: StatsFactoryContext, options: NormalizedStatsOptions) => void,
2196-
* groupAssetsByChunk: (groupConfigs: GroupConfig<KnownStatsAsset, BaseGroupWithChildren<KnownStatsAsset>>[], context: StatsFactoryContext, options: NormalizedStatsOptions) => void,
2197-
* excludeAssets: (groupConfigs: GroupConfig<KnownStatsAsset, BaseGroup & { filteredChildren: number, size: number }>[], context: StatsFactoryContext, options: NormalizedStatsOptions) => void,
2198-
* }} AssetsGroupers
2199-
*/
2200-
2201-
/** @type {AssetsGroupers} */
2182+
/** @type {GroupersByOption<StatsAsset>} */
22022183
const ASSETS_GROUPERS = {
22032184
_: (groupConfigs, context, options) => {
22042185
/**
@@ -2344,18 +2325,10 @@ const ASSETS_GROUPERS = {
23442325
}
23452326
};
23462327

2347-
/**
2348-
* Describes the modules groupers shape.
2349-
* @typedef {{
2350-
* _: (groupConfigs: GroupConfig<KnownStatsModule, BaseGroup & { filteredChildren?: number, children?: KnownStatsModule[], size: number, sizes: Record<string, number> }>[], context: StatsFactoryContext, options: NormalizedStatsOptions) => void,
2351-
* excludeModules: (groupConfigs: GroupConfig<KnownStatsModule, BaseGroup & { filteredChildren: number, size: number, sizes: Record<string, number> }>[], context: StatsFactoryContext, options: NormalizedStatsOptions) => void,
2352-
* }} ModulesGroupers
2353-
*/
2354-
23552328
/** @typedef {(name: string, module: StatsModule, type: "module" | "chunk" | "root-of-chunk" | "nested") => boolean} ModuleFilterItemTypeFn */
23562329

23572330
/**
2358-
* @type {(type: ExcludeModulesType) => ModulesGroupers}
2331+
* @type {(type: ExcludeModulesType) => GroupersByOption<StatsModule>}
23592332
*/
23602333
const MODULES_GROUPERS = (type) => ({
23612334
_: (groupConfigs, context, options) => {
@@ -2541,12 +2514,7 @@ const MODULES_GROUPERS = (type) => ({
25412514
}
25422515
});
25432516

2544-
/**
2545-
* Defines the module reasons groupers type used by this module.
2546-
* @typedef {{ groupReasonsByOrigin: (groupConfigs: GroupConfig<KnownStatsModuleReason, BaseGroup & { module: string, children: KnownStatsModuleReason[], active: boolean }>[], context: StatsFactoryContext, options: NormalizedStatsOptions) => void }} ModuleReasonsGroupers
2547-
*/
2548-
2549-
/** @type {ModuleReasonsGroupers} */
2517+
/** @type {GroupersByOption<StatsModuleReason>} */
25502518
const MODULE_REASONS_GROUPERS = {
25512519
groupReasonsByOrigin: (groupConfigs) => {
25522520
groupConfigs.push({
@@ -2561,17 +2529,7 @@ const MODULE_REASONS_GROUPERS = {
25612529
}
25622530
};
25632531

2564-
/**
2565-
* @type {{
2566-
* "compilation.assets": AssetsGroupers,
2567-
* "asset.related": AssetsGroupers,
2568-
* "compilation.modules": ModulesGroupers,
2569-
* "chunk.modules": ModulesGroupers,
2570-
* "chunk.rootModules": ModulesGroupers,
2571-
* "module.modules": ModulesGroupers,
2572-
* "module.reasons": ModuleReasonsGroupers,
2573-
* }}
2574-
*/
2532+
/** @type {{ [K in "compilation.assets" | "asset.related" | "compilation.modules" | "chunk.modules" | "chunk.rootModules" | "module.modules" | "module.reasons"]: GroupersByOption<StatsFactoryItemKeys[K][1]> }} */
25752533
const RESULT_GROUPERS = {
25762534
"compilation.assets": ASSETS_GROUPERS,
25772535
"asset.related": ASSETS_GROUPERS,
@@ -2648,18 +2606,10 @@ const sortByField = (field) => {
26482606
return /** @type {Comparator<T>} */ (sortFn);
26492607
};
26502608

2651-
/**
2652-
* Describes the asset sorters shape.
2653-
* @typedef {{
2654-
* assetsSort: (comparators: Comparator<Asset>[], context: StatsFactoryContext, options: NormalizedStatsOptions) => void,
2655-
* _: (comparators: Comparator<Asset>[], context: StatsFactoryContext, options: NormalizedStatsOptions) => void,
2656-
* }} AssetSorters
2657-
*/
2658-
2659-
/** @type {Comparator<Asset>} */
2609+
/** @type {Comparator<StatsAsset>} */
26602610
const compareAssetsByName = compareSelect((asset) => asset.name, compareIds);
26612611

2662-
/** @type {AssetSorters} */
2612+
/** @type {SortersByOption<StatsAsset>} */
26632613
const ASSET_SORTERS = {
26642614
assetsSort: (comparators, context, { assetsSort }) => {
26652615
comparators.push(sortByField(assetsSort));
@@ -2669,16 +2619,7 @@ const ASSET_SORTERS = {
26692619
}
26702620
};
26712621

2672-
/**
2673-
* @type {{
2674-
* "compilation.chunks": { chunksSort: (comparators: Comparator<Chunk>[], context: StatsFactoryContext, options: NormalizedStatsOptions) => void },
2675-
* "compilation.modules": { modulesSort: (comparators: Comparator<Module>[], context: StatsFactoryContext, options: NormalizedStatsOptions) => void },
2676-
* "chunk.modules": { chunkModulesSort: (comparators: Comparator<Module>[], context: StatsFactoryContext, options: NormalizedStatsOptions) => void },
2677-
* "module.modules": { nestedModulesSort: (comparators: Comparator<Module>[], context: StatsFactoryContext, options: NormalizedStatsOptions) => void },
2678-
* "compilation.assets": AssetSorters,
2679-
* "asset.related": AssetSorters,
2680-
* }}
2681-
*/
2622+
/** @type {{ [K in "compilation.chunks" | "compilation.modules" | "chunk.modules" | "module.modules" | "compilation.assets" | "asset.related"]: SortersByOption<StatsFactoryItemKeys[K][1]> }} */
26822623
const RESULT_SORTERS = {
26832624
"compilation.chunks": {
26842625
chunksSort: (comparators, context, { chunksSort }) => {
@@ -2704,22 +2645,19 @@ const RESULT_SORTERS = {
27042645
"asset.related": ASSET_SORTERS
27052646
};
27062647

2707-
/**
2708-
* Defines the extract function type used by this module.
2709-
* @template T
2710-
* @typedef {T extends Record<string, Record<string, infer F>> ? F : never} ExtractFunction
2711-
*/
2712-
27132648
/**
27142649
* Processes the provided config.
2650+
* The handler is generic over the key, so a tap it makes per key resolves that key's exact hook overload.
27152651
* @template {Record<string, Record<string, (...args: never[]) => void>>} T
27162652
* @param {T} config the config see above
27172653
* @param {NormalizedStatsOptions} options stats options
2718-
* @param {(hookFor: keyof T, fn: ExtractFunction<T>) => void} fn handler function called for every active line in config
2654+
* @param {<K extends keyof T>(hookFor: K, fn: T[K][string]) => void} fn handler function called for every active line in config
27192655
* @returns {void}
27202656
*/
27212657
const iterateConfig = (config, options, fn) => {
2722-
for (const hookFor of Object.keys(config)) {
2658+
for (const hookFor of /** @type {(keyof T & string)[]} */ (
2659+
Object.keys(config)
2660+
)) {
27232661
const subConfig = config[hookFor];
27242662
for (const option of Object.keys(subConfig)) {
27252663
if (option !== "_") {
@@ -2736,12 +2674,15 @@ const iterateConfig = (config, options, fn) => {
27362674
}
27372675
}
27382676
}
2739-
fn(hookFor, /** @type {ExtractFunction<T>} */ (subConfig[option]));
2677+
fn(
2678+
hookFor,
2679+
/** @type {T[keyof T & string][string]} */ (subConfig[option])
2680+
);
27402681
}
27412682
}
27422683
};
27432684

2744-
/** @type {Record<string, string>} */
2685+
/** @type {{ [K in keyof StatsFactoryItemNameKeys]: keyof StatsFactoryExtractKeys }} */
27452686
const ITEM_NAMES = {
27462687
"compilation.children[]": "compilation",
27472688
"compilation.modules[]": "module",
@@ -2766,35 +2707,40 @@ const ITEM_NAMES = {
27662707
"moduleTraceItem.dependencies[]": "moduleTraceDependency"
27672708
};
27682709

2769-
/**
2770-
* Defines the named object type used by this module.
2771-
* @template T
2772-
* @typedef {{ name: T }} NamedObject
2773-
*/
2774-
27752710
/**
27762711
* Merges the provided values into a single result.
2777-
* @template {{ name: string }} T
2712+
* @template {{ name?: ChunkName }} T
27782713
* @param {T[]} items items to be merged
2779-
* @returns {NamedObject<T>} an object
2714+
* @returns {Record<string, T>} an object
27802715
*/
27812716
const mergeToObject = (items) => {
27822717
const obj = Object.create(null);
27832718
for (const item of items) {
2784-
obj[item.name] = item;
2719+
obj[/** @type {string} */ (item.name)] = item;
27852720
}
27862721
return obj;
27872722
};
27882723

2789-
/**
2790-
* @template {{ name: string }} T
2791-
* @type {Record<string, (items: T[]) => NamedObject<T>>}
2792-
*/
2724+
/** @type {{ [K in "compilation.entrypoints" | "compilation.namedChunkGroups"]: (items: StatsFactoryItemKeys[K][1][]) => StatsFactoryMergedItems<K> }} */
27932725
const MERGER = {
27942726
"compilation.entrypoints": mergeToObject,
27952727
"compilation.namedChunkGroups": mergeToObject
27962728
};
27972729

2730+
/**
2731+
* Calls `fn` with each own key of `table` and its value, in key order.
2732+
* The handler is generic over the key, so a tap it makes per key resolves that key's exact hook overload.
2733+
* @template {object} T
2734+
* @param {T} table table
2735+
* @param {<K extends keyof T>(key: K, value: T[K]) => void} fn handler function called for every key
2736+
* @returns {void}
2737+
*/
2738+
const forEachKey = (table, fn) => {
2739+
for (const key of /** @type {(keyof T)[]} */ (Object.keys(table))) {
2740+
fn(key, table[key]);
2741+
}
2742+
};
2743+
27982744
const PLUGIN_NAME = "DefaultStatsFactoryPlugin";
27992745

28002746
class DefaultStatsFactoryPlugin {
@@ -2815,7 +2761,7 @@ class DefaultStatsFactoryPlugin {
28152761
(stats, options) => {
28162762
iterateConfig(SIMPLE_EXTRACTORS, options, (hookFor, fn) => {
28172763
stats.hooks.extract
2818-
.for(/** @type {string} */ (hookFor))
2764+
.for(hookFor)
28192765
.tap(PLUGIN_NAME, (obj, data, ctx) =>
28202766
fn(obj, data, ctx, options, stats)
28212767
);
@@ -2843,26 +2789,24 @@ class DefaultStatsFactoryPlugin {
28432789
});
28442790
iterateConfig(RESULT_SORTERS, options, (hookFor, fn) => {
28452791
stats.hooks.sortResults
2846-
.for(/** @type {string} */ (hookFor))
2792+
.for(hookFor)
28472793
.tap(PLUGIN_NAME, (comparators, ctx) =>
28482794
fn(comparators, ctx, options)
28492795
);
28502796
});
28512797
iterateConfig(RESULT_GROUPERS, options, (hookFor, fn) => {
28522798
stats.hooks.groupResults
2853-
.for(/** @type {string} */ (hookFor))
2799+
.for(hookFor)
28542800
.tap(PLUGIN_NAME, (groupConfigs, ctx) =>
28552801
fn(groupConfigs, ctx, options)
28562802
);
28572803
});
2858-
for (const key of Object.keys(ITEM_NAMES)) {
2859-
const itemName = ITEM_NAMES[key];
2804+
forEachKey(ITEM_NAMES, (key, itemName) => {
28602805
stats.hooks.getItemName.for(key).tap(PLUGIN_NAME, () => itemName);
2861-
}
2862-
for (const key of Object.keys(MERGER)) {
2863-
const merger = MERGER[key];
2806+
});
2807+
forEachKey(MERGER, (key, merger) => {
28642808
stats.hooks.merge.for(key).tap(PLUGIN_NAME, merger);
2865-
}
2809+
});
28662810
if (options.children) {
28672811
if (Array.isArray(options.children)) {
28682812
stats.hooks.getItemFactory

0 commit comments

Comments
 (0)