adriengibrat
Typescript Custom Error
Extend native Error to create custom errors
ts-custom-error is a tiny (~500 bytes of minified & gzipped Javascript) package providing a CustomError class and a customErrorFactory function to easily extends native Error in node and evergreen browsers.
It's written in Typescript and try to offer the best development and debug experiences: bundled in Javascript with Typescript definition files, map files and bundled js files for various environments: transpiled to es5 with commonjs, module and umd exports, the umd bundle is also available minified for easy import in browsers.
Why
Because extending native Error in node and in browsers is tricky
class MyError extends Error {
constructor(m) {
super(m)
}
}doesn't work as expected in ES6 and is broken in Typescript.
Use CustomError class
Simply extends and call super in you custom constructor.
import { CustomError } from 'ts-custom-error'
class HttpError extends CustomError {
public constructor(
public code: number,
message?: string,
) {
super(message)
}
}
...
new HttpError(404, 'Not found')You may want more advanced contructor logic and custom methods, see examples
Use customErrorFactory factory
Custom error contructor returned by the factory pass the same unit tests as Class constructor.
Factory still allows custom logic inside constructor:
import { customErrorFactory } from 'ts-custom-error'
const HttpError = customErrorFactory(function HttpError (code: number, message= '') {
this.code = code
this.message = message
})
...
new HttpError(404, 'Not found')Custom Error from customErrorFactory can:
- Be called as a simple function
HttpError(404, 'Not found') - Extend any native Error, using the second optional argument
`ts import { customErrorFactory } from 'ts-custom-error'
const ValidationError = customErrorFactory(function ValidationError (message= 'Invalid parameter') { this.message = message }, TypeError)
### Known limitations
#### Minification and transpilation mangle custom Error names.
Unexpected results are:
- Minified identifiers in place of custom Error name in Stacktrace
- Wrong error recognition where using errors name (bad practice) instead of `instanceof`
You may fix this behaviour by:
- Using [uglifyjs options](https://github.com/mishoo/UglifyJS2/blob/harmony/README.md) `--mangle 'except=["MyError"]'` (need to specify all custom error names) or `--keep_fnames` / `--keep_classnames` (nothing to specify but your bundle size will be larger)
- Setting explicitly error name:
```ts
import { CustomError } from 'ts-custom-error'
class MyError extends CustomError {
constructor() {
super()
// Set name explicitly as minification can mangle class names
Object.defineProperty(this, 'name', { value: 'MyError' })
}
}import { customErrorFactory } from 'ts-custom-error'
const MyError = customErrorFactory(function MyError () {
// Set name explicitly as minification can remove function expression names
Object.defineProperty(this, 'name', { value: 'MyError' })
})Usefull development commands
Watch source changes and run corresponding unit tests
npm startRun all unit tests
npm testGet coverage report
npm run coverageFormat staged code and run commitizen (enforce commit message convention)
npm run commit
Automate all the things
⚠️ This project is mainly a pet project and its first purpose is to be a playground for various external services and tools:
- opinionated code style mostly inspired from standardjs
- automatic code formating with prettier
- code quality analysis by codeclimate
, bithound, bettercodehub & CodeQL - automated continuous integration on
travisgithub actions & Dependabot - automated semantic versioning with changelog generation and release deployment on npm and github thanks to semantic-release
Licence
Starting version 3.0.0 this project is under MIT licence, there are no code change between version 2.2.2 and version 3.0.0 but changing licence was considered as a breaking change. All versions < 3.0.0 are under WTFPL.
Similar packages
custom-error provides a factory with custom name and parent error
custom-errors provides a class and a factory with custom name and message, easy integration with with express and (log)[https://github.com/visionmedia/log.js]
custom-error-generator provides a factory with custom name, default properties and a constructor (node only)
custom-error-instance provides a factory with custom name, properties and construction logic (! browser compatibility: redefine constructor name)
node-custom-errors provides factories to create abstract or concrete error with default message, an optional constructor function allow more custom properties/methods (node/chrome only, because no feature detection)
extendable-error provides a class with clean stacktrace even in non v8 environments
extendable-error-class provides simple class
extend-error provides a factory attached to global Error object, allows custom name, code & message error
error-extend provides a factory with custom name, default code & message properties, an optional init function allow more custom properties/methods