@@ -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 */
0 commit comments