main.d.ts

import type { Styles } from 'chalk-string'
import type figures from 'figures'

/**
 * Validate `beautiful-error` options
 */
export function validateOptions(options: unknown): asserts options is Options

/**
 * `beautiful-error` options
 */
export interface Options {
  /**
   * Whether to show the `error` stack trace.
   *
   * @default true
   */
  readonly stack?: boolean

  /**
   * Whether to show nested errors, i.e.
   * [`error.cause`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/cause)
   * and
   * [`error.errors`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/AggregateError/errors).
   *
   * @default true
   */
  readonly cause?: boolean

  /**
   * Whether to show the error's additional properties.
   *
   * @default true
   */
  readonly props?: boolean

  /**
   * Whether to colorize the error's message, stack trace and additional properties.
   *
   * Quoted strings in the error's message are printed in bold (for `"..."` and
   * `'...'`) and in italic (for `` `...` ``).
   *
   * @default `true` in terminals, `false` otherwise
   */
  readonly colors?: boolean

  /**
   * Icon prepended to the error's name. The available values are listed
   * [here](https://github.com/sindresorhus/figures/blob/main/readme.md#figures-1).
   * Can be disabled by passing an empty string.
   *
   * @default 'cross'
   */
  readonly icon?: keyof typeof figures | ''

  /**
   * Color/style of the error's icon and name. The available values are listed
   * [here](https://github.com/ehmicky/chalk-string#available-styles).
   * Several styles can be specified by using spaces.
   * Can be disabled by passing an empty string.
   *
   * @default 'red bold'
   */
  readonly header?: Styles | ''

  /**
   * Name of a method to map the output. That method must take the output as a
   * string argument, transform it then return it.
   *
   * @example
   * ```js
   * class ExampleError extends Error {
   *   beautiful(output) {
   *     return output.replaceAll('secret', '***')
   *   }
   * }
   *
   * const error = new ExampleError('Unknown value: secret')
   * const message = beautifulError(error) // 'Unknown value: ***'
   * ```
   *
   * @default 'beautiful'
   */
  readonly custom?: string | symbol

  /**
   * Specify different options per error class. The object:
   *  - Keys are either the
   *    [`error.name`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/name),
   *    or `"default"` (used if no `error.name` matches)
   *  - Values are options objects
   *
   * @default {}
   *
   * @example
   * ```js
   * const message = beautifulError(error, {
   *   InputError: { icon: 'warning', stack: false },
   *   DatabaseError: { icon: 'info', stack: false },
   *   default: { icon: 'cross' },
   * })
   * ```
   */
  readonly classes?: {
    readonly [errorName: string]: Omit<Options, 'classes'>
  }
}

/**
 * Returns `error` as a prettified string.
 *
 * This never throws. Invalid `error`s are silently
 * [normalized](https://github.com/ehmicky/normalize-exception).
 *
 * @example
 * ```js
 * import beautifulError from 'beautiful-error'
 *
 * try {
 *   // ...
 * } catch (error) {
 *   const message = beautifulError(error)
 *   console.error(message)
 * }
 * ```
 */
export default function beautifulError(
  error: unknown,
  options?: Options,
): string