Package Exports

fockeror
fockeror/package.json

Readme

Fockeror

Fockeror — типобезопасная фабрика ошибок для TypeScript. Позволяет определить набор предсказуемых, типизированных ошибок с автоматическими уникальными кодами, подстановкой значений в сообщения и интеграцией с любым фреймворком.

🔑 Уникальные коды – каждая ошибка получает код формата base64url(префикс):hex(ключ:индекс)
📝 Плейсхолдеры – динамические сообщения с синтаксисом ${{ placeholder }}
🧩 Интеграция с фреймворками – подключите свой форматтер исключений (например, HttpException из NestJS или ApiError из Express)
📦 Статические или динамические ошибки – используйте error.exception для статической ошибки или error.execute({ ... }) для динамической подстановки
🪵 Поддержка логгера – опциональный логгер для отладки и предупреждений о валидации

Установка

npm install fockeror

Быстрый старт

import { FockerorFactory } from 'fockeror';
// 1. Определите свой форматтер исключений (пример для NestJS)
import { HttpException } from "@nestjs/common";


// 2. Создайте фабрику
const factory = new FockerorFactory(HttpException, console);

// 3. Определите шаблоны ошибок
const errors = factory.execute('AUTH', {
  INVALID_TOKEN: {
    message: 'Неверный токен',
    description: 'Предоставленный токен повреждён или истёк',
    status: 401,
  },
  USER_NOT_FOUND: {
    message: 'Пользователь ${{ userId }} не найден',
    description: 'Пользователь с id ${{ userId }} не существует',
    status: 404,
  },
});

// 4. Используйте их
// Статическая ошибка (без плейсхолдеров)
throw errors.INVALID_TOKEN.exception;

// Динамическая ошибка с подстановкой значений
throw errors.USER_NOT_FOUND.execute({ userId: '123' });

Зачем нужен Fockeror?

Никаких «магических» строк – ошибки типизированы и поддерживают автодополнение.
Централизованное описание ошибок – храните все бизнес-ошибки в одном месте.
Безопасная подстановка плейсхолдеров – если значение отсутствует, ошибка логируется, а сообщение не ломается.
Не зависит от фреймворка – работает с Express, NestJS, Fastify или любой другой библиотекой.

API

`FockerorFactory`

`constructor(formatterClass, logger?)`

formatterClass – класс для преобразования внутреннего исключения Exception в специфичный для фреймворка тип. Должен принимать параметры (response, status, options).
logger – опциональный логгер, реализующий интерфейс { error?: (err: Error) => unknown; execute?: (msg: string) => unknown }

`execute(prefix, templates)`

prefix – строка для генерации уникального кода (будет преобразована в base64url)
templates – объект, где ключи — имена ошибок, значения — ErrorTemplateInput

Возвращает объект с экземплярами Fockeror с теми же ключами, что и templates.

`Fockeror<Placeholders, FormatterClass>`

`.exception` (геттер)

Возвращает статическое отформатированное исключение (плейсхолдеры не заменяются).

`.execute(placeholders?, cause?)`

placeholders – объект с значениями для замены плейсхолдеров
cause – опциональная ошибка-причина

Возвращает отформатированное исключение.

`.throw(placeholders?, cause?)` / `.throw(cause?)`

Немедленно выбрасывает отформатированное исключение.

Формат шаблона ошибки

type ErrorTemplateInput = {
  message: string;        // может содержать ${{ placeholder }}
  description: string;    // может содержать ${{ placeholder }}
  status?: number;        // HTTP статус (по умолчанию 500)
  cause?: Error;          // опциональная причина
  options?: Record<string, unknown>; // дополнительные данные для форматтера
};

Синтаксис плейсхолдеров

Плейсхолдеры должны быть записаны как ${{ key }} ровно с одним пробелом внутри фигурных скобок.
Во время выполнения регулярное выражение допускает любое количество пробелов, но для корректного вывода типов TypeScript требуется ровно один пробел.

✅ Привет, ${{ name }}
❌ Привет, ${{name}}
❌ Привет, ${{ name }}

Продвинутое использование

Использование логгера

const logger = {
  error: (err: Error) => console.error(err.message),
  execute: (msg: string) => console.debug(msg),
};

const factory = new FockerorFactory(MyFormatter, logger);

Если при подстановке значения плейсхолдер отсутствует, логгер получит ошибку.

Свой форматтер исключений

Класс форматтера получает три аргумента:

class MyFormatter {
  constructor(
    public readonly response: string | Record<string, unknown>,
    public readonly status: number,
    public readonly options?: { cause?: Error; description?: string },
  ) {}
}

Коды ошибок

Каждая ошибка получает уникальный код в формате:
base64url(префикс):hex(имяОшибки:индекс)

Код автоматически добавляется в начало поля message.
Пример: QVVUSDo=:494e56414c49445f544f4b454e3a30 : Неверный токен

Лицензия

MIT

fockeror