Add color option

Closes GH-21.

Co-authored-by: Robert Estelle <robertestelle@gmail.com>

Author: wooorm

.gitignore

@@ -5,4 +5,5 @@
 coverage/
 node_modules/
 yarn.lock
+!/lib/types.d.ts
 !/index.d.ts

index.d.ts

@@ -1,17 +1,2 @@
+export type {Options, Options as InspectOptions} from './lib/types.js'
 export {inspectColor, inspectNoColor, inspect} from './lib/index.js'
-
-// To do: next major: remove.
-/**
- * Deprecated, use `Options`.
- */
-export type InspectOptions = Options
-
-/**
- * Configuration.
- */
-export interface Options {
-  /**
-   * Whether to include positional information (default: `true`).
-   */
-  showPositions?: boolean | null | undefined
-}

lib/index.js

@@ -1,80 +1,77 @@
 /**
  * @import {Options} from 'unist-util-inspect'
  * @import {Node} from 'unist'
+ * @import {State} from './types.js'
  */
 
-/**
- * @typedef State
- *   Info passed around.
- * @property {boolean} showPositions
- *   Whether to include positional information.
- */
+import {color as colorDefault} from '#conditional-color'
 
-import {color} from '#conditional-color'
+/** @type {Options} */
+const emptyOptions = {}
+
+// To do: next major (?): use `Object.hasOwn`.
+const own = {}.hasOwnProperty
 
 /**
- * Inspect a node, with color in Node, without color in browsers.
+ * Inspect a node, without color.
  *
- * @param tree
+ * @param {unknown} tree
  *   Tree to inspect.
- * @param options
- *   Configuration (optional).
- * @returns
+ * @param {Options | null | undefined} [options]
+ *   Configuration.
+ * @returns {string}
  *   Pretty printed `tree`.
  */
-/* c8 ignore next */
-export const inspect = color ? inspectColor : inspectNoColor
-
-// To do: next major (?): use `Object.hasOwn`.
-const own = {}.hasOwnProperty
-
-const bold = ansiColor(1, 22)
-const dim = ansiColor(2, 22)
-const yellow = ansiColor(33, 39)
-const green = ansiColor(32, 39)
+export function inspect(tree, options) {
+  const settings = options || emptyOptions
+  const color =
+    typeof settings.color === 'boolean' ? settings.color : colorDefault
+  const showPositions =
+    typeof settings.showPositions === 'boolean' ? settings.showPositions : true
+  /** @type {State} */
+  const state = {
+    bold: color ? ansiColor(1, 22) : identity,
+    dim: color ? ansiColor(2, 22) : identity,
+    green: color ? ansiColor(32, 39) : identity,
+    showPositions,
+    yellow: color ? ansiColor(33, 39) : identity
+  }
 
-// ANSI color regex.
-/* eslint-disable no-control-regex */
-const colorExpression =
-  /(?:(?:\u001B\[)|\u009B)(?:\d{1,3})?(?:(?:;\d{0,3})*)?[A-M|f-m]|\u001B[A-M]/g
-/* eslint-enable no-control-regex */
+  return inspectValue(tree, state)
+}
 
+// To do: remove.
 /**
  * Inspect a node, without color.
  *
+ * @deprecated
+ *   Use `inspect` instead, with `color: false`.
  * @param {unknown} tree
  *   Tree to inspect.
- * @param {Options | null | undefined} [options]
+ * @param {Omit<Options, 'color'> | null | undefined} [options]
  *   Configuration.
  * @returns {string}
  *   Pretty printed `tree`.
  */
 export function inspectNoColor(tree, options) {
-  return inspectColor(tree, options).replace(colorExpression, '')
+  return inspect(tree, {...options, color: false})
 }
 
+// To do: remove.
 /**
  * Inspects a node, using color.
  *
+ * @deprecated
+ *   Use `inspect` instead, with `color: true`.
  * @param {unknown} tree
  *   Tree to inspect.
- * @param {Options | null | undefined} [options]
+ * @param {Omit<Options, 'color'> | null | undefined} [options]
  *   Configuration (optional).
  * @returns {string}
  *   Pretty printed `tree`.
  */
 export function inspectColor(tree, options) {
-  /** @type {State} */
-  const state = {
-    showPositions:
-      !options ||
-      options.showPositions === null ||
-      options.showPositions === undefined
-        ? true
-        : options.showPositions
-  }
-
-  return inspectValue(tree, state)
+  return inspect(tree, {...options, color: true})
 }
 
 /**
@@ -129,15 +126,16 @@ function inspectNodes(nodes, state) {
 
   while (++index < nodes.length) {
     result.push(
-      dim(
+      state.dim(
         (index < nodes.length - 1 ? '├' : '└') +
           '─' +
           String(index).padEnd(size)
       ) +
         ' ' +
         indent(
           inspectValue(nodes[index], state),
-          (index < nodes.length - 1 ? dim('│') : ' ') + ' '.repeat(size + 2),
+          (index < nodes.length - 1 ? state.dim('│') : ' ') +
+            ' '.repeat(size + 2),
           true
         )
     )
@@ -202,14 +200,17 @@ function inspectFields(object, state) {
     }
 
     result.push(
-      key + dim(':') + (/\s/.test(formatted.charAt(0)) ? '' : ' ') + formatted
+      key +
+        state.dim(':') +
+        (/\s/.test(formatted.charAt(0)) ? '' : ' ') +
+        formatted
     )
   }
 
   return indent(
     result.join('\n'),
     (isArrayUnknown(object.children) && object.children.length > 0
-      ? dim('│')
+      ? state.dim('│')
       : ' ') + ' '
   )
 }
@@ -250,7 +251,7 @@ function inspectTree(node, state) {
  *   Formatted node.
  */
 function formatNode(node, state) {
-  const result = [bold(node.type)]
+  const result = [state.bold(node.type)]
   // Cast as record to allow indexing.
   const map = /** @type {Record<string, unknown>} */ (
     /** @type {unknown} */ (node)
@@ -263,13 +264,17 @@ function formatNode(node, state) {
   }
 
   if (isArrayUnknown(map.children)) {
-    result.push(dim('['), yellow(String(map.children.length)), dim(']'))
+    result.push(
+      state.dim('['),
+      state.yellow(String(map.children.length)),
+      state.dim(']')
+    )
   } else if (typeof map.value === 'string') {
-    result.push(' ', green(inspectNonTree(map.value)))
+    result.push(' ', state.green(inspectNonTree(map.value)))
   }
 
   if (position) {
-    result.push(' ', dim('('), position, dim(')'))
+    result.push(' ', state.dim('('), position, state.dim(')'))
   }
 
   return result.join('')
@@ -394,3 +399,12 @@ function isNode(value) {
 function isArrayUnknown(node) {
   return Array.isArray(node)
 }
+
+/**
+ * @template T
+ * @param {T} value
+ * @returns {T}
+ */
+function identity(value) {
+  return value
+}

lib/types.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Configuration.
+ */
+export interface Options {
+  /**
+   * Whether to use ANSI colors (default: `true` in Node, `false` otherwise).
+   */
+  color?: boolean | null | undefined
+  /**
+   * Whether to include positional info (default: `true`).
+   */
+  showPositions?: boolean | null | undefined
+}
+
+/**
+ * Info passed around.
+ */
+export interface State {
+  /**
+   * Node type.
+   */
+  bold: Style
+  /**
+   * Punctuation.
+   */
+  dim: Style
+  /**
+   * Non-tree value.
+   */
+  green: Style
+  /**
+   * Whether to include positional info.
+   */
+  showPositions: boolean
+  /**
+   * Numeric count of node children.
+   */
+  yellow: Style
+}
+
+/**
+ * Style a string.
+ *
+ * @param value
+ *   Value to style.
+ * @returns
+ *   Styled value.
+ */
+type Style = (value: string) => string

lib/types.js

@@ -0,0 +1,2 @@
+// Types only.
+export {}

readme.md

@@ -113,11 +113,15 @@ Pretty printed `tree` (`string`).
 
 ### `inspectColor(tree[, options])`
 
+> 🪦 **Deprecated**: use `color` option of `inspect`.
+
 Inspect a tree, with color.
 Otherwise same as [`inspect`][api-inspect].
 
 ### `inspectNoColor(tree[, options])`
 
+> 🪦 **Deprecated**: use `color` option of `inspect`.
+
 Inspect a tree, without color.
 Otherwise same as [`inspect`][api-inspect].
 
@@ -127,6 +131,8 @@ Configuration (TypeScript type).
 
 ###### Fields
 
+* `color` (`boolean`, default: `true` in Node, `false` otherwise)
+  — whether to use ANSI colors
 * `showPositions` (`boolean`, default: `true`)
   — whether to include positional information
 

tsconfig.json

@@ -12,5 +12,5 @@
     "target": "es2022"
   },
   "exclude": ["coverage/", "node_modules/"],
-  "include": ["**/*.js", "index.d.ts"]
+  "include": ["**/*.js", "lib/types.d.ts", "index.d.ts"]
 }