diff --git a/docs/developer-guide/formatters.md b/docs/developer-guide/formatters.md index 5e28ed7e12..b51e1055e0 100644 --- a/docs/developer-guide/formatters.md +++ b/docs/developer-guide/formatters.md @@ -3,12 +3,15 @@ A formatter is a function with the following signature: ```js +/** + * @type {import('stylelint').Formatter} + */ function formatter(results, returnValue) { return "a string of formatted results"; } ``` -Where the first argument (`results`) is an array of stylelint result objects in the form: +Where the first argument (`results`) is an array of stylelint result objects (type `Array`) in the form: ```js // A stylelint result object @@ -42,7 +45,7 @@ Where the first argument (`results`) is an array of stylelint result objects in } ``` -And the second argument (`returnValue`) is an object with one or more of the following keys: +And the second argument (`returnValue`) is an object (type `StylelintStandaloneReturnValue`) with one or more of the following keys: ```js { diff --git a/lib/formatters/compactFormatter.js b/lib/formatters/compactFormatter.js index 8454a40580..3b60e0b4de 100644 --- a/lib/formatters/compactFormatter.js +++ b/lib/formatters/compactFormatter.js @@ -3,8 +3,7 @@ const _ = require('lodash'); /** - * @param {import('stylelint').StylelintResult[]} results - * @returns {string} + * @type {import('stylelint').Formatter} */ const formatter = (results) => _.flatMap(results, (result) => diff --git a/lib/formatters/jsonFormatter.js b/lib/formatters/jsonFormatter.js index e07e6b2612..da5ae965ea 100644 --- a/lib/formatters/jsonFormatter.js +++ b/lib/formatters/jsonFormatter.js @@ -3,8 +3,7 @@ /** * Omit any properties starting with `_`, which are fake-private * - * @param {import('stylelint').StylelintResult[]} results - * @returns {string} + * @type {import('stylelint').Formatter} */ module.exports = function jsonFormatter(results) { const cleanedResults = results.map((result) => diff --git a/lib/formatters/stringFormatter.js b/lib/formatters/stringFormatter.js index d3f97a0d1b..7047f2b595 100644 --- a/lib/formatters/stringFormatter.js +++ b/lib/formatters/stringFormatter.js @@ -189,8 +189,7 @@ function formatter(messages, source) { } /** - * @param {import('stylelint').StylelintResult[]} results - * @returns {string} + * @type {import('stylelint').Formatter} */ module.exports = function (results) { let output = invalidOptionsFormatter(results); diff --git a/lib/formatters/unixFormatter.js b/lib/formatters/unixFormatter.js index cff9f3ac03..6e89f87adc 100644 --- a/lib/formatters/unixFormatter.js +++ b/lib/formatters/unixFormatter.js @@ -3,8 +3,7 @@ const _ = require('lodash'); /** - * @param {import('stylelint').StylelintResult[]} results - * @returns {string} + * @type {import('stylelint').Formatter} */ const unixFormatter = (results) => { const lines = _.flatMap(results, (result) => diff --git a/lib/formatters/verboseFormatter.js b/lib/formatters/verboseFormatter.js index 303b19bcfc..5683b044a2 100644 --- a/lib/formatters/verboseFormatter.js +++ b/lib/formatters/verboseFormatter.js @@ -5,8 +5,7 @@ const chalk = require('chalk'); const stringFormatter = require('./stringFormatter'); /** - * @param {import('stylelint').StylelintResult[]} results - * @returns {string} + * @type {import('stylelint').Formatter} */ module.exports = function (results) { let output = stringFormatter(results); diff --git a/lib/standalone.js b/lib/standalone.js index cd0fcd1435..303f17d485 100644 --- a/lib/standalone.js +++ b/lib/standalone.js @@ -25,6 +25,7 @@ const writeFileAtomic = require('write-file-atomic'); /** @typedef {import('stylelint').StylelintStandaloneOptions} StylelintOptions */ /** @typedef {import('stylelint').StylelintStandaloneReturnValue} StylelintStandaloneReturnValue */ /** @typedef {import('stylelint').StylelintResult} StylelintResult */ +/** @typedef {import('stylelint').Formatter} Formatter */ /** * @param {StylelintOptions} options @@ -77,7 +78,7 @@ module.exports = function (options) { throw new Error('You must pass stylelint a `files` glob or a `code` string, though not both'); } - /** @type {Function} */ + /** @type {Formatter} */ let formatterFunction; if (typeof formatter === 'string') { diff --git a/types/stylelint/index.d.ts b/types/stylelint/index.d.ts index 277f3eabee..39a61017b3 100644 --- a/types/stylelint/index.d.ts +++ b/types/stylelint/index.d.ts @@ -83,6 +83,13 @@ declare module 'stylelint' { warn(message: string, options?: StylelintWarningOptions): void; }; + export type Formatter = ( + results: Array, + returnValue?: StylelintStandaloneReturnValue, + ) => string; + + export type FormatterIdentifier = 'compact' | 'json' | 'string' | 'unix' | 'verbose' | Formatter; + export type StylelintOptions = { config?: StylelintConfig; configFile?: string; @@ -152,7 +159,7 @@ declare module 'stylelint' { maxWarnings?: number; syntax?: string; customSyntax?: string; - formatter?: 'compact' | 'json' | 'string' | 'unix' | 'verbose' | Function; + formatter?: FormatterIdentifier; disableDefaultIgnores?: boolean; fix?: boolean; allowEmptyInput?: boolean; @@ -231,7 +238,7 @@ declare module 'stylelint' { export type StylelintPublicAPI = { lint: Function; rules: { [k: string]: any }; - formatters: { [k: string]: Function }; + formatters: { [k: string]: Formatter }; createPlugin: Function; createLinter: Function; utils: {