@reformer/core 1.0.0-beta.3

package/dist/core/types/validation-schema.js

@@ -0,0 +1,10 @@
+/**
+ * Типы для validation schema паттерна
+ *
+ * Основано на Angular Signal Forms подходе:
+ * - Валидация определяется отдельно от схемы полей
+ * - Поддержка условной валидации (applyWhen)
+ * - Cross-field валидация (validateTree)
+ * - Асинхронная валидация с контекстом
+ */
+export {};

package/dist/core/utils/create-form.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Фабричная функция для создания формы с правильной типизацией
+ *
+ * Решает проблему с типизацией конструктора GroupNode, который возвращает
+ * Proxy (GroupNodeWithControls), но TypeScript не может это вывести автоматически.
+ *
+ * @group Utilities
+ *
+ * @example
+ * ```typescript
+ * // Вместо:
+ * const form: GroupNodeWithControls<MyForm> = new GroupNode<MyForm>(config);
+ *
+ * // Используйте:
+ * const form = createForm<MyForm>(config);
+ * ```
+ */
+import type { GroupNodeWithControls, GroupNodeConfig, FormSchema } from '../types';
+/**
+ * Создать форму с полной конфигурацией (form, behavior, validation)
+ *
+ * @group Utilities
+ *
+ * @param config - Конфигурация формы с полями, поведением и валидацией
+ * @returns Типизированная форма с Proxy-доступом к полям
+ *
+ * @example
+ * ```typescript
+ * const form = createForm<UserForm>({
+ *   form: {
+ *     email: { value: '', component: Input },
+ *     password: { value: '', component: Input },
+ *   },
+ *   validation: (path) => {
+ *     required(path.email);
+ *     email(path.email);
+ *     required(path.password);
+ *     minLength(path.password, 8);
+ *   },
+ * });
+ *
+ * // TypeScript знает о полях:
+ * form.email.setValue('test@mail.com');
+ * ```
+ */
+export declare function createForm<T>(config: GroupNodeConfig<T>): GroupNodeWithControls<T>;
+/**
+ * Создать форму только со схемой полей (обратная совместимость)
+ *
+ * @param schema - Схема полей формы
+ * @returns Типизированная форма с Proxy-доступом к полям
+ *
+ * @example
+ * ```typescript
+ * const form = createForm<UserForm>({
+ *   email: { value: '', component: Input },
+ *   password: { value: '', component: Input },
+ * });
+ * ```
+ */
+export declare function createForm<T>(schema: FormSchema<T>): GroupNodeWithControls<T>;

package/dist/core/utils/create-form.js

@@ -0,0 +1,24 @@
+/**
+ * Фабричная функция для создания формы с правильной типизацией
+ *
+ * Решает проблему с типизацией конструктора GroupNode, который возвращает
+ * Proxy (GroupNodeWithControls), но TypeScript не может это вывести автоматически.
+ *
+ * @group Utilities
+ *
+ * @example
+ * ```typescript
+ * // Вместо:
+ * const form: GroupNodeWithControls<MyForm> = new GroupNode<MyForm>(config);
+ *
+ * // Используйте:
+ * const form = createForm<MyForm>(config);
+ * ```
+ */
+import { GroupNode } from '../nodes/group-node';
+/**
+ * Реализация фабричной функции
+ */
+export function createForm(schemaOrConfig) {
+    return new GroupNode(schemaOrConfig);
+}

package/dist/core/utils/debounce.d.ts

@@ -0,0 +1,160 @@
+/**
+ * Debouncer - утилита для отложенного выполнения функций
+ *
+ * Устраняет дублирование debounce логики между field-node.ts и behavior-registry.ts
+ *
+ * @internal
+ *
+ * @example
+ * ```typescript
+ * const debouncer = new Debouncer(300);
+ *
+ * // Отложить выполнение на 300мс
+ * await debouncer.debounce(async () => {
+ *   await validateField();
+ * });
+ *
+ * // Отменить отложенное выполнение
+ * debouncer.cancel();
+ *
+ * // Выполнить немедленно, отменив отложенное
+ * await debouncer.flush(async () => {
+ *   await validateField();
+ * });
+ * ```
+ */
+/**
+ * Класс для debouncing (отложенного выполнения) функций
+ *
+ * @internal
+ *
+ * Откладывает выполнение функции на заданное время. Если функция вызывается
+ * повторно до истечения времени, предыдущий вызов отменяется.
+ *
+ * Полезно для:
+ * - Отложенной валидации при вводе (debounced validation)
+ * - Отложенного сохранения данных
+ * - Отложенной обработки событий behaviors
+ *
+ * @example
+ * ```typescript
+ * // В FieldNode
+ * class FieldNode {
+ *   private validationDebouncer: Debouncer;
+ *
+ *   constructor(config) {
+ *     this.validationDebouncer = new Debouncer(config.debounce || 0);
+ *   }
+ *
+ *   async validate(): Promise<boolean> {
+ *     return this.validationDebouncer.debounce(async () => {
+ *       // Валидация выполнится через debounce мс
+ *       return await this.runValidation();
+ *     });
+ *   }
+ * }
+ * ```
+ */
+export declare class Debouncer {
+    private readonly delay;
+    /**
+     * Таймер для отложенного выполнения
+     * @private
+     */
+    private timer?;
+    /**
+     * Создать Debouncer с заданной задержкой
+     *
+     * @param delay Задержка в миллисекундах (0 = без задержки)
+     *
+     * @example
+     * ```typescript
+     * const debouncer = new Debouncer(300); // 300мс задержка
+     * const immediate = new Debouncer(0);  // Без задержки
+     * ```
+     */
+    constructor(delay: number);
+    /**
+     * Отложить выполнение функции
+     *
+     * Если вызывается повторно до истечения delay, предыдущий вызов отменяется
+     * и таймер перезапускается.
+     *
+     * @param fn Функция для выполнения (может быть async)
+     * @returns Promise, который разрешается результатом функции
+     *
+     * @example
+     * ```typescript
+     * const debouncer = new Debouncer(300);
+     *
+     * // Первый вызов - запланирован через 300мс
+     * debouncer.debounce(async () => console.log('First'));
+     *
+     * // Второй вызов через 100мс - отменяет первый, запланирован через 300мс
+     * debouncer.debounce(async () => console.log('Second'));
+     *
+     * // Через 300мс выведет только: "Second"
+     * ```
+     */
+    debounce<T>(fn: () => T | Promise<T>): Promise<T>;
+    /**
+     * Отменить отложенное выполнение
+     *
+     * Если есть запланированный вызов, он будет отменен и не выполнится.
+     * Promise из debounce() никогда не разрешится.
+     *
+     * @example
+     * ```typescript
+     * const debouncer = new Debouncer(300);
+     *
+     * debouncer.debounce(async () => {
+     *   console.log('This will not execute');
+     * });
+     *
+     * debouncer.cancel(); // Отменяем вызов
+     * ```
+     */
+    cancel(): void;
+    /**
+     * Выполнить функцию немедленно, отменив любой отложенный вызов
+     *
+     * Полезно когда нужно принудительно выполнить действие сейчас,
+     * игнорируя debounce.
+     *
+     * @param fn Функция для немедленного выполнения
+     * @returns Promise с результатом функции
+     *
+     * @example
+     * ```typescript
+     * const debouncer = new Debouncer(300);
+     *
+     * // Запланировано через 300мс
+     * debouncer.debounce(async () => console.log('Delayed'));
+     *
+     * // Отменяем отложенный и выполняем немедленно
+     * await debouncer.flush(async () => console.log('Immediate'));
+     * // Выведет: "Immediate" (сразу)
+     * // "Delayed" не выполнится (отменен)
+     * ```
+     */
+    flush<T>(fn: () => T | Promise<T>): Promise<T>;
+    /**
+     * Проверить, есть ли активный (запланированный) вызов
+     *
+     * @returns true если есть запланированный вызов
+     *
+     * @example
+     * ```typescript
+     * const debouncer = new Debouncer(300);
+     *
+     * console.log(debouncer.isPending()); // false
+     *
+     * debouncer.debounce(() => console.log('Test'));
+     * console.log(debouncer.isPending()); // true
+     *
+     * // Через 300мс
+     * console.log(debouncer.isPending()); // false
+     * ```
+     */
+    isPending(): boolean;
+}

package/dist/core/utils/debounce.js

@@ -0,0 +1,197 @@
+/**
+ * Debouncer - утилита для отложенного выполнения функций
+ *
+ * Устраняет дублирование debounce логики между field-node.ts и behavior-registry.ts
+ *
+ * @internal
+ *
+ * @example
+ * ```typescript
+ * const debouncer = new Debouncer(300);
+ *
+ * // Отложить выполнение на 300мс
+ * await debouncer.debounce(async () => {
+ *   await validateField();
+ * });
+ *
+ * // Отменить отложенное выполнение
+ * debouncer.cancel();
+ *
+ * // Выполнить немедленно, отменив отложенное
+ * await debouncer.flush(async () => {
+ *   await validateField();
+ * });
+ * ```
+ */
+/**
+ * Класс для debouncing (отложенного выполнения) функций
+ *
+ * @internal
+ *
+ * Откладывает выполнение функции на заданное время. Если функция вызывается
+ * повторно до истечения времени, предыдущий вызов отменяется.
+ *
+ * Полезно для:
+ * - Отложенной валидации при вводе (debounced validation)
+ * - Отложенного сохранения данных
+ * - Отложенной обработки событий behaviors
+ *
+ * @example
+ * ```typescript
+ * // В FieldNode
+ * class FieldNode {
+ *   private validationDebouncer: Debouncer;
+ *
+ *   constructor(config) {
+ *     this.validationDebouncer = new Debouncer(config.debounce || 0);
+ *   }
+ *
+ *   async validate(): Promise<boolean> {
+ *     return this.validationDebouncer.debounce(async () => {
+ *       // Валидация выполнится через debounce мс
+ *       return await this.runValidation();
+ *     });
+ *   }
+ * }
+ * ```
+ */
+export class Debouncer {
+    delay;
+    /**
+     * Таймер для отложенного выполнения
+     * @private
+     */
+    timer;
+    /**
+     * Создать Debouncer с заданной задержкой
+     *
+     * @param delay Задержка в миллисекундах (0 = без задержки)
+     *
+     * @example
+     * ```typescript
+     * const debouncer = new Debouncer(300); // 300мс задержка
+     * const immediate = new Debouncer(0);  // Без задержки
+     * ```
+     */
+    constructor(delay) {
+        this.delay = delay;
+    }
+    /**
+     * Отложить выполнение функции
+     *
+     * Если вызывается повторно до истечения delay, предыдущий вызов отменяется
+     * и таймер перезапускается.
+     *
+     * @param fn Функция для выполнения (может быть async)
+     * @returns Promise, который разрешается результатом функции
+     *
+     * @example
+     * ```typescript
+     * const debouncer = new Debouncer(300);
+     *
+     * // Первый вызов - запланирован через 300мс
+     * debouncer.debounce(async () => console.log('First'));
+     *
+     * // Второй вызов через 100мс - отменяет первый, запланирован через 300мс
+     * debouncer.debounce(async () => console.log('Second'));
+     *
+     * // Через 300мс выведет только: "Second"
+     * ```
+     */
+    async debounce(fn) {
+        return new Promise((resolve, reject) => {
+            // Отменяем предыдущий таймер, если есть
+            if (this.timer) {
+                clearTimeout(this.timer);
+            }
+            // Если delay = 0, выполняем немедленно
+            if (this.delay === 0) {
+                Promise.resolve()
+                    .then(() => fn())
+                    .then(resolve)
+                    .catch(reject);
+                return;
+            }
+            // Запускаем новый таймер
+            this.timer = setTimeout(async () => {
+                try {
+                    const result = await fn();
+                    resolve(result);
+                }
+                catch (error) {
+                    reject(error);
+                }
+            }, this.delay);
+        });
+    }
+    /**
+     * Отменить отложенное выполнение
+     *
+     * Если есть запланированный вызов, он будет отменен и не выполнится.
+     * Promise из debounce() никогда не разрешится.
+     *
+     * @example
+     * ```typescript
+     * const debouncer = new Debouncer(300);
+     *
+     * debouncer.debounce(async () => {
+     *   console.log('This will not execute');
+     * });
+     *
+     * debouncer.cancel(); // Отменяем вызов
+     * ```
+     */
+    cancel() {
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = undefined;
+        }
+    }
+    /**
+     * Выполнить функцию немедленно, отменив любой отложенный вызов
+     *
+     * Полезно когда нужно принудительно выполнить действие сейчас,
+     * игнорируя debounce.
+     *
+     * @param fn Функция для немедленного выполнения
+     * @returns Promise с результатом функции
+     *
+     * @example
+     * ```typescript
+     * const debouncer = new Debouncer(300);
+     *
+     * // Запланировано через 300мс
+     * debouncer.debounce(async () => console.log('Delayed'));
+     *
+     * // Отменяем отложенный и выполняем немедленно
+     * await debouncer.flush(async () => console.log('Immediate'));
+     * // Выведет: "Immediate" (сразу)
+     * // "Delayed" не выполнится (отменен)
+     * ```
+     */
+    async flush(fn) {
+        this.cancel();
+        return await fn();
+    }
+    /**
+     * Проверить, есть ли активный (запланированный) вызов
+     *
+     * @returns true если есть запланированный вызов
+     *
+     * @example
+     * ```typescript
+     * const debouncer = new Debouncer(300);
+     *
+     * console.log(debouncer.isPending()); // false
+     *
+     * debouncer.debounce(() => console.log('Test'));
+     * console.log(debouncer.isPending()); // true
+     *
+     * // Через 300мс
+     * console.log(debouncer.isPending()); // false
+     * ```
+     */
+    isPending() {
+        return this.timer !== undefined;
+    }
+}

package/dist/core/utils/error-handler.d.ts

@@ -0,0 +1,180 @@
+/**
+ * FormErrorHandler - централизованная обработка ошибок в формах
+ *
+ * Устраняет несогласованность обработки ошибок между:
+ * - field-node.ts (логирует и конвертирует в ValidationError)
+ * - behavior-applicator.ts (логирует и пробрасывает)
+ * - validation-applicator.ts (логирует и проглатывает)
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await validator(value);
+ * } catch (error) {
+ *   return FormErrorHandler.handle(error, 'AsyncValidator', ErrorStrategy.CONVERT);
+ * }
+ * ```
+ */
+import type { ValidationError } from '../types';
+/**
+ * Стратегия обработки ошибок
+ *
+ * Определяет, что делать с ошибкой после логирования
+ */
+export declare enum ErrorStrategy {
+    /**
+     * Пробросить ошибку дальше (throw)
+     * Используется когда ошибка критична и должна остановить выполнение
+     */
+    THROW = "throw",
+    /**
+     * Залогировать и проглотить ошибку (продолжить выполнение)
+     * Используется когда ошибка не критична
+     */
+    LOG = "log",
+    /**
+     * Конвертировать ошибку в ValidationError
+     * Используется в async validators для отображения ошибки валидации пользователю
+     */
+    CONVERT = "convert"
+}
+/**
+ * Централизованный обработчик ошибок для форм
+ *
+ * Обеспечивает:
+ * - Единообразное логирование ошибок в DEV режиме
+ * - Гибкие стратегии обработки (throw/log/convert)
+ * - Типобезопасное извлечение сообщений из Error/string/unknown
+ *
+ * @example
+ * ```typescript
+ * // В async validator (конвертировать в ValidationError)
+ * try {
+ *   await validateEmail(value);
+ * } catch (error) {
+ *   return FormErrorHandler.handle(error, 'EmailValidator', ErrorStrategy.CONVERT);
+ * }
+ *
+ * // В behavior applicator (пробросить критичную ошибку)
+ * try {
+ *   applyBehavior(schema);
+ * } catch (error) {
+ *   FormErrorHandler.handle(error, 'BehaviorApplicator', ErrorStrategy.THROW);
+ * }
+ *
+ * // В validator (залогировать и продолжить)
+ * try {
+ *   validator(value);
+ * } catch (error) {
+ *   FormErrorHandler.handle(error, 'Validator', ErrorStrategy.LOG);
+ * }
+ * ```
+ */
+export declare class FormErrorHandler {
+    /**
+     * Обработать ошибку согласно заданной стратегии
+     *
+     * @param error Ошибка для обработки (Error | string | unknown)
+     * @param context Контекст ошибки для логирования (например, 'AsyncValidator', 'BehaviorRegistry')
+     * @param strategy Стратегия обработки (THROW | LOG | CONVERT)
+     * @returns ValidationError если strategy = CONVERT, undefined если strategy = LOG, никогда не возвращается если strategy = THROW
+     *
+     * @example
+     * ```typescript
+     * // THROW - пробросить ошибку
+     * try {
+     *   riskyOperation();
+     * } catch (error) {
+     *   FormErrorHandler.handle(error, 'RiskyOperation', ErrorStrategy.THROW);
+     *   // Этот код никогда не выполнится
+     * }
+     *
+     * // LOG - залогировать и продолжить
+     * try {
+     *   nonCriticalOperation();
+     * } catch (error) {
+     *   FormErrorHandler.handle(error, 'NonCritical', ErrorStrategy.LOG);
+     *   // Продолжаем выполнение
+     * }
+     *
+     * // CONVERT - конвертировать в ValidationError
+     * try {
+     *   await validator(value);
+     * } catch (error) {
+     *   const validationError = FormErrorHandler.handle(
+     *     error,
+     *     'AsyncValidator',
+     *     ErrorStrategy.CONVERT
+     *   );
+     *   return validationError;
+     * }
+     * ```
+     */
+    static handle(error: unknown, context: string, strategy?: ErrorStrategy): ValidationError | never | void;
+    /**
+     * Извлечь сообщение из ошибки
+     *
+     * Обрабатывает различные типы ошибок:
+     * - Error объекты → error.message
+     * - Строки → возвращает как есть
+     * - Объекты с message → извлекает message
+     * - Другое → String(error)
+     *
+     * @param error Ошибка для извлечения сообщения
+     * @returns Сообщение ошибки
+     * @private
+     *
+     * @example
+     * ```typescript
+     * FormErrorHandler.extractMessage(new Error('Test'));
+     * // 'Test'
+     *
+     * FormErrorHandler.extractMessage('String error');
+     * // 'String error'
+     *
+     * FormErrorHandler.extractMessage({ message: 'Object error' });
+     * // 'Object error'
+     *
+     * FormErrorHandler.extractMessage(null);
+     * // 'null'
+     * ```
+     */
+    private static extractMessage;
+    /**
+     * Создать ValidationError с заданными параметрами
+     *
+     * Утилитная функция для создания ValidationError объектов
+     *
+     * @param code Код ошибки
+     * @param message Сообщение ошибки
+     * @param field Поле (опционально)
+     * @returns ValidationError объект
+     *
+     * @example
+     * ```typescript
+     * const error = FormErrorHandler.createValidationError(
+     *   'required',
+     *   'This field is required',
+     *   'email'
+     * );
+     * // { code: 'required', message: 'This field is required', field: 'email' }
+     * ```
+     */
+    static createValidationError(code: string, message: string, field?: string): ValidationError;
+    /**
+     * Проверить, является ли объект ValidationError
+     *
+     * Type guard для ValidationError
+     *
+     * @param value Значение для проверки
+     * @returns true если value является ValidationError
+     *
+     * @example
+     * ```typescript
+     * if (FormErrorHandler.isValidationError(result)) {
+     *   console.log(result.code); // OK, типобезопасно
+     * }
+     * ```
+     */
+    static isValidationError(value: unknown): value is ValidationError;
+}