errnode

Universal API for creating Node.js errors

Contents

• What is this?
• When should I use this?
• Install
• Use
• API
  • E
  • codes
  • determineSpecificType(value)
  • errors
  • formatList(list[, type])
  • hideStackFrames(fn)
  • isNodeError(value)
  • syscodes
• Types
  • Code
  • ErrnoException<[T]>
  • MessageFn<[T][, Args]>
  • NodeErrorConstructor<[T][, Args]>
  • NodeErrorMap
  • NodeError<[T]>
  • Stringifiable
  • SystemCode
  • SystemErrorMap
• Contribute

What is this?

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

When should I use this?

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

Install

This package is ESM only.

In Node.js (version 18+) with yarn:

yarn add @flex-development/errnode

See Git - Protocols | Yarn for details regarding installing from Git.

In Deno with esm.sh:

import{ERR_MODULE_NOT_FOUND}from'https://esm.sh/@flex-development/errnode'

In browsers with esm.sh:

<scripttype="module">import{ERR_MODULE_NOT_FOUND}from'https://esm.sh/@flex-development/errnode'</script>

Use

Say we have the file example.mjs:

import{ERR_INVALID_ARG_TYPE,isNodeError}from'@flex-development/errnode'/** * Ensure `value` is a string. * * @see {@linkcode ErrInvalidArgType} * * @param {unknown} value * Value supplied by user * @param {string} name * Name of invalid argument or property * @return {value is string} * `true` if `value` is a string * @throws {import('@flex-development/errnode').ErrInvalidArgType} * If `value` is not a string */functionvalidateString(value,name){if(typeofvalue==='string')returntruethrownewERR_INVALID_ARG_TYPE(name,'string',value)}try{validateString(null,'path')}catch(e){console.log('isNodeError:',isNodeError(e))console.log('TypeError:',einstanceofTypeError,'\n')throwe}

...running node example.mjs yields:

isNodeError: true
TypeError: true
file:///node_modules/@flex-development/errnode/dist/internal/stack-trace.mjs:9
Error.captureStackTrace(error);
^
TypeError: The 'path' argument must be of type string. Received null
at __node_internal_captureLargerStackTrace (file:///node_modules/@flex-development/errnode/dist/internal/stack-trace.mjs:9:9)
at new NodeError (file:///node_modules/@flex-development/errnode/dist/e.mjs:50:45)
at validateString (file:///example.mjs:19:9)
at file:///example.mjs:23:3
at ModuleJob.run (node:internal/modules/esm/module_job:234:25)
at async ModuleLoader.import (node:internal/modules/esm/loader:473:24)
at async asyncRunEntryPointWithESMLoader (node:internal/modules/run_main:123:5) {
code: 'ERR_INVALID_ARG_TYPE'
}

API

This package exports the following identifiers:

• E
• codes
• determineSpecificType
• errors
  • ERR_ARG_NOT_ITERABLE
  • ERR_ENCODING_NOT_SUPPORTED
  • ERR_IMPORT_ASSERTION_TYPE_FAILED
  • ERR_IMPORT_ASSERTION_TYPE_MISSING
  • ERR_IMPORT_ASSERTION_TYPE_UNSUPPORTED
  • ERR_IMPORT_ATTRIBUTE_MISSING
  • ERR_IMPORT_ATTRIBUTE_TYPE_INCOMPATIBLE
  • ERR_IMPORT_ATTRIBUTE_UNSUPPORTED
  • ERR_INCOMPATIBLE_OPTION_PAIR
  • ERR_INVALID_ARG_TYPE
  • ERR_INVALID_ARG_VALUE
  • ERR_INVALID_FILE_URL_HOST
  • ERR_INVALID_FILE_URL_PATH
  • ERR_INVALID_MODULE_SPECIFIER
  • ERR_INVALID_PACKAGE_CONFIG
  • ERR_INVALID_PACKAGE_TARGET
  • ERR_INVALID_RETURN_VALUE
  • ERR_INVALID_THIS
  • ERR_INVALID_TUPLE
  • ERR_INVALID_URL_SCHEME
  • ERR_INVALID_URL
  • ERR_METHOD_NOT_IMPLEMENTED
  • ERR_MISSING_ARGS
  • ERR_MISSING_OPTION
  • ERR_MODULE_NOT_FOUND
  • ERR_NETWORK_IMPORT_DISALLOWED
  • ERR_NO_CRYPTO
  • ERR_NO_ICU
  • 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
  • ERR_UNSUPPORTED_RESOLVE_REQUEST
• formatList
• hideStackFrames
• isNodeError
• syscodes

There is no default export.

Errors

Constructor functions representing Node.js error codes. Constructor arguments are used to build error messages.

Errors (and their types) can be imported individually:

import{ERR_INVALID_MODULE_SPECIFIER,ERR_INVALID_PACKAGE_CONFIG,ERR_INVALID_PACKAGE_TARGET,ERR_MODULE_NOT_FOUND,ERR_PACKAGE_IMPORT_NOT_DEFINED,ERR_PACKAGE_PATH_NOT_EXPORTED,ERR_UNSUPPORTED_DIR_IMPORT,typeErrInvalidModuleSpecifier,typeErrInvalidModuleSpecifierArgs,typeErrInvalidModuleSpecifierConstructor,typeErrInvalidPackageConfig,typeErrInvalidPackageConfigArgs,typeErrInvalidPackageConfigConstructor,typeErrInvalidPackageTarget,typeErrInvalidPackageTargetArgs,typeErrInvalidPackageTargetConstructor,typeErrModuleNotFound,typeErrModuleNotFoundArgs,typeErrModuleNotFoundConstructor,typeErrPackageImportNotDefined,typeErrPackageImportNotDefinedArgs,typeErrPackageImportNotDefinedConstructor,typeErrPackagePathNotExported,typeErrPackagePathNotExportedArgs,typeErrPackagePathNotExportedConstructor,typeErrUnsupportedDirImport,typeErrUnsupportedDirImportConstructor}from'@flex-development/errnode'

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

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

See the source code for documentation.

Note: This package does not export a constructor for every error. Submit a feature request (or pull request if you're up for the challenge 😉) to add a constructor. E can be used instead, however.

E(code, Base, message)

Create a Node.js error constructor.

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

Signatures

functionE<TextendsNodeErrorConstructor>(code: T['prototype']['code'],Base: ErrorConstructor,message: MessageFn<T['prototype'],Parameters<T>>|string): TfunctionE<TextendsNodeError,Argsextendsany[]=any[]>(code: T['code'],Base: ErrorConstructor,message: MessageFn<T,Args>): NodeErrorConstructor<T,Args>

Parameters

• code (Code) — error code
• Base (ErrorConstructor) — base class
• message (MessageFn | string) — error message string or function

Returns

(NodeErrorConstructor) NodeError constructor.

codes

Node.js error codes.

See NODE_VERSIONS for a list of supported Node.js versions.

determineSpecificType(value)

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

Parameters

• value (unknown) — value to check

Returns

(string) specific type of value.

formatList(list[, type])

Create a list string in the form 'A and B' or 'A, B, ..., and Z.

Parameters

• list (string | readonly string[]) — list to format
• type ('and' | 'or' | null | undefined, optional) — list transition type to insert before last element
  • default: 'and'

Returns

(string) formatted list.

hideStackFrames(fn)

Remove unnecessary frames from Node.js core errors.

Type Parameters

• T (Fn) — function to wrap

Parameters

• fn (T) — function to wrap

Returns

(T) the wrapped function.

isNodeError(value)

Check if value is a NodeError.

Parameters

• value (unknown) — value to check

Returns

(value is NodeError) true if value is NodeError, false otherwise.

syscodes

System error codes.

See NODE_VERSIONS for a list of supported Node.js versions.

Types

This package is fully typed with TypeScript.

Code

Union of registered codes that can occur where a node error code is expected (TypeScript type).

To register new codes, augment NodeErrorMap. They will be added to this union automatically.

typeCode=Extract<keyofNodeErrorMap,string>

ErrnoException<[T]>

Node.js exception object (TypeScript interface).

Type Parameters

• T (SystemCode, optional) — system error code
  • default: SystemCode

Extends

• Error

Properties

• code (T) — system error code
• errno (number) — libuv error number
• message (string) — error message, always prefixed by syscall and code
• path? (string | undefined) — relevant invalid pathname
• syscall (string) — failed syscall description

MessageFn<[T][, Args]>

Build an error message.

Type Parameters

• T (NodeError, optional) — node error
  • default: NodeError
• Args (readonly any[], optional) — message arguments
  • default: any[]

Parameters

• this (T) — node error object
• ...args (Args) — message arguments

Returns

(string) error message.

NodeErrorConstructor<[T][, Args]>

Node.js error constructor (TypeScript interface).

Type Parameters

• T (NodeError, optional) — node error
  • default: NodeError
• Args (readonly any[], optional) — message arguments
  • default: any[]

Signatures

• new (...args: Args): T
• (...args: Args): T

Properties

• prototype (T) — node.js error prototype

NodeErrorMap

Registry of Node.js error codes (TypeScript interface).

When developing utilities that use more codes, augment NodeErrorMap to register those codes:

declare module '@flex-development/errnode'{interfaceNodeErrorMap{ERR_CUSTOM: true}}

NodeError<[T]>

Node.js error object (TypeScript interface).

Type Parameters

• T (Code, optional) — error code
  • default: Code

Extends

• Error

Properties

• code (T) — error code
• toString (() => string) — get a string representation of the error

Stringifiable

A value with a toString method (TypeScript interface).

Properties

• toString (() => string) — get a string representation of the value

SystemCode

Union of registered codes that can occur where a system error code is expected (TypeScript type).

To register new codes, augment SystemErrorMap. They will be added to this union automatically.

typeSystemCode=Extract<keyofSystemErrorMap,string>

SystemErrorMap

Registry of system error codes (TypeScript interface).

When developing utilities that use more codes, augment SystemErrorMap to register those codes:

declare module '@flex-development/errnode'{interfaceSystemErrorMap{ECUSTOM: true}}

Contribute

See CONTRIBUTING.md.

This project has a code of conduct. By interacting with this repository, organization, or community you agree to abide by its terms.