error-kid

A simple toolkit to work with custom errors. Definitely not a kid.

Installation

# yarn
yarn add error-kid

# pnpm
pnpm i error-kid

# npm
npm i error-kid

errorClass

A function returning a tuple, containing a new basic error class that has no payload on the first place, and a predicate function on the second one.

import { errorClass } from 'error-kid';

const UnknownError = errorClass('UnknownError');
UnknownError.name; // 'UnknownError'

const error = new UnknownError();
error.message; // ''
error.cause; // undefined
error instanceof Error; // true
error instanceof UnknownError; // true

UnknownError.is(new Error); // false
UnknownError.is(error); // true

By default, the created error class constructor accepts no arguments. It also passes nothing to the Error super constructor.

To change this behavior, define the arguments' type and provide a function to convert passed arguments to the Error super constructor. It can also be a message presented as string, or a tuple passed to the super constructor.

Here is the example:

import { errorClass } from 'error-kid';

// The generic parameter must be any tuple. It describes
// arguments passed to the UnknownError constructor.
const UnknownError = errorClass<[
  errorText: string,
  retriesCount: number,
  cause?: unknown
]>('UnknownError', (errorText, retriesCount, cause) => {
  // `Error` constructor requires the first argument
  // to be the error message. The second one is ErrorOptions,
  // containing the `cause` property.
  return [
    `Unknown error occurred. Retries count: ${retriesCount}. Error text: ${errorText}`,
    { cause },
  ];
});

const error = new UnknownError('Ooopsie!', 3, new Error('Just because'));
error.message; // "Unknown error occurred. Retries count: 3. Error text: Ooopsie!"
error.cause; // Error('Just because')

// All these defines are ok:
const Err1 = errorClass('Err1', 'Timed out');
const Err2 = errorClass('Err2', ['Timed out']);
const Err3 = errorClass('Err3', ['Timed out', new Error('Oops')]);
const Err4 = errorClass('Err4', () => ['Timed out', new Error('Oops')]);
const Err5 = errorClass('Err5', () => ['Timed out']);

errorClassWithData

A function that creates a new error class containing some payload. It enhances the result of calling the errorClass function.

This function requires specifying at least one generic type parameter describing the error payload. The second generic type parameter is optional (an empty tuple by default) and must be a tuple, describing a list of arguments, passed to the error class constructor.

The second argument of the generator is a function, converting constructor arguments to the data.

import { errorClassWithData } from 'error-kid';


const TimeoutError = errorClassWithData<{ duration: number }, [duration: number]>(
  'UnknownError',
  duration => ({ duration }),
);

const error = new TimeoutError(1000);
error.data; // { duration: 1000 }

TimeoutError.is(error); // true

As in the errorClass function, you can also pass the third argument, which is a function, transforming incoming arguments to the arguments, passed to the Error super constructor.

Let's enhance the previous example a bit:

import { errorClassWithData } from 'error-kid';

const TimeoutError = errorClassWithData<
  { duration: number },
  [duration: number, cause?: unknown]
>(
  'UnknownError',
  duration => ({ duration }),
  (duration, cause) => [`Timed out: ${duration}ms`, { cause }],
);

const err1 = new TimeoutError(1000);
err1.data; // { duration: 1000 }
err1.message; // "Timed out: 1000ms"
err1.cause; // undefined

const err2 = new TimeoutError(1000, new Error('Just because'));
err2.data; // { duration: 1000 }
err2.message; // "Timed out: 1000ms"
err2.cause; // Error('Just because') 

Usage Tips For TypeScript

If your project uses TypeScript, creating a new error class it is recommended to use the class keyword. Here is how the usage looks traditionally:

const MyError = errorClass('MyError', 'Just an error');

In this case you will not be able to use the MyError as a type in the TS type system. So, this code will not work as expected:

type Fn = () => (MyError | undefined);

TypeScript will not recognize that MyError is actually a class, and you will have to write this kind of code:

type Fn = () => (InstanceType<typeof MyError> | undefined);

It is not very convenient, right? To avoid this kind of problem, define your errors using this way:

class MyError extends errorClass('MyError', 'Just an error') {
}

// So, this will work fine.
type Fn = () => (MyError | undefined);