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

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 --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:

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 start

• Run all unit tests

npm test

• Get coverage report

npm run coverage

• Format 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 ~~travis~~ github 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