@reformer/core 1.0.0-beta.3

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

@@ -0,0 +1,41 @@
+export interface ResourceItem<T> {
+    id: string | number;
+    label: string;
+    description: string;
+    value: T;
+    [key: string]: unknown;
+}
+export interface ResourceResult<T> {
+    items: ResourceItem<T>[];
+    totalCount: number;
+}
+export interface ResourceConfig<T> {
+    type: 'static' | 'preload' | 'partial';
+    load: (params?: ResourceLoadParams) => Promise<ResourceResult<T>>;
+}
+export interface ResourceLoadParams {
+    search?: string;
+    page?: number;
+    pageSize?: number;
+    [key: string]: unknown;
+}
+/**
+ * Статический ресурс - данные загружаются один раз
+ * @param items - массив элементов
+ */
+export declare function staticResource<T>(items: ResourceItem<T>[]): ResourceConfig<T>;
+/**
+ * Предзагрузка - данные загружаются один раз при первом обращении через функцию
+ * @param loader - функция загрузки, принимает параметры и возвращает массив
+ */
+export declare function preloadResource<T>(loader: (params?: ResourceLoadParams) => Promise<ResourceItem<T>[]>): ResourceConfig<T>;
+/**
+ * Парциональная загрузка - данные загружаются порциями с учетом поиска/пагинации
+ * @param loader - функция загрузки, принимает параметры и возвращает массив
+ */
+export declare function partialResource<T>(loader: (params?: ResourceLoadParams) => Promise<ResourceItem<T>[]>): ResourceConfig<T>;
+export declare const Resources: {
+    static: typeof staticResource;
+    preload: typeof preloadResource;
+    partial: typeof partialResource;
+};

package/dist/core/utils/resources.js

@@ -0,0 +1,69 @@
+// ============================================================================
+// Типы ресурсов
+// ============================================================================
+// ============================================================================
+// 1. Статическая стратегия
+// ============================================================================
+/**
+ * Статический ресурс - данные загружаются один раз
+ * @param items - массив элементов
+ */
+export function staticResource(items) {
+    return {
+        type: 'static',
+        load: async () => ({
+            items,
+            totalCount: items.length,
+        }),
+    };
+}
+// ============================================================================
+// 2. Предзагрузка
+// ============================================================================
+/**
+ * Предзагрузка - данные загружаются один раз при первом обращении через функцию
+ * @param loader - функция загрузки, принимает параметры и возвращает массив
+ */
+export function preloadResource(loader) {
+    let cache = null;
+    return {
+        type: 'preload',
+        load: async (params) => {
+            if (!cache) {
+                const items = await loader(params);
+                cache = {
+                    items,
+                    totalCount: items.length,
+                };
+            }
+            return cache;
+        },
+    };
+}
+// ============================================================================
+// 3. Парциональная загрузка
+// ============================================================================
+/**
+ * Парциональная загрузка - данные загружаются порциями с учетом поиска/пагинации
+ * @param loader - функция загрузки, принимает параметры и возвращает массив
+ */
+export function partialResource(loader) {
+    return {
+        type: 'partial',
+        load: async (params) => {
+            const items = await loader(params);
+            return {
+                items,
+                totalCount: items.length, // Можно расширить для поддержки серверной пагинации
+            };
+        },
+    };
+}
+// ============================================================================
+// Экспорт всех стратегий
+// ============================================================================
+export const Resources = {
+    static: staticResource,
+    preload: preloadResource,
+    partial: partialResource,
+};

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/subscription-manager.js

@@ -0,0 +1,214 @@
+/**
+ * Менеджер подписок для 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 class SubscriptionManager {
+    /**
+     * Хранилище подписок
+     * Ключ: уникальный идентификатор подписки
+     * Значение: функция отписки (dispose)
+     */
+    subscriptions = new Map();
+    /**
+     * Добавляет подписку
+     *
+     * Если подписка с таким ключом уже существует, отписывается от неё
+     * и заменяет новой. Это предотвращает утечки памяти при повторной
+     * регистрации подписки с тем же ключом.
+     *
+     * @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, dispose) {
+        // Если подписка с таким ключом уже есть, отписываемся от неё
+        if (this.subscriptions.has(key)) {
+            if (process.env.NODE_ENV !== 'production') {
+                console.warn(`[SubscriptionManager] Subscription "${key}" already exists, replacing`);
+            }
+            this.subscriptions.get(key)?.();
+        }
+        // Сохраняем новую подписку
+        this.subscriptions.set(key, dispose);
+        // Возвращаем функцию отписки
+        return () => this.remove(key);
+    }
+    /**
+     * Удаляет подписку по ключу
+     *
+     * Вызывает функцию отписки и удаляет подписку из хранилища.
+     * Если подписка с таким ключом не найдена, ничего не делает.
+     *
+     * @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) {
+        const dispose = this.subscriptions.get(key);
+        if (dispose) {
+            dispose();
+            this.subscriptions.delete(key);
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Очищает все подписки
+     *
+     * Вызывает функции отписки для всех активных подписок
+     * и очищает хранилище. Обычно используется при dispose узла формы.
+     *
+     * @example
+     * ```typescript
+     * class FieldNode {
+     *   private subscriptions = new SubscriptionManager();
+     *
+     *   dispose() {
+     *     // Отписываемся от всех effect
+     *     this.subscriptions.clear();
+     *   }
+     * }
+     * ```
+     */
+    clear() {
+        // Используем forEach для совместимости
+        this.subscriptions.forEach((dispose) => {
+            dispose();
+        });
+        this.subscriptions.clear();
+    }
+    /**
+     * Возвращает количество активных подписок
+     *
+     * Полезно для отладки утечек памяти. Если количество подписок
+     * растет без ограничений, это может указывать на то, что
+     * компоненты не отписываются должным образом.
+     *
+     * @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() {
+        return this.subscriptions.size;
+    }
+    /**
+     * Проверяет, есть ли подписка с данным ключом
+     *
+     * @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) {
+        return this.subscriptions.has(key);
+    }
+    /**
+     * Возвращает список всех ключей активных подписок
+     *
+     * Полезно для отладки: можно увидеть, какие подписки активны.
+     *
+     * @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() {
+        return Array.from(this.subscriptions.keys());
+    }
+    /**
+     * Отписывается от всех подписок (алиас для clear())
+     *
+     * Используется при dispose() узла формы для совместимости с ожидаемым API.
+     *
+     * @example
+     * ```typescript
+     * class FieldNode {
+     *   private subscriptions = new SubscriptionManager();
+     *
+     *   dispose() {
+     *     this.subscriptions.dispose();
+     *   }
+     * }
+     * ```
+     */
+    dispose() {
+        this.clear();
+    }
+}

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

@@ -0,0 +1,116 @@
+/**
+ * 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';
+/**
+ * Проверить, является ли значение любым 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;