@flex-development/errnode
Advanced tools
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:
EcodesdetermineSpecificTypeerrors
ERR_ARG_NOT_ITERABLEERR_ENCODING_NOT_SUPPORTEDERR_IMPORT_ASSERTION_TYPE_FAILEDERR_IMPORT_ASSERTION_TYPE_MISSINGERR_IMPORT_ASSERTION_TYPE_UNSUPPORTEDERR_IMPORT_ATTRIBUTE_MISSINGERR_IMPORT_ATTRIBUTE_TYPE_INCOMPATIBLEERR_IMPORT_ATTRIBUTE_UNSUPPORTEDERR_INCOMPATIBLE_OPTION_PAIRERR_INVALID_ARG_TYPEERR_INVALID_ARG_VALUEERR_INVALID_FILE_URL_HOSTERR_INVALID_FILE_URL_PATHERR_INVALID_MODULE_SPECIFIERERR_INVALID_PACKAGE_CONFIGERR_INVALID_PACKAGE_TARGETERR_INVALID_RETURN_VALUEERR_INVALID_THISERR_INVALID_TUPLEERR_INVALID_URL_SCHEMEERR_INVALID_URLERR_METHOD_NOT_IMPLEMENTEDERR_MISSING_ARGSERR_MISSING_OPTIONERR_MODULE_NOT_FOUNDERR_NETWORK_IMPORT_DISALLOWEDERR_NO_CRYPTOERR_NO_ICUERR_OPERATION_FAILEDERR_PACKAGE_IMPORT_NOT_DEFINEDERR_PACKAGE_PATH_NOT_EXPORTEDERR_UNHANDLED_ERRORERR_UNKNOWN_BUILTIN_MODULEERR_UNKNOWN_ENCODINGERR_UNKNOWN_FILE_EXTENSIONERR_UNKNOWN_MODULE_FORMATERR_UNSUPPORTED_DIR_IMPORTERR_UNSUPPORTED_ESM_URL_SCHEMEERR_UNSUPPORTED_RESOLVE_REQUESTformatListhideStackFramesisNodeErrorsyscodesThere 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 :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.
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 codeBase (ErrorConstructor)
— base classmessage (MessageFn | string)
— error message string or function(NodeErrorConstructor) NodeError constructor.
codesNode.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.
value (unknown)
— value to check(string) specific type of value.
formatList(list[, type])Create a list string in the form 'A and B' or 'A, B, ..., and Z.
list (string | readonly string[])
— list to formattype ('and' | 'or' | null | undefined, optional)
— list transition type to insert before last element
'and'(string) formatted list.
hideStackFrames(fn)Remove unnecessary frames from Node.js core errors.
T (Fn)
— function to wrapfn (T)
— function to wrap(T) the wrapped function.
isNodeError(value)Check if value is a NodeError.
value (unknown)
— value to check(value is NodeError) true if value is NodeError, false otherwise.
syscodesSystem error codes.
See NODE_VERSIONS for a list of supported Node.js versions.
This package is fully typed with TypeScript.
CodeUnion 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).
T (SystemCode, optional)
— system error code
SystemCodeErrorcode (T)
— system error codeerrno (number)
— libuv error numbermessage (string)
— error message, always prefixed by syscall and codepath? (string | undefined)
— relevant invalid pathnamesyscall (string)
— failed syscall descriptionMessageFn<[T][, Args]>Build an error message.
T (NodeError, optional)
— node error
NodeErrorArgs (readonly any[], optional)
— message arguments
any[]this (T)
— node error object...args (Args)
— message arguments(string) error message.
NodeErrorConstructor<[T][, Args]>Node.js error constructor (TypeScript interface).
T (NodeError, optional)
— node error
NodeErrorArgs (readonly any[], optional)
— message arguments
any[]new (...args: Args): T(...args: Args): Tprototype (T)
— node.js error prototypeNodeErrorMapRegistry 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).
T (Code, optional)
— error code
CodeErrorcode (T)
— error codetoString (() => string)
— get a string representation of the errorStringifiableA value with a toString method (TypeScript interface).
toString (() => string)
— get a string representation of the valueSystemCodeUnion 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>
SystemErrorMapRegistry 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.
FAQs
Universal API for creating Node.js errors
We found that @flex-development/errnode demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Multiple high-impact npm maintainers confirm they have been targeted in the same social engineering campaign that compromised Axios.
Security News
Axios compromise traced to social engineering, showing how attacks on maintainers can bypass controls and expose the broader software supply chain.
Security News
Node.js has paused its bug bounty program after funding ended, removing payouts for vulnerability reports but keeping its security process unchanged.