Error Message Utils

error-message-utils helps TypeScript and JavaScript apps turn unknown errors into a consistent shape:

• a readable message
• a stable error code
• optional extra data

Use Exception for most application code. Use encodeError and decodeError when you need to send or receive an error code inside a plain string.

Install

npm i -S error-message-utils

Recommended Usage: Exception

Exception is an Error subclass that stores a normalized message, a code, and optional data.

import { Exception } from 'error-message-utils';

throw new Exception('The provided email is already in use.', 'EMAIL_EXISTS', {
  field: 'email',
});

const exception = new Exception('Request failed', 'REQUEST_FAILED');

exception instanceof Error; // true
exception instanceof Exception; // true
exception.name; // 'Exception'
exception.message; // 'Request failed'
exception.code; // 'REQUEST_FAILED'
exception.data; // null
exception.toString(); // 'Request failed{(REQUEST_FAILED)}'
exception.toRecord();
// {
//   message: 'Request failed',
//   code: 'REQUEST_FAILED',
//   data: null,
// }

Wrap Unknown Errors

When you catch an unknown error, pass it to Exception. The package will extract the best message and code it can find.

import { Exception } from 'error-message-utils';

try {
  await sendReceiptEmail();
} catch (error) {
  throw new Exception(error, 'RECEIPT_EMAIL_FAILED', {
    operation: 'sendReceiptEmail',
  });
}

Extend Exception

Create small domain-specific exception classes when your app has a stable set of error codes.

import { Exception } from 'error-message-utils';

const USER_ERROR_CODES = {
  EmailTaken: 'USER_EMAIL_TAKEN',
  Unauthorized: 'USER_UNAUTHORIZED',
} as const;

type IUserErrorCode = (typeof USER_ERROR_CODES)[keyof typeof USER_ERROR_CODES];

export class UserException extends Exception {
  public constructor(message: string, code: IUserErrorCode, data?: unknown) {
    super(message, code, data);
    this.name = 'UserException';
  }
}

throw new UserException(
  'The provided email is already in use.',
  USER_ERROR_CODES.EmailTaken,
  { field: 'email' },
);

Common Tasks

Extract a Message

extractMessage accepts any value and returns the best readable message it can find.

import { extractMessage } from 'error-message-utils';

extractMessage(
  new Error('Top level error', {
    cause: new Error('First nested cause', {
      cause: new Error('Second nested cause'),
    }),
  }),
);
// 'Top level error; [CAUSE]: First nested cause; [CAUSE]: Second nested cause'

extractMessage({
  message: {
    err: {
      message: 'This error message is nested deeply!',
    },
  },
});
// 'This error message is nested deeply!'

Zod errors are formatted with their first issue message and path.

import { z } from 'zod';
import { extractMessage } from 'error-message-utils';

const result = z.object({ name: z.string() }).safeParse({ name: 123 });

if (!result.success) {
  extractMessage(result.error);
  // 'Invalid input: expected string, received number (name)'
}

Get an Error Code

Use getErrorCode when you only need the resolved code.

import { Exception, getErrorCode } from 'error-message-utils';

const exception = new Exception('Access denied', 'ACCESS_DENIED');

getErrorCode(exception); // 'ACCESS_DENIED'
getErrorCode('Access denied'); // null

Use hasErrorCode when you want a direct boolean check.

import { Exception, hasErrorCode } from 'error-message-utils';

const exception = new Exception('Access denied', 'ACCESS_DENIED');

hasErrorCode(exception, 'ACCESS_DENIED'); // true
hasErrorCode(exception, 'PAYMENT_FAILED'); // false

Encode and Decode Plain Strings

encodeError and decodeError are lower-level helpers for systems that can only pass string messages.

import { decodeError, encodeError } from 'error-message-utils';

const encodedError = encodeError(
  'The provided email is already in use.',
  'EMAIL_EXISTS',
);

encodedError;
// 'The provided email is already in use.{(EMAIL_EXISTS)}'

decodeError(encodedError);
// {
//   message: 'The provided email is already in use.',
//   code: 'EMAIL_EXISTS',
//   data: null,
// }

Detect Resolved Codes with isEncodedError

isEncodedError returns true when an error resolves to a non-default code. For direct code inspection, prefer getErrorCode or hasErrorCode.

import { encodeError, isEncodedError } from 'error-message-utils';

isEncodedError('Some random unencoded error'); // false
isEncodedError(new Error('Some random unencoded error')); // false
isEncodedError(encodeError('Some unknown error.', 'UNKNOWN_ERROR')); // true

Check the Default Message

Use isDefaultErrorMessage to detect the fallback message returned when no useful message can be extracted.

import { DEFAULT_MESSAGE, isDefaultErrorMessage } from 'error-message-utils';

isDefaultErrorMessage(DEFAULT_MESSAGE); // true
isDefaultErrorMessage(`${DEFAULT_MESSAGE} More details.`); // true
isDefaultErrorMessage(`${DEFAULT_MESSAGE} More details.`, true); // false

Public API

Import public items from the package root:

import {
  DEFAULT_CODE,
  DEFAULT_MESSAGE,
  Exception,
  decodeError,
  encodeError,
  extractMessage,
  getErrorCode,
  hasErrorCode,
  isDefaultErrorMessage,
  isEncodedError,
  type IDecodedError,
  type IErrorCode,
  type IErrorCodeCarrier,
  type IExceptionRecord,
} from 'error-message-utils';

Classes

| Export | Description | | --- | --- | | Exception | An Error subclass that normalizes an unknown error into message, code, and data. It can also serialize itself with toString() or toRecord(). |

Functions

| Export | Signature | Description | | --- | --- | --- | | extractMessage | (error: unknown) => string | Extracts the best readable message from strings, Error instances, nested error-like objects, Error.cause chains, arrays, plain objects, and Zod errors. Returns DEFAULT_MESSAGE when no useful message can be extracted. | | encodeError | (error: unknown, code: IErrorCode) => string | Extracts a message from error and appends the wrapped code at the end of the message. | | decodeError | (error: unknown) => IDecodedError | Extracts a message, resolves a code from an encoded message or code-carrying object, and returns { message, code, data }. | | isEncodedError | (error: unknown) => boolean | Returns true when decodeError(error).code resolves to a non-default code. | | getErrorCode | (error: unknown) => IErrorCode \| null | Returns the resolved non-default code, or null when no non-default code is found. | | hasErrorCode | (error: unknown, code: IErrorCode) => boolean | Checks whether an error resolves to the provided code. Raw code values are compared with strict equality. | | isDefaultErrorMessage | (value: string, fullMatch?: boolean) => boolean | Checks whether a string contains DEFAULT_MESSAGE. Pass true as the second argument to require an exact match. |

Types

type IErrorCode = string | number;

type IDecodedError = {
  message: string;
  code: IErrorCode;
  data: unknown | null;
};

type IErrorCodeCarrier = {
  code: IErrorCode;
} & Record<string, unknown>;

type IExceptionRecord = {
  message: string;
  code: IErrorCode;
  data: unknown | null;
};

| Export | Description | | --- | --- | | IErrorCode | The supported type for application error codes. | | IDecodedError | The object returned by decodeError. | | IErrorCodeCarrier | A plain object shape that can provide a code to decodeError, getErrorCode, hasErrorCode, and Exception. | | IExceptionRecord | The serializable object returned by Exception.toRecord(). |

Constants

const DEFAULT_CODE = -1;

const DEFAULT_MESSAGE =
  'The error message could not be extracted, check the logs for more information.';

| Export | Description | | --- | --- | | DEFAULT_CODE | The fallback code used when no code can be resolved. | | DEFAULT_MESSAGE | The fallback message used when no readable message can be extracted. |

Running Tests

npm test

License

MIT