Change Request: add a typedef for formatter functions
See original GitHub issueESLint 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.
Issue Analytics
- State:
- Created 2 years ago
- Reactions:2
- Comments:9 (9 by maintainers)
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 existingFormatter
type toLoadedFormatter
to avoid any ambiguity?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 existingFormatter
type is only used internally, could we rename it to e.g.LoadedFormatter
, freeing upFormatter
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
@typedef
s 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