@reformer/core 2.0.1 → 4.0.0

package/dist/core/types/{group-node-proxy.d.ts → form-proxy.d.ts}

@@ -1,34 +1,4 @@
-/**
- * Типы для Proxy-доступа к полям GroupNode
- *
- * Решает проблему типизации, когда GroupNode<T> использует Proxy для прямого доступа к полям.
- * TypeScript не может автоматически определить правильные типы для вложенных форм и массивов.
- *
- * @group Types
- *
- * @example
- * ```typescript
- * interface MyForm {
- *   name: string;
- *   address: {
- *     city: string;
- *   };
- *   items: Array<{ title: string }>;
- * }
- *
- * const form: GroupNodeWithControls<MyForm> = new GroupNode(schema);
- *
- * //  TypeScript знает, что это FieldNode<string>
- * form.name.setValue('John');
- *
- * //  TypeScript знает, что это GroupNode<{city: string}>
- * form.address.city.setValue('Moscow');
- *
- * //  TypeScript знает, что это ArrayNode<{title: string}>
- * form.items.push({ title: 'New Item' });
- * ```
- */
-import type { FormFields } from './index';
+import { FormFields } from './index';
 type FieldNode<_T> = any;
 type GroupNode<_T> = any;
 type ArrayNode<_T> = any;
@@ -36,9 +6,9 @@ type ArrayNode<_T> = any;
  * Мапит тип модели данных T на правильные типы узлов формы
  *
  * Рекурсивно определяет типы узлов на основе структуры данных:
- * - `T[K] extends Array<infer U>` где U - объект → `ArrayNodeWithControls<U>`
+ * - `T[K] extends Array<infer U>` где U - объект → `FormArrayProxy<U>`
  * - `T[K] extends Array<infer U>` где U - примитив → `FieldNode<T[K]>` (массив как обычное поле)
- * - `T[K] extends object` → `GroupNodeWithControls<T[K]>` (вложенная форма с типизацией)
+ * - `T[K] extends object` → `FormProxy<T[K]>` (вложенная форма с типизацией)
  * - `T[K]` примитив → `FieldNode<T[K]>` (простое поле)
  *
  * Использует NonNullable для правильной обработки опциональных полей
@@ -48,8 +18,8 @@ type ArrayNode<_T> = any;
  *
  * @template T - Тип модели данных формы
  */
-export type FormNodeControls<T> = {
-    [K in keyof T]: NonNullable<T[K]> extends Array<infer U> ? U extends FormFields ? ArrayNodeWithControls<U> : FieldNode<T[K]> : NonNullable<T[K]> extends FormFields ? NonNullable<T[K]> extends Date | File | Blob ? FieldNode<T[K]> : GroupNodeWithControls<NonNullable<T[K]>> : FieldNode<T[K]>;
+export type FormControlsProxy<T> = {
+    [K in keyof T]: NonNullable<T[K]> extends Array<infer U> ? U extends FormFields ? FormArrayProxy<U> : FieldNode<T[K]> : NonNullable<T[K]> extends FormFields ? NonNullable<T[K]> extends Date | File | Blob ? FieldNode<T[K]> : FormProxy<NonNullable<T[K]>> : FieldNode<T[K]>;
 };
 /**
  * Комбинированный тип для GroupNode с Proxy доступом к полям
@@ -72,7 +42,7 @@ export type FormNodeControls<T> = {
  *   };
  * }
  *
- * const form: GroupNodeWithControls<UserForm> = new GroupNode(schema);
+ * const form = createForm<UserForm>(schema);
  *
  * // Доступ к методам GroupNode
  * await form.validate();
@@ -84,7 +54,7 @@ export type FormNodeControls<T> = {
  * form.profile.name.setValue('John');
  * ```
  */
-export type GroupNodeWithControls<T> = GroupNode<T> & FormNodeControls<T>;
+export type FormProxy<T> = GroupNode<T> & FormControlsProxy<T>;
 /**
  * Комбинированный тип для ArrayNode с Proxy доступом к элементам
  *
@@ -102,7 +72,7 @@ export type GroupNodeWithControls<T> = GroupNode<T> & FormNodeControls<T>;
  *   completed: boolean;
  * }
  *
- * const todos: ArrayNodeWithControls<TodoItem> = new ArrayNode(schema);
+ * const todos: FormArrayProxy<TodoItem> = new ArrayNode(schema);
  *
  * // Доступ к методам ArrayNode
  * todos.push({ title: 'New todo', completed: false });
@@ -117,19 +87,19 @@ export type GroupNodeWithControls<T> = GroupNode<T> & FormNodeControls<T>;
  * });
  * ```
  */
-export type ArrayNodeWithControls<T extends FormFields> = ArrayNode<T> & {
+export type FormArrayProxy<T extends FormFields> = ArrayNode<T> & {
     /**
      * Безопасный доступ к элементу массива по индексу
      * Возвращает GroupNode с типизированными полями или undefined
      */
-    at(index: number): GroupNodeWithControls<T> | undefined;
+    at(index: number): FormProxy<T> | undefined;
     /**
      * Итерация по элементам массива с типизированными элементами
      */
-    forEach(callback: (item: GroupNodeWithControls<T>, index: number) => void): void;
+    forEach(callback: (item: FormProxy<T>, index: number) => void): void;
     /**
      * Маппинг элементов массива с типизированными элементами
      */
-    map<R>(callback: (item: GroupNodeWithControls<T>, index: number) => R): R[];
+    map<R>(callback: (item: FormProxy<T>, index: number) => R): R[];
 };
 export {};

package/dist/core/types/index.d.ts

@@ -1,3 +1,7 @@
+import { BehaviorSchemaFn } from '../behavior/types';
+import { FormSchema } from './deep-schema';
+import { ValidationSchemaFn } from './validation-schema';
+import { FormNode } from '../nodes/form-node';
 /**
  * Represents any valid form value type
  * Use this instead of 'any' for form values to maintain type safety
@@ -20,12 +24,46 @@ export type UnknownFormValue = unknown;
  * @category Validation Types
  */
 export type ValidatorFn<T = FormValue> = (value: T) => ValidationError | null;
+/**
+ * Опции для асинхронного валидатора
+ * @group Types
+ * @category Validation Types
+ */
+export interface AsyncValidatorOptions {
+    /**
+     * AbortSignal для отмены валидации
+     * Позволяет отменить асинхронную операцию при новой валидации
+     */
+    signal?: AbortSignal;
+}
 /**
  * Асинхронная функция валидации
+ *
+ * @param value - Значение для валидации
+ * @param options - Опции валидации (опционально)
+ * @returns Promise с ошибкой валидации или null если значение валидно
+ *
+ * @example
+ * ```typescript
+ * // Простой валидатор (без поддержки отмены)
+ * const emailExists: AsyncValidatorFn<string> = async (value) => {
+ *   const exists = await checkEmail(value);
+ *   return exists ? { code: 'exists', message: 'Email already exists' } : null;
+ * };
+ *
+ * // Валидатор с поддержкой отмены
+ * const emailExistsAbortable: AsyncValidatorFn<string> = async (value, options) => {
+ *   const exists = await fetch(`/api/check-email?email=${value}`, {
+ *     signal: options?.signal // Передаём signal в fetch для отмены запроса
+ *   });
+ *   return exists ? { code: 'exists', message: 'Email already exists' } : null;
+ * };
+ * ```
+ *
  * @group Types
  * @category Validation Types
  */
-export type AsyncValidatorFn<T = FormValue> = (value: T) => Promise<ValidationError | null>;
+export type AsyncValidatorFn<T = FormValue> = (value: T, options?: AsyncValidatorOptions) => Promise<ValidationError | null>;
 /**
  * Ошибка валидации
  * @group Types
@@ -64,10 +102,7 @@ export type { FieldPath, FieldPathNode } from '../types/field-path';
 export type { ContextualValidatorFn, ContextualAsyncValidatorFn, TreeValidatorFn, ConditionFn, ValidateOptions, ValidateAsyncOptions, ValidateTreeOptions, ValidationSchemaFn, ValidatorRegistration, } from './validation-schema';
 export type { FormSchema, ArrayConfig } from './deep-schema';
 export type { FormContext } from './form-context';
-export type { FormNodeControls, GroupNodeWithControls, ArrayNodeWithControls, } from './group-node-proxy';
-import type { BehaviorSchemaFn } from '../behavior/types';
-import type { FormSchema } from './deep-schema';
-import type { ValidationSchemaFn } from './validation-schema';
+export type { FormControlsProxy, FormProxy, FormArrayProxy } from './form-proxy';
 /**
  * Конфигурация GroupNode с поддержкой схем
  * Используется для создания форм с автоматическим применением behavior и validation схем
@@ -82,6 +117,18 @@ export interface GroupNodeConfig<T> {
     behavior?: BehaviorSchemaFn<T>;
     /** Схема валидации (required, email, minLength и т.д.) */
     validation?: ValidationSchemaFn<T>;
+    /**
+     * Опциональный ValidationRegistry для dependency injection
+     * Используется для тестирования с mock-реестрами
+     * @internal
+     */
+    _validationRegistry?: unknown;
+    /**
+     * Опциональный BehaviorRegistry для dependency injection
+     * Используется для тестирования с mock-реестрами
+     * @internal
+     */
+    _behaviorRegistry?: unknown;
 }
 /**
  * Тип для Record с unknown значениями
@@ -112,7 +159,6 @@ export interface ArrayNodeLike {
     at(index: number): FormNode<unknown> | undefined;
     length: unknown;
 }
-import type { FormNode } from '../nodes/form-node';
 /**
  * Конфиг с полем schema (для ArrayConfig)
  * @internal

package/dist/core/types/validation-schema.d.ts

@@ -1,15 +1,6 @@
-/**
- * Типы для validation schema паттерна
- *
- * Основано на Angular Signal Forms подходе:
- * - Валидация определяется отдельно от схемы полей
- * - Поддержка условной валидации (applyWhen)
- * - Cross-field валидация (validateTree)
- * - Асинхронная валидация с контекстом
- */
-import type { FormFields, ValidationError } from './index';
-import type { FieldPath } from './field-path';
-import type { FormContext } from './form-context';
+import { FormFields, ValidationError } from './index';
+import { FieldPath } from './field-path';
+import { FormContext } from './form-context';
 /**
  * Функция валидации поля с контекстом
  *

package/dist/core/utils/abstract-registry.d.ts

@@ -0,0 +1,74 @@
+import { RegistryStack } from './registry-stack';
+/**
+ * Базовый класс для реестров (BehaviorRegistry, ValidationRegistry).
+ *
+ * Реализует паттерн Template Method для управления регистрацией:
+ * `beginRegistration()` → `onBeginRegistration()`, `endRegistration()` → `onEndRegistration()`.
+ *
+ * @typeParam TRegistration - Тип регистрируемых элементов.
+ *
+ * @example
+ * ```typescript
+ * import { AbstractRegistry } from '@reformer/core';
+ *
+ * class MyRegistry extends AbstractRegistry<{ name: string }> {
+ *   protected onEndRegistration(items: { name: string }[]) {
+ *     console.log('Registered', items.length);
+ *   }
+ * }
+ * ```
+ */
+export declare abstract class AbstractRegistry<TRegistration> {
+    /** Флаг активной регистрации */
+    protected isRegistering: boolean;
+    /** Массив зарегистрированных элементов */
+    protected registrations: TRegistration[];
+    /**
+     * Получить стек для конкретного класса реестра
+     * Создает новый стек если не существует
+     *
+     * @param ctor - Конструктор класса реестра
+     * @returns RegistryStack для данного класса
+     */
+    protected static getStack<T extends AbstractRegistry<any>>(ctor: new (...args: any[]) => T): RegistryStack<T>;
+    /**
+     * Получить текущий активный реестр из стека
+     * Должен быть переопределен в наследниках как static метод
+     *
+     * @param ctor - Конструктор класса реестра
+     * @returns Текущий активный реестр или null
+     */
+    protected static getCurrentFromStack<T extends AbstractRegistry<any>>(ctor: new (...args: any[]) => T): T | null;
+    /**
+     * Начать регистрацию
+     *
+     * Помещает this в global stack для изоляции форм
+     * Вызывает hook onBeginRegistration()
+     */
+    beginRegistration(): void;
+    /**
+     * Проверить, активна ли регистрация
+     */
+    isActive(): boolean;
+    /**
+     * Получить зарегистрированные элементы
+     */
+    getRegistrations(): TRegistration[];
+    /**
+     * Hook: вызывается в начале регистрации
+     * Может быть переопределен в наследниках для инициализации
+     */
+    protected onBeginRegistration(): void;
+    /**
+     * Завершить регистрацию и извлечь из стека
+     *
+     * @param registryName - Имя реестра для отладки
+     */
+    protected completeRegistration(registryName: string): void;
+    /**
+     * Отменить регистрацию без применения
+     *
+     * @param registryName - Имя реестра для отладки
+     */
+    cancelRegistration(registryName: string): void;
+}

package/dist/core/utils/aggregate-signals.d.ts

@@ -0,0 +1,71 @@
+import { ReadonlySignal, Signal } from '@preact/signals-core';
+import { FieldStatus, ValidationError } from '../types';
+import { FormNode } from '../nodes/form-node';
+/**
+ * Функция получения дочерних узлов
+ * Возвращает массив FormNode для агрегации состояния
+ */
+type GetChildrenFn<T> = () => FormNode<T>[];
+/**
+ * Результат создания агрегированных сигналов
+ */
+export interface AggregateSignals {
+    /** Все дочерние узлы валидны и нет собственных ошибок */
+    valid: ReadonlySignal<boolean>;
+    /** Есть ошибки (инверсия valid) */
+    invalid: ReadonlySignal<boolean>;
+    /** Хотя бы один дочерний узел в состоянии pending */
+    pending: ReadonlySignal<boolean>;
+    /** Хотя бы один дочерний узел touched */
+    touched: ReadonlySignal<boolean>;
+    /** Хотя бы один дочерний узел dirty */
+    dirty: ReadonlySignal<boolean>;
+    /** Собственные ошибки + ошибки всех дочерних узлов */
+    errors: ReadonlySignal<ValidationError[]>;
+    /** Статус: disabled > pending > invalid > valid */
+    status: ReadonlySignal<FieldStatus>;
+}
+/**
+ * Опции для создания агрегированных сигналов
+ */
+export interface AggregateSignalsOptions<T> {
+    /** Функция получения дочерних узлов */
+    getChildren: GetChildrenFn<T>;
+    /** Signal с собственными ошибками контейнера (form-level или array-level) */
+    ownErrors: Signal<ValidationError[]>;
+    /** Опциональный signal disabled состояния (для GroupNode) */
+    disabled?: Signal<boolean>;
+}
+/**
+ * Создать агрегированные computed signals для контейнерного узла
+ *
+ * Используется в GroupNode и ArrayNode для унификации логики
+ * вычисления состояния на основе дочерних узлов.
+ *
+ * @param options - Опции конфигурации
+ * @returns Объект с computed signals
+ *
+ * @example GroupNode
+ * ```typescript
+ * const signals = createAggregateSignals({
+ *   getChildren: () => Array.from(this._fields.values()),
+ *   ownErrors: this._formErrors,
+ *   disabled: this._disabled,
+ * });
+ * this.valid = signals.valid;
+ * this.invalid = signals.invalid;
+ * // ...
+ * ```
+ *
+ * @example ArrayNode
+ * ```typescript
+ * const signals = createAggregateSignals({
+ *   getChildren: () => this.items.value,
+ *   ownErrors: this._arrayErrors,
+ * });
+ * this.valid = signals.valid;
+ * // ...
+ * ```
+ */
+export declare function createAggregateSignals<T>(options: AggregateSignalsOptions<T>): AggregateSignals;
+export {};

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

@@ -1,21 +1,4 @@
-/**
- * Фабричная функция для создания формы с правильной типизацией
- *
- * Решает проблему с типизацией конструктора 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';
+import { FormProxy, GroupNodeConfig, FormSchema } from '../types';
 /**
  * Создать форму с полной конфигурацией (form, behavior, validation)
  *
@@ -43,7 +26,7 @@ import type { GroupNodeWithControls, GroupNodeConfig, FormSchema } from '../type
  * form.email.setValue('test@mail.com');
  * ```
  */
-export declare function createForm<T>(config: GroupNodeConfig<T>): GroupNodeWithControls<T>;
+export declare function createForm<T>(config: GroupNodeConfig<T>): FormProxy<T>;
 /**
  * Создать форму только со схемой полей (обратная совместимость)
  *
@@ -58,4 +41,4 @@ export declare function createForm<T>(config: GroupNodeConfig<T>): GroupNodeWith
  * });
  * ```
  */
-export declare function createForm<T>(schema: FormSchema<T>): GroupNodeWithControls<T>;
+export declare function createForm<T>(schema: FormSchema<T>): FormProxy<T>;

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

@@ -1,21 +1,4 @@
-/**
- * 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';
+import { ValidationError } from '../types';
 /**
  * Стратегия обработки ошибок
  *

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

@@ -1,4 +1,4 @@
-import type { UnknownRecord } from '../types';
+import { UnknownRecord } from '../types';
 /**
  * Сегмент пути к полю формы
  *

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

@@ -1,12 +1,4 @@
-/**
- * FieldPath proxy - типобезопасный доступ к путям полей формы
- *
- * Единый модуль для validation и behavior схем.
- * Предоставляет типизированную навигацию по структуре формы.
- *
- * @module utils/field-path
- */
-import type { FieldPath, FieldPathNode } from '../types';
+import { FieldPath, FieldPathNode } from '../types';
 /**
  * Создать FieldPath proxy для формы
  *
@@ -19,7 +11,17 @@ import type { FieldPath, FieldPathNode } from '../types';
  */
 export declare function createFieldPath<T>(): FieldPath<T>;
 /**
- * Извлечь путь из FieldPathNode
+ * Извлечь строковый путь из {@link FieldPathNode}.
+ *
+ * @param node - Узел `FieldPathNode` либо строка-путь.
+ * @returns Путь вида `"a.b.c"`.
+ *
+ * @example
+ * ```typescript
+ * import { extractPath } from '@reformer/core';
+ *
+ * const path = (renderPath) => extractPath(renderPath.user.email); // → 'user.email'
+ * ```
  */
 export declare function extractPath(node: FieldPathNode<unknown, unknown> | unknown): string;
 /**
@@ -43,6 +45,16 @@ export declare function extractPath(node: FieldPathNode<unknown, unknown> | unkn
  */
 export declare function toFieldPath<T>(node: FieldPathNode<unknown, T, never> | FieldPathNode<any, T, any>): FieldPath<T>;
 /**
- * Извлечь ключ поля из FieldPathNode
+ * Извлечь имя последнего сегмента ({@link FieldPathSegment}) пути.
+ *
+ * @param node - Узел `FieldPathNode` либо строка-путь.
+ * @returns Имя поля без префикса родителя (последний сегмент).
+ *
+ * @example
+ * ```typescript
+ * import { extractKey } from '@reformer/core';
+ *
+ * extractKey(path.user.email); // → 'email'
+ * ```
  */
 export declare function extractKey(node: FieldPathNode<unknown, unknown> | unknown): string;

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

@@ -0,0 +1,176 @@
+import { FormFields, FormValue, FieldStatus, ValidationError } from '../types';
+/**
+ * Тип события изменения в форме
+ */
+export type FormChangeType = 'value' | 'status' | 'errors' | 'touched' | 'dirty';
+/**
+ * Событие изменения в форме
+ */
+export interface FormChangeEvent {
+    /** Тип изменения */
+    type: FormChangeType;
+    /** Путь к полю */
+    path: string;
+    /** Timestamp события */
+    timestamp: number;
+    /** Старое значение */
+    oldValue?: unknown;
+    /** Новое значение */
+    newValue: unknown;
+}
+/**
+ * Интерфейс узла формы для observer
+ */
+export interface ObservableFormNode {
+    value: {
+        value: FormValue;
+    };
+    status: {
+        value: FieldStatus;
+    };
+    errors: {
+        value: ValidationError[];
+    };
+    touched: {
+        value: boolean;
+    };
+    dirty: {
+        value: boolean;
+    };
+}
+/**
+ * Интерфейс формы для observer
+ */
+export interface ObservableForm<T extends FormFields> {
+    value: {
+        value: T;
+    };
+    status: {
+        value: FieldStatus;
+    };
+    errors: {
+        value: ValidationError[];
+    };
+    touched: {
+        value: boolean;
+    };
+    dirty: {
+        value: boolean;
+    };
+    getFieldByPath(path: string): ObservableFormNode | undefined;
+}
+/**
+ * Callback для обработки событий изменения
+ */
+export type FormChangeCallback = (event: FormChangeEvent) => void;
+/**
+ * Опции для FormObserver
+ */
+export interface FormObserverOptions {
+    /** Включить логирование в консоль (по умолчанию true в DEV) */
+    enableLogging?: boolean;
+    /** Фильтр типов событий */
+    eventTypes?: FormChangeType[];
+    /** Фильтр путей полей (regex или массив) */
+    pathFilter?: RegExp | string[];
+}
+/**
+ * FormObserver - мониторинг изменений в форме
+ *
+ * Полезен для:
+ * - Отладки сложных форм
+ * - Логирования изменений для аудита
+ * - Синхронизации с внешними системами
+ *
+ * @example
+ * ```typescript
+ * const observer = new FormObserver(form, {
+ *   enableLogging: true,
+ *   eventTypes: ['value', 'errors']
+ * });
+ *
+ * // Подписка на события
+ * const unsubscribe = observer.subscribe((event) => {
+ *   console.log(`${event.type} at ${event.path}:`, event.newValue);
+ * });
+ *
+ * // Включить трассировку
+ * const disposeTracing = observer.enableTracing();
+ *
+ * // Cleanup
+ * unsubscribe();
+ * disposeTracing();
+ * ```
+ */
+export declare class FormObserver<T extends FormFields> {
+    private readonly form;
+    private listeners;
+    private disposers;
+    private options;
+    /**
+     * @param form - Форма для наблюдения
+     * @param options - Опции observer
+     */
+    constructor(form: ObservableForm<T>, options?: FormObserverOptions);
+    /**
+     * Подписаться на события изменения
+     *
+     * @param callback - Функция обработки события
+     * @returns Функция отписки
+     *
+     * @example
+     * ```typescript
+     * const unsubscribe = observer.subscribe((event) => {
+     *   // Отправить событие в analytics
+     *   analytics.track('form_change', event);
+     * });
+     * ```
+     */
+    subscribe(callback: FormChangeCallback): () => void;
+    /**
+     * Включить трассировку формы
+     *
+     * Подписывается на изменения основных сигналов формы
+     * и вызывает listeners при каждом изменении
+     *
+     * @returns Функция для отключения трассировки
+     *
+     * @example
+     * ```typescript
+     * const dispose = observer.enableTracing();
+     *
+     * // Позже, для отключения
+     * dispose();
+     * ```
+     */
+    enableTracing(): () => void;
+    /**
+     * Наблюдать за конкретным полем
+     *
+     * @param path - Путь к полю
+     * @returns Функция для отключения наблюдения
+     *
+     * @example
+     * ```typescript
+     * // Наблюдать за полем email
+     * const dispose = observer.watchField('email');
+     * ```
+     */
+    watchField(path: string): () => void;
+    /**
+     * Отправить событие всем listeners
+     */
+    private emit;
+    /**
+     * Проверить, нужно ли отслеживать тип события
+     */
+    private shouldTrack;
+    /**
+     * Проверить, соответствует ли путь фильтру
+     */
+    private matchesPathFilter;
+    /**
+     * Очистить все подписки и disposers
+     */
+    dispose(): void;
+}