ts-error

**TL/DR: An extendable error class that actually works with TypeScript and ES6
support compatible with all environments, even very old browsers.**

This package provides an extendable error class, ExtendableError for
JavaScript / TypeScript. There exist a number of similar packages on NPM, but
they all have shortcomings, like not supporting TypeScript, being awkward to use
with TypeScript 2, not being compatible with old browsers, not printing the
stack trace when used with console.log or similar functions or not having all
features I wanted. So I decided to write my own.

Obviously, it's not all 100% written from scratch, but rather I collected the
good parts from various existing open source error packages and some
StackOverflow answers, fixed various errors, wrote some tests and put it
together in one package.

The purpose of extendable errors classes is to be able to throw error objects
that are subclasses of the built-in JavaScript Error class, which has a number
of gotchas, and to then filter them with the instanceof operator in the
catch clause of a try/catch block as well as potentially adding additional
variables to the error object.

This ExtendableError class will:

- subclass the built-in Error class. Subclasses created from ExtendableError
will subclass Error, ExtendableError and any other classes in the
inheritance chain.
- have a name attribute equal to the class name
- have a string representation with toString() that includes the name and
message properties of the error object. This is also fixed for all versions of
IE, where the error object usually does _not_ print error objects like this.
- include all non-standard properties that default Error objects provide in
different browsers
- provide a stack trace, if default Error objects have the stack property or
the Error.captureStackTrace exists (on V8, so in Chrome and node.js).
Additionally, on V8, the stack trace will not include the constructor
functions of the error subclasses.
- have a stack trace with the actual error name instead of Error
- display the stack trace (or the toString() representation, if the stack trace
does not exist), including the error name at the beginning, when printed with
console.log(e) (except for Chrome, where this does not work, even though the
stack property includes the actual name. I don't think it is possible to fix
this, but if anyone knows a way, let me know!)

It is compatible with node.js, provides an old-style CommonJS module and a
new-style ES6 module as well as a TypeScript definition file. It is extensively
tested and works in node.js and all browsers I have tested (including IE6 and
various old browsers as well as mobile browsers).

It's also really small, with less than 200 lines of code, and it has no
production dependencies.

Install

You can install the ts-error package
from NPM with the command:

``sh


If you use yarn

yarn add ts-error

If you use NPM

npm install ts-error
`

Usage

Simply import the package and optionally subclass ExtendableError and create a
new error object. The message property that should be passed to the object
will is optional and will default to an empty string. If undefined is passed,
this is also turned into an empty string.

For compatiblity, the package requires various methods, that are not defined in
old browsers. The CommonJs version (only!) includes polyfills for these
functions without polluting the global namespace, if the required functions are
not defined. If you want to use your own polyfills, load them before loading
this package.

In TypeScript:

`ts
import { ExtendableError } from "ts-error";

class CustomError extends ExtendableError {}

try {
throw new CustomError("Optional Error message");
} catch (e) {
if (e instanceof CustomError) {
// ...
} else {
// ...
}
}
`

In ES6 / esnext:

`js
import { ExtendableError } from "ts-error";

class CustomError extends ExtendableError {}

try {
throw new CustomError("Optional Error message");
} catch (e) {
if (e instanceof CustomError) {
// ...
} else {
// ...
}
}
`

In ES5:

`js
var ExtendableError = require("ts-error").ExtendableError;

// This is taken from TypeScript compiler output, because it works quite reliably.
// There are various other methods though, so use whatever you like, if you have to use ES5.
var __extends =
(this && this.__extends) ||
(function() {
var extendStatics =
Object.setPrototypeOf ||
({ __proto__: [] } instanceof Array &&
function(d, b) {
d.__proto__ = b;
}) ||
function(d, b) {
for (var p in b) if (b.hasOwnProperty(p)) d[p] = b[p];
};
return function(d, b) {
extendStatics(d, b);
function __() {
this.constructor = d;
}
d.prototype =
b === null
? Object.create(b)
: ((__.prototype = b.prototype), new __());
};
})();

var CustomError = /* @class / (function(_super) {
__extends(CustomError, _super);
function CustomError() {
return (_super !== null && _super.apply(this, arguments)) || this;
}
return CustomError;
})(ExtendableError);

try {
throw new CustomError("Optional Error message");
} catch (e) {
if (e instanceof CustomError) {
// ...
} else {
// ...
}
}
`

**Please note that error names will not be displayed correctly if the error
class definitions get uglified, because the display of error messages relies on
Function.prototype.name to infer the correct error message.** You can
configure any uglifier to ignore certain function or class names, either via a
source code annotation or using a regex configuration parameter to decide which
properties to mangle.

Tests

The module is extensively tested in JavaScript, ES6+ and TypeScript and works in
node.js as well as all browsers I have tested: All versions of Chrome 15+,
Firefox 3+, Safari 4+, Edge 14+, IE6+, Opera 10.6+, Yandex 14.12, various iOS
browsers down to the iPhone 3GS running iOS3 and the Android browser down to
Android 4. Note that I haven't test all versions of these browsers (except for
IE and Edge due to their notorious buggyness), but rather the oldest few and
more recent ones, because I would assume if they work in either of these, they
will work in all versions.

**If you encounter any issues, please file an issue and I will investigate and
fix it.**

You can run all tests together with npm run test, which will build all browser
tests and then execute the node and browser tests sequentially. All tests are
written in TypeScript and compiled to various targets to ensure compatibility.
All build configuration is in tests/build.

If you choose to build and run tests manually / individually, you first need to
run npm run pretest:create-lib-symlinks, which creates symlinks of the
TypeScript definition file in the lib directory.

$3

The node.js tests use mocha and chai together with ts-node. The test
source code is in tests/node. For node.js testing, the following commands
exist:

- npm run test:node:cjs: Test the CommonJs module lib/cjs.js with the
compile target ES3.
- npm run test:node:es: Test the ES6+ module lib/es.js with the compile
target esnext.
- npm run test:node: Run the CJS followed by the ES6+ tests.

Browser testing is a bit more complex. To ensure that the package is compatible
even with the oldest browsers, I had to create a few helper functions to emulate
the required functionality of mocha and chai. Old browsers like IE do not
have a console and various quirks, so it is necessary to execute the tests after
the DOM has loaded and write the results to the HTML body.

$3

You can build all browser tests with npm run build:test as well as in watch
mode with npm run build:test:watch. The test source code is in
tests/browser/src. This will run webpack to compile and bundle the test files
for various targets and copy some HTML files. The output will be in
tests/browser/dist, the bundled JS in tests/browser/dist/js. You can then
start the test with npm run test:browser. This will start lite-server, serve
the compiled files and should open a browser window automatically.

In the browser, you will see a navigation for testing of the scripts compiled to
targets ES3, ES5, ES6 and esnext. For each of these, you will have the option to
use print the results in the console or not. If you choose the console option,
the results will be printed in the console. If you choose the non-console option
or a console is not available in your browser, it will append the results to the
DOM.

If you would like to build some of the browser tests individually, the following
commands are available:

- npm run build:test:browser:es3: Build the test files for ES3
- npm run build:test:browser:es3:watch: Build the test files for ES3 in watch
mode
- npm run build:test:browser:es5: Build the test files for ES5
- npm run build:test:browser:es5:watch: Build the test files for ES5 in watch
mode
- npm run build:test:browser:es6: Build the test files for ES6
- npm run build:test:browser:es6:watch: Build the test files for ES6 in watch
mode
- npm run build:test:browser:esnext: Build the test files for esnext
- npm run build:test:browser:esnext:watch: Build the test files for esnext in
watch mode
- npm run build:test:browser: Execute all of the build commands concurrently
- npm run build:test:browser:watch: Execute all of the build commands
concurrently in watch mode
- npm run build:test: Same as npm run build:test:browser
- npm run build:test:watch: Same as npm run build:test:browser:watch`

License

MIT (see ./LICENSE).