Universal API for creating Node.js errors

• What is this?
• When should I use this?
  • Differences between Node.js
• Install
• Use
• API
  • Error Models
    • ERR_AMBIGUOUS_ARGUMENT(reason)
    • ERR_ARG_NOT_ITERABLE(name)
    • ERR_ASYNC_CALLBACK(name)
    • ERR_ILLEGAL_CONSTRUCTOR()
    • ERR_IMPORT_ASSERTION_TYPE_FAILED(id, type)
    • ERR_IMPORT_ASSERTION_TYPE_MISSING(id, type)
    • ERR_IMPORT_ASSERTION_TYPE_UNSUPPORTED(type)
    • ERR_INCOMPATIBLE_OPTION_PAIR(option1, option2)
    • ERR_INVALID_ARG_TYPE(name, expected, actual)
    • ERR_INVALID_ARG_VALUE(name, value[, reason])
    • ERR_INVALID_MODULE_SPECIFIER(request[, reason][, base])
    • ERR_INVALID_PACKAGE_CONFIG(id[, base][, reason])
    • ERR_INVALID_PACKAGE_TARGET(dir, key, target[, internal][, base])
    • ERR_INVALID_RETURN_VALUE(expected, name, value)
    • ERR_INVALID_URL(input)
    • ERR_METHOD_NOT_IMPLEMENTED(method)
    • ERR_MISSING_OPTION(option)
    • ERR_MODULE_NOT_FOUND(id, base[, type])
    • ERR_NETWORK_IMPORT_DISALLOWED(specifier, base, reason)
    • ERR_OPERATION_FAILED(reason)
    • ERR_PACKAGE_IMPORT_NOT_DEFINED(specifier, base[, dir])
    • ERR_PACKAGE_PATH_NOT_EXPORTED(dir, subpath[, base])
    • ERR_UNHANDLED_ERROR([err])
    • ERR_UNKNOWN_BUILTIN_MODULE(name)
    • ERR_UNKNOWN_ENCODING(encoding)
    • ERR_UNKNOWN_FILE_EXTENSION(ext, id[, suggestion])
    • ERR_UNKNOWN_MODULE_FORMAT(format, id)
    • ERR_UNSUPPORTED_DIR_IMPORT(id, base)
    • ERR_UNSUPPORTED_ESM_URL_SCHEME(url, supported[, windows])
  • Utilities
    • createNodeError(code, Base, message)
    • determineSpecificType(value)
• Types
  • Enums
  • Interfaces
  • Type Defintions
• Contribute

This package provides a universal API for creating Node.js errors.

This package is designed to help developers build Node.js tools like ponyfills, as well as more verbose tools like mlly, by providing a set of utilities and constructor functions for creating Node.js errors.

• Does not capture larger stack traces: The Node.js API temporarily overrides Error.stackTraceLimit to capture larger stack traces. This is not implemented to maintain browser compatibility.

This package is ESM only.

yarn add @flex-development/errnode

From Git:

yarn add @flex-development/errnode@flex-development/errnode

See Git - Protocols | Yarn  for details on requesting a specific branch, commit, or tag.

import {
  createNodeError,
  ErrorCode,
  type MessageFn,
  type NodeError,
  type NodeErrorConstructor
} from '@flex-development/errnode'

/**
 * [`ERR_INVALID_URL`][1] schema.
 *
 * [1]: https://nodejs.org/api/errors.html#err_invalid_url
 *
 * @extends {NodeError<TypeError>}
 */
interface ErrInvalidUrl extends NodeError<TypeError> {
  /**
   * Error code.
   */
  code: ErrorCode.ERR_INVALID_URL

  /**
   * URL that failed to parse.
   *
   * @example
   *  'http://[127.0.0.1\x00c8763]:8000/'
   */
  input: string
}

/**
 * `ERR_INVALID_URL` model.
 *
 * Thrown when an invalid URL is passed to a [WHATWG][1] [`URL` constructor][2]
 * or [`url.parse()`][3] to be parsed.
 *
 * [1]: https://nodejs.org/api/url.html#the-whatwg-url-api
 * [2]: https://nodejs.org/api/url.html#new-urlinput-base
 * [3]: https://nodejs.org/api/url.html#urlparseurlstring-parsequerystring-slashesdenotehost
 *
 * @see https://nodejs.org/api/errors.html#err_invalid_url
 *
 * @class
 *
 * @param {string} input - URL that failed to parse
 * @return {ErrInvalidUrl} New `TypeError` instance
 */
const ERR_INVALID_URL: NodeErrorConstructor<
  ErrInvalidUrl,
  MessageFn<[string]>
> = createNodeError(
  ErrorCode.ERR_INVALID_URL,
  TypeError,
  /**
   * Creates an [`ERR_INVALID_URL`][1] message.
   *
   * [1]: https://nodejs.org/api/errors.html#err_invalid_url
   *
   * @see https://github.com/nodejs/node/blob/v19.3.0/lib/internal/errors.js#L1381-L1386
   *
   * @this {ErrInvalidUrl}
   *
   * @param {string} input - URL that failed to parse
   * @return {string} Error message
   */
  function msg(this: ErrInvalidUrl, input: string): string {
    this.input = input
    return 'Invalid URL'
  }
)

/**
 * URL that will fail to parse.
 *
 * @const {string} BAD_URL
 */
const BAD_URL: string = 'http://[127.0.0.1\x00c8763]:8000/'

/**
 * {@linkcode ERR_INVALID_URL} instance.
 *
 * @const {ErrInvalidUrl} err
 */
const err: ErrInvalidUrl = new ERR_INVALID_URL(BAD_URL)

console.error(err)
console.debug('err instanceof TypeError:', err instanceof TypeError)

...running that yields:

TypeError [ERR_INVALID_URL]: Invalid URL
    at new NodeError (file:////home/runner/work/errnode/errnode/src/create-node-error.ts:103:5)
    at file:////home/runner/work/errnode/errnode/scratch.ts:90:28
    at ModuleJob.run (node:internal/modules/esm/module_job:193:25)
    at async Promise.all (index 0)
    at async ESMLoader.import (node:internal/modules/esm/loader:533:24)
    at async loadESM (node:internal/process/esm_loader:91:5)
    at async handleMainPromise (node:internal/modules/run_main:65:12) {
  code: 'ERR_INVALID_URL',
  input: 'http://[127.0.0.1\x00c8763]:8000/'
}
err instanceof TypeError: true

This package exports the following identifiers:

• ERR_AMBIGUOUS_ARGUMENT
• ERR_ARG_NOT_ITERABLE
• ERR_ASYNC_CALLBACK
• ERR_ILLEGAL_CONSTRUCTOR
• ERR_IMPORT_ASSERTION_TYPE_FAILED
• ERR_IMPORT_ASSERTION_TYPE_MISSING
• ERR_IMPORT_ASSERTION_TYPE_UNSUPPORTED
• ERR_INCOMPATIBLE_OPTION_PAIR
• ERR_INVALID_ARG_TYPE
• ERR_INVALID_ARG_VALUE
• ERR_INVALID_MODULE_SPECIFIER
• ERR_INVALID_PACKAGE_CONFIG
• ERR_INVALID_PACKAGE_TARGET
• ERR_INVALID_RETURN_VALUE
• ERR_INVALID_URL
• ERR_METHOD_NOT_IMPLEMENTED
• ERR_MISSING_OPTION
• ERR_MODULE_NOT_FOUND
• ERR_NETWORK_IMPORT_DISALLOWED
• ERR_OPERATION_FAILED
• ERR_PACKAGE_IMPORT_NOT_DEFINED
• ERR_PACKAGE_PATH_NOT_EXPORTED
• ERR_UNHANDLED_ERROR
• ERR_UNKNOWN_BUILTIN_MODULE
• ERR_UNKNOWN_ENCODING
• ERR_UNKNOWN_FILE_EXTENSION
• ERR_UNKNOWN_MODULE_FORMAT
• ERR_UNSUPPORTED_DIR_IMPORT
• ERR_UNSUPPORTED_ESM_URL_SCHEME
• createNodeError
• determineSpecificType
• errors

There is no default export.

Constructor functions representing Node.js error codes, callable only with the new keyword. Constructor arguments are used to generate error messages.

Models can be imported individually:

import {
  ERR_INVALID_ARG_VALUE,
  ERR_INVALID_MODULE_SPECIFIER,
  ERR_INVALID_PACKAGE_CONFIG,
  ERR_INVALID_PACKAGE_TARGET,
  ERR_INVALID_URL,
  ERR_MODULE_NOT_FOUND,
  ERR_NETWORK_IMPORT_DISALLOWED,
  ERR_PACKAGE_IMPORT_NOT_DEFINED,
  ERR_PACKAGE_PATH_NOT_EXPORTED,
  ERR_UNKNOWN_FILE_EXTENSION,
  ERR_UNSUPPORTED_DIR_IMPORT,
  ERR_UNSUPPORTED_ESM_URL_SCHEME
 } from '@flex-development/errnode'

...or all at once using the errors export:

import { errors } from '@flex-development/errnode'

Note: This package does not export a model for every error code. Submit a feature request (or pull request if you're up for the challenge 😉) to add a model. For more fine-grained control, however, use createNodeError instead.

Thrown when a function argument is being used in a way that suggests that the function signature may be misunderstood.

• {string} name — Name of ambiguous argument
• {string} reason — Reason name is ambiguous
• Returns: {NodeError<TypeError>}

Source: src/models/err-ambiguous-argument.ts

Thrown when an iterable argument (i.e. a value that works with for...of loops) is required, but not provided to a Node.js API.

• {string} name — Name of non-iterable argument
• Returns: {NodeError<TypeError>}

Source: src/models/err-arg-not-iterable.ts

Thrown when an attempt is made to register something that is not a function as an AsyncHooks callback.

• {string} name — Name of argument that must be a function
• Returns: {NodeError<TypeError>}

Source: src/models/err-async-callback.ts

Thrown when an attempt is made to construct an object using a non-public constructor.

• Returns: {NodeError<TypeError>}

Source: src/models/err-illegal-constructor.ts

Thrown when an import assertion has failed, preventing the specified module from being imported.

• {string} id — Id of module that cannot be imported
• {string} type — Invalid import assertion type
• Returns: {NodeError<TypeError>}

Source: src/models/err-import-assertion-type-failed.ts

Thrown when an import assertion is missing, preventing the specified module from being imported.

• {string} id — Id of module that cannot be imported
• {string} type — Invalid import assertion type
• Returns: {NodeError<TypeError>}

Source: src/models/err-import-assertion-type-missing.ts

Thrown when an import assertion is not supported by a version of Node.js.

• {string} type — Unsupported import assertion type
• Returns: {NodeError<TypeError>}

Source: src/models/err-import-assertion-type-unsupported.ts

Thrown when an option pair is incompatible with each other and cannot be used at the same time.

• {string} option1 — Option that cannot be used
• {string} option2 — Option that is incompatible with option1
• Returns: {NodeError<TypeError>}

Source: src/models/err-incompatible-option-pair.ts

Thrown when an argument of the wrong type is passed to a Node.js API.

• {string} name — Name of invalid argument or property
• {OneOrMany<string>} expected — Expected type(s)
• {unknown} actual — Value supplied by user
• Returns: {NodeError<TypeError>}

Source: src/models/err-invalid-arg-type.ts

Thrown when an invalid or unsupported value is passed for a given argument or property.

• {string} name — Name of invalid argument or property
• {unknown} value — Value supplied by user
• {string?} [reason='is invalid'] — Reason value is invalid
• Returns: {NodeError<TypeError>}

Source: src/models/err-invalid-arg-value.ts

Thrown when an imported module string is an invalid URL, package name, or package subpath specifier.

• {string} request — Invalid module specifier
• {string?} [reason=''] — Reason request is invalid
• {string?} [base=''] — Id of module request was imported from
• Returns: {NodeError<TypeError>}

Source: src/models/err-invalid-module-specifier.ts

Thrown when a package.json file fails parsing.

• {string} id — Location of invalid package.json file
• {string?} [base=''] — Id of module being imported. May also include where module is being imported from
• {string?} [reason=''] — Reason package config is invalid
• Returns: {NodeError}

Source: src/models/err-invalid-package-config.ts

Thrown when a package.json "exports" or "imports" field contains an invalid target mapping value for the attempted module resolution.

• {string} dir — Id of directory containing package.json
• {string} key — "exports" or "imports" key
• {unknown} target — Invalid package target
• {boolean?} [internal=false] — target is "imports"?
• {string?} [base=''] — Id of module package.json was imported from
• Returns: {NodeError}

Source: src/models/err-invalid-package-target.ts

Thrown when a function does not return an expected value type on execution, such as when a function is expected to return a promise.

• {string} expected — Expected return value type
• {string} name — Name of function that returned invalid value type
• {unknown} value — Value supplied by user
• Returns: {NodeError<TypeError>}

Source: src/models/err-invalid-return-value.ts

Thrown when an invalid URL is passed to a WHATWG URL constructor or url.parse() to be parsed.

• {string} input — URL that failed to parse
• Returns: {ErrInvalidUrl}

Source: src/models/err-invalid-url.ts

Thrown when a method is required but not implemented.

• {string} method — Method name
• Returns: {NodeError}

Source: src/models/err-method-not-implemented.ts

Thrown when a required option is missing. For APIs that accept options objects, some options might be mandatory.

• {string} option — Option name
• Returns: {NodeError<TypeError>}

Source: src/models/err-missing-option.ts

Thrown when a module file cannot be resolved by the ECMAScript modules loader while attempting an import operation or when loading a program entry point.

• {string} id — Id of missing module
• {string} base — Id of module id was imported from
• {string?} [type='package'] — Module file type
• Returns: {NodeError}

Source: src/models/err-module-not-found.ts

Thrown when a network module attempts to load another module that it is not allowed to load.

• {string} specifier — Invalid module specifier
• {string} base — Id of module specifier was imported from
• {string} reason — Reason for error
• Returns: {NodeError}

Source: src/models/err-network-import-disallowed.ts

Thrown when an operation has failed. Typically used to signal the general failure of an asynchronous operation.

• {string} reason — Reason for operation failure
• Returns: {NodeError}

Source: src/models/err-operation-failed.ts

Thrown when a package.json "imports" field does not define the given package import specifier.

• {string} specifier — Invalid package import specifier
• {string} base — Id of module specifier was imported from
• {string?} [dir=''] — Id of directory containing package.json
• Returns: {NodeError<TypeError>}

Source: src/models/err-package-import-not-defined.ts

Thrown when a package.json "exports" field does not export the requested subpath.

• {string} dir — Id of directory containing package.json
• {string} subpath — Requested subpath
• {string?} [base=''] — Id of module subpath was imported from
• Returns: {NodeError}

Source: src/models/err-package-path-not-exported.ts

Thrown when an unhandled error occurs.

• {string?} [err=''] — Stringified error
• Returns: {NodeError}

Source: src/models/err-unhandled-error.ts

Thrown when an unknown builtin module is encountered.

• {string} name — Module name
• Returns: {NodeError}

Source: src/models/err-unknown-builtin-module.ts

Thrown when an invalid or unknown encoding option is passed to a Node.js API.

• {string} encoding — Invalid or unknown encoding
• Returns: {NodeError<TypeError>}

Source: src/models/err-unknown-encoding.ts

Thrown when an attempt is made to load a module with an unknown or unsupported file extension.

• {string} ext — Unknown or unsupported file extension
• {string} id — Id of module containing ext
• {string?} [suggestion=''] — Recommended fix
• Returns: {NodeError<TypeError>}

Source: src/models/err-unknown-file-extension.ts

Thrown when an attempt is made to load a module with an unknown or unsupported format.

• {string} format — Unknown or unsupported format
• {string} id — Id of module with format
• Returns: {NodeError<RangeError>}

Source: src/models/err-unknown-module-format.ts

Thrown when a directory URL is imported.

• {string} id — Module id of directory
• {string} base — Id of module id was imported from
• Returns: {NodeError}

Source: src/models/err-unsupported-dir-import.ts

Thrown when an unsupported URL scheme is used in an import statement. URL schemes other than file and data are unsupported.

• {URL} url — URL containing unsupported scheme
• {string[]} supported — Supported URL schemes
• {boolean?} [windows=false] — Windows operating system?
• Returns: {NodeError}

Source: src/models/err-unsupported-esm-url-scheme.ts

Creates a Node.js error constructor.

Constructor arguments are passed to util.format if the error message is a string, or message itself if it is a function. Message functions will also be called with the new Node.js error instance as this.

• {ErrorCode} code — Node.js error code
• {ErrnodeConstructor} Base — Error base class
• {Message} message — Error message string or function
• Returns: {NodeErrorConstructor NodeError constructor

Source: src/utils/create-node-error.ts

Determines the specific type of a value for type-mismatch errors.

• {unknown} value — Value to evaluate
• Returns: {string} Specific type of value

Source: src/utils/determine-specific-type.ts

This package is fully typed with TypeScript. It exports the following definitions:

• ErrorCode
• SystemErrorCode

• CallSite
• ErrInvalidUrl
• ErrnoException
• NodeErrorConstructor

• ErrnodeConstructor
• MessageFn
• Message
• NodeError

See CONTRIBUTING.md.