feat: support async formatter

docs/developer-guide/nodejs-api.md

@@ -404,7 +404,7 @@ This edit information means replacing the range of the `range` property by the `
 
 The `Formatter` value is the object to convert the [LintResult] objects to text. The [eslint.loadFormatter()][eslint-loadformatter] method returns it. It has the following method:
 
-* `format` (`(results: LintResult[]) => string`)<br>
+* `format` (`(results: LintResult[]) => string | Promise<string>`)<br>
   The method to convert the [LintResult] objects to text.
 
 ---

docs/developer-guide/working-with-custom-formatters.md

@@ -11,6 +11,16 @@ module.exports = function(results) {
 };
 ```
 
+Formatter can also be an async function (from ESLint 8.2.0), the following shows a simple example:
+
+```js
+//my-awesome-formatter.js
+module.exports = async function(results) {
+    const formatted = await asyncTask();
+    return formatted;
+};
+```
+
 To run ESLint with this formatter, you can use the `-f` (or `--format`) command line flag:
 
 ```bash

lib/cli.js

@@ -178,7 +178,7 @@ async function printResults(engine, results, format, outputFile) {
         return false;
     }
 
-    const output = formatter.format(results);
+    const output = await formatter.format(results);
 
     if (output) {
         if (outputFile) {

tests/fixtures/async-formatter.js

@@ -0,0 +1,4 @@
+/*global module*/
+module.exports = function(results) {
+  return Promise.resolve('from async formatter');
+};

tests/lib/cli.js

@@ -287,6 +287,17 @@ describe("cli", () => {
         });
     });
 
+    describe("when given an async formatter path", () => {
+        it("should execute without any errors", async () => {
+            const formatterPath = getFixturePath("async-formatter.js");
+            const filePath = getFixturePath("passing.js");
+            const exit = await cli.execute(`-f ${formatterPath} ${filePath}`);
+
+            assert.strictEqual(log.info.getCall(0).args[0], "from async formatter");
+            assert.strictEqual(exit, 0);
+        });
+    });
+
     describe("when executing a file with a lint error", () => {
         it("should exit with error", async () => {
             const filePath = getFixturePath("undef.js");