@reformer/core 3.0.0 → 4.0.0

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';
 /**
  * Класс для применения валидаторов к форме
  *

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

@@ -1,70 +1,86 @@
+import { GroupNode } from '../nodes/group-node';
+import { FieldNode } from '../nodes/field-node';
+import { FormProxy } from '../types/form-proxy';
+import { FormContext } from '../types/form-context';
 /**
- * Реализация контекста валидации
+ * Базовый класс контекста валидации
+ * Содержит общую логику для всех типов контекстов
+ * @internal
  */
-import type { GroupNode } from '../nodes/group-node';
-import type { FieldNode } from '../nodes/field-node';
-import type { FormProxy } from '../types/form-proxy';
-import type { FormContext } from '../types/form-context';
-/**
- * Реализация контекста валидации для отдельного поля
- * Реализует FormContext
- */
-export declare class ValidationContextImpl<TForm, TField> implements FormContext<TForm> {
-    private _form;
-    private control;
+declare abstract class BaseValidationContext<TForm> implements FormContext<TForm> {
+    protected readonly _form: GroupNode<TForm>;
     /**
      * Форма с типизированным Proxy-доступом к полям
      */
     readonly form: FormProxy<TForm>;
-    constructor(form: GroupNode<TForm>, _fieldKey: keyof TForm, control: FieldNode<TField>);
-    /**
-     * Получить текущее значение поля (внутренний метод для validation-applicator)
-     * @internal
-     */
-    value(): TField;
+    constructor(form: GroupNode<TForm>);
     /**
      * Безопасно установить значение поля по строковому пути
      * Автоматически использует emitEvent: false для предотвращения циклов
      */
     setFieldValue(path: string, value: unknown): void;
+    /**
+     * Получить поле формы по строковому пути
+     */
+    getFieldByPath(path: string): import('../..').FormNode<import('../types').FormValue> | undefined;
 }
 /**
- * Реализация контекста для cross-field валидации
- * Реализует FormContext
+ * Контекст валидации одного поля. Создаётся фреймворком и передаётся в валидаторы
+ * (`required`, `validate`, …) — напрямую инстанцировать не нужно.
+ *
+ * @example
+ * ```typescript
+ * import { validate } from '@reformer/core/validators';
+ *
+ * validate(path.password, (value, ctx) => {
+ *   // ctx — экземпляр ValidationContextImpl, доступ к ctx.form для cross-field логики
+ *   if (value !== ctx.form.confirmPassword.value) {
+ *     return { code: 'mismatch', message: 'Пароли не совпадают' };
+ *   }
+ *   return null;
+ * });
+ * ```
  */
-export declare class TreeValidationContextImpl<TForm> implements FormContext<TForm> {
-    private _form;
+export declare class ValidationContextImpl<TForm, TField> extends BaseValidationContext<TForm> {
+    private control;
+    constructor(form: GroupNode<TForm>, _fieldKey: keyof TForm, control: FieldNode<TField>);
     /**
-     * Форма с типизированным Proxy-доступом к полям
+     * Получить текущее значение поля (внутренний метод для validation-applicator)
+     * @internal
      */
-    readonly form: FormProxy<TForm>;
+    value(): TField;
+}
+/**
+ * Контекст cross-field валидации. Передаётся в `validateTree`/`validateForm`
+ * callback'и — напрямую инстанцировать не нужно.
+ *
+ * @example
+ * ```typescript
+ * import { validateForm } from '@reformer/core';
+ *
+ * validateForm(form, (ctx) => {
+ *   // ctx — экземпляр TreeValidationContextImpl
+ *   if (ctx.form.startDate.value > ctx.form.endDate.value) {
+ *     return [{ code: 'date-range', message: 'Дата начала позже даты окончания' }];
+ *   }
+ *   return [];
+ * });
+ * ```
+ */
+export declare class TreeValidationContextImpl<TForm> extends BaseValidationContext<TForm> {
     constructor(form: GroupNode<TForm>);
-    /**
-     * Безопасно установить значение поля по строковому пути
-     * Автоматически использует emitEvent: false для предотвращения циклов
-     */
-    setFieldValue(path: string, value: unknown): void;
 }
 /**
- * Реализация контекста валидации для ArrayNode
- * Позволяет валидаторам типа notEmpty работать с массивами
+ * Контекст валидации для ArrayNode
+ * Предоставляет доступ к значению массива
  */
-export declare class ArrayValidationContextImpl<TForm, TItem> implements FormContext<TForm> {
-    private _form;
+export declare class ArrayValidationContextImpl<TForm, TItem> extends BaseValidationContext<TForm> {
     private arrayValue;
-    /**
-     * Форма с типизированным Proxy-доступом к полям
-     */
-    readonly form: FormProxy<TForm>;
     constructor(form: GroupNode<TForm>, _fieldKey: keyof TForm, arrayValue: TItem[]);
     /**
      * Получить текущее значение массива (для валидатора)
      * @internal
      */
     value(): TItem[];
-    /**
-     * Безопасно установить значение поля по строковому пути
-     * Автоматически использует emitEvent: false для предотвращения циклов
-     */
-    setFieldValue(path: string, value: unknown): void;
 }
+export {};