@dotcom-reliability-kit/errors

@dotcom-reliability-kit/errors

A suite of error classes which help you throw the most appropriate error in any situation, and identify when errors are known vs unknown. This module is part of FT.com Reliability Kit.

• Usage
  • OperationalError
    • .relatesToSystems
    • .cause
    • .isErrorMarkedAsOperational
  • HttpError
    • Why use this over http-errors?
• Contributing
• License

Usage

Install @dotcom-reliability-kit/errors as a dependency:

npm install --save @dotcom-reliability-kit/errors

Include in your code:

import {OperationalError} from '@dotcom-reliability-kit/errors';
// or
const {OperationalError} = require('@dotcom-reliability-kit/errors');

This module exports different Error classes which have different jobs. All can be imported in the same way as the example above.

OperationalError

The OperationalError class is the base class for most other error types. "Operational" in this context means "we understand why this error has occurred", so by using this error type you're helping your team to understand when a thrown error is unexpected.

Joyent's Error Handling docs have a good explanation of Operational Errors.

It works in the same way as a normal error, expecting a message:

throw new OperationalError('example message');

You can alternatively construct an operational error with a data object. This accepts a code property, which must be set to a unique identifier for the type of error which is occurring, and a message property which contains a human-readable message:

throw new OperationalError({
    message: 'example message',
    code: 'EXAMPLE_CODE'
});

Error codes are normalized to be uppercase, alphanumeric, and underscore-delimited. Error properties can be accessed like any other property:

error.message // example message
error.code // EXAMPLE_CODE

You may also pass additional properties into an error object, these will be collected and stored on a data property on the error:

const error = new OperationalError({
    message: 'example message',
    code: 'EXAMPLE_CODE',
    article: 'd92acacb-ac53-4505-aa88-eae4b42de994'
});

error.data.article // d92acacb-ac53-4505-aa88-eae4b42de994

OperationalError.relatesToSystems

The relatesToSystems property of an operational error stores a list of FT systems which are related to the error that you're throwing.

This array could include:

• dependencies which have returned an HTTP error status code
• data stores which haven't provided the expected data

OperationalError.cause

The cause property of an operational error stores the root cause error instance, e.g. an error that has been caught as part of a try/catch block. It allows the operational error to include the diagnostic information captured by the root cause error.

OperationalError.isErrorMarkedAsOperational()

You can test whether an error is operational (known about) either by using the isErrorMarkedAsOperational method. It accepts an error object of any kind and will return true if that error has a truthy isOperational property and false otherwise:

OperationalError.isErrorMarkedAsOperational(new OperationalError('example message')); // true
OperationalError.isErrorMarkedAsOperational(new Error('example message')); // false

HttpError

The HttpError class extends OperationalError and represents an HTTP error status. It can work in the same way as a normal error, expecting a message. In this case it will represent an HTTP 500:

throw new HttpError('example message');

You can alternatively construct an HTTP error with a data object. This accepts a statusCode property, which is a valid HTTP status code number, as well as all of the properties you can set in OperationalError:

throw new HttpError({
    message: 'your thing was not found',
    statusCode: 404
});

It's also possible to create an HTTP error with a status code alone, which will default the message to the corresponding HTTP status message:

throw new HttpError(404);

Error properties can be accessed like any other property:

error.message // your thing was not found
error.statusCode // 404
error.status // 404
error.statusMessage // Not Found
error.code // HTTP_404

Why use this over http-errors?

The benefit of using this error rather than the excellent http-errors library is that we extend OperationalError by default. This means that all HTTP errors you throw are considered "known errors" by the rest of our tooling. We also set a code property by default which results in less code in our monitoring dashboards – we don't need to check both code and statusCode properties to determine the type of error thrown.

Contributing

See the central contributing guide for Reliability Kit.

License

Licensed under the MIT license.
Copyright © 2022, The Financial Times Ltd.