fockeror 0.2.1 → 0.4.0

package/README.md

@@ -0,0 +1,153 @@
+# Fockeror
+
+[![npm версия](https://img.shields.io/npm/v/fockeror.svg)](https://www.npmjs.com/package/fockeror)
+[![Лицензия: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**Fockeror** — типобезопасная фабрика ошибок для TypeScript. Позволяет определить набор предсказуемых, типизированных ошибок с автоматическими уникальными кодами, подстановкой значений в сообщения и интеграцией с любым фреймворком.
+
+- 🔑 **Уникальные коды** – каждая ошибка получает код формата `base64url(префикс):hex(ключ:индекс)`
+- 📝 **Плейсхолдеры** – динамические сообщения с синтаксисом `${{ placeholder }}`
+- 🧩 **Интеграция с фреймворками** – подключите свой форматтер исключений (например, `HttpException` из NestJS или `ApiError` из Express)
+- 📦 **Статические или динамические ошибки** – используйте `error.exception` для статической ошибки или `error.execute({ ... })` для динамической подстановки
+- 🪵 **Поддержка логгера** – опциональный логгер для отладки и предупреждений о валидации
+
+## Установка
+
+```bash
+npm install fockeror
+```
+
+## Быстрый старт
+
+```typescript
+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?)`
+
+Немедленно выбрасывает отформатированное исключение.
+
+### Формат шаблона ошибки
+
+```typescript
+type ErrorTemplateInput = {
+  message: string;        // может содержать ${{ placeholder }}
+  description: string;    // может содержать ${{ placeholder }}
+  status?: number;        // HTTP статус (по умолчанию 500)
+  cause?: Error;          // опциональная причина
+  options?: Record<string, unknown>; // дополнительные данные для форматтера
+};
+```
+
+## Синтаксис плейсхолдеров
+
+Плейсхолдеры должны быть записаны как `${{ key }}` **ровно с одним пробелом** внутри фигурных скобок.  
+Во время выполнения регулярное выражение допускает любое количество пробелов, но для корректного вывода типов TypeScript требуется ровно один пробел.
+
+✅ `Привет, ${{ name }}`  
+❌ `Привет, ${{name}}`  
+❌ `Привет, ${{  name  }}`
+
+## Продвинутое использование
+
+### Использование логгера
+
+```typescript
+const logger = {
+  error: (err: Error) => console.error(err.message),
+  execute: (msg: string) => console.debug(msg),
+};
+
+const factory = new FockerorFactory(MyFormatter, logger);
+```
+
+Если при подстановке значения плейсхолдер отсутствует, логгер получит ошибку.
+
+### Свой форматтер исключений
+
+Класс форматтера получает три аргумента:
+
+```typescript
+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

package/dist/constants.d.ts

@@ -6,6 +6,11 @@
  * // Найдёт: ${{ username }}
  */
 export declare const PLACEHOLDER_PATTERN: RegExp;
+export declare const OFFSETS: {
+    readonly START: number;
+    /** negative (`-length`) */
+    readonly END: number;
+};
 /** Статус HTTP по умолчанию (500 Internal Server Error). */
 export declare const DEFAULT_HTTP_STATUS: 500;
 /** Регулярное выражение для экранирования специальных символов при создании RegExp из ключа. */

package/dist/constants.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CLEAN_REGEX_REPLACER = exports.CLEAN_SEARCH_REGEX = exports.DEFAULT_HTTP_STATUS = exports.PLACEHOLDER_PATTERN = void 0;
+exports.CLEAN_REGEX_REPLACER = exports.CLEAN_SEARCH_REGEX = exports.DEFAULT_HTTP_STATUS = exports.OFFSETS = exports.PLACEHOLDER_PATTERN = void 0;
 /**
  * Регулярное выражение для поиска плейсхолдеров вида `${{ key }}`.
  * Допускает только один пробел внутри скобок.
@@ -9,6 +9,11 @@ exports.CLEAN_REGEX_REPLACER = exports.CLEAN_SEARCH_REGEX = exports.DEFAULT_HTTP
  * // Найдёт: ${{ username }}
  */
 exports.PLACEHOLDER_PATTERN = /\$\{\{\s{1}([^}\s]+)\s{1}\}\}/g;
+exports.OFFSETS = {
+    START: "${{ ".length,
+    /** negative (`-length`) */
+    END: -" }}".length,
+};
 /** Статус HTTP по умолчанию (500 Internal Server Error). */
 exports.DEFAULT_HTTP_STATUS = 500;
 /** Регулярное выражение для экранирования специальных символов при создании RegExp из ключа. */

package/dist/factory.d.ts

@@ -28,13 +28,13 @@ import type { ErrorTemplateInput, ExceptionFormatterClass, Ferors, Logger } from
  * throw errors.USER_NOT_FOUND.execute({ userId: '123' });
  */
 export declare class FockerorFactory<FormatterClass> {
-    private readonly logger;
     private readonly formatterClass;
+    private readonly logger?;
     /**
      * @param logger - Экземпляр логгера (должен соответствовать интерфейсу Logger).
      * @param formatterClass - Класс для форматирования исключения (должен иметь конструктор, совместимый с Exception).
      */
-    constructor(logger: Logger, formatterClass: ExceptionFormatterClass<FormatterClass>);
+    constructor(formatterClass: ExceptionFormatterClass<FormatterClass>, logger?: Logger | undefined);
     /**
      * Генерирует набор ошибок для указанного префикса и шаблонов.
      * Для каждого шаблона создаётся экземпляр `Fockeror` с автоматически вычисленными плейсхолдерами.

package/dist/factory.js

@@ -32,15 +32,15 @@ const fockeror_1 = require("./fockeror");
  * throw errors.USER_NOT_FOUND.execute({ userId: '123' });
  */
 class FockerorFactory {
-    logger;
     formatterClass;
+    logger;
     /**
      * @param logger - Экземпляр логгера (должен соответствовать интерфейсу Logger).
      * @param formatterClass - Класс для форматирования исключения (должен иметь конструктор, совместимый с Exception).
      */
-    constructor(logger, formatterClass) {
-        this.logger = logger;
+    constructor(formatterClass, logger) {
         this.formatterClass = formatterClass;
+        this.logger = logger;
     }
     /**
      * Генерирует набор ошибок для указанного префикса и шаблонов.
@@ -58,12 +58,12 @@ class FockerorFactory {
             const input = templates[key];
             const errorTemplate = this.defineError(input);
             const code = this.generateCode(prefix, key, index);
-            this.logger.execute(`Загрузка ошибки ${prefix} ${code} : ${errorTemplate.message}`);
+            this.logger?.execute?.(`Загрузка ошибки ${prefix} ${code} : ${errorTemplate.message}`);
             const prefixed = {
                 ...errorTemplate,
                 message: `${code} : ${errorTemplate.message}`,
             };
-            const fockeror = new fockeror_1.Fockeror(prefixed, this.logger, this.formatterClass);
+            const fockeror = new fockeror_1.Fockeror(prefixed, this.formatterClass, this.logger);
             return [key, fockeror];
         });
         return Object.fromEntries(entries);
@@ -76,7 +76,7 @@ class FockerorFactory {
     defineError(error) {
         const combined = `${error.message} ${error.description}`;
         const matches = combined.match(constants_1.PLACEHOLDER_PATTERN);
-        const allKeys = matches?.map((m) => m.slice(1, -1)) ?? [];
+        const allKeys = matches?.map((m) => m.slice(constants_1.OFFSETS.START, constants_1.OFFSETS.END)) ?? [];
         const uniqueKeys = Array.from(new Set(allKeys));
         return { ...error, placeholders: uniqueKeys };
     }

package/dist/fockeror.d.ts

@@ -19,8 +19,8 @@ import type { ErrorTemplate, ExceptionFormatterClass, Logger, PlaceholderObject
  */
 export declare class Fockeror<const Placeholders extends string[], FormatterClass> {
     readonly template: ErrorTemplate<Placeholders>;
-    private readonly logger;
     private readonly formatterClass;
+    private readonly logger?;
     private readonly placeholderRegexes;
     /**
      * Создаёт экземпляр Fockeror.
@@ -29,7 +29,7 @@ export declare class Fockeror<const Placeholders extends string[], FormatterClas
      * @param formatterClass - Класс для форматирования исключения в специфичный для фреймворка тип.
      * @throws {Error} Если объявленные в `placeholders` ключи не соответствуют реально найденным в тексте.
      */
-    constructor(template: ErrorTemplate<Placeholders>, logger: Logger, formatterClass: ExceptionFormatterClass<FormatterClass>);
+    constructor(template: ErrorTemplate<Placeholders>, formatterClass: ExceptionFormatterClass<FormatterClass>, logger?: Logger | undefined);
     execute(placeholders: PlaceholderObject<Placeholders>, cause?: Error): FormatterClass;
     execute(cause?: Error): FormatterClass;
     throw(placeholders: PlaceholderObject<Placeholders>, cause?: Error): never;

package/dist/fockeror.js

@@ -23,8 +23,8 @@ const exception_1 = require("./exception");
  */
 class Fockeror {
     template;
-    logger;
     formatterClass;
+    logger;
     placeholderRegexes;
     /**
      * Создаёт экземпляр Fockeror.
@@ -33,10 +33,10 @@ class Fockeror {
      * @param formatterClass - Класс для форматирования исключения в специфичный для фреймворка тип.
      * @throws {Error} Если объявленные в `placeholders` ключи не соответствуют реально найденным в тексте.
      */
-    constructor(template, logger, formatterClass) {
+    constructor(template, formatterClass, logger) {
         this.template = template;
-        this.logger = logger;
         this.formatterClass = formatterClass;
+        this.logger = logger;
         this.placeholderRegexes = this.extractPlaceholders(template);
     }
     /**
@@ -99,7 +99,7 @@ class Fockeror {
         for (const [key, regex] of this.placeholderRegexes.entries()) {
             const value = placeholders[key];
             if (value === undefined) {
-                this.logger.error(new Error(`Placeholder \${{ ${key} }} not provided in data`));
+                this.logger?.error?.(new Error(`Placeholder \${{ ${key} }} not provided in data`));
                 continue;
             }
             message = message.replace(regex, value);
@@ -146,7 +146,7 @@ class Fockeror {
             errors.push(new Error(`Placeholder from text "${placeholder}" not found in placeholders list`));
         }
         if (errors.length !== 0) {
-            errors.forEach((e) => this.logger.error(e));
+            errors.forEach((e) => this.logger?.error?.(e));
             throw new Error("Placeholder validation failed.");
         }
     }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "fockeror",
-  "version": "0.2.1",
-  "description": "",
+  "version": "0.4.0",
+  "description": "Типобезопасная фабрика ошибок с уникальными кодами, подстановкой плейсхолдеров и форматированием исключений, не зависящим от фреймворка.",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "scripts": {
@@ -27,7 +27,19 @@
   "files": [
     "dist"
   ],
-  "keywords": [],
+  "keywords": [
+    "error",
+    "error-handling",
+    "exceptions",
+    "typescript",
+    "errors-factory",
+    "placeholders",
+    "typed-errors",
+    "http-errors",
+    "error-codes",
+    "validation",
+    "logger"
+  ],
   "author": {
     "name": "FOCKUSTY",
     "email": "viserd.yt@gmail.com",