feat: add type FormatterFunction, update LoadedFormatter (#18872)

fasttime · web-flow · commit a48f8c29b58c · 2024-09-11T11:50:07.000-04:00
* feat: add type `FormatterFunction`, update `LoadedFormatter`

* add TypeDoc for `FormatterFunction`

* mark second argument of `FormatterFunction` as required, update TypeDoc
diff --git a/lib/shared/types.js b/lib/shared/types.js
@@ -245,6 +245,6 @@ module.exports = {};
  * A formatter function.
  * @callback FormatterFunction
  * @param {LintResult[]} results The list of linting results.
- * @param {{cwd: string, maxWarningsExceeded?: MaxWarningsExceeded, rulesMeta: Record<string, RuleMeta>}} [context] A context object.
+ * @param {{cwd: string, maxWarningsExceeded?: MaxWarningsExceeded, rulesMeta: Record<string, RuleMeta>}} context A context object.
  * @returns {string | Promise<string>} Formatted text.
  */
diff --git a/lib/types/index.d.ts b/lib/types/index.d.ts
@@ -1411,7 +1411,7 @@ export class ESLint {
 
     isPathIgnored(filePath: string): Promise<boolean>;
 
-    loadFormatter(nameOrPath?: string): Promise<ESLint.Formatter>;
+    loadFormatter(nameOrPath?: string): Promise<ESLint.LoadedFormatter>;
 }
 
 export namespace ESLint {
@@ -1555,14 +1555,38 @@ export namespace ESLint {
         replacedBy: string[];
     }
 
-    interface Formatter {
-        format(results: LintResult[], data?: LintResultData): string | Promise<string>;
+    interface ResultsMeta {
+        maxWarningsExceeded?: MaxWarningsExceeded | undefined;
+    }
+
+    /** The type of an object resolved by {@link ESLint.loadFormatter}. */
+    interface LoadedFormatter {
+
+        /**
+         * Used to call the underlying formatter.
+         * @param results An array of lint results to format.
+         * @param resultsMeta An object with an optional `maxWarningsExceeded` property that will be
+         * passed to the underlying formatter function along with other properties set by ESLint.
+         * This argument can be omitted if `maxWarningsExceeded` is not needed.
+         * @return The formatter output.
+         */
+        format(results: LintResult[], resultsMeta?: ResultsMeta): string | Promise<string>;
     }
 
+    // The documented type name is `LoadedFormatter`, but `Formatter` has been historically more used.
+    type Formatter = LoadedFormatter;
+
+    /**
+     * The expected signature of a custom formatter.
+     * @param results An array of lint results to format.
+     * @param context Additional information for the formatter.
+     * @return The formatter output.
+     */
+    type FormatterFunction =
+    (results: LintResult[], context: LintResultData) => string | Promise<string>;
+
     // Docs reference the types by those name
     type EditInfo = Rule.Fix;
-    type LoadedFormatter = Formatter;
-    type ResultsMeta = LintResultData;
 }
 
 // #endregion
diff --git a/tests/lib/types/types.test.ts b/tests/lib/types/types.test.ts
@@ -1003,7 +1003,7 @@ linterWithEslintrcConfig.getRules();
     const customFormatter1: ESLint.Formatter = { format: () => "ok" };
     const customFormatter2: ESLint.Formatter = { format: () => Promise.resolve("ok") };
 
-    let data: ESLint.LintResultData;
+    let resultsMeta: ESLint.ResultsMeta;
     const meta: Rule.RuleMetaData = {
         type: "suggestion",
         docs: {
@@ -1019,15 +1019,15 @@ linterWithEslintrcConfig.getRules();
         },
     };
 
-    data = { cwd: "/foo/bar", rulesMeta: { "no-extra-semi": meta } };
+    resultsMeta = { maxWarningsExceeded: { maxWarnings: 42, foundWarnings: 43 } };
 
     const version: string = ESLint.version;
 
     (async () => {
         const results: ESLint.LintResult[] = await resultsPromise;
         const formatter = await formatterPromise;
 
-        const output: string = await formatter.format(results, data);
+        const output: string = await formatter.format(results, resultsMeta);
 
         eslint.getRulesMetaForResults(results);
 
@@ -1131,7 +1131,7 @@ linterWithEslintrcConfig.getRules();
     const customFormatter1: ESLint.Formatter = { format: () => "ok" };
     const customFormatter2: ESLint.Formatter = { format: () => Promise.resolve("ok") };
 
-    let data: ESLint.LintResultData;
+    let resultsMeta: ESLint.ResultsMeta;
     const meta: Rule.RuleMetaData = {
         type: "suggestion",
         docs: {
@@ -1147,15 +1147,15 @@ linterWithEslintrcConfig.getRules();
         },
     };
 
-    data = { cwd: "/foo/bar", rulesMeta: { "no-extra-semi": meta } };
+    resultsMeta = { maxWarningsExceeded: { maxWarnings: 42, foundWarnings: 43 } };
 
     const version: string = LegacyESLint.version;
 
     (async () => {
         const results: ESLint.LintResult[] = await resultsPromise;
         const formatter = await formatterPromise;
 
-        const output: string = await formatter.format(results, data);
+        const output: string = await formatter.format(results, resultsMeta);
 
         eslint.getRulesMetaForResults(results);
 
@@ -1169,6 +1169,20 @@ linterWithEslintrcConfig.getRules();
 
 // #endregion
 
+// #region ESLint.Formatter
+
+function jsonFormatter(results: ESLint.LintResult[]) {
+    return JSON.stringify(results, null, 2);
+};
+
+const customFormatter: ESLint.FormatterFunction = jsonFormatter;
+
+function wrapperFormatter(results: ESLint.LintResult[], { cwd, maxWarningsExceeded, rulesMeta }: ESLint.LintResultData) {
+    customFormatter(results, { cwd, maxWarningsExceeded, rulesMeta });
+}
+
+// #endregion ESLint.Formatter
+
 // #region ESLint.LintResult
 
 let results!: ESLint.LintResult[];
@@ -1216,7 +1230,7 @@ for (const result of results) {
     }
 }
 
-// #region ESLint.LintResult
+// #endregion ESLint.LintResult
 
 // #region ESLintRules
 
