fockeror 0.1.0 → 0.2.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 FOCKUSTY
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 FOCKUSTY
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/constants.d.ts

@@ -1,4 +1,14 @@
+/**
+ * Регулярное выражение для поиска плейсхолдеров вида `${{ key }}`.
+ * Допускает только один пробел внутри скобок.
+ *
+ * @example
+ * // Найдёт: ${{ username }}
+ */
 export declare const PLACEHOLDER_PATTERN: RegExp;
+/** Статус HTTP по умолчанию (500 Internal Server Error). */
 export declare const DEFAULT_HTTP_STATUS: 500;
+/** Регулярное выражение для экранирования специальных символов при создании RegExp из ключа. */
 export declare const CLEAN_SEARCH_REGEX: RegExp;
+/** Строка замены для экранирования специальных символов. */
 export declare const CLEAN_REGEX_REPLACER = "\\$&";

package/dist/constants.js

@@ -1,7 +1,17 @@
 "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;
+/**
+ * Регулярное выражение для поиска плейсхолдеров вида `${{ key }}`.
+ * Допускает только один пробел внутри скобок.
+ *
+ * @example
+ * // Найдёт: ${{ username }}
+ */
 exports.PLACEHOLDER_PATTERN = /\$\{\{\s{1}([^}\s]+)\s{1}\}\}/g;
+/** Статус HTTP по умолчанию (500 Internal Server Error). */
 exports.DEFAULT_HTTP_STATUS = 500;
+/** Регулярное выражение для экранирования специальных символов при создании RegExp из ключа. */
 exports.CLEAN_SEARCH_REGEX = /[.*+?^${}()|[\]\\]/g;
+/** Строка замены для экранирования специальных символов. */
 exports.CLEAN_REGEX_REPLACER = "\\$&";

package/dist/exception.d.ts

@@ -1,8 +1,24 @@
 import type { ExceptionFormatterClass, ExceptionOptions } from "./types";
+/**
+ * Базовый класс исключения, хранящий данные об ошибке.
+ * Позволяет форматировать исключение в специфичный для фреймворка класс через `format()`.
+ */
 export declare class Exception {
     readonly response: string | Record<string, unknown>;
     readonly status: number;
     readonly options?: ExceptionOptions | undefined;
+    /**
+     * @param response - Текст сообщения или объект с данными об ошибке.
+     * @param status - HTTP статус-код.
+     * @param options - Дополнительные опции (cause, description и т.д.).
+     */
     constructor(response: string | Record<string, unknown>, status: number, options?: ExceptionOptions | undefined);
+    /**
+     * Преобразует текущее исключение в экземпляр форматтера, специфичного для фреймворка.
+     * @param formatterClass - Класс-конструктор, принимающий параметры (response, status, options).
+     * @returns Экземпляр класса форматтера.
+     * @template T - Тип возвращаемого форматтера.
+     */
     format<T>(formatterClass: ExceptionFormatterClass<T>): T;
 }
+export default Exception;

package/dist/exception.js

@@ -1,17 +1,33 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Exception = void 0;
+/**
+ * Базовый класс исключения, хранящий данные об ошибке.
+ * Позволяет форматировать исключение в специфичный для фреймворка класс через `format()`.
+ */
 class Exception {
     response;
     status;
     options;
+    /**
+     * @param response - Текст сообщения или объект с данными об ошибке.
+     * @param status - HTTP статус-код.
+     * @param options - Дополнительные опции (cause, description и т.д.).
+     */
     constructor(response, status, options) {
         this.response = response;
         this.status = status;
         this.options = options;
     }
+    /**
+     * Преобразует текущее исключение в экземпляр форматтера, специфичного для фреймворка.
+     * @param formatterClass - Класс-конструктор, принимающий параметры (response, status, options).
+     * @returns Экземпляр класса форматтера.
+     * @template T - Тип возвращаемого форматтера.
+     */
     format(formatterClass) {
         return new formatterClass(this.response, this.status, this.options);
     }
 }
 exports.Exception = Exception;
+exports.default = Exception;

package/dist/factory.d.ts

@@ -1,9 +1,52 @@
 import type { ErrorTemplateInput, ExceptionFormatterClass, Ferors, Logger } from "./types";
-export declare class FerorFactory<FormatterClass> {
+/**
+ * Фабричный класс, создающий набор предопределённых ошибок с автоматически сгенерированными кодами.
+ * Каждой ошибке присваивается уникальный код формата `base64url(prefix):hex(key:index)`.
+ * Плейсхолдеры извлекаются автоматически из полей `message` и `description`.
+ *
+ * @template FormatterClass - Тип класса-форматтера исключений.
+ *
+ * @example
+ * const factory = new FockerorFactory(logger, CustomExceptionFormatter);
+ * const errors = factory.execute('AUTH', {
+ *   INVALID_TOKEN: {
+ *     message: 'Invalid token',
+ *     description: 'The token is expired',
+ *     status: 401,
+ *   },
+ *   USER_NOT_FOUND: {
+ *     message: 'User ${{ userId }} not found',
+ *     description: 'No user with id ${{ userId }} exists',
+ *     status: 404,
+ *   },
+ * });
+ *
+ * // Статическое исключение (без плейсхолдеров)
+ * throw errors.INVALID_TOKEN.exception;
+ *
+ * // Динамическое исключение с подстановкой
+ * throw errors.USER_NOT_FOUND.execute({ userId: '123' });
+ */
+export declare class FockerorFactory<FormatterClass> {
     private readonly logger;
     private readonly formatterClass;
+    /**
+     * @param logger - Экземпляр логгера (должен соответствовать интерфейсу Logger).
+     * @param formatterClass - Класс для форматирования исключения (должен иметь конструктор, совместимый с Exception).
+     */
     constructor(logger: Logger, formatterClass: ExceptionFormatterClass<FormatterClass>);
+    /**
+     * Генерирует набор ошибок для указанного префикса и шаблонов.
+     * Для каждого шаблона создаётся экземпляр `Fockeror` с автоматически вычисленными плейсхолдерами.
+     *
+     * @param prefix - Строка для генерации уникального кода (будет преобразована в base64url).
+     * @param templates - Объект, где ключи — идентификаторы ошибок, значения — `ErrorTemplateInput`.
+     * @returns Объект с экземплярами `Fockeror`, ключи соответствуют ключам входного объекта.
+     *
+     * @template Templates - Тип входных шаблонов.
+     */
     execute<const Templates extends Record<string, ErrorTemplateInput>>(prefix: string, templates: Templates): Ferors<Templates, FormatterClass>;
     private generateCode;
     private defineError;
 }
+export default FockerorFactory;

package/dist/factory.js

@@ -1,15 +1,57 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FerorFactory = void 0;
+exports.FockerorFactory = void 0;
 const constants_1 = require("./constants");
-const feror_1 = require("./feror");
-class FerorFactory {
+const fockeror_1 = require("./fockeror");
+/**
+ * Фабричный класс, создающий набор предопределённых ошибок с автоматически сгенерированными кодами.
+ * Каждой ошибке присваивается уникальный код формата `base64url(prefix):hex(key:index)`.
+ * Плейсхолдеры извлекаются автоматически из полей `message` и `description`.
+ *
+ * @template FormatterClass - Тип класса-форматтера исключений.
+ *
+ * @example
+ * const factory = new FockerorFactory(logger, CustomExceptionFormatter);
+ * const errors = factory.execute('AUTH', {
+ *   INVALID_TOKEN: {
+ *     message: 'Invalid token',
+ *     description: 'The token is expired',
+ *     status: 401,
+ *   },
+ *   USER_NOT_FOUND: {
+ *     message: 'User ${{ userId }} not found',
+ *     description: 'No user with id ${{ userId }} exists',
+ *     status: 404,
+ *   },
+ * });
+ *
+ * // Статическое исключение (без плейсхолдеров)
+ * throw errors.INVALID_TOKEN.exception;
+ *
+ * // Динамическое исключение с подстановкой
+ * throw errors.USER_NOT_FOUND.execute({ userId: '123' });
+ */
+class FockerorFactory {
     logger;
     formatterClass;
+    /**
+     * @param logger - Экземпляр логгера (должен соответствовать интерфейсу Logger).
+     * @param formatterClass - Класс для форматирования исключения (должен иметь конструктор, совместимый с Exception).
+     */
     constructor(logger, formatterClass) {
         this.logger = logger;
         this.formatterClass = formatterClass;
     }
+    /**
+     * Генерирует набор ошибок для указанного префикса и шаблонов.
+     * Для каждого шаблона создаётся экземпляр `Fockeror` с автоматически вычисленными плейсхолдерами.
+     *
+     * @param prefix - Строка для генерации уникального кода (будет преобразована в base64url).
+     * @param templates - Объект, где ключи — идентификаторы ошибок, значения — `ErrorTemplateInput`.
+     * @returns Объект с экземплярами `Fockeror`, ключи соответствуют ключам входного объекта.
+     *
+     * @template Templates - Тип входных шаблонов.
+     */
     execute(prefix, templates) {
         const templateKeys = Object.keys(templates);
         const entries = templateKeys.map((key, index) => {
@@ -21,7 +63,8 @@ class FerorFactory {
                 ...errorTemplate,
                 message: `${code} : ${errorTemplate.message}`,
             };
-            return [key, new feror_1.Feror(prefixed, this.logger, this.formatterClass)];
+            const fockeror = new fockeror_1.Fockeror(prefixed, this.logger, this.formatterClass);
+            return [key, fockeror];
         });
         return Object.fromEntries(entries);
     }
@@ -38,4 +81,5 @@ class FerorFactory {
         return { ...error, placeholders: uniqueKeys };
     }
 }
-exports.FerorFactory = FerorFactory;
+exports.FockerorFactory = FockerorFactory;
+exports.default = FockerorFactory;

package/dist/fockeror.d.ts

@@ -0,0 +1,52 @@
+import type { ErrorTemplate, ExceptionFormatterClass, Logger, PlaceholderObject } from "./types";
+/**
+ * Класс, представляющий конкретную ошибку с возможностью динамической подстановки плейсхолдеров по примеру `${{ key }}`.
+ * @template Placeholders - Кортеж ключей плейсхолдеров (например, `['userId', 'action']`).
+ * @template FormatterClass - Тип класса-форматтера для преобразования исключения.
+ *
+ * @example
+ * const error = new Fockeror({
+ *   message: 'User ${{ userId }} not found',
+ *   description: 'No user with id ${{ userId }} exists',
+ *   placeholders: ['userId']
+ * }, logger, formatterClass);
+ *
+ * // Подстановка значений
+ * throw error.throw({ userId: '123' });
+ *
+ * // Статическое исключение (без подстановки)
+ * throw error.exception;
+ */
+export declare class Fockeror<const Placeholders extends string[], FormatterClass> {
+    readonly template: ErrorTemplate<Placeholders>;
+    private readonly logger;
+    private readonly formatterClass;
+    private readonly placeholderRegexes;
+    /**
+     * Создаёт экземпляр Fockeror.
+     * @param template - Шаблон ошибки (должен содержать корректный массив `placeholders`).
+     * @param logger - Экземпляр логгера (должен соответствовать интерфейсу Logger).
+     * @param formatterClass - Класс для форматирования исключения в специфичный для фреймворка тип.
+     * @throws {Error} Если объявленные в `placeholders` ключи не соответствуют реально найденным в тексте.
+     */
+    constructor(template: ErrorTemplate<Placeholders>, logger: Logger, formatterClass: ExceptionFormatterClass<FormatterClass>);
+    execute(placeholders: PlaceholderObject<Placeholders>, cause?: Error): FormatterClass;
+    execute(cause?: Error): FormatterClass;
+    throw(placeholders: PlaceholderObject<Placeholders>, cause?: Error): never;
+    throw(cause?: Error): never;
+    /**
+     * Геттер, возвращающий статическое исключение (без подстановки плейсхолдеров).
+     * Позволяет использовать краткую запись `throw error.exception`.
+     */
+    get exception(): FormatterClass;
+    private createStaticException;
+    private createDynamicException;
+    private formatTemplate;
+    private createException;
+    private collectPlaceholdersFromText;
+    private validatePlaceholders;
+    private buildRegexMap;
+    private extractPlaceholders;
+    private createRegEx;
+}
+export default Fockeror;

package/dist/fockeror.js

@@ -0,0 +1,171 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Fockeror = void 0;
+const constants_1 = require("./constants");
+const exception_1 = require("./exception");
+/**
+ * Класс, представляющий конкретную ошибку с возможностью динамической подстановки плейсхолдеров по примеру `${{ key }}`.
+ * @template Placeholders - Кортеж ключей плейсхолдеров (например, `['userId', 'action']`).
+ * @template FormatterClass - Тип класса-форматтера для преобразования исключения.
+ *
+ * @example
+ * const error = new Fockeror({
+ *   message: 'User ${{ userId }} not found',
+ *   description: 'No user with id ${{ userId }} exists',
+ *   placeholders: ['userId']
+ * }, logger, formatterClass);
+ *
+ * // Подстановка значений
+ * throw error.throw({ userId: '123' });
+ *
+ * // Статическое исключение (без подстановки)
+ * throw error.exception;
+ */
+class Fockeror {
+    template;
+    logger;
+    formatterClass;
+    placeholderRegexes;
+    /**
+     * Создаёт экземпляр Fockeror.
+     * @param template - Шаблон ошибки (должен содержать корректный массив `placeholders`).
+     * @param logger - Экземпляр логгера (должен соответствовать интерфейсу Logger).
+     * @param formatterClass - Класс для форматирования исключения в специфичный для фреймворка тип.
+     * @throws {Error} Если объявленные в `placeholders` ключи не соответствуют реально найденным в тексте.
+     */
+    constructor(template, logger, formatterClass) {
+        this.template = template;
+        this.logger = logger;
+        this.formatterClass = formatterClass;
+        this.placeholderRegexes = this.extractPlaceholders(template);
+    }
+    /**
+     * Возвращает отформатированное исключение с подстановкой данных.
+     * Если передан пустой объект `placeholders` или вызов без аргументов, возвращается статическое исключение.
+     *
+     * @param placeholdersOrCause - Объект с значениями для замены плейсхолдеров или причина ошибки.
+     * @param cause - Дополнительная причина ошибки (если первый аргумент — placeholders).
+     * @returns Экземпляр форматтера (обычно исключение фреймворка).
+     *
+     * @example
+     * const error = new Fockeror({ message: 'Hello ${{ name }}', description: '', placeholders: ['name'] }, logger, formatter);
+     * const exception = error.execute({ name: 'World' });
+     * throw exception;
+     */
+    execute(placeholdersOrCause, cause) {
+        let placeholders;
+        let actualCause;
+        if (placeholdersOrCause instanceof Error) {
+            actualCause = placeholdersOrCause;
+        }
+        else {
+            placeholders = placeholdersOrCause;
+            actualCause = cause;
+        }
+        if (!placeholders || Object.keys(placeholders).length === 0) {
+            return this.createStaticException(actualCause);
+        }
+        return this.createDynamicException(placeholders, actualCause);
+    }
+    /**
+     * Немедленно выбрасывает отформатированное исключение с подстановкой данных.
+     * @param placeholdersOrCause - Объект с значениями для замены плейсхолдеров или причина ошибки.
+     * @param cause - Дополнительная причина ошибки.
+     * @throws {FormatterClass} Всегда выбрасывает исключение, отформатированное через `formatterClass`.
+     */
+    throw(placeholdersOrCause, cause) {
+        if (placeholdersOrCause instanceof Error) {
+            throw this.execute(placeholdersOrCause);
+        }
+        throw this.execute(placeholdersOrCause, cause);
+    }
+    /**
+     * Геттер, возвращающий статическое исключение (без подстановки плейсхолдеров).
+     * Позволяет использовать краткую запись `throw error.exception`.
+     */
+    get exception() {
+        return this.createStaticException();
+    }
+    createStaticException(cause) {
+        return this.createException({ ...this.template, placeholders: [] }, cause);
+    }
+    createDynamicException(placeholders, cause) {
+        const error = this.formatTemplate(placeholders);
+        return this.createException(error, cause);
+    }
+    formatTemplate(placeholders) {
+        let message = this.template.message;
+        let description = this.template.description;
+        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`));
+                continue;
+            }
+            message = message.replace(regex, value);
+            description = description.replace(regex, value);
+        }
+        return {
+            ...this.template,
+            message,
+            description,
+            placeholders: [],
+        };
+    }
+    createException(error, cause) {
+        const status = error.status ?? this.template.status ?? constants_1.DEFAULT_HTTP_STATUS;
+        const exception = new exception_1.Exception(error.message, status, {
+            description: error.description,
+            cause: cause ?? error.cause,
+        });
+        return exception.format(this.formatterClass);
+    }
+    collectPlaceholdersFromText(template) {
+        const text = `${template.message} ${template.description}`;
+        const set = new Set();
+        for (const match of text.matchAll(constants_1.PLACEHOLDER_PATTERN)) {
+            set.add(match[1]);
+        }
+        return set;
+    }
+    validatePlaceholders(collectedPlaceholders, declaredPlaceholders) {
+        if (!declaredPlaceholders) {
+            return;
+        }
+        const errors = [];
+        for (const placeholder of declaredPlaceholders) {
+            if (collectedPlaceholders.has(placeholder)) {
+                continue;
+            }
+            errors.push(new Error(`Placeholder "${placeholder}" not found in text`));
+        }
+        for (const placeholder of collectedPlaceholders) {
+            if (declaredPlaceholders.includes(placeholder)) {
+                continue;
+            }
+            errors.push(new Error(`Placeholder from text "${placeholder}" not found in placeholders list`));
+        }
+        if (errors.length !== 0) {
+            errors.forEach((e) => this.logger.error(e));
+            throw new Error("Placeholder validation failed.");
+        }
+    }
+    buildRegexMap(keys) {
+        const map = new Map();
+        for (const key of keys) {
+            map.set(key, this.createRegEx(key));
+        }
+        return map;
+    }
+    extractPlaceholders(template) {
+        const collected = this.collectPlaceholdersFromText(template);
+        this.validatePlaceholders(collected, template.placeholders);
+        return this.buildRegexMap(collected);
+    }
+    createRegEx(key) {
+        const clean = key.replace(constants_1.CLEAN_SEARCH_REGEX, constants_1.CLEAN_REGEX_REPLACER);
+        return new RegExp(`\\$\\{\\{\\s{1}${clean}\\s{1}\\}\\}`);
+    }
+}
+exports.Fockeror = Fockeror;
+exports.default = Fockeror;

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-import { FerorFactory } from "./factory";
-export * from "./feror";
+import { FockerorFactory } from "./factory";
+export * from "./fockeror";
 export * from "./factory";
 export * from "./exception";
-export type { Logger, ExceptionOptions, } from "./types";
-export default FerorFactory;
+export type { Logger, ExceptionOptions } from "./types";
+export default FockerorFactory;

package/dist/index.js

@@ -15,7 +15,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 const factory_1 = require("./factory");
-__exportStar(require("./feror"), exports);
+__exportStar(require("./fockeror"), exports);
 __exportStar(require("./factory"), exports);
 __exportStar(require("./exception"), exports);
-exports.default = factory_1.FerorFactory;
+exports.default = factory_1.FockerorFactory;

package/dist/types.d.ts

@@ -1,24 +1,63 @@
 import { Exception } from "./exception";
-import type { Feror } from "./feror";
+import type { Fockeror } from "./fockeror";
+/** Интерфейс логгера, используемого в модуле. */
 export interface Logger {
+    /** Логирование ошибки. */
     error: (message: Error) => unknown;
+    /** Логирование информационного сообщения. */
     execute: (message: string) => unknown;
 }
+/**
+ * Объект, содержащий значения для подстановки вместо плейсхолдеров.
+ * @template Placeholders - Массив строковых ключей (например, `['userId', 'role']`).
+ * @example
+ * type Data = PlaceholderObject<['userId', 'role']>; // { userId: string; role: string }
+ */
 export type PlaceholderObject<Placeholders extends string[]> = {
     [P in Placeholders[number]]: string;
 };
+/**
+ * Рекурсивный тип, извлекающий все ключи плейсхолдеров из строки в кортеж.
+ * **Важно:** для корректного вывода типов используйте ровно один пробел внутри `${{ key }}`.
+ * В рантайме допускается любое количество пробелов благодаря регулярному выражению.
+ *
+ * @template InputString - Исходная строка.
+ * @template Acc - Аккумулятор кортежа (по умолчанию []).
+ * @example
+ * type Keys = ExtractPlaceholdersTuple<"Hello ${{ name }}, your id is ${{ id }}">; // ['name', 'id']
+ */
 export type ExtractPlaceholdersTuple<InputString extends string, Acc extends string[] = []> = InputString extends `${infer _}\${{ ${infer P} }}${infer Rest}` ? ExtractPlaceholdersTuple<Rest, [...Acc, P]> : Acc;
+/**
+ * Вычисляет кортеж плейсхолдеров, объединяя поля `message` и `description` шаблона.
+ * @template T - Объект с обязательными полями `message` и `description`.
+ * @example
+ * type Template = { message: "User ${{ userId }}", description: "Action ${{ action }}" };
+ * type Placeholders = InferPlaceholders<Template>; // ['userId', 'action']
+ */
 export type InferPlaceholders<T extends {
     message: string;
     description: string;
 }> = ExtractPlaceholdersTuple<`${T["message"]} ${T["description"]}`>;
+/**
+ * Входной формат описания ошибки без автоматически вычисляемого поля `placeholders`.
+ * Используется при создании фабрики ошибок.
+ */
 export type ErrorTemplateInput = {
+    /** Текст сообщения об ошибке (может содержать плейсхолдеры `${{ key }}`). */
     message: string;
+    /** Подробное описание ошибки (может содержать плейсхолдеры `${{ key }}`). */
     description: string;
+    /** Дополнительная причина ошибки (объект Error). */
     cause?: Error;
+    /** HTTP статус-код (по умолчанию 500). */
     status?: number;
+    /** Дополнительные опции, которые будут переданы в форматтер исключения. */
     options?: Record<string, unknown>;
 };
+/**
+ * Внутренний шаблон ошибки, где поле `placeholders` выводится автоматически из `message` и `description`.
+ * @template Placeholders - Кортеж ключей плейсхолдеров.
+ */
 export interface ErrorTemplate<Placeholders extends string[]> {
     message: string;
     description: string;
@@ -27,14 +66,27 @@ export interface ErrorTemplate<Placeholders extends string[]> {
     options?: Record<string, unknown>;
     placeholders: Placeholders;
 }
+/** Карта ключ → регулярное выражение для замены плейсхолдера в строке. */
 export type PlaceholderRegexMap<Placeholders extends string[]> = Map<keyof PlaceholderObject<Placeholders>, RegExp>;
+/** Шаблон после замены всех плейсхолдеров (плейсхолдеры отсутствуют). */
 export type FormattedErrorTemplate = ErrorTemplate<[]>;
-export type Ferors<ErrorTemplate extends Record<string, ErrorTemplateInput>, FormatterClass> = {
-    [K in keyof ErrorTemplate]: Feror<InferPlaceholders<ErrorTemplate[K]>, FormatterClass>;
+/**
+ * Преобразует запись входных шаблонов в запись экземпляров `Feror`.
+ * @template T - Объект с шаблонами ошибок.
+ * @template FormatterClass - Класс форматтера исключений.
+ */
+export type Ferors<T extends Record<string, ErrorTemplateInput>, FormatterClass> = {
+    [K in keyof T]: Fockeror<InferPlaceholders<T[K]>, FormatterClass>;
 };
+/** Опции исключения (cause, description). */
 export interface ExceptionOptions {
     cause?: unknown;
     description?: string;
 }
-export type ExceptionConstuctorParameters = ConstructorParameters<typeof Exception>;
-export type ExceptionFormatterClass<T> = new (...parameters: ExceptionConstuctorParameters) => T;
+/** Параметры конструктора класса Exception. */
+export type ExceptionConstructorParameters = ConstructorParameters<typeof Exception>;
+/**
+ * Класс-конструктор форматтера исключений.
+ * @template T - Тип возвращаемого экземпляра.
+ */
+export type ExceptionFormatterClass<T> = new (...parameters: ExceptionConstructorParameters) => T;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fockeror",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -12,15 +12,19 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./index": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
     }
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/fockusty/fockeror.git"
+    "url": "https://github.com/FOCKUSTY/fockeror.git"
   },
-  "homepage": "https://github.com/fockusty/fockeror#readme",
+  "homepage": "https://github.com/FOCKUSTY/fockeror#readme",
   "bugs": {
-    "url": "https://github.com/fockusty/fockeror/issues"
+    "url": "https://github.com/FOCKUSTY/fockeror/issues"
   },
   "files": [
     "dist"

package/dist/feror.d.ts

@@ -1,21 +0,0 @@
-import type { ErrorTemplate, ExceptionFormatterClass, Logger, PlaceholderObject } from "./types";
-export declare class Feror<const Placeholders extends string[], FormatterClass> {
-    readonly template: ErrorTemplate<Placeholders>;
-    private readonly logger;
-    private readonly formatterClass;
-    private readonly placeholderRegexes;
-    constructor(template: ErrorTemplate<Placeholders>, logger: Logger, formatterClass: ExceptionFormatterClass<FormatterClass>);
-    execute(placeholders: PlaceholderObject<Placeholders>, cause?: Error): FormatterClass;
-    execute(cause?: Error): FormatterClass;
-    throw(placeholders: PlaceholderObject<Placeholders>, cause?: Error): never;
-    throw(cause?: Error): never;
-    private createStaticException;
-    private createDynamicException;
-    private formatTemplate;
-    private createException;
-    private collectPlaceholdersFromText;
-    private validatePlaceholders;
-    private buildRegexMap;
-    private extractPlaceholders;
-    private createRegEx;
-}

package/dist/feror.js

@@ -1,119 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.Feror = void 0;
-const constants_1 = require("./constants");
-const exception_1 = require("./exception");
-const PLACEHOLDER_PATTERN = /\$\{\{\s{1}([^}\s]+)\s{1}\}\}/g;
-class Feror {
-    template;
-    logger;
-    formatterClass;
-    placeholderRegexes;
-    constructor(template, logger, formatterClass) {
-        this.template = template;
-        this.logger = logger;
-        this.formatterClass = formatterClass;
-        this.placeholderRegexes = this.extractPlaceholders(template);
-    }
-    execute(placeholdersOrCause, cause) {
-        let placeholders = undefined;
-        let actualCause;
-        if (placeholdersOrCause instanceof Error) {
-            actualCause = placeholdersOrCause;
-        }
-        else {
-            placeholders = placeholdersOrCause;
-            actualCause = cause;
-        }
-        if (!placeholders || Object.keys(placeholders).length === 0) {
-            return this.createStaticException(actualCause);
-        }
-        return this.createDynamicException(placeholders, actualCause);
-    }
-    throw(placeholdersOrCause, cause) {
-        if (placeholdersOrCause instanceof Error) {
-            throw this.execute(placeholdersOrCause);
-        }
-        throw this.execute(placeholdersOrCause, cause);
-    }
-    createStaticException(cause) {
-        return this.createException({ ...this.template, placeholders: [] }, cause);
-    }
-    createDynamicException(placeholders, cause) {
-        const error = this.formatTemplate(placeholders);
-        return this.createException(error, cause);
-    }
-    formatTemplate(placeholders) {
-        let message = this.template.message;
-        let description = this.template.description;
-        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`));
-                continue;
-            }
-            message = message.replace(regex, value);
-            description = description.replace(regex, value);
-        }
-        return {
-            ...this.template,
-            message,
-            description,
-            placeholders: [],
-        };
-    }
-    createException(error, cause) {
-        const status = error.status ?? this.template.status ?? constants_1.DEFAULT_HTTP_STATUS;
-        return new exception_1.Exception(error.message, status, {
-            description: error.description,
-            cause: cause ?? error.cause,
-        }).format(this.formatterClass);
-    }
-    collectPlaceholdersFromText(template) {
-        const text = `${template.message} ${template.description}`;
-        const set = new Set();
-        for (const match of text.matchAll(PLACEHOLDER_PATTERN)) {
-            set.add(match[1]);
-        }
-        return set;
-    }
-    validatePlaceholders(collectedPlaceholders, declaredPlaceholders) {
-        if (!declaredPlaceholders) {
-            return;
-        }
-        const errors = [];
-        for (const placeholder of declaredPlaceholders) {
-            if (collectedPlaceholders.has(placeholder)) {
-                continue;
-            }
-            errors.push(new Error(`Placeholder "${placeholder}" not found in text`));
-        }
-        for (const placeholder of collectedPlaceholders) {
-            if (declaredPlaceholders.includes(placeholder)) {
-                continue;
-            }
-            errors.push(new Error(`Placeholder from text "${placeholder}" not found in placeholders list`));
-        }
-        if (errors.length !== 0) {
-            errors.forEach((e) => this.logger.error(e));
-            throw new Error("Placeholder validation failed.");
-        }
-    }
-    buildRegexMap(keys) {
-        const placeholdersMap = new Map();
-        for (const key of keys) {
-            placeholdersMap.set(key, this.createRegEx(key));
-        }
-        return placeholdersMap;
-    }
-    extractPlaceholders(template) {
-        const collected = this.collectPlaceholdersFromText(template);
-        this.validatePlaceholders(collected, template.placeholders);
-        return this.buildRegexMap(collected);
-    }
-    createRegEx(key) {
-        const clean = key.replace(constants_1.CLEAN_SEARCH_REGEX, constants_1.CLEAN_REGEX_REPLACER);
-        return new RegExp(`\\$\\{\\{\\s{1}${clean}\\s{1}\\}\\}`);
-    }
-}
-exports.Feror = Feror;