@biorate/errors

Base class for creating typed, code‑based error classes with structured metadata and util.format‑style message templates.

Features

• Error code — auto‑derived from the constructor name (e.code === 'MyError').
• Templated message — uses util.format %s / %d / %j placeholders.
• Structured metadata — any extra payload attached via the meta getter.
• Zero dependencies in runtime — only built‑in util module.
• Full Error contract — preserves stack, message, name, and captureStackTrace.

Installation

pnpm add @biorate/errors

Quick start

import { BaseError } from '@biorate/errors';

class MyError extends BaseError {
  constructor(args?: unknown[], meta?: unknown) {
    super('Something happened at %s, code %d', args, meta);
  }
}

const err = new MyError([new Date(), 42], { userId: 1 });

console.log(err.code);    // "MyError"
console.log(err.message); // "Something happened at Sun Jun ... 2025, code 42"
console.log(err.meta);    // { userId: 1 }
console.log(err.stack);   // Full stack trace

API Reference

BaseError

| Member | Type | Description | |--------------------|------------------------------|----------------------------------------------------------| | constructor | (message, args?, meta?, ...options?) | Template string with positional util.format args. | | .message | string | Formatted message (inherited from Error). | | .code | string | Returns this.constructor.name. | | .meta | unknown | Arbitrary metadata payload (second constructor arg). | | .stack | string \| undefined | Stack trace (V8 captureStackTrace when available). |

Constructor signature

new BaseError(message: string, args?: unknown[], meta?: unknown, ...options: unknown[]);

• message — template using %s, %d, %j, %% etc. (Node.js util.format).
• args — array of values injected into the template.
• meta — any extra data stored on this.meta.
• ...options — additional arguments forwarded to Error constructor (e.g. options.cause).

Usage patterns

Basic typed errors

class NotFoundError extends BaseError {
  constructor(id: string) {
    super('Resource not found: %s', [id]);
  }
}

throw new NotFoundError('user_42');
// NotFoundError: Resource not found: user_42

Errors with structured metadata

class ValidationError extends BaseError {
  constructor(field: string, value: unknown) {
    super('Validation failed for [%s]', [field], { field, value });
  }
}

const e = new ValidationError('email', 'invalid');
console.log(e.meta); // { field: 'email', value: 'invalid' }

Overriding HTTP status via meta

class PaymentError extends BaseError {
  constructor(msg: string) {
    super(msg, undefined, { status: 402 });
  }
}

const e = new PaymentError('Insufficient funds');
console.log(e.meta); // { status: 402 }

This pattern is used by AllExceptionsFilter from @biorate/nestjs-tools to return proper HTTP status codes.

Serialization with toJSON

class ApiError extends BaseError {
  constructor(code: number, message: string) {
    super('%s', [message], { status: code });
  }

  toJSON() {
    return { code: this.code, message: this.message, meta: this.meta };
  }
}

console.log(JSON.stringify(new ApiError(400, 'bad request')));
// {"code":"ApiError","message":"bad request","meta":{"status":400}}

Architecture

┌─────────────────┐
│   BaseError     │  extends  Error
├─────────────────┤
│  #meta: any     │
│  .code          │  → constructor.name
│  .message       │  → util.format(template, ...args)
│  .meta          │  → #meta getter
│  .stack         │  → Error.captureStackTrace
└─────────────────┘
        ▲
        │ extends
┌───────────────────┐
│   MyAwesomeError  │  ← custom error per domain
│   super(msg,args, │
│     meta)         │
└───────────────────┘

Best practices

1. One class per error type — allows instanceof checks and catch filtering.
2. Use %s placeholders for dynamic values, never string concatenation in the template.
3. Add meta.status for HTTP errors to propagate status codes to NestJS filters.
4. Keep class names descriptive — they become e.code, visible in logs.

Learn

• Documentation can be found here - docs.

Release History

See the CHANGELOG

License

MIT

Copyright (c) 2021-present Leonid Levkin (llevkin)