@reformer/core 1.0.0-beta.3

package/dist/core/utils/error-handler.js

@@ -0,0 +1,226 @@
+/**
+ * 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);
+ * }
+ * ```
+ */
+/**
+ * Стратегия обработки ошибок
+ *
+ * Определяет, что делать с ошибкой после логирования
+ */
+export var ErrorStrategy;
+(function (ErrorStrategy) {
+    /**
+     * Пробросить ошибку дальше (throw)
+     * Используется когда ошибка критична и должна остановить выполнение
+     */
+    ErrorStrategy["THROW"] = "throw";
+    /**
+     * Залогировать и проглотить ошибку (продолжить выполнение)
+     * Используется когда ошибка не критична
+     */
+    ErrorStrategy["LOG"] = "log";
+    /**
+     * Конвертировать ошибку в ValidationError
+     * Используется в async validators для отображения ошибки валидации пользователю
+     */
+    ErrorStrategy["CONVERT"] = "convert";
+})(ErrorStrategy || (ErrorStrategy = {}));
+/**
+ * Централизованный обработчик ошибок для форм
+ *
+ * Обеспечивает:
+ * - Единообразное логирование ошибок в 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 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, context, strategy = ErrorStrategy.THROW) {
+        // Извлекаем сообщение из ошибки
+        const message = this.extractMessage(error);
+        // Логируем в DEV режиме
+        if (import.meta.env.DEV) {
+            console.error(`[${context}]`, error);
+        }
+        // Применяем стратегию
+        switch (strategy) {
+            case ErrorStrategy.THROW:
+                throw error;
+            case ErrorStrategy.LOG:
+                // Просто логируем, не возвращаем ничего
+                return;
+            case ErrorStrategy.CONVERT:
+                // Конвертируем в ValidationError
+                return {
+                    code: 'validator_error',
+                    message,
+                    params: { field: context },
+                };
+        }
+    }
+    /**
+     * Извлечь сообщение из ошибки
+     *
+     * Обрабатывает различные типы ошибок:
+     * - 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'
+     * ```
+     */
+    static extractMessage(error) {
+        if (error instanceof Error) {
+            return error.message;
+        }
+        if (typeof error === 'string') {
+            return error;
+        }
+        if (typeof error === 'object' && error !== null && 'message' in error) {
+            return String(error.message);
+        }
+        return String(error);
+    }
+    /**
+     * Создать 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, message, field) {
+        return {
+            code,
+            message,
+            params: field ? { field } : undefined,
+        };
+    }
+    /**
+     * Проверить, является ли объект ValidationError
+     *
+     * Type guard для ValidationError
+     *
+     * @param value Значение для проверки
+     * @returns true если value является ValidationError
+     *
+     * @example
+     * ```typescript
+     * if (FormErrorHandler.isValidationError(result)) {
+     *   console.log(result.code); // OK, типобезопасно
+     * }
+     * ```
+     */
+    static isValidationError(value) {
+        return (typeof value === 'object' &&
+            value !== null &&
+            'code' in value &&
+            'message' in value &&
+            typeof value.code === 'string' &&
+            typeof value.message === 'string');
+    }
+}

package/dist/core/utils/field-path-navigator.d.ts

@@ -0,0 +1,240 @@
+import type { UnknownRecord } from '../types';
+/**
+ * Сегмент пути к полю формы
+ *
+ * Представляет один сегмент в пути к полю, например:
+ * - `"email" → { key: 'email' }`
+ * - `"items[0]" → { key: 'items', index: 0 }`
+ *
+ * @internal
+ *
+ * @example
+ * ```typescript
+ * // Путь "items[0].name" разбивается на:
+ * [
+ *   { key: 'items', index: 0 },
+ *   { key: 'name' }
+ * ]
+ * ```
+ */
+export interface PathSegment {
+    /**
+     * Ключ поля
+     */
+    key: string;
+    /**
+     * Индекс в массиве (опционально)
+     * Присутствует только для сегментов вида "items[0]"
+     */
+    index?: number;
+}
+/**
+ * Навигация по путям к полям формы
+ *
+ * Централизует логику парсинга и навигации по путям к полям формы.
+ * Используется в ValidationContext, BehaviorContext, GroupNode для единообразной
+ * обработки путей вида "address.city" или "items[0].name".
+ *
+ * Устраняет дублирование логики парсинга путей в 4 местах кодовой базы.
+ *
+ * @internal
+ *
+ * @example
+ * ```typescript
+ * const navigator = new FieldPathNavigator();
+ *
+ * // Парсинг пути
+ * const segments = navigator.parsePath('items[0].title');
+ * // [{ key: 'items', index: 0 }, { key: 'title' }]
+ *
+ * // Получение значения из объекта
+ * const obj = { items: [{ title: 'Item 1' }] };
+ * const value = navigator.getValueByPath(obj, 'items[0].title');
+ * // 'Item 1'
+ *
+ * // Получение узла формы
+ * const titleNode = navigator.getNodeByPath(form, 'items[0].title');
+ * titleNode?.setValue('New Title');
+ * ```
+ */
+export declare class FieldPathNavigator {
+    /**
+     * Парсит путь в массив сегментов
+     *
+     * Поддерживаемые форматы:
+     * - Простые пути: "name", "email"
+     * - Вложенные пути: "address.city", "user.profile.avatar"
+     * - Массивы: "items[0]", "items[0].name", "tags[1][0]"
+     * - Комбинации: "orders[0].items[1].price"
+     *
+     * @param path Путь к полю (строка с точками и квадратными скобками)
+     * @returns Массив сегментов пути
+     *
+     * @example
+     * ```typescript
+     * navigator.parsePath('email');
+     * // [{ key: 'email' }]
+     *
+     * navigator.parsePath('address.city');
+     * // [{ key: 'address' }, { key: 'city' }]
+     *
+     * navigator.parsePath('items[0].name');
+     * // [{ key: 'items', index: 0 }, { key: 'name' }]
+     * ```
+     */
+    parsePath(path: string): PathSegment[];
+    /**
+     * Добавляет сегмент в массив, обрабатывая массивы
+     * @private
+     */
+    private addSegment;
+    /**
+     * Получает значение по пути из объекта
+     *
+     * Проходит по всем сегментам пути и возвращает конечное значение.
+     * Если путь не найден, возвращает undefined.
+     *
+     * @param obj Объект для навигации
+     * @param path Путь к значению
+     * @returns Значение или undefined, если путь не найден
+     *
+     * @example
+     * ```typescript
+     * const obj = {
+     *   email: 'test@mail.com',
+     *   address: { city: 'Moscow' },
+     *   items: [{ title: 'Item 1' }]
+     * };
+     *
+     * navigator.getValueByPath(obj, 'email');
+     * // 'test@mail.com'
+     *
+     * navigator.getValueByPath(obj, 'address.city');
+     * // 'Moscow'
+     *
+     * navigator.getValueByPath(obj, 'items[0].title');
+     * // 'Item 1'
+     *
+     * navigator.getValueByPath(obj, 'invalid.path');
+     * // undefined
+     * ```
+     */
+    getValueByPath(obj: UnknownRecord, path: string): unknown;
+    /**
+     * Устанавливает значение по пути в объекте (мутирует объект)
+     *
+     * Создает промежуточные объекты, если они не существуют.
+     * Выбрасывает ошибку, если ожидается массив, но его нет.
+     *
+     * @param obj Объект для модификации
+     * @param path Путь к значению
+     * @param value Новое значение
+     *
+     * @throws {Error} Если ожидается массив по пути, но его нет
+     *
+     * @example
+     * ```typescript
+     * const obj = { address: { city: '' } };
+     * navigator.setValueByPath(obj, 'address.city', 'Moscow');
+     * // obj.address.city === 'Moscow'
+     *
+     * const obj2: UnknownRecord = {};
+     * navigator.setValueByPath(obj2, 'address.city', 'Moscow');
+     * // Создаст { address: { city: 'Moscow' } }
+     *
+     * const obj3 = { items: [{ title: 'Old' }] };
+     * navigator.setValueByPath(obj3, 'items[0].title', 'New');
+     * // obj3.items[0].title === 'New'
+     * ```
+     */
+    setValueByPath(obj: UnknownRecord, path: string, value: unknown): void;
+    /**
+     * Получить значение из FormNode по пути
+     *
+     * Автоматически извлекает значение из FormNode (через .value.value).
+     * Используется в ValidationContext и BehaviorContext для единообразного
+     * доступа к значениям полей формы.
+     *
+     * @param form Корневой узел формы (обычно GroupNode)
+     * @param path Путь к полю
+     * @returns Значение поля или undefined, если путь не найден
+     *
+     * @example
+     * ```typescript
+     * const form = new GroupNode({
+     *   email: { value: 'test@mail.com', component: Input },
+     *   address: {
+     *     city: { value: 'Moscow', component: Input }
+     *   },
+     *   items: [{ title: { value: 'Item 1', component: Input } }]
+     * });
+     *
+     * navigator.getFormNodeValue(form, 'email');
+     * // 'test@mail.com'
+     *
+     * navigator.getFormNodeValue(form, 'address.city');
+     * // 'Moscow'
+     *
+     * navigator.getFormNodeValue(form, 'items[0].title');
+     * // 'Item 1'
+     *
+     * navigator.getFormNodeValue(form, 'invalid.path');
+     * // undefined
+     * ```
+     */
+    getFormNodeValue(form: unknown, path: string): unknown;
+    /**
+     * Type guard для проверки, является ли объект FormNode
+     *
+     * Проверяет наличие характерных свойств FormNode:
+     * - value (Signal)
+     * - value.value (значение Signal)
+     *
+     * @param obj Объект для проверки
+     * @returns true, если объект является FormNode
+     * @private
+     */
+    private isFormNode;
+    /**
+     * Получает узел формы по пути
+     *
+     * Навигирует по структуре FormNode (GroupNode/FieldNode/ArrayNode)
+     * и возвращает узел по указанному пути.
+     *
+     * Поддерживает:
+     * - Доступ к полям GroupNode через fields Map
+     * - Доступ к элементам ArrayNode через индекс
+     * - Proxy-доступ к полям (для обратной совместимости)
+     *
+     * @param form Корневой узел формы (обычно GroupNode)
+     * @param path Путь к узлу
+     * @returns Узел формы или null, если путь не найден
+     *
+     * @example
+     * ```typescript
+     * const form = new GroupNode({
+     *   email: { value: '', component: Input },
+     *   address: {
+     *     city: { value: '', component: Input }
+     *   },
+     *   items: [{ title: { value: '', component: Input } }]
+     * });
+     *
+     * const emailNode = navigator.getNodeByPath(form, 'email');
+     * // FieldNode
+     *
+     * const cityNode = navigator.getNodeByPath(form, 'address.city');
+     * // FieldNode
+     *
+     * const itemNode = navigator.getNodeByPath(form, 'items[0]');
+     * // GroupNode
+     *
+     * const titleNode = navigator.getNodeByPath(form, 'items[0].title');
+     * // FieldNode
+     *
+     * const invalidNode = navigator.getNodeByPath(form, 'invalid.path');
+     * // null
+     * ```
+     */
+    getNodeByPath(form: unknown, path: string): unknown | null;
+}