Add support for promise if w/o callback

Closes GH-80.

Author: wooorm

index.js

@@ -3,6 +3,7 @@
  * @typedef {import('./lib/file-set.js').Completer} Completer
  * @typedef {import('./lib/index.js').Callback} Callback
  * @typedef {import('./lib/configuration.js').ConfigTransform} ConfigTransform
+ * @typedef {import('./lib/index.js').ContextWithCode} ContextWithCode
  * @typedef {import('./lib/index.js').Context} Context
  * @typedef {import('./lib/file-set.js').FileSet} FileSet
  * @typedef {import('./lib/index.js').Options} Options

lib/index.js

@@ -5,7 +5,6 @@
  * @import {ConfigTransform, PresetSupportingSpecifiers} from './configuration.js'
  * @import {FileSet} from './file-set.js'
  * @import {ResolveFrom} from './ignore.js'
- * @import {Context} from './index.js'
  */
 
 /**
@@ -24,14 +23,23 @@
  *   Nothing.
  *
  *   Note: `void` included because `promisify` otherwise fails.
- *
+ */
+
+/**
+ * @typedef {Context & {code: 0 | 1}} ContextWithCode
+ *   Processing context with code.
+ */
+
+/**
  * @typedef Context
  *   Processing context.
  * @property {FileSet} fileSet
  *   Internally used info.
  * @property {Array<VFile>} files
  *   Processed files.
- *
+ */
+
+/**
  * @typedef Options
  *   Configuration.
  *
@@ -140,7 +148,9 @@
  *   Whether to output as a syntax tree (default: `options.tree`).
  * @property {boolean | undefined} [verbose=false]
  *   Report extra info (default: `false`); given to the reporter.
- *
+ */
+
+/**
  * @typedef Settings
  *   Resolved {@link Options `Options`} passed around.
  * @property {Options['processor']} processor
@@ -181,7 +191,9 @@
  * @property {Options['quiet']} quiet
  * @property {Options['frail']} frail
  * @property {Options['verbose']} verbose
- *
+ */
+
+/**
  * @callback VFileReporter
  *   Reporter.
  *
@@ -193,13 +205,16 @@
  *   Configuration.
  * @returns {Promise<string> | string}
  *   Report.
- *
+ */
+
+/**
  * @typedef {{[Key in keyof VFileReporterKnownFields]: VFileReporterKnownFields[Key]} & Record<string, unknown>} VFileReporterOptions
  *   Configuration.
  *
  *   Note: this weird type fixes TSC:
  */
 
+import assert from 'node:assert/strict'
 import process from 'node:process'
 import {PassThrough} from 'node:stream'
 import {fileURLToPath} from 'node:url'
@@ -209,14 +224,57 @@ import {fileSetPipeline} from './file-set-pipeline/index.js'
 /**
  * Process.
  *
+ * @overload
+ * @param {Options} options
+ * @param {Callback} callback
+ * @returns {undefined}
+ *
+ * @overload
+ * @param {Options} options
+ * @returns {Promise<ContextWithCode>}
+ *
+ * @overload
+ * @param {Options} options
+ * @param {Callback | null | undefined} [callback]
+ * @returns {Promise<ContextWithCode> | undefined}
+ *
  * @param {Options} options
  *   Configuration (required).
+ * @param {Callback | null | undefined} [callback]
+ *   Callback.
+ * @returns {Promise<ContextWithCode> | undefined}
+ *   Nothing.
+ */
+export function engine(options, callback) {
+  if (callback) {
+    return engineCallback(options, callback)
+  }
+
+  return new Promise(function (resolve, reject) {
+    engineCallback(options, function (error, code, context) {
+      if (error) {
+        reject(error)
+      } else {
+        assert(code !== undefined)
+        assert(context !== undefined)
+        resolve({code, fileSet: context.fileSet, files: context.files})
+      }
+    })
+  })
+}
+
+/**
+ * Process,
+ * always using callbacks.
+ *
+ * @param {Options} options
+ *   Configuration.
  * @param {Callback} callback
  *   Callback.
  * @returns {undefined}
  *   Nothing.
  */
-export function engine(options, callback) {
+function engineCallback(options, callback) {
   /** @type {Settings} */
   const settings = {}
   /** @type {NodeJS.ReadStream | PassThrough} */
@@ -231,10 +289,6 @@ export function engine(options, callback) {
     // Empty.
   }
 
-  if (!callback) {
-    throw new Error('Missing `callback`')
-  }
-
   if (!options || !options.processor) {
     return next(new Error('Missing `processor`'))
   }

readme.md

@@ -17,12 +17,13 @@
 * [Install](#install)
 * [Use](#use)
 * [API](#api)
-  * [`engine(options, callback)`](#engineoptions-callback)
+  * [`engine(options, callback?)`](#engineoptions-callback)
   * [`Configuration`](#configuration)
   * [`Completer`](#completer)
   * [`Callback`](#callback)
   * [`ConfigResult`](#configresult)
   * [`ConfigTransform`](#configtransform)
+  * [`ContextWithCode`](#contextwithcode)
   * [`Context`](#context)
   * [`FileSet`](#fileset)
   * [`Options`](#options)
@@ -154,20 +155,21 @@ This package exports the identifiers [`Configuration`][api-configuration] and
 [`engine`][api-engine].
 There is no default export.
 
-### `engine(options, callback)`
+### `engine(options, callback?)`
 
 Process.
 
 ###### Parameters
 
 * `options` ([`Options`][api-options], required)
   — configuration
-* `callback` ([`Callback`][api-callback], required)
-  — configuration
+* `callback` ([`Callback`][api-callback], optional)
+  — callback
 
 ###### Returns
 
-Nothing (`undefined`).
+If a callback is given, nothing (`undefined`).
+Otherwise [`Promise<ContextWithCode>`][api-context-with-code].
 
 ### `Configuration`
 
@@ -250,6 +252,20 @@ Transform arbitrary configs to our format (TypeScript type).
 
 Our config format ([`Preset`][api-preset]).
 
+### `ContextWithCode`
+
+Processing context with code (TypeScript type).
+
+###### Extends
+
+* [`Context`][api-context]
+
+###### Fields
+
+* `code` (`0` or `1`)
+  — exit code,
+  `0` if successful or `1` if unsuccessful
+
 ### `Context`
 
 Processing context (TypeScript type).
@@ -1538,6 +1554,7 @@ It exports the additional types
 [`Callback`][api-callback],
 [`ConfigResult`][api-config-result],
 [`ConfigTransform`][api-config-transform],
+[`ContextWithCode`][api-context-with-code],
 [`Context`][api-context],
 [`FileSet`][api-file-set],
 [`Options`][api-options],
@@ -1591,6 +1608,8 @@ abide by its terms.
 
 [api-context]: #context
 
+[api-context-with-code]: #contextwithcode
+
 [api-engine]: #engineoptions-callback
 
 [api-file-set]: #fileset

test/color.js

@@ -1,13 +1,11 @@
 import assert from 'node:assert/strict'
 import fs from 'node:fs/promises'
 import test from 'node:test'
-import {promisify} from 'node:util'
 import {engine} from 'unified-engine'
 import {cleanError} from './util/clean-error.js'
 import {noop} from './util/noop-processor.js'
 import {spy} from './util/spy.js'
 
-const run = promisify(engine)
 const fixtures = new URL('fixtures/', import.meta.url)
 
 test('color', async function (t) {
@@ -17,15 +15,15 @@ test('color', async function (t) {
 
     await fs.mkdir(cwd, {recursive: true})
 
-    const code = await run({
+    const result = await engine({
       color: true,
       cwd,
       files: ['readme.md'],
       processor: noop,
       streamError: stderr.stream
     })
 
-    assert.equal(code, 1)
+    assert.equal(result.code, 1)
     assert.equal(
       cleanError(stderr()),
       [

test/completers.js

@@ -6,12 +6,10 @@ import assert from 'node:assert/strict'
 import fs from 'node:fs/promises'
 import path from 'node:path'
 import test from 'node:test'
-import {promisify} from 'node:util'
 import {engine} from 'unified-engine'
 import {noop} from './util/noop-processor.js'
 import {spy} from './util/spy.js'
 
-const run = promisify(engine)
 const fixtures = new URL('fixtures/', import.meta.url)
 
 test('completers', async function (t) {
@@ -23,7 +21,7 @@ test('completers', async function (t) {
     // `pluginId` can be used for those to ensure the completer runs once.
     otherCompleter.pluginId = 'foo'
 
-    const code = await run({
+    const result = await engine({
       cwd: new URL('two-files/', fixtures),
       files: ['one.txt'],
       plugins: [
@@ -61,7 +59,7 @@ test('completers', async function (t) {
       streamError: stderr.stream
     })
 
-    assert.equal(code, 0)
+    assert.equal(result.code, 0)
     assert.equal(stderr(), 'one.txt: no issues found\n')
 
     /**
@@ -108,7 +106,7 @@ test('completers', async function (t) {
   await t.test('should support `fileSet.add` from plugins', async function () {
     const cwd = new URL('extensions/', fixtures)
     const stderr = spy()
-    const code = await run({
+    const result = await engine({
       cwd,
       files: ['foo.txt'],
       output: 'nested/',
@@ -127,7 +125,7 @@ test('completers', async function (t) {
 
     await fs.unlink(url)
 
-    assert.equal(code, 0)
+    assert.equal(result.code, 0)
     assert.equal(document, '')
     assert.equal(stderr(), 'foo.txt > nested' + path.sep + 'foo.txt: written\n')
   })

test/configuration-default.js

@@ -1,12 +1,10 @@
 import assert from 'node:assert/strict'
 import test from 'node:test'
-import {promisify} from 'node:util'
 import {engine} from 'unified-engine'
 import {noop} from './util/noop-processor.js'
 import {spy} from './util/spy.js'
 
 const fixtures = new URL('fixtures/', import.meta.url)
-const run = promisify(engine)
 
 test('`defaultConfig`', async function (t) {
   const defaultConfig = {
@@ -22,7 +20,7 @@ test('`defaultConfig`', async function (t) {
       globalThis.unifiedEngineTestCalls = 0
       globalThis.unifiedEngineTestValues = {}
 
-      const code = await run({
+      const result = await engine({
         cwd: new URL('config-default/', fixtures),
         defaultConfig,
         extensions: ['txt'],
@@ -32,7 +30,7 @@ test('`defaultConfig`', async function (t) {
         streamError: stderr.stream
       })
 
-      assert.equal(code, 0)
+      assert.equal(result.code, 0)
       assert.equal(stderr(), 'one.txt: no issues found\n')
       assert.equal(globalThis.unifiedEngineTestCalls, 1)
       assert.deepEqual(globalThis.unifiedEngineTestValues, {
@@ -50,7 +48,7 @@ test('`defaultConfig`', async function (t) {
       globalThis.unifiedEngineTestCalls = 0
       globalThis.unifiedEngineTestValues = {}
 
-      const code = await run({
+      const result = await engine({
         cwd: new URL('config-default/', fixtures),
         defaultConfig,
         extensions: ['txt'],
@@ -60,7 +58,7 @@ test('`defaultConfig`', async function (t) {
         streamError: stderr.stream
       })
 
-      assert.equal(code, 0)
+      assert.equal(result.code, 0)
       assert.equal(stderr(), 'one.txt: no issues found\n')
       assert.equal(globalThis.unifiedEngineTestCalls, 1)
       assert.deepEqual(