@reformer/core 1.0.0-beta.1

package/dist/core/utils/subscription-manager.d.ts

@@ -0,0 +1,180 @@
+/**
+ * Менеджер подписок для FormNode
+ *
+ * Централизует управление effect-подписками в узлах формы,
+ * предотвращает утечки памяти и упрощает отладку.
+ *
+ * Каждая подписка имеет уникальный ключ, что позволяет:
+ * - Отписываться от конкретной подписки по ключу
+ * - Автоматически заменять существующие подписки
+ * - Отслеживать количество активных подписок (для отладки)
+ *
+ * @internal
+ *
+ * @example
+ * ```typescript
+ * class FieldNode {
+ *   private subscriptions = new SubscriptionManager();
+ *
+ *   watch(callback: Function) {
+ *     const dispose = effect(() => callback(this.value.value));
+ *     return this.subscriptions.add('watch', dispose);
+ *   }
+ *
+ *   dispose() {
+ *     this.subscriptions.clear();
+ *   }
+ * }
+ * ```
+ */
+export declare class SubscriptionManager {
+    /**
+     * Хранилище подписок
+     * Ключ: уникальный идентификатор подписки
+     * Значение: функция отписки (dispose)
+     */
+    private subscriptions;
+    /**
+     * Добавляет подписку
+     *
+     * Если подписка с таким ключом уже существует, отписывается от неё
+     * и заменяет новой. Это предотвращает утечки памяти при повторной
+     * регистрации подписки с тем же ключом.
+     *
+     * @param key Уникальный ключ подписки
+     * @param dispose Функция отписки (обычно возвращаемая из effect())
+     * @returns Функция для отписки от этой конкретной подписки
+     *
+     * @example
+     * ```typescript
+     * const manager = new SubscriptionManager();
+     *
+     * // Добавление подписки
+     * const unsubscribe = manager.add('mySubscription', () => {
+     *   console.log('Disposing subscription');
+     * });
+     *
+     * // Отписка через возвращаемую функцию
+     * unsubscribe();
+     *
+     * // Или через manager.remove()
+     * manager.add('anotherSub', disposeFn);
+     * manager.remove('anotherSub');
+     * ```
+     */
+    add(key: string, dispose: () => void): () => void;
+    /**
+     * Удаляет подписку по ключу
+     *
+     * Вызывает функцию отписки и удаляет подписку из хранилища.
+     * Если подписка с таким ключом не найдена, ничего не делает.
+     *
+     * @param key Ключ подписки
+     * @returns true, если подписка была удалена, false если не найдена
+     *
+     * @example
+     * ```typescript
+     * const manager = new SubscriptionManager();
+     * manager.add('mySub', disposeFn);
+     *
+     * // Удаление подписки
+     * const removed = manager.remove('mySub'); // true
+     *
+     * // Попытка удалить несуществующую подписку
+     * const removed2 = manager.remove('nonExistent'); // false
+     * ```
+     */
+    remove(key: string): boolean;
+    /**
+     * Очищает все подписки
+     *
+     * Вызывает функции отписки для всех активных подписок
+     * и очищает хранилище. Обычно используется при dispose узла формы.
+     *
+     * @example
+     * ```typescript
+     * class FieldNode {
+     *   private subscriptions = new SubscriptionManager();
+     *
+     *   dispose() {
+     *     // Отписываемся от всех effect
+     *     this.subscriptions.clear();
+     *   }
+     * }
+     * ```
+     */
+    clear(): void;
+    /**
+     * Возвращает количество активных подписок
+     *
+     * Полезно для отладки утечек памяти. Если количество подписок
+     * растет без ограничений, это может указывать на то, что
+     * компоненты не отписываются должным образом.
+     *
+     * @returns Количество активных подписок
+     *
+     * @example
+     * ```typescript
+     * const manager = new SubscriptionManager();
+     * console.log(manager.size()); // 0
+     *
+     * manager.add('sub1', disposeFn1);
+     * manager.add('sub2', disposeFn2);
+     * console.log(manager.size()); // 2
+     *
+     * manager.clear();
+     * console.log(manager.size()); // 0
+     * ```
+     */
+    size(): number;
+    /**
+     * Проверяет, есть ли подписка с данным ключом
+     *
+     * @param key Ключ подписки
+     * @returns true, если подписка существует
+     *
+     * @example
+     * ```typescript
+     * const manager = new SubscriptionManager();
+     * manager.add('mySub', disposeFn);
+     *
+     * console.log(manager.has('mySub')); // true
+     * console.log(manager.has('nonExistent')); // false
+     * ```
+     */
+    has(key: string): boolean;
+    /**
+     * Возвращает список всех ключей активных подписок
+     *
+     * Полезно для отладки: можно увидеть, какие подписки активны.
+     *
+     * @returns Массив ключей всех активных подписок
+     *
+     * @example
+     * ```typescript
+     * const manager = new SubscriptionManager();
+     * manager.add('watch-value', disposeFn1);
+     * manager.add('watch-errors', disposeFn2);
+     *
+     * console.log(manager.getKeys()); // ['watch-value', 'watch-errors']
+     * ```
+     */
+    getKeys(): string[];
+    /**
+     * Отписывается от всех подписок (алиас для clear())
+     *
+     * Используется при dispose() узла формы для совместимости с ожидаемым API.
+     *
+     * @example
+     * ```typescript
+     * class FieldNode {
+     *   private subscriptions = new SubscriptionManager();
+     *
+     *   dispose() {
+     *     this.subscriptions.dispose();
+     *   }
+     * }
+     * ```
+     */
+    dispose(): void;
+}

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

@@ -0,0 +1,98 @@
+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
+ *
+ * Проверяет базовые свойства, общие для всех типов узлов
+ *
+ * @group Utilities
+ * @category Type Guards
+ *
+ * @param value - Значение для проверки
+ * @returns true если value является FormNode
+ *
+ * @example
+ * ```typescript
+ * if (isFormNode(value)) {
+ *   value.setValue(newValue);
+ *   value.validate();
+ * }
+ * ```
+ */
+export declare function isFormNode(value: unknown): value is FormNode<FormValue>;
+/**
+ * Проверить, является ли значение FieldNode (примитивное поле)
+ *
+ * FieldNode представляет примитивное поле формы (string, number, boolean и т.д.)
+ * и имеет валидаторы, но не имеет вложенных полей или элементов массива
+ *
+ * @group Utilities
+ * @category Type Guards
+ *
+ * @param value - Значение для проверки
+ * @returns true если value является FieldNode
+ *
+ * @example
+ * ```typescript
+ * if (isFieldNode(node)) {
+ *   node.validators; //  OK
+ *   node.asyncValidators; //  OK
+ *   node.markAsTouched(); //  OK
+ * }
+ * ```
+ */
+export declare function isFieldNode(value: unknown): value is FieldNode<FormValue>;
+/**
+ * Проверить, является ли значение GroupNode (объект с вложенными полями)
+ *
+ * GroupNode представляет объект с вложенными полями формы
+ * и имеет методы для применения validation/behavior схем
+ *
+ * @param value - Значение для проверки
+ * @returns true если value является GroupNode
+ *
+ * @example
+ * ```typescript
+ * if (isGroupNode(node)) {
+ *   node.applyValidationSchema(schema); //  OK
+ *   node.getFieldByPath('user.email'); //  OK
+ * }
+ * ```
+ */
+export declare function isGroupNode(value: unknown): value is GroupNode<FormFields>;
+/**
+ * Проверить, является ли значение ArrayNode (массив форм)
+ *
+ * ArrayNode представляет массив вложенных форм (обычно GroupNode)
+ * и имеет array-like методы (push, removeAt, at)
+ *
+ * @param value - Значение для проверки
+ * @returns true если value является ArrayNode
+ *
+ * @example
+ * ```typescript
+ * if (isArrayNode(node)) {
+ *   node.push(); //  OK - добавить элемент
+ *   node.removeAt(0); //  OK - удалить элемент
+ *   const item = node.at(0); //  OK - получить элемент
+ * }
+ * ```
+ */
+export declare function isArrayNode(value: unknown): value is ArrayNode<FormFields>;
+/**
+ * Получить тип узла как строку (для отладки)
+ *
+ * Полезно для логирования и отладки
+ *
+ * @param node - Узел для проверки
+ * @returns Строковое название типа узла
+ *
+ * @example
+ * ```typescript
+ * console.log('Node type:', getNodeType(node)); // "FieldNode" | "GroupNode" | "ArrayNode" | "FormNode" | "Unknown"
+ * ```
+ */
+export declare function getNodeType(node: unknown): string;

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

@@ -0,0 +1,22 @@
+import { FieldPath } from '../../types/field-path';
+import { ConditionFn } from '../../types/validation-schema';
+import { FieldPathNode } from '../../types';
+/**
+ * Применить валидацию только при выполнении условия
+ *
+ * @group Validation
+ * @category Core Functions
+ *
+ * @example
+ * ```typescript
+ * applyWhen(
+ *   path.loanType,
+ *   (type) => type === 'mortgage',
+ *   (path) => {
+ *     required(path.propertyValue, { message: 'Укажите стоимость' });
+ *     min(path.propertyValue, 1000000);
+ *   }
+ * );
+ * ```
+ */
+export declare function applyWhen<TForm, TField>(fieldPath: FieldPathNode<TForm, TField>, condition: ConditionFn<TField>, validationFn: (path: FieldPath<TForm>) => void): void;

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

@@ -0,0 +1,52 @@
+import { FieldPathNode, FieldPath } from '../../types';
+import { ValidationSchemaFn } from '../../types/validation-schema';
+/**
+ * Применить validation схему к корневому path формы
+ *
+ * Используется для композиции схем на уровне всей формы.
+ *
+ * @group Validation
+ * @category Core Functions
+ *
+ * @param path - Корневой FieldPath формы (весь объект путей)
+ * @param validationSchema - Схема валидации
+ *
+ * @example
+ * ```typescript
+ * const creditApplicationValidation: ValidationSchemaFn<CreditApplicationForm> = (path) => {
+ *   apply(path, basicInfoValidation);
+ *   apply(path, contactInfoValidation);
+ * };
+ * ```
+ */
+export declare function apply<TForm>(path: FieldPath<TForm>, validationSchema: ValidationSchemaFn<TForm>): void;
+/**
+ * Применить validation схему к вложенному полю или полям
+ *
+ * Поддерживает:
+ * - Одно поле или массив полей
+ * - Одну схему или массив схем
+ * - Все комбинации (поле + схема, поле + схемы, поля + схема, поля + схемы)
+ *
+ * @param fields - Одно поле или массив полей
+ * @param validationSchemas - Одна схема или массив схем
+ *
+ * @example
+ * ```typescript
+ * // Одна схема к одному полю
+ * apply(path.registrationAddress, addressValidation);
+ *
+ * // Одна схема к нескольким полям
+ * apply([path.homeAddress, path.workAddress], addressValidation);
+ *
+ * // Несколько схем к одному полю
+ * apply(path.email, [emailValidation, uniqueEmailValidation]);
+ *
+ * // Несколько схем к нескольким полям
+ * apply(
+ *   [path.email, path.confirmEmail],
+ *   [emailValidation, matchValidation]
+ * );
+ * ```
+ */
+export declare function apply<TForm, TField>(fields: FieldPathNode<TForm, TField> | Array<FieldPathNode<TForm, TField> | undefined> | undefined, validationSchemas: ValidationSchemaFn<TField> | Array<ValidationSchemaFn<TField>>): void;

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

@@ -0,0 +1,8 @@
+/**
+ * Core validation functions
+ */
+export { validate } from './validate';
+export { validateAsync } from './validate-async';
+export { validateTree } from './validate-tree';
+export { applyWhen } from './apply-when';
+export { apply } from './apply';

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

@@ -0,0 +1,36 @@
+import { ContextualAsyncValidatorFn, ValidateAsyncOptions } from '../../types/validation-schema';
+import { FieldPathNode } from '../../types';
+/**
+ * Зарегистрировать асинхронный валидатор для поля
+ *
+ * @group Validation
+ * @category Core Functions
+ *
+ * @example
+ * ```typescript
+ * validateAsync(
+ *   path.inn,
+ *   async (ctx: ValidationContext<TForm, TField>) => {
+ *     const inn = ctx.value();
+ *     if (!inn) return null;
+ *
+ *     const response = await fetch('/api/validate-inn', {
+ *       method: 'POST',
+ *       body: JSON.stringify({ inn }),
+ *     });
+ *
+ *     const data = await response.json();
+ *     if (!data.valid) {
+ *       return {
+ *         code: 'invalidInn',
+ *         message: 'ИНН не найден в базе данных ФНС',
+ *       };
+ *     }
+ *
+ *     return null;
+ *   },
+ *   { debounce: 1000 }
+ * );
+ * ```
+ */
+export declare function validateAsync<TForm, TField>(fieldPath: FieldPathNode<TForm, TField>, validatorFn: ContextualAsyncValidatorFn<TForm, TField>, options?: ValidateAsyncOptions): void;

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

@@ -0,0 +1,35 @@
+import { TreeValidatorFn, ValidateTreeOptions } from '../../types';
+/**
+ * Зарегистрировать cross-field валидатор
+ *
+ * Используется для валидации, которая зависит от нескольких полей
+ *
+ * @group Validation
+ * @category Core Functions
+ *
+ * @remarks
+ * Параметр `ctx` в callback требует явной типизации для корректного вывода типов:
+ * ```typescript
+ * validateTree((ctx: { form: MyFormType }) => { ... });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Явная типизация ctx для избежания implicit any
+ * validateTree(
+ *   (ctx: { form: MyForm }) => {
+ *     if (ctx.form.initialPayment && ctx.form.propertyValue) {
+ *       if (ctx.form.initialPayment > ctx.form.propertyValue) {
+ *         return {
+ *           code: 'initialPaymentTooHigh',
+ *           message: 'Первоначальный взнос не может превышать стоимость',
+ *         };
+ *       }
+ *     }
+ *     return null;
+ *   },
+ *   { targetField: 'initialPayment' }
+ * );
+ * ```
+ */
+export declare function validateTree<TForm>(validatorFn: TreeValidatorFn<TForm>, options?: ValidateTreeOptions): void;

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

@@ -0,0 +1,26 @@
+import { ContextualValidatorFn, FieldPathNode, ValidateOptions } from '../../types';
+/**
+ * Зарегистрировать кастомный синхронный валидатор для поля
+ * Поддерживает опциональные поля
+ *
+ * @group Validation
+ * @category Core Functions
+ *
+ * @example
+ * ```typescript
+ * validate(path.birthDate, (ctx: ValidationContext<TForm, TField>) => {
+ *   const birthDate = new Date(ctx.value());
+ *   const age = calculateAge(birthDate);
+ *
+ *   if (age < 18) {
+ *     return {
+ *       code: 'tooYoung',
+ *       message: 'Заемщику должно быть не менее 18 лет',
+ *     };
+ *   }
+ *
+ *   return null;
+ * });
+ * ```
+ */
+export declare function validate<TForm, TField>(fieldPath: FieldPathNode<TForm, TField> | undefined, validatorFn: ContextualValidatorFn<TForm, TField>, options?: ValidateOptions): void;

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

@@ -0,0 +1,27 @@
+export { validate } from './core/validate';
+export { validateAsync } from './core/validate-async';
+export { validateTree } from './core/validate-tree';
+export { apply } from './core/apply';
+export { applyWhen } from './core/apply-when';
+export { required } from './validators/required';
+export { min } from './validators/min';
+export { max } from './validators/max';
+export { minLength } from './validators/min-length';
+export { maxLength } from './validators/max-length';
+export { email } from './validators/email';
+export { pattern } from './validators/pattern';
+export { url } from './validators/url';
+export { phone, type PhoneFormat } from './validators/phone';
+export { number } from './validators/number';
+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 '../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

@@ -0,0 +1,48 @@
+import { GroupNode } from '../nodes/group-node';
+import { ValidationSchemaFn, FormFields } from '../types';
+/**
+ * Валидировать форму в соответствии с указанной схемой
+ *
+ * Функция создает временный контекст валидации, применяет валидаторы
+ * из схемы и очищает контекст без сохранения в реестр.
+ *
+ * @param form - GroupNode для валидации
+ * @param schema - Схема валидации (ValidationSchemaFn)
+ * @returns Promise<boolean> - `true` если форма валидна, `false` если есть ошибки
+ *
+ * @example Multi-step форма: валидация текущего шага
+ * ```typescript
+ * const goToNextStep = async () => {
+ *   const isValid = await validateForm(form, step1LoanValidation);
+ *
+ *   if (!isValid) {
+ *     form.markAsTouched(); // Показать ошибки
+ *     return false;
+ *   }
+ *
+ *   setCurrentStep(2);
+ *   return true;
+ * };
+ * ```
+ *
+ * @example Полная валидация перед submit
+ * ```typescript
+ * const handleSubmit = async () => {
+ *   const isValid = await validateForm(form, fullValidationSchema);
+ *
+ *   if (isValid) {
+ *     await form.submit(onSubmit);
+ *   }
+ * };
+ * ```
+ *
+ * @example Условная валидация
+ * ```typescript
+ * const schema = isBusinessAccount
+ *   ? businessValidation
+ *   : personalValidation;
+ *
+ * const isValid = await validateForm(form, schema);
+ * ```
+ */
+export declare function validateForm<T extends FormFields>(form: GroupNode<T>, schema: ValidationSchemaFn<T>): Promise<boolean>;

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

@@ -0,0 +1,70 @@
+import { GroupNode } from '../nodes/group-node';
+import { ValidatorRegistration } from '../types';
+/**
+ * Класс для применения валидаторов к форме
+ *
+ * Выполняет:
+ * - Группировку валидаторов по полям
+ * - Фильтрацию по условиям (condition)
+ * - Применение sync/async валидаторов к FieldNode
+ * - Применение tree валидаторов (кросс-полевая валидация)
+ *
+ * @template T Тип формы (объект)
+ */
+export declare class ValidationApplicator<T> {
+    private readonly form;
+    constructor(form: GroupNode<T>);
+    /**
+     * Применить валидаторы к полям формы
+     *
+     * Этапы применения:
+     * 1. Разделение валидаторов на field и tree
+     * 2. Применение field валидаторов (sync/async)
+     * 3. Применение tree валидаторов (кросс-полевая валидация)
+     *
+     * @param validators Зарегистрированные валидаторы
+     */
+    apply(validators: ValidatorRegistration[]): Promise<void>;
+    /**
+     * Группировка валидаторов по типам
+     *
+     * Разделяет валидаторы на:
+     * - Field validators (sync/async) - группируются по fieldPath
+     * - Tree validators - применяются ко всей форме
+     *
+     * @param validators Все зарегистрированные валидаторы
+     * @returns Сгруппированные валидаторы
+     */
+    private groupValidators;
+    /**
+     * Применение field валидаторов к полям
+     *
+     * Для каждого поля:
+     * 1. Найти FieldNode по пути
+     * 2. Проверить условия (condition)
+     * 3. Выполнить sync/async валидаторы
+     * 4. Установить ошибки на поле
+     *
+     * @param validatorsByField Валидаторы, сгруппированные по полям
+     */
+    private applyFieldValidators;
+    /**
+     * Применение tree валидаторов (кросс-полевая валидация)
+     *
+     * Tree валидаторы имеют доступ ко всей форме через TreeValidationContext.
+     * Ошибки устанавливаются на targetField (если указано).
+     *
+     * @param treeValidators Список tree валидаторов
+     */
+    private applyTreeValidators;
+    /**
+     * Проверка условия (condition) для валидатора
+     *
+     * Условие определяет, должен ли валидатор выполняться.
+     * Использует getFieldByPath для поддержки вложенных путей.
+     *
+     * @param condition Условие валидатора
+     * @returns true, если условие выполнено
+     */
+    private checkCondition;
+}