@fastify/error

A small utility, used by Fastify itself, for generating consistent error objects across your codebase and plugins.

Install

npm i @fastify/error

Usage

The module exports a function that you can use for consistent error objects, it takes 4 parameters:

1createError(code, message [, statusCode [, Base [, captureStackTrace]]])

• code (string, required) - The error code, you can access it later with error.code. For consistency, we recommend prefixing plugin error codes with FST_
• message (string, required) - The error message. You can also use interpolated strings for formatting the message.
• statusCode (number, optional) - The status code that Fastify will use if the error is sent via HTTP.
• Base (ErrorConstructor, optional) - The base error object that will be used. (eg TypeError, RangeError)
• captureStackTrace (boolean, optional) - Whether to capture the stack trace or not.

1const createError = require('@fastify/error')
2const CustomError = createError('ERROR_CODE', 'Hello')
3console.log(new CustomError()) // error.message => 'Hello'

How to use an interpolated string:

1const createError = require('@fastify/error')
2const CustomError = createError('ERROR_CODE', 'Hello %s')
3console.log(new CustomError('world')) // error.message => 'Hello world'

How to add cause:

1const createError = require('@fastify/error')
2const CustomError = createError('ERROR_CODE', 'Hello %s')
3console.log(new CustomError('world', {cause: new Error('cause')}))
4// error.message => 'Hello world'
5// error.cause => Error('cause')

TypeScript

It is possible to limit your error constructor with a generic type using TypeScript:

1const CustomError = createError<[string]>('ERROR_CODE', 'Hello %s')
2new CustomError('world')
3//@ts-expect-error
4new CustomError(1)

instanceof

All errors created with createError will be instances of the base error constructor you provided, or Error if none was provided.

1const createError = require('@fastify/error')
2const CustomError = createError('ERROR_CODE', 'Hello %s', 500, TypeError)
3const customError = new CustomError('world')
4
5console.log(customError instanceof CustomError) // true
6console.log(customError instanceof TypeError) // true
7console.log(customError instanceof Error) // true

All instantiated errors are instances of the FastifyError class, which can be required directly from the module.

1const { createError, FastifyError } = require('@fastify/error')
2const CustomError = createError('ERROR_CODE', 'Hello %s', 500, TypeError)
3const customError = new CustomError('world')
4
5console.log(customError instanceof FastifyError) // true

A FastifyError created by createError can extend another FastifyError while maintaining correct instanceof behavior.

1const { createError, FastifyError } = require('@fastify/error')
2
3const CustomError = createError('ERROR_CODE', 'Hello %s', 500, TypeError)
4const ChildCustomError = createError('CHILD_ERROR_CODE', 'Hello %s', 500, CustomError)
5
6const customError = new ChildCustomError('world')
7
8console.log(customError instanceof ChildCustomError) // true
9console.log(customError instanceof CustomError) // true
10console.log(customError instanceof FastifyError) // true
11console.log(customError instanceof TypeError) // true
12console.log(customError instanceof Error) // true

If fastify-error is installed multiple times directly or as a transitive dependency, instanceof checks for errors created by createError will still work correctly across these installations, as long as their error codes (e.g., FST_ERR_CUSTOM_ERROR) are identical.

1const { createError, FastifyError } = require('@fastify/error')
2
3// CustomError from `@fastify/some-plugin` is created with `createError` and
4// has its own `@fastify/error` installation as dependency. CustomError has
5// FST_ERR_CUSTOM_ERROR as code.
6const { CustomError: CustomErrorFromPlugin } = require('@fastify/some-plugin')
7
8const CustomError = createError('FST_ERR_CUSTOM_ERROR', 'Hello %s', 500)
9
10const customError = new CustomError('world')
11const customErrorFromPlugin = new CustomErrorFromPlugin('world')
12
13console.log(customError instanceof CustomError) // true
14console.log(customError instanceof CustomErrorFromPlugin) // true
15console.log(customErrorFromPlugin instanceof CustomError) // true
16console.log(customErrorFromPlugin instanceof CustomErrorFromPlugin) // true

Changing the code of an instantiated Error will not change the result of the instanceof operator.

1const { createError, FastifyError } = require('@fastify/error')
2
3const CustomError = createError('ERROR_CODE', 'Hello %s', 500, TypeError)
4const AnotherCustomError = createError('ANOTHER_ERROR_CODE', 'Hello %s', 500, CustomError)
5
6const customError = new CustomError('world')
7customError.code = 'ANOTHER_ERROR_CODE'
8
9console.log(customError instanceof CustomError) // true
10console.log(customError instanceof AnotherCustomError) // false

License

Licensed under MIT.