Universal API for creating Node.js errors
This package provides a universal API for creating Node.js errors.
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.
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
:
<script type="module">
import { ERR_MODULE_NOT_FOUND } from 'https://esm.sh/@flex-development/errnode'
</script>
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
*/
function validateString(value, name) {
if (typeof value === 'string') return true
throw new ERR_INVALID_ARG_TYPE(name, 'string', value)
}
try {
validateString(null, 'path')
} catch (e) {
console.log('isNodeError:', isNodeError(e))
console.log('TypeError:', e instanceof TypeError, '\n')
throw e
}
...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'
}
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.
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,
type ErrInvalidModuleSpecifier,
type ErrInvalidModuleSpecifierArgs,
type ErrInvalidModuleSpecifierConstructor,
type ErrInvalidPackageConfig,
type ErrInvalidPackageConfigArgs,
type ErrInvalidPackageConfigConstructor,
type ErrInvalidPackageTarget,
type ErrInvalidPackageTargetArgs,
type ErrInvalidPackageTargetConstructor,
type ErrModuleNotFound,
type ErrModuleNotFoundArgs,
type ErrModuleNotFoundConstructor,
type ErrPackageImportNotDefined,
type ErrPackageImportNotDefinedArgs,
type ErrPackageImportNotDefinedConstructor,
type ErrPackagePathNotExported,
type ErrPackagePathNotExportedArgs,
type ErrPackagePathNotExportedConstructor,
type ErrUnsupportedDirImport,
type ErrUnsupportedDirImportConstructor
} 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.
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
.
function E<T extends NodeErrorConstructor>(
code: T['prototype']['code'],
Base: ErrorConstructor,
message: MessageFn<T['prototype'], Parameters<T>> | string
): T
function E<T extends NodeError, Args extends any[] = any[]>(
code: T['code'],
Base: ErrorConstructor,
message: MessageFn<T, Args>
): NodeErrorConstructor<T, Args>
-
code
(Code
) — error code -
Base
(ErrorConstructor
) — base class -
message
(MessageFn
|string
) — error message string or function
(NodeErrorConstructor
) NodeError
constructor.
Node.js error codes.
See NODE_VERSIONS
for a list of supported Node.js versions.
Determine the specific type of a value for type-mismatch errors.
-
value
(unknown
) — value to check
(string
) specific type of value
.
Create a list string in the form 'A and B'
or 'A, B, ..., and Z
.
-
list
(string | readonly string[]
) — list to format -
type
('and' | 'or' | null | undefined
, optional) — list transition type to insert before last element-
default:
'and'
-
default:
(string
) formatted list.
Remove unnecessary frames from Node.js core errors.
-
T
(Fn
) — function to wrap
-
fn
(T
) — function to wrap
(T
) the wrapped function.
Check if value
is a NodeError
.
-
value
(unknown
) — value to check
(value is NodeError
) true
if value
is NodeError
, false
otherwise.
System error codes.
See NODE_VERSIONS
for a list of supported Node.js versions.
This package is fully typed with TypeScript.
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.
type Code = Extract<keyof NodeErrorMap, string>
Node.js exception object (TypeScript interface).
-
T
(SystemCode
, optional) — system error code-
default:
SystemCode
-
default:
Error
-
code
(T
) — system error code -
errno
(number
) — libuv error number -
message
(string
) — error message, always prefixed bysyscall
andcode
-
path?
(string | undefined
) — relevant invalid pathname -
syscall
(string
) — failed syscall description
Build an error message.
-
T
(NodeError
, optional) — node error-
default:
NodeError
-
default:
-
Args
(readonly any[]
, optional) — message arguments-
default:
any[]
-
default:
-
this
(T
) — node error object -
...args
(Args
) — message arguments
(string
) error message.
Node.js error constructor (TypeScript interface).
-
T
(NodeError
, optional) — node error-
default:
NodeError
-
default:
-
Args
(readonly any[]
, optional) — message arguments-
default:
any[]
-
default:
new (...args: Args): T
(...args: Args): T
-
prototype
(T
) — node.js error prototype
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' {
interface NodeErrorMap {
ERR_CUSTOM: true
}
}
Node.js error object (TypeScript interface).
-
T
(Code
, optional) — error code-
default:
Code
-
default:
Error
-
code
(T
) — error code -
toString
(() => string
) — get a string representation of the error
A value with a toString
method (TypeScript interface).
-
toString
(() => string
) — get a string representation of the value
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.
type SystemCode = Extract<keyof SystemErrorMap, string>
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' {
interface SystemErrorMap {
ECUSTOM: true
}
}
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.