unify-errors

Shared application error types for TypeScript services. The package keeps transport details out of the core model and focuses on a portable payload: code, message, details, and localizedMessage.

Usage

import { BadRequest } from 'unify-errors';

function errorExample() {
  throw new BadRequest('INVALID_AMOUNT', {
    message: 'Amount must be positive',
    details: ['Got: -5'],
    localizedMessage: 'Amount must be greater than zero',
  });
}

Error model

All built-in error classes extend CustomError.

new BadRequest(code, {
  message,
  details,
  localizedMessage,
});

CustomErrorOptions

Field	Type	Description
message	string	Technical message intended for logs or debugging
details	string[]	Optional detail lines that adapters can expose or strip
localizedMessage	string	Optional user-facing message

ErrorResponse

CustomError#toResponse(includeDetails?) serializes the shared payload:

{
  code?: string;
  message?: string;
  details: string[];
  localizedMessage?: string;
}

Built-in errors

• BadRequest
• Unauthorized
• Forbidden
• NotFound
• Conflict
• TimeOut
• TooManyRequests
• InternalServerError
• NotImplemented
• ServiceUnavailable

Custom errors

Create a new class by extending CustomError and keeping transport status mapping in your adapter layer.

import { CustomError, type CustomErrorOptions } from 'unify-errors';

export class PaymentDeclined extends CustomError {
  constructor(code: string, options: CustomErrorOptions = {}) {
    super(code, options);

    Object.setPrototypeOf(this, PaymentDeclined.prototype);
    this.name = 'PaymentDeclined';
  }
}

Tests

bun test