Some utilities around JavaScript Error creation and manipulation.
- written in TypeScript
- no dependencies
Usage
Exposed constants: known error fields
Exposes the properties we can expect on a JavaScript "Error" object.
See the source code for more details.
import {
STRICT_STANDARD_ERROR_FIELDS,
QUASI_STANDARD_ERROR_FIELDS,
COMMON_ERROR_FIELDS,
COMMON_ERROR_FIELDS_EXTENDED,
} from '@offirmo/error-utils'
Note that COMMON_ERROR_FIELDS_EXTENDED
contains private properties,
but since they are optional and have rare names, there shouldn't be any conflict.
Exposed types: error interface with more properties
-
XError
(eXtended error) = with properties up toCOMMON_ERROR_FIELDS
-
XXError
= idem with properties up toCOMMON_ERROR_FIELDS_EXTENDED
import {
XError,
XXError,
} from '@offirmo/error-utils'
Utility: slightly more convenient way to create errors than new Error(…)
Allows passing additional properties along the error creation, in one go.
- if the properties are recognized as top level (
COMMON_ERROR_FIELDS_EXTENDED
) they'll be attached directly - if not, they'll be attached to a root
details
property
Also:
- Will ensure that the string "error" is present in the message (case-insensitive), will prepend it if not
- Will pick the message from the details as a fallback if the 1st param is not provided/falsy (convenience for rare cases)
import { createError } from '@offirmo/error-utils'
// classic = it's the same
const err = new Error(`Foo API: bar is incorrect!`)
const err = createError(`Foo API: bar is incorrect!`) // return type = XXError
// advanced: extra properties
const err = createError(`Foo API: bar is incorrect!`, { statusCode: 401, foo: 'bar' })
// advanced: extra properties + custom constructor
const err = createError(`Foo API: bar is incorrect!`, { statusCode: 401, foo: 'bar' }, TypeError)
// above is equivalent to:
const err = new TypeError(`Foo API: bar is incorrect!`)
err.statusCode = 401
err.details = {
foo: 'bar',
}
Utility: normalize anything into a true, writable Error object
Normalize anything into a true, normal error.
Anything can be thrown in JavaScript: undefined
, string, number...
But that's obviously not a good practice.
Even Error-like objects are sometime fancy:
- seen: in a browser, sometimes, an error-like, un-writable object is thrown
- seen: frozen
- seen: non-enumerable props
So we want to ensure a true, safe, writable error object.
NOTE: will always recreate the error
import { normalizeError } from '@offirmo/error-utils'
try {
...(unreliable code)
}
catch (err_like) {
throw normalizeError(err_like)
}