Change Request: add a typedef for formatter functions

ESLint version

v8.10.0

What problem do you want to solve?

ESLint does not include a type definition for the signature of a formatter function.

A (custom) formatter is a plain function that accepts a list of lint results and an optional second parameter context with properties cwd and rulesMeta. This would be the expected type of the default export of a formatter module (a TypeScript example).

By contrast, there exists a type Formatter which is used for a different purpose: it is the type of a value resolved by eslint.loadFormatter. This is an object with a method named format that accepts a single argument.

What do you think is the correct solution?

Adding a type definition for the signature of a formatter function would be useful as a guideline to work with custom formatters and other tools that deal with those formatters, in the same way the type definitions for e.g. Rule or Plugin help with rules and plugins.

Participation

• I am willing to submit a pull request for this change.

Additional comments

I could submit a PR if desired, but I would probably need some input from the team, for example about naming conventions.

[btmills]

I think we shouldn’t treat changes in JSDoc typedefs as breaking.

That certainly simplifies a lot for us at this stage if we can get away with it. At some point, we’ll need to declare the types part of the stable public API, but having flexibility now would make the transition easier.

Thanks @fasttime for the link to a conversation where the ambiguous name was unhelpful. Perhaps we should both call the new type FormatterFunction and rename the existing Formatter type to LoadedFormatter to avoid any ambiguity?

[btmills]

This brings us one step closer to #15559, so 👍 from me! Good research on the existing Formatter type. The name collision is unfortunate, but it brings up an interesting question: since the existing Formatter type is only used internally, could we rename it to e.g. LoadedFormatter, freeing up Formatter for the publicly-consumable type?

Question for the team: as we’re working on typing ESLint’s codebase as part of #15559, are existing internal @typedefs stable public API? If we renamed the existing @typedef Formatter below, which is only used internally, to free up the name for the type of format functions for the public API, would that be a breaking change?

https://github.com/eslint/eslint/blob/802c85c28283362d48d77876e924fd381a15f573/lib/eslint/eslint.js#L39-L43