@reformer/core 2.0.1 → 4.0.0

package/dist/core/utils/form-proxy-builder.d.ts

@@ -0,0 +1,25 @@
+import { FormNode } from '../nodes/form-node';
+import { FormProxy } from '../types/form-proxy';
+/**
+ * Создать Proxy для типобезопасного доступа к полям GroupNode
+ *
+ * Proxy обеспечивает:
+ * - Доступ к полям через точечную нотацию (form.email, form.address.city)
+ * - Приоритет собственных свойств GroupNode над полями
+ * - Цепочку proxy для вложенных GroupNode
+ * - Блокировку прямого присваивания полям (только через setValue/patchValue)
+ *
+ * @param target - GroupNode для которого создаётся proxy
+ * @param fields - Map полей формы
+ * @returns Типизированный Proxy
+ *
+ * @internal
+ *
+ * @example
+ * ```typescript
+ * const proxy = buildFormProxy(groupNode, groupNode._fields);
+ * proxy.email.setValue('test@example.com');
+ * console.log(proxy.email.value.value);
+ * ```
+ */
+export declare function buildFormProxy<T>(target: FormNode<T>, fields: Map<keyof T, FormNode<unknown>>): FormProxy<T>;

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

@@ -0,0 +1,121 @@
+import { ReadonlySignal } from '@preact/signals-core';
+import { FormFields } from '../types';
+/**
+ * Интерфейс формы для FormSubmitter
+ * Минимальный контракт для работы с любой формой
+ */
+export interface SubmittableForm<T extends FormFields> {
+    /** Пометить все поля как touched */
+    markAsTouched(): void;
+    /** Валидировать форму */
+    validate(): Promise<boolean>;
+    /** Получить значения формы */
+    getValue(): T;
+}
+/**
+ * Опции для submit
+ */
+export interface SubmitOptions {
+    /** Пропустить валидацию перед submit */
+    skipValidation?: boolean;
+    /** Пропустить markAsTouched перед submit */
+    skipTouch?: boolean;
+}
+/**
+ * Результат submit
+ */
+export interface SubmitResult<R> {
+    /** Успешно ли выполнен submit */
+    success: boolean;
+    /** Результат от onSubmit callback */
+    data: R | null;
+    /** Ошибка, если submit не удался */
+    error?: Error;
+}
+/**
+ * FormSubmitter - управляет процессом отправки формы
+ *
+ * @example
+ * ```typescript
+ * const submitter = new FormSubmitter(form);
+ *
+ * // Простой submit
+ * const result = await submitter.submit(async (values) => {
+ *   return await api.saveForm(values);
+ * });
+ *
+ * // Проверка состояния
+ * if (submitter.submitting.value) {
+ *   console.log('Форма отправляется...');
+ * }
+ * ```
+ */
+export declare class FormSubmitter<T extends FormFields> {
+    private readonly form;
+    /** Внутренний сигнал состояния отправки */
+    private readonly _submitting;
+    /** Публичный read-only сигнал состояния отправки */
+    readonly submitting: ReadonlySignal<boolean>;
+    /**
+     * @param form - Форма для отправки
+     */
+    constructor(form: SubmittableForm<T>);
+    /**
+     * Отправить форму
+     *
+     * Процесс:
+     * 1. Помечает все поля как touched (для отображения ошибок)
+     * 2. Валидирует форму
+     * 3. Если валидация успешна - вызывает onSubmit
+     * 4. Управляет состоянием submitting
+     *
+     * @param onSubmit - Callback для отправки данных
+     * @param options - Опции submit
+     * @returns Результат от onSubmit или null если валидация не пройдена
+     *
+     * @example
+     * ```typescript
+     * const result = await submitter.submit(async (values) => {
+     *   const response = await fetch('/api/form', {
+     *     method: 'POST',
+     *     body: JSON.stringify(values)
+     *   });
+     *   return response.json();
+     * });
+     *
+     * if (result === null) {
+     *   console.log('Форма не прошла валидацию');
+     * }
+     * ```
+     */
+    submit<R>(onSubmit: (values: T) => Promise<R> | R, options?: SubmitOptions): Promise<R | null>;
+    /**
+     * Отправить форму с расширенным результатом
+     *
+     * В отличие от submit(), возвращает объект с информацией об успехе/ошибке
+     *
+     * @param onSubmit - Callback для отправки данных
+     * @param options - Опции submit
+     * @returns Объект SubmitResult с данными и статусом
+     *
+     * @example
+     * ```typescript
+     * const result = await submitter.submitWithResult(async (values) => {
+     *   return await api.saveForm(values);
+     * });
+     *
+     * if (result.success) {
+     *   console.log('Сохранено:', result.data);
+     * } else if (result.error) {
+     *   console.error('Ошибка:', result.error.message);
+     * } else {
+     *   console.log('Валидация не пройдена');
+     * }
+     * ```
+     */
+    submitWithResult<R>(onSubmit: (values: T) => Promise<R> | R, options?: SubmitOptions): Promise<SubmitResult<R>>;
+    /**
+     * Проверить, идет ли отправка формы
+     */
+    isSubmitting(): boolean;
+}

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

@@ -9,7 +9,14 @@ export { SubscriptionManager } from './subscription-manager';
 export { getCurrentValidationRegistry, getCurrentBehaviorRegistry } from './registry-helpers';
 export { RegistryStack } from './registry-stack';
 export { isFormNode, isFieldNode, isGroupNode, isArrayNode, getNodeType } from './type-guards';
-export { Debouncer } from './debounce';
 export { FormErrorHandler, ErrorStrategy } from './error-handler';
 export { createForm } from './create-form';
-export * from './resources';
+export { uniqueId } from './unique-id';
+export { safeCallback, runOutsideEffect, safeDebouncedCallback } from './safe-effect';
+export { AbstractRegistry } from './abstract-registry';
+export { FormSubmitter } from './form-submitter';
+export type { SubmittableForm, SubmitOptions, SubmitResult } from './form-submitter';
+export { FormStatusMachine } from './status-machine';
+export type { StatusEvent } from './status-machine';
+export { FormObserver } from './form-observer';
+export type { FormChangeType, FormChangeEvent, FormChangeCallback, FormObserverOptions, ObservableForm, ObservableFormNode, } from './form-observer';

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

@@ -1,10 +1,3 @@
-/**
- * Вспомогательные функции для работы с реестрами
- *
- * Централизует логику получения текущего активного реестра валидации/поведения
- * из context stack, избегая дублирования кода в schema-validators.ts,
- * array-validators.ts и schema-behaviors.ts
- */
 import { ValidationRegistry } from '../validation/validation-registry';
 import { BehaviorRegistry } from '../behavior/behavior-registry';
 /**

package/dist/core/utils/safe-effect.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Утилиты для безопасной работы с сигналами в effect контексте
+ *
+ * Эти утилиты решают проблему "Cycle detected" в @preact/signals-core,
+ * которая возникает при модификации сигналов внутри effect.
+ *
+ * @group Utils
+ * @module utils/safe-effect
+ */
+/**
+ * Создает callback, который выполняется вне контекста effect
+ *
+ * Использует queueMicrotask для отложенного выполнения,
+ * что позволяет модифицировать сигналы без вызова "Cycle detected"
+ *
+ * @param callback - Функция для выполнения
+ * @returns Обёрнутая функция, безопасная для вызова внутри effect
+ *
+ * @example
+ * ```typescript
+ * // Вместо:
+ * effect(() => {
+ *   queueMicrotask(() => {
+ *     callback(value, context);
+ *   });
+ * });
+ *
+ * // Используем:
+ * effect(() => {
+ *   safeCallback(callback)(value, context);
+ * });
+ * ```
+ */
+export declare function safeCallback<TArgs extends unknown[]>(callback: (...args: TArgs) => void | Promise<void>): (...args: TArgs) => void;
+/**
+ * Выполняет функцию вне контекста effect
+ *
+ * Более простой вариант для одиночного вызова
+ *
+ * @param fn - Функция для выполнения
+ *
+ * @example
+ * ```typescript
+ * effect(() => {
+ *   const value = signal.value;
+ *   runOutsideEffect(() => {
+ *     otherSignal.value = transform(value);
+ *   });
+ * });
+ * ```
+ */
+export declare function runOutsideEffect(fn: () => void | Promise<void>): void;
+/**
+ * Создает версию callback с поддержкой debounce, безопасную для effect
+ *
+ * Комбинирует debounce логику с выходом из effect контекста
+ *
+ * @param callback - Функция для выполнения
+ * @param withDebounce - Функция debounce обёртки из BehaviorRegistry
+ * @returns Обёрнутая функция
+ *
+ * @example
+ * ```typescript
+ * return effect(() => {
+ *   const value = node.value.value;
+ *   safeDebouncedCallback(
+ *     () => callback(value, context),
+ *     withDebounce
+ *   )();
+ * });
+ * ```
+ */
+export declare function safeDebouncedCallback(callback: () => void | Promise<void>, withDebounce: (fn: () => void) => void): () => void;

package/dist/core/utils/status-machine.d.ts

@@ -0,0 +1,153 @@
+import { ReadonlySignal } from '@preact/signals-core';
+import { FieldStatus } from '../types';
+/**
+ * События для State Machine
+ */
+export type StatusEvent = {
+    type: 'START_VALIDATION';
+} | {
+    type: 'VALIDATION_SUCCESS';
+} | {
+    type: 'VALIDATION_FAILURE';
+} | {
+    type: 'DISABLE';
+} | {
+    type: 'ENABLE';
+    hasErrors?: boolean;
+} | {
+    type: 'SET_ERRORS';
+    hasErrors: boolean;
+};
+/**
+ * FormStatusMachine - управляет состоянием поля формы
+ *
+ * Предоставляет:
+ * - Единый источник истины для статуса
+ * - Computed signals для derived состояний (valid, invalid, pending, disabled)
+ * - Валидацию переходов между состояниями
+ *
+ * @example
+ * ```typescript
+ * const statusMachine = new FormStatusMachine('valid');
+ *
+ * // Начало валидации
+ * statusMachine.startValidation();
+ * console.log(statusMachine.pending.value); // true
+ *
+ * // Завершение валидации с ошибками
+ * statusMachine.completeValidation(true);
+ * console.log(statusMachine.invalid.value); // true
+ *
+ * // Отключение поля
+ * statusMachine.disable();
+ * console.log(statusMachine.disabled.value); // true
+ * ```
+ */
+export declare class FormStatusMachine {
+    /** Внутренний сигнал статуса */
+    private readonly _status;
+    /** Публичный read-only сигнал статуса */
+    readonly status: ReadonlySignal<FieldStatus>;
+    /** Поле валидно */
+    readonly valid: ReadonlySignal<boolean>;
+    /** Поле невалидно */
+    readonly invalid: ReadonlySignal<boolean>;
+    /** Идет валидация */
+    readonly pending: ReadonlySignal<boolean>;
+    /** Поле отключено */
+    readonly disabled: ReadonlySignal<boolean>;
+    /**
+     * @param initial - Начальный статус (по умолчанию 'valid')
+     */
+    constructor(initial?: FieldStatus);
+    /**
+     * Начать валидацию
+     *
+     * Переводит статус в 'pending' если поле не отключено
+     *
+     * @example
+     * ```typescript
+     * statusMachine.startValidation();
+     * // status: 'pending'
+     * ```
+     */
+    startValidation(): void;
+    /**
+     * Завершить валидацию
+     *
+     * @param hasErrors - Есть ли ошибки валидации
+     *
+     * @example
+     * ```typescript
+     * // Валидация успешна
+     * statusMachine.completeValidation(false);
+     * // status: 'valid'
+     *
+     * // Есть ошибки
+     * statusMachine.completeValidation(true);
+     * // status: 'invalid'
+     * ```
+     */
+    completeValidation(hasErrors: boolean): void;
+    /**
+     * Установить ошибки напрямую (без перехода через pending)
+     *
+     * Используется для синхронной валидации или установки ошибок извне
+     *
+     * @param hasErrors - Есть ли ошибки
+     *
+     * @example
+     * ```typescript
+     * statusMachine.setErrors(true);
+     * // status: 'invalid'
+     * ```
+     */
+    setErrors(hasErrors: boolean): void;
+    /**
+     * Отключить поле
+     *
+     * Переводит статус в 'disabled'
+     *
+     * @example
+     * ```typescript
+     * statusMachine.disable();
+     * // status: 'disabled'
+     * ```
+     */
+    disable(): void;
+    /**
+     * Включить поле
+     *
+     * @param hasErrors - Есть ли ошибки (определяет valid/invalid)
+     *
+     * @example
+     * ```typescript
+     * statusMachine.enable(false);
+     * // status: 'valid'
+     *
+     * statusMachine.enable(true);
+     * // status: 'invalid'
+     * ```
+     */
+    enable(hasErrors?: boolean): void;
+    /**
+     * Обработать событие (альтернативный API)
+     *
+     * @param event - Событие для обработки
+     *
+     * @example
+     * ```typescript
+     * statusMachine.dispatch({ type: 'START_VALIDATION' });
+     * statusMachine.dispatch({ type: 'VALIDATION_FAILURE' });
+     * ```
+     */
+    dispatch(event: StatusEvent): void;
+    /**
+     * Получить текущий статус
+     */
+    getStatus(): FieldStatus;
+    /**
+     * Проверить, можно ли начать валидацию
+     */
+    canValidate(): boolean;
+}

package/dist/core/utils/type-guards.d.ts

@@ -1,26 +1,8 @@
-/**
- * Type Guards - централизованные функции проверки типов узлов
- *
- * Устраняет дублирование между form-node.ts, validation-applicator.ts и validation-context.ts
- *
- * @group Utilities
- * @category Type Guards
- *
- * @example
- * ```typescript
- * import { isFieldNode, isGroupNode } from '@/core/utils/type-guards';
- *
- * if (isFieldNode(node)) {
- *   // TypeScript знает, что node это FieldNode
- *   node.validators;
- * }
- * ```
- */
-import type { FormNode } from '../nodes/form-node';
-import type { FieldNode } from '../nodes/field-node';
-import type { GroupNode } from '../nodes/group-node';
-import type { ArrayNode } from '../nodes/array-node';
-import type { FormFields, FormValue } from '../types';
+import { FormNode } from '../nodes/form-node';
+import { FieldNode } from '../nodes/field-node';
+import { GroupNode } from '../nodes/group-node';
+import { ArrayNode } from '../nodes/array-node';
+import { FormFields, FormValue } from '../types';
 /**
  * Проверить, является ли значение любым FormNode
  *

package/dist/core/utils/unique-id.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Генератор уникальных идентификаторов
+ *
+ * Использует атомный счётчик для генерации гарантированно уникальных ключей.
+ * Решает проблему возможного дублирования ключей при использовании
+ * Date.now() + Math.random() в быстрых последовательных вызовах.
+ *
+ * @example
+ * ```typescript
+ * const key1 = uniqueId(SubscriptionKey.Watch); // "watch-1"
+ * const key2 = uniqueId(SubscriptionKey.Watch); // "watch-2"
+ * const key3 = uniqueId(SubscriptionKey.ComputeFrom); // "computeFrom-3"
+ * ```
+ */
+/**
+ * Типобезопасные ключи для подписок
+ * Используются с uniqueId() для генерации уникальных идентификаторов
+ */
+export declare const SubscriptionKey: {
+    /** FieldNode.watch() */
+    readonly Watch: "watch";
+    /** FieldNode.computeFrom() */
+    readonly ComputeFrom: "computeFrom";
+    /** GroupNode.linkFields() */
+    readonly LinkFields: "linkFields";
+    /** GroupNode.watchField() */
+    readonly WatchField: "watchField";
+    /** ArrayNode.watchItems() */
+    readonly WatchItems: "watchItems";
+    /** ArrayNode.watchLength() */
+    readonly WatchLength: "watchLength";
+};
+export type SubscriptionKeyType = (typeof SubscriptionKey)[keyof typeof SubscriptionKey];
+/**
+ * Генерирует уникальный идентификатор с указанным префиксом.
+ *
+ * @param prefix - Префикс для идентификатора (используйте {@link SubscriptionKey}).
+ * @returns Уникальный идентификатор в формате `${prefix}-${counter}`.
+ *
+ * @example
+ * ```typescript
+ * import { uniqueId, SubscriptionKey } from '@reformer/core';
+ *
+ * uniqueId(SubscriptionKey.WatchField); // → 'watchField-1'
+ * uniqueId(SubscriptionKey.WatchField); // → 'watchField-2'
+ * ```
+ */
+export declare function uniqueId(prefix: SubscriptionKeyType): string;
+/**
+ * Сбросить счётчик (только для тестов)
+ * @internal
+ */
+export declare function resetUniqueIdCounter(): void;

package/dist/core/validation/core/apply-when.d.ts

@@ -1,12 +1,6 @@
-/**
- * Условная валидация
- *
- * @group Validation
- * @category Core Functions
- */
-import type { FieldPath } from '../../types/field-path';
-import type { ConditionFn } from '../../types/validation-schema';
-import type { FieldPathNode } from '../../types';
+import { FieldPath } from '../../types/field-path';
+import { ConditionFn } from '../../types/validation-schema';
+import { FieldPathNode } from '../../types';
 /**
  * Применить валидацию только при выполнении условия
  *

package/dist/core/validation/core/apply.d.ts

@@ -1,16 +1,5 @@
-/**
- * Композиция validation схем
- *
- * Предоставляет функции для переиспользования validation схем:
- * - apply: применение схемы к полям (новый API)
- *
- * Дополняет существующий toFieldPath и applyWhen.
- *
- * @group Validation
- * @category Core Functions
- */
-import type { FieldPathNode, FieldPath } from '../../types';
-import type { ValidationSchemaFn } from '../../types/validation-schema';
+import { FieldPathNode, FieldPath } from '../../types';
+import { ValidationSchemaFn } from '../../types/validation-schema';
 /**
  * Применить validation схему к корневому path формы
  *

package/dist/core/validation/core/validate-async.d.ts

@@ -1,11 +1,5 @@
-/**
- * Асинхронная валидация поля
- *
- * @group Validation
- * @category Core Functions
- */
-import type { ContextualAsyncValidatorFn, ValidateAsyncOptions } from '../../types/validation-schema';
-import type { FieldPathNode } from '../../types';
+import { ContextualAsyncValidatorFn, ValidateAsyncOptions } from '../../types/validation-schema';
+import { FieldPathNode } from '../../types';
 /**
  * Зарегистрировать асинхронный валидатор для поля
  *

package/dist/core/validation/core/validate-tree.d.ts

@@ -1,9 +1,3 @@
-/**
- * Cross-field валидация
- *
- * @group Validation
- * @category Core Functions
- */
 import { TreeValidatorFn, ValidateTreeOptions } from '../../types';
 /**
  * Зарегистрировать cross-field валидатор

package/dist/core/validation/core/validate.d.ts

@@ -1,10 +1,4 @@
-/**
- * Кастомная синхронная валидация поля
- *
- * @group Validation
- * @category Core Functions
- */
-import type { ContextualValidatorFn, FieldPathNode, ValidateOptions } from '../../types';
+import { ContextualValidatorFn, FieldPathNode, ValidateOptions } from '../../types';
 /**
  * Зарегистрировать кастомный синхронный валидатор для поля
  * Поддерживает опциональные поля

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

@@ -13,9 +13,15 @@ export { pattern } from './validators/pattern';
 export { url } from './validators/url';
 export { phone, type PhoneFormat } from './validators/phone';
 export { number } from './validators/number';
-export { date } from './validators/date';
+export { isDate } from './validators/is-date';
+export { minDate } from './validators/min-date';
+export { maxDate } from './validators/max-date';
+export { pastDate } from './validators/past-date';
+export { futureDate } from './validators/future-date';
+export { minAge } from './validators/min-age';
+export { maxAge } from './validators/max-age';
 export { notEmpty, validateItems } from './validators/array-validators';
-export { createFieldPath, extractPath, extractKey, toFieldPath } from './field-path';
+export { createFieldPath, extractPath, extractKey, toFieldPath } from '../utils/field-path';
 export { validateForm } from './validate-form';
 export { ValidationRegistry } from './validation-registry';
 export { ValidationContextImpl, TreeValidationContextImpl } from './validation-context';

package/dist/core/validation/validate-form.d.ts

@@ -1,42 +1,5 @@
-/**
- * validateForm - утилита для валидации формы в соответствии со схемой
- *
- * Позволяет применить validation schema к форме без изменения
- * зарегистрированной схемы в ValidationRegistry.
- *
- * ## Использование
- *
- * - **Multi-step формы**: валидация только полей текущего шага
- * - **Условная валидация**: применение разных схем в зависимости от состояния
- * - **Временная валидация**: проверка без сохранения в реестр
- *
- * ## Как это работает
- *
- * 1. Создаётся временный ValidationRegistry для схемы
- * 2. Валидируются все FieldNode (field-level валидаторы из FieldConfig)
- * 3. Применяются ТОЛЬКО contextual validators из переданной схемы
- * 4. Временный реестр отменяется (не сохраняется в форму)
- *
- * ## Важно для multi-step форм
- *
- * Форма может быть создана С полной схемой валидации:
- * ```typescript
- * createForm({
- *   form: schema,
- *   validation: fullValidation, // Полная схема
- * });
- * ```
- *
- * При этом `validateForm(form, stepSchema)` будет применять
- * только валидаторы из `stepSchema`, игнорируя валидаторы
- * из других шагов.
- *
- * @see docs/multi-step-validation.md для подробной документации
- *
- * @module validation
- */
 import { GroupNode } from '../nodes/group-node';
-import type { ValidationSchemaFn, FormFields } from '../types';
+import { ValidationSchemaFn, FormFields } from '../types';
 /**
  * Валидировать форму в соответствии с указанной схемой
  *

package/dist/core/validation/validation-applicator.d.ts

@@ -1,24 +1,5 @@
-/**
- * Применение валидаторов к форме
- *
- * Извлечено из GroupNode для соблюдения SRP (Single Responsibility Principle).
- * Отвечает только за логику применения валидаторов к полям формы.
- *
- * @template T Тип формы
- *
- * @example
- * ```typescript
- * class GroupNode {
- *   private readonly validationApplicator = new ValidationApplicator(this);
- *
- *   async applyContextualValidators(validators: ValidatorRegistration[]) {
- *     await this.validationApplicator.apply(validators);
- *   }
- * }
- * ```
- */
-import type { GroupNode } from '../nodes/group-node';
-import type { ValidatorRegistration } from '../types';
+import { GroupNode } from '../nodes/group-node';
+import { ValidatorRegistration } from '../types';
 /**
  * Класс для применения валидаторов к форме
  *