Document webpack change: add plugin system for Stats presets, defaults, creation and printing

[webpack-bot]

A pull request by @sokra was merged and maintainers requested a documentation change.

See pull request: https://github.com/webpack/webpack/pull/8520

---

What kind of change does this PR introduce? Refactoring

Did you add tests for your changes? Existing tests

Does this PR introduce a breaking change? Yes, errors in stats changed

What needs to be documented once your changes are merged? Errors and Warnings in Stats are now no longer strings but objects with multiple properties i. e. message chunkId moduleId moduleName stack details

This adds 4 new hooks to Compilation which allow to customize/extend Stats.

Compilation.hooks.statsPreset

It's a HookMap called for a preset (if used) with an options object. A plugin which handles a preset should set options in the options object. It should avoid overriding existing options.

Example:

compilation.hooks.statsPreset.for("my-preset").tap("MyPlugin", options => {
  if(options.all === undefined) options.all = true;
});

Compilation.hooks.statsNormalize

It's called for a options object and should normalize to a format usable by the following hooks. It should also normalize missing options to the default value.

Example:

compilation.hooks.statsNormalize.tap("MyPlugin", options => {
  if(options.myOption === undefined) options.myOption = [];
  if(!Array.isArray(options.myOption)) options.myOptions = [options.myOptions];
});

Compilation.hooks.statsFactory

Gives access to the StatsFactory for specific options.

Signature: (factory, options)

Compilation.hooks.statsPrinter

Gives access to the StatsPrinter for specific options.

Signature: (printer, options)

StatsFactory.hooks.extract

HookMap with signature: (object, data, context)

data contains the class. object is an object which properties should be added too. context has contextual information, like classes on the path.

Example:

factory.hooks.extract.for("compilation").tap("MyPlugin", (object, compilation) => {
  object.customProperty = MyPlugin.getCustomValue(compilation);
});

StatsFactory.hooks.result

HookMap with signature: (result, context)

Called with the result on each level.

StatsFactory Array default handling

Arrays are process in multiple steps (all HookMaps):

• StatsFactory.hooks.filter (item, context, index: number, unfilteredIndex: number)
• StatsFactory.hooks.sort (comparators: Function[], context)
• StatsFactory.hooks.filterSorted (item, context, index: number, unfilteredIndex: number)
• factory called for every item
  • StatsFactory.hooks.getItemName (item, context)
  • StatsFactory.hooks.getItemFactory (item, context)
• StatsFactory.hooks.sortResults (comparators: Function[], context)
• StatsFactory.hooks.filterResults (item, context, index: number, unfilteredIndex: number)
• StatsFactory.hooks.merge (items, context)

StatsPrinter.hooks.print

HookMap with signature: (object, context)

Called when a part should be printed.

StatsPrinter.hooks.result

HookMap with signature: (result: string, context)

Called for the resulting string for a part.

StatsPrinter Object default handling

• Object.keys -> elements
• StatsPrinter.hooks.sortElements (elements, context)
• StatsPrinter.print is called for every element
• StatsPrinter.hooks.printElements (printedElements, context)

StatsPrinter Array default handling

• StatsPrinter.hooks.sortItems (items, context)
• StatsPrinter.print is called for every item
  • StatsPrinter.hooks.getItemName (item, context)
• StatsPrinter.hooks.printItems (printedItems, context)