@flex-development/errnode
v3.1.1
Published
Universal API for creating Node.js errors
Downloads
139
Maintainers
Readme
errnode
Universal API for creating Node.js errors
Contents
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
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>
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
*/
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'
}
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,
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 :wink:) 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
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>
Parameters
code
(Code
) — error codeBase
(ErrorConstructor
) — base classmessage
(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 formattype
('and' | 'or' | null | undefined
, optional) — list transition type to insert before last element- default:
'and'
- default:
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.
type Code = Extract<keyof NodeErrorMap, string>
ErrnoException<[T]>
Node.js exception object (TypeScript interface).
Type Parameters
T
(SystemCode
, optional) — system error code- default:
SystemCode
- default:
Extends
Error
Properties
code
(T
) — system error codeerrno
(number
) — libuv error numbermessage
(string
) — error message, always prefixed bysyscall
andcode
path?
(string | undefined
) — relevant invalid pathnamesyscall
(string
) — failed syscall description
MessageFn<[T][, Args]>
Build an error message.
Type Parameters
T
(NodeError
, optional) — node error- default:
NodeError
- default:
Args
(readonly any[]
, optional) — message arguments- default:
any[]
- default:
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
- default:
Args
(readonly any[]
, optional) — message arguments- default:
any[]
- default:
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' {
interface NodeErrorMap {
ERR_CUSTOM: true
}
}
NodeError<[T]>
Node.js error object (TypeScript interface).
Type Parameters
T
(Code
, optional) — error code- default:
Code
- default:
Extends
Error
Properties
code
(T
) — error codetoString
(() => 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.
type SystemCode = Extract<keyof SystemErrorMap, 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' {
interface SystemErrorMap {
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.