Add type Formatter for formatter functions (#4823)

stylelint · Jun 9, 2020 · 5b6b996 · 5b6b996
1 parent 769f917
commit 5b6b996
Show file tree

Hide file tree

Showing 8 changed files with 21 additions and 15 deletions.
diff --git 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<StylelintResult>`) 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -83,6 +83,13 @@ declare module 'stylelint' {
 		warn(message: string, options?: StylelintWarningOptions): void;
 	};
 
+	export type Formatter = (
+		results: Array<StylelintResult>,
+		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: {