Skip to content

Commit ffa644a

Browse files
refactor(types): let plugins declare their stats keys
1 parent 6431073 commit ffa644a

6 files changed

Lines changed: 365 additions & 628 deletions

File tree

‎cspell.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,7 @@
2323
"asyncloader",
2424
"atlaskit",
2525
"ATTLIST",
26+
"augmentable",
2627
"autocapitalize",
2728
"autocrlf",
2829
"autospace",

‎eslint.config.mjs‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -153,7 +153,8 @@ export default defineConfig([
153153
plugins: { jsdoc: getJsdocPlugin() },
154154
rules: {
155155
// The keywords an option type states for `tooling/generate-schemas.js`,
156-
// which JSON Schema has and JSDoc does not
156+
// which JSON Schema has and JSDoc does not, and `augmentable`, which
157+
// `tooling/generate-types.js` exports for declaration merging
157158
"jsdoc/check-tag-names": [
158159
"error",
159160
{
@@ -180,7 +181,8 @@ export default defineConfig([
180181
"tsType",
181182
"typeOnly",
182183
"properties",
183-
"not"
184+
"not",
185+
"augmentable"
184186
]
185187
}
186188
]

‎lib/stats/StatsFactory.js‎

Lines changed: 43 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -80,8 +80,10 @@ const smartGrouping = require("./smartGrouping");
8080
*/
8181

8282
/**
83-
* The `[object, data]` each `extract` key webpack registers receives.
84-
* @typedef {object} KnownStatsFactoryExtract
83+
* The `[object, data]` `extract` receives for each object key, which also types that key's `getItemFactory` data and `result` value.
84+
* A plugin types its own keys by declaration merging: `declare module "webpack" { interface StatsFactoryExtractKeys { "myPlugin.data": [MyObject, MyData] } }`.
85+
* @augmentable
86+
* @typedef {object} StatsFactoryExtractKeys
8587
* @property {[StatsCompilation, Compilation]} compilation
8688
* @property {[StatsAsset, PreprocessedAsset]} asset
8789
* @property {[StatsAsset, PreprocessedAsset]} asset$visible
@@ -101,13 +103,15 @@ const smartGrouping = require("./smartGrouping");
101103
*/
102104

103105
/**
104-
* The `[item, created item]` of each array path webpack creates.
106+
* The `[item, created item]` of each array path, typing its item hooks (`filter`, `sort`, `filterSorted`) and created item hooks (`sortResults`, `groupResults`, `filterResults`, `merge`); an optional third element is what `merge` makes of the created items, which `result` then gets instead of their array.
107+
* A plugin types its own paths by declaration merging: `declare module "webpack" { interface StatsFactoryItemKeys { "myPlugin.items": [MyItem, MyCreatedItem] } }`.
108+
* @augmentable
105109
* @typedef {{
106110
* "compilation.assets": [PreprocessedAsset, StatsAsset],
107111
* "compilation.chunks": [Chunk, StatsChunk],
108112
* "compilation.modules": [Module, StatsModule],
109-
* "compilation.entrypoints": [ChunkGroupInfoWithName, StatsChunkGroup],
110-
* "compilation.namedChunkGroups": [ChunkGroupInfoWithName, StatsChunkGroup],
113+
* "compilation.entrypoints": [ChunkGroupInfoWithName, StatsChunkGroup, Record<string, StatsChunkGroup>],
114+
* "compilation.namedChunkGroups": [ChunkGroupInfoWithName, StatsChunkGroup, Record<string, StatsChunkGroup>],
111115
* "compilation.errors": [Error, StatsError],
112116
* "compilation.warnings": [Error, StatsError],
113117
* "compilation.hints": [Error, StatsError],
@@ -124,14 +128,19 @@ const smartGrouping = require("./smartGrouping");
124128
* "module.children": [Module, StatsModule],
125129
* moduleTrace: [ModuleTrace, StatsModuleTraceItem],
126130
* "moduleTraceItem.dependencies": [Dependency, StatsModuleTraceDependency],
127-
* }} KnownStatsFactoryItems
131+
* }} StatsFactoryItemKeys
128132
*/
129133

130-
/** @typedef {{ [Key in keyof KnownStatsFactoryItems]: KnownStatsFactoryItems[Key][0] }} KnownStatsFactoryRawItems */
131-
/** @typedef {{ [Key in keyof KnownStatsFactoryItems]: KnownStatsFactoryItems[Key][1] }} KnownStatsFactoryResultItems */
134+
/**
135+
* The value `result` gets for an array path: what `merge` made of its created items, else their array.
136+
* @template {keyof StatsFactoryItemKeys} K
137+
* @typedef {StatsFactoryItemKeys[K] extends [EXPECTED_ANY, EXPECTED_ANY, infer M] ? M : StatsFactoryItemKeys[K][1][]} StatsFactoryMergedItems
138+
*/
132139

133140
/**
134-
* The item `getItemName` receives for each `<array path>[]` key webpack registers.
141+
* The item `getItemName` receives for each `<array path>[]` key: the first element of that path's `StatsFactoryItemKeys` entry.
142+
* A plugin types its own keys by declaration merging: `declare module "webpack" { interface StatsFactoryItemNameKeys { "myPlugin.items[]": MyItem } }`.
143+
* @augmentable
135144
* @typedef {{
136145
* "compilation.assets[]": PreprocessedAsset,
137146
* "compilation.chunks[]": Chunk,
@@ -154,100 +163,95 @@ const smartGrouping = require("./smartGrouping");
154163
* "module.children[]": Module,
155164
* "moduleTrace[]": ModuleTrace,
156165
* "moduleTraceItem.dependencies[]": Dependency,
157-
* }} KnownStatsFactoryItemNames
166+
* }} StatsFactoryItemNameKeys
158167
*/
159168

160-
/**
161-
* The data `getItemFactory` receives: an item name key gets that item's data.
162-
* @typedef {{ [Key in keyof KnownStatsFactoryExtract]: KnownStatsFactoryExtract[Key][1] } & { "compilation.children[].compilation": Compilation }} KnownStatsFactoryItemFactories
163-
*/
164-
165-
/**
166-
* The value `result` passes on: an object key's stats object, an array path's (merged) items.
167-
* @typedef {{ [Key in keyof KnownStatsFactoryExtract]: KnownStatsFactoryExtract[Key][0] } & { [Key in Exclude<keyof KnownStatsFactoryResultItems, "compilation.entrypoints" | "compilation.namedChunkGroups">]: KnownStatsFactoryResultItems[Key][] } & { "compilation.entrypoints": Record<string, StatsChunkGroup>, "compilation.namedChunkGroups": Record<string, StatsChunkGroup> }} KnownStatsFactoryResults
168-
*/
169+
// TODO in the next major release: drop the open `for(key: string)` overloads,
170+
// so a key missing from the `StatsFactory*Keys` registries is a type error
169171

170172
/**
171173
* A value under a stats key a plugin registers, whose shape webpack does not know.
172174
* @typedef {EXPECTED_ANY} StatsPluginValue
173175
*/
174176

175177
/**
176-
* `extract` hooks: the exact `[object, data]` for keys webpack registers, open for plugin keys.
178+
* `extract` hooks: the exact `[object, data]` for keys in `StatsFactoryExtractKeys`, open for others.
177179
* @typedef {{
178-
* for<K extends keyof KnownStatsFactoryExtract>(key: K): SyncBailHook<[KnownStatsFactoryExtract[K][0], KnownStatsFactoryExtract[K][1], StatsFactoryContext], void>,
180+
* for<K extends keyof StatsFactoryExtractKeys>(key: K): SyncBailHook<[StatsFactoryExtractKeys[K][0], StatsFactoryExtractKeys[K][1], StatsFactoryContext], void>,
179181
* for(key: string): SyncBailHook<[StatsPluginValue, StatsPluginValue, StatsFactoryContext], void>
180182
* } & HookMap<SyncBailHook<[StatsPluginValue, StatsPluginValue, StatsFactoryContext], void>>} StatsFactoryExtractHookMap
181183
*/
182184

183185
/**
184-
* Filter hooks over the raw item: exact for known array paths, open for plugin keys.
186+
* Filter hooks over the item: exact for array paths in `StatsFactoryItemKeys`, open for others.
185187
* @typedef {{
186-
* for<K extends keyof KnownStatsFactoryRawItems>(key: K): SyncBailHook<[KnownStatsFactoryRawItems[K], StatsFactoryContext, number, number], boolean | void>,
188+
* for<K extends keyof StatsFactoryItemKeys>(key: K): SyncBailHook<[StatsFactoryItemKeys[K][0], StatsFactoryContext, number, number], boolean | void>,
187189
* for(key: string): SyncBailHook<[StatsPluginValue, StatsFactoryContext, number, number], boolean | void>
188190
* } & HookMap<SyncBailHook<[StatsPluginValue, StatsFactoryContext, number, number], boolean | void>>} StatsFactoryItemFilterHookMap
189191
*/
190192

191193
/**
192-
* Sort hooks over the raw item: exact for known array paths, open for plugin keys.
194+
* Sort hooks over the item: exact for array paths in `StatsFactoryItemKeys`, open for others.
193195
* @typedef {{
194-
* for<K extends keyof KnownStatsFactoryRawItems>(key: K): SyncBailHook<[Comparator<KnownStatsFactoryRawItems[K]>[], StatsFactoryContext], void>,
196+
* for<K extends keyof StatsFactoryItemKeys>(key: K): SyncBailHook<[Comparator<StatsFactoryItemKeys[K][0]>[], StatsFactoryContext], void>,
195197
* for(key: string): SyncBailHook<[Comparator<StatsPluginValue>[], StatsFactoryContext], void>
196198
* } & HookMap<SyncBailHook<[Comparator<StatsPluginValue>[], StatsFactoryContext], void>>} StatsFactoryItemSortHookMap
197199
*/
198200

199201
/**
200-
* Filter hooks over the created item: exact for known array paths, open for plugin keys.
202+
* Filter hooks over the created item: exact for array paths in `StatsFactoryItemKeys`, open for others.
201203
* @typedef {{
202-
* for<K extends keyof KnownStatsFactoryResultItems>(key: K): SyncBailHook<[KnownStatsFactoryResultItems[K], StatsFactoryContext, number, number], boolean | void>,
204+
* for<K extends keyof StatsFactoryItemKeys>(key: K): SyncBailHook<[StatsFactoryItemKeys[K][1], StatsFactoryContext, number, number], boolean | void>,
203205
* for(key: string): SyncBailHook<[StatsPluginValue, StatsFactoryContext, number, number], boolean | void>
204206
* } & HookMap<SyncBailHook<[StatsPluginValue, StatsFactoryContext, number, number], boolean | void>>} StatsFactoryResultFilterHookMap
205207
*/
206208

207209
/**
208-
* Sort hooks over the created item: exact for known array paths, open for plugin keys.
210+
* Sort hooks over the created item: exact for array paths in `StatsFactoryItemKeys`, open for others.
209211
* @typedef {{
210-
* for<K extends keyof KnownStatsFactoryResultItems>(key: K): SyncBailHook<[Comparator<KnownStatsFactoryResultItems[K]>[], StatsFactoryContext], void>,
212+
* for<K extends keyof StatsFactoryItemKeys>(key: K): SyncBailHook<[Comparator<StatsFactoryItemKeys[K][1]>[], StatsFactoryContext], void>,
211213
* for(key: string): SyncBailHook<[Comparator<StatsPluginValue>[], StatsFactoryContext], void>
212214
* } & HookMap<SyncBailHook<[Comparator<StatsPluginValue>[], StatsFactoryContext], void>>} StatsFactoryResultSortHookMap
213215
*/
214216

215217
/**
216-
* `groupResults` hooks: group configs over the exact created item for known keys, open for plugin keys.
218+
* `groupResults` hooks: group configs over the exact created item for array paths in `StatsFactoryItemKeys`, open for others.
217219
* @typedef {{
218-
* for<K extends keyof KnownStatsFactoryResultItems, G = object>(key: K): SyncBailHook<[GroupConfig<KnownStatsFactoryResultItems[K], G>[], StatsFactoryContext], void>,
220+
* for<K extends keyof StatsFactoryItemKeys, G = object>(key: K): SyncBailHook<[GroupConfig<StatsFactoryItemKeys[K][1], G>[], StatsFactoryContext], void>,
219221
* for(key: string): SyncBailHook<[GroupConfig<StatsPluginValue, StatsPluginValue>[], StatsFactoryContext], void>
220222
* } & HookMap<SyncBailHook<[GroupConfig<StatsPluginValue, StatsPluginValue>[], StatsFactoryContext], void>>} StatsFactoryGroupResultsHookMap
221223
*/
222224

223225
/**
224-
* `merge` hooks: the exact created items for known keys, merged by default into an object by name.
226+
* `merge` hooks: the exact created items for array paths in `StatsFactoryItemKeys`, merged by default into an object by name.
225227
* @typedef {{
226-
* for<K extends keyof KnownStatsFactoryResultItems, R = Record<string, KnownStatsFactoryResultItems[K]>>(key: K): SyncBailHook<[KnownStatsFactoryResultItems[K][], StatsFactoryContext], R | void>,
228+
* for<K extends keyof StatsFactoryItemKeys, R = Record<string, StatsFactoryItemKeys[K][1]>>(key: K): SyncBailHook<[StatsFactoryItemKeys[K][1][], StatsFactoryContext], R | void>,
227229
* for(key: string): SyncBailHook<[StatsPluginValue[], StatsFactoryContext], StatsPluginValue | void>
228230
* } & HookMap<SyncBailHook<[StatsPluginValue[], StatsFactoryContext], StatsPluginValue>>} StatsFactoryMergeHookMap
229231
*/
230232

231233
/**
232-
* `result` hooks: the exact stats value for known keys, open for plugin keys.
234+
* `result` hooks: the exact object for keys in `StatsFactoryExtractKeys` and (merged) items for array paths in `StatsFactoryItemKeys`, open for others.
233235
* @typedef {{
234-
* for<K extends keyof KnownStatsFactoryResults>(key: K): SyncBailHook<[KnownStatsFactoryResults[K], StatsFactoryContext], KnownStatsFactoryResults[K]>,
236+
* for<K extends keyof StatsFactoryExtractKeys>(key: K): SyncBailHook<[StatsFactoryExtractKeys[K][0], StatsFactoryContext], StatsFactoryExtractKeys[K][0]>,
237+
* for<K extends keyof StatsFactoryItemKeys>(key: K): SyncBailHook<[StatsFactoryMergedItems<K>, StatsFactoryContext], StatsFactoryMergedItems<K>>,
235238
* for(key: string): SyncBailHook<[StatsPluginValue, StatsFactoryContext], StatsPluginValue>
236239
* } & HookMap<SyncBailHook<[StatsPluginValue, StatsFactoryContext], StatsPluginValue>>} StatsFactoryResultHookMap
237240
*/
238241

239242
/**
240-
* `getItemName` hooks: the exact item for known `<array path>[]` keys, open for plugin keys.
243+
* `getItemName` hooks: the exact item for keys in `StatsFactoryItemNameKeys`, open for others.
241244
* @typedef {{
242-
* for<K extends keyof KnownStatsFactoryItemNames>(key: K): SyncBailHook<[KnownStatsFactoryItemNames[K], StatsFactoryContext], string | void>,
245+
* for<K extends keyof StatsFactoryItemNameKeys>(key: K): SyncBailHook<[StatsFactoryItemNameKeys[K], StatsFactoryContext], string | void>,
243246
* for(key: string): SyncBailHook<[StatsPluginValue, StatsFactoryContext], string | void>
244247
* } & HookMap<SyncBailHook<[StatsPluginValue, StatsFactoryContext], string | void>>} StatsFactoryGetItemNameHookMap
245248
*/
246249

247250
/**
248-
* `getItemFactory` hooks: the exact data for known item keys, open for plugin keys.
251+
* `getItemFactory` hooks: the exact data for item names in `StatsFactoryExtractKeys`, open for others.
249252
* @typedef {{
250-
* for<K extends keyof KnownStatsFactoryItemFactories>(key: K): SyncBailHook<[KnownStatsFactoryItemFactories[K], StatsFactoryContext], StatsFactory | void>,
253+
* for<K extends keyof StatsFactoryExtractKeys>(key: K): SyncBailHook<[StatsFactoryExtractKeys[K][1], StatsFactoryContext], StatsFactory | void>,
254+
* for(key: "compilation.children[].compilation"): SyncBailHook<[Compilation, StatsFactoryContext], StatsFactory | void>,
251255
* for(key: string): SyncBailHook<[StatsPluginValue, StatsFactoryContext], StatsFactory | void>
252256
* } & HookMap<SyncBailHook<[StatsPluginValue, StatsFactoryContext], StatsFactory | void>>} StatsFactoryGetItemFactoryHookMap
253257
*/

‎lib/stats/StatsPrinter.js‎

Lines changed: 21 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -90,8 +90,10 @@ const { HookMap, SyncBailHook, SyncWaterfallHook } = require("tapable");
9090
/** @typedef {KnownStatsPrinterColorFunctions & KnownStatsPrinterFormatters & KnownStatsPrinterContext & Record<string, EXPECTED_ANY>} StatsPrinterContext */
9191
/** @typedef {StatsPrinterContext & Required<KnownStatsPrinterColorFunctions> & Required<KnownStatsPrinterFormatters> & { type: string }} StatsPrinterContextWithExtra */
9292
/**
93-
* The value `print` receives for each object key webpack prints; the key also matches same-named fields.
94-
* @typedef {object} KnownStatsPrintObjects
93+
* The value `print` receives for each object key, which also matches same-named fields.
94+
* A plugin types its own keys by declaration merging: `declare module "webpack" { interface StatsPrinterPrintKeys { "myPlugin.data": MyObject } }`.
95+
* @augmentable
96+
* @typedef {object} StatsPrinterPrintKeys
9597
* @property {StatsCompilation} compilation
9698
* @property {StatsAsset} asset
9799
* @property {StatsChunk} chunk
@@ -108,7 +110,9 @@ const { HookMap, SyncBailHook, SyncWaterfallHook } = require("tapable");
108110
*/
109111

110112
/**
111-
* The item of each array path webpack prints stats objects for.
113+
* The item of each array path, which `sortItems` receives the array of.
114+
* A plugin types its own paths by declaration merging: `declare module "webpack" { interface StatsPrinterItemKeys { "myPlugin.items": MyItem } }`.
115+
* @augmentable
112116
* @typedef {{
113117
* "compilation.assets": StatsAsset,
114118
* "compilation.modules": StatsModule,
@@ -134,11 +138,13 @@ const { HookMap, SyncBailHook, SyncWaterfallHook } = require("tapable");
134138
* "error.moduleTrace": StatsModuleTraceItem,
135139
* "error.errors": StatsError,
136140
* "moduleTraceItem.dependencies": StatsModuleTraceDependency,
137-
* }} KnownStatsPrintItems
141+
* }} StatsPrinterItemKeys
138142
*/
139143

140144
/**
141-
* The item `getItemName` receives for each `<array path>[]` key of `KnownStatsPrintItems`.
145+
* The item `getItemName` receives for each `<array path>[]` key: that path's `StatsPrinterItemKeys` entry.
146+
* A plugin types its own keys by declaration merging: `declare module "webpack" { interface StatsPrinterItemNameKeys { "myPlugin.items[]": MyItem } }`.
147+
* @augmentable
142148
* @typedef {{
143149
* "compilation.assets[]": StatsAsset,
144150
* "compilation.modules[]": StatsModule,
@@ -164,29 +170,32 @@ const { HookMap, SyncBailHook, SyncWaterfallHook } = require("tapable");
164170
* "error.moduleTrace[]": StatsModuleTraceItem,
165171
* "error.errors[]": StatsError,
166172
* "moduleTraceItem.dependencies[]": StatsModuleTraceDependency,
167-
* }} KnownStatsPrintItemNames
173+
* }} StatsPrinterItemNameKeys
168174
*/
169175

176+
// TODO in the next major release: drop the open `for(key: string)` overloads,
177+
// so a key missing from the `StatsPrinter*Keys` registries is a type error
178+
170179
/**
171-
* `sortItems` hooks: the exact items for known array paths, open for plugin keys.
180+
* `sortItems` hooks: the exact items for array paths in `StatsPrinterItemKeys`, open for others.
172181
* @typedef {{
173-
* for<K extends keyof KnownStatsPrintItems>(key: K): SyncBailHook<[KnownStatsPrintItems[K][], StatsPrinterContext], boolean | void>,
182+
* for<K extends keyof StatsPrinterItemKeys>(key: K): SyncBailHook<[StatsPrinterItemKeys[K][], StatsPrinterContext], boolean | void>,
174183
* for(key: string): SyncBailHook<[StatsPluginValue[], StatsPrinterContext], boolean | void>
175184
* } & HookMap<SyncBailHook<[StatsPluginValue[], StatsPrinterContext], boolean | void>>} StatsPrinterSortItemsHookMap
176185
*/
177186

178187
/**
179-
* `getItemName` hooks: the exact item for known `<array path>[]` keys, open for plugin keys.
188+
* `getItemName` hooks: the exact item for keys in `StatsPrinterItemNameKeys`, open for others.
180189
* @typedef {{
181-
* for<K extends keyof KnownStatsPrintItemNames>(key: K): SyncBailHook<[KnownStatsPrintItemNames[K], StatsPrinterContext], string | void>,
190+
* for<K extends keyof StatsPrinterItemNameKeys>(key: K): SyncBailHook<[StatsPrinterItemNameKeys[K], StatsPrinterContext], string | void>,
182191
* for(key: string): SyncBailHook<[StatsPluginValue, StatsPrinterContext], string | void>
183192
* } & HookMap<SyncBailHook<[StatsPluginValue, StatsPrinterContext], string | void>>} StatsPrinterGetItemNameHookMap
184193
*/
185194

186195
/**
187-
* `print` hooks: the exact value for known object keys, open for plugin keys.
196+
* `print` hooks: the exact value for keys in `StatsPrinterPrintKeys`, open for others.
188197
* @typedef {{
189-
* for<K extends keyof KnownStatsPrintObjects>(key: K): SyncBailHook<[KnownStatsPrintObjects[K], StatsPrinterContext], string | undefined | void>,
198+
* for<K extends keyof StatsPrinterPrintKeys>(key: K): SyncBailHook<[StatsPrinterPrintKeys[K], StatsPrinterContext], string | undefined | void>,
190199
* for(key: string): SyncBailHook<[StatsPluginValue, StatsPrinterContext], string | undefined | void>
191200
* } & HookMap<SyncBailHook<[StatsPluginValue, StatsPrinterContext], string | undefined | void>>} StatsPrinterPrintHookMap
192201
*/

0 commit comments

Comments
 (0)