@pravosleva/reactive-engine 0.4.2-beta → 1.0.1-beta

package/dist/index.d.ts

@@ -1,605 +1,2 @@
-import { default as default_2 } from 'react';
-import { useEffect } from 'react';
-import { useState } from 'react';
-
-export declare abstract class AbstractService {
-    protected engine: ReactiveEngine;
-    constructor(engine: ReactiveEngine);
-    protected createNumericSignal(val: number, name: string): Signal<number>;
-    protected createComputed<T>(fn: () => T): Computed<T>;
-    protected createSignal<T>(val: T, name?: string): Signal<T>;
-    protected onInit(): void;
-}
-
-export declare const BaseREService: typeof AbstractService;
-
-export declare abstract class BaseREServiceEnhanced {
-    protected engine: ReactiveEngine;
-    constructor(engine: ReactiveEngine);
-    protected onInit(): void;
-}
-
-declare interface CacheOptions {
-    /** Время жизни кэша в миллисекундах. По умолчанию 5 минут (300000 мс) */
-    ttl?: number;
-}
-
-export declare type CleanupFn = () => void;
-
-/**
- * Интерфейс для вычисляемого значения.
- * @template T
- * @interface Computed<T>
- */
-export declare interface Computed<T> {
-    /**
-     * Только читаемое значение вычисляемого значения.
-     * @type {T}
-     */
-    readonly value: T;
-    /**
-     * Подписка на изменение вычисляемого значения.
-     * @function subscribe
-     * @param {Function} cb - Коллбек функция для обработки изменения.
-     * @returns {CleanupFn} - Функция для очистки подписки.
-     */
-    subscribe: (cb: (val: T) => void) => CleanupFn;
-    /**
-     * Принудительное уничтожение вычисляемого значения и его эффекта для предотвращения утечек памяти.
-     */
-    destroy: () => void;
-}
-
-/**
- * Функция высшего порядка (HOC) для автоматического отслеживания сигналов внутри React-компонента.
- * Полный аналог `observer` из MobX.
- *
- * @template P - Объект пропсов оборачиваемого компонента.
- * @param engine - Экземпляр реактивного движка {@link ReactiveEngine}.
- * @returns Функция-декоратор, преобразующая обычный компонент в реактивный.
- *
- * @example
- * ```tsx
- * import { createObserver } from '@pravosleva/reactive-engine';
- * import { engine } from '~/utils/ReactiveEngine'; // Ваш локальный экземпляр движка
- *
- * const observer = createObserver(engine);
- * const counterSignal = engine.signal(0);
- *
- * // Компонент автоматически перерисуется при изменении counterSignal.value
- * export const CounterView = observer(() => {
- *   return (
- *     <div>
- *       <p>Счетчик: {counterSignal.value}</p>
- *       <button onClick={() => counterSignal.value++}>+1</button>
- *     </div>
- *   );
- * });
- * ```
- *
- * @source
- */
-export declare const createObserver: (engine: ReactiveEngine) => <P extends object>(Component: default_2.ComponentType<P>) => default_2.ComponentType<P>;
-
-/**
- * Фабрика для создания инлайн-компонента `<Observer>`.
- *
- * @param engine - Экземпляр реактивного движка {@link ReactiveEngine}.
- * @returns Специальный React-компонент для точечной изоляции реактивных обновлений в JSX.
- *
- * @example
- * ```tsx
- * import { createObserverComponent, engine } from '@pravosleva/reactive-engine';
- *
- * const Observer = createObserverComponent(engine);
- * const priceSignal = engine.signal(100);
- *
- * export const MyComponent = () => {
- *   return (
- *     <div>
- *       <h1>Статический тяжелый контент (не перерисовывается)</h1>
- *       <Observer>
- *         {() => <span>Живая цена: {priceSignal.value}</span>}
- *       </Observer>
- *     </div>
- *   );
- * };
- * ```
- */
-export declare const createObserverComponent: (engine: ReactiveEngine) => ({ children }: ObserverProps) => any;
-
-declare interface DebounceOptions {
-    /** Задержка в миллисекундах. По умолчанию 300 мс */
-    delay?: number;
-}
-
-export declare type EffectFn = () => CleanupFn | void;
-
-export declare type Factory<T> = (engine: ReactiveEngine) => T;
-
-export declare interface IEffect {
-    run: () => void;
-    label?: string;
-    cleanups: Set<CleanupFn>;
-}
-
-/**
- * Функция для очистки эффекта.
- * @typedef {() => void} CleanupFn
- */
-/**
- * Функция эффекта, которая может возвращать функцию очистки.
- * @typedef {() => CleanupFn | void} EffectFn
- */
-/**
- * Токен для зависимости.
- * @typedef {string | symbol | { new(engine: ReactiveEngine, ...args: any[]): T }} Token<T>
- */
-/**
- * Фабрика для создания сервиса.
- * @template T
- * @typedef {(engine: ReactiveEngine) => T} Factory<T>
- */
-/**
- * Интерфейс для эффекта.
- * @interface IEffect
- */
-export declare interface IEffect {
-    /**
-     * Запуск эффекта.
-     * @function run
-     * @returns {void}
-     */
-    run: () => void;
-    /**
-     * Коллекция функций очистки.
-     * @type {Set<CleanupFn>}
-     */
-    cleanups: Set<CleanupFn>;
-}
-
-declare interface LongPollingOptions {
-    /** Коллбэк для инкремента реактивного тика (перехода на следующую итерацию поллинга) */
-    onNextTick: () => void;
-    /**
-     * Коллбэк, вызываемый при возникновении сетевой ошибки.
-     * Позволяет внешней системе узнать о сбое и текущем времени ожидания до следующей попытки.
-     *
-     * @param {number} delayMs - Текущая задержка Exponential Backoff в миллисекундах перед следующим запросом.
-     * @param {() => void} onRetryScheduled - Коллбэк-триггер. Должен быть вызван один раз, чтобы
-     * просигнализировать декоратору, что шаг зафиксирован и задержка для следующей ошибки может быть увеличена.
-     */
-    onError: (delayMs: number, onRetryScheduled: () => void) => void;
-    /** Пауза перед открытием следующего соединения в миллисекундах. По умолчанию 500 мс */
-    delay?: number;
-    /** Стартовая задержка Exponential Backoff в миллисекундах. По умолчанию 2000 мс */
-    errorInitialDelay?: number;
-    /** Потолок задержки Exponential Backoff в миллисекундах. По умолчанию 8000 мс */
-    errorMaxDelay?: number;
-    /** Внешний сигнал для жесткой остановки рекурсивных таймаутов */
-    externalSignal?: AbortSignal;
-}
-
-declare interface ObservableItem<T> {
-    readonly value: T;
-    subscribe: (cb: (val: T) => void) => CleanupFn;
-    destroy?: () => void;
-}
-
-declare interface ObservableItem_2<T> {
-    readonly value: T;
-    subscribe: (cb: (val: T) => void) => CleanupFn;
-    destroy?: () => void;
-}
-
-/**
- * Свойства для инлайн-компонента {@link Observer}.
- */
-declare interface ObserverProps {
-    /**
-     * Функция-рендер, возвращающая JSX-разметку.
-     * Сигналы, прочитанные внутри этого коллбека, будут автоматически отслеживаться.
-     */
-    children: () => default_2.ReactNode;
-}
-
-/**
- * Класс реактивного движка.
- */
-export declare class ReactiveEngine {
-    private activeEffect;
-    private isBatching;
-    private pendingEffects;
-    private services;
-    private factories;
-    private proxyCache;
-    private allEffects;
-    /**
-     * Коллбек для уведомления об изменении сигнала.
-     * Использование unknown вместо any гарантирует безопасную работу с типами prev/next.
-     */
-    onSignalChange?: (name: string, next: unknown, prev: unknown) => void;
-    private reactAdapters;
-    /**
-     * DI: Регистрация зависимости.
-     * @template T
-     * @function provide
-     * @param {Token<T>} token - Токен для зависимости.
-     * @param {T | Factory<T>} valueOrFactory - Значение или фабрика для создания сервиса.
-     * @returns {void}
-     * @source
-     */
-    provide<T>(token: Token<T>, valueOrFactory: T | Factory<T>): void;
-    /**
-     * DI: Инъекция; Получение сервиса по токену.
-     * @template T
-     * @function inject
-     * @param {Token<T>} token - Токен для зависимости.
-     * @returns {T} - Сервис.
-     * @source
-     */
-    inject<T>(token: Token<T>): T;
-    /**
-     * Создание сигнала.
-     * @template T
-     * @function signal
-     * @param {T} initialValue - Начальное значение сигнала.
-     * @param {string | SignalOptions<T>} [optionsOrName] - Имя или опции сигнала.
-     * @returns {Signal<T>} - Сигнал.
-     * @source
-     */
-    signal<T>(initialValue: T, optionsOrName?: string | SignalOptions<T>): Signal<T>;
-    /**
-     * Создание эффекта.
-     * @function effect
-     * @param {EffectFn} fn - Функция эффекта.
-     * @param {string} [label] - Необязательная метка для логирования и отладки.
-     * @returns {CleanupFn} - Функция для очистки эффекта.
-     * @source
-     */
-    effect(fn: EffectFn, label?: string): CleanupFn;
-    private computedCache;
-    private cleanupRegistry;
-    /**
-     * Создание вычисляемого значения.
-     * @template T
-     * @function computed
-     * @param {Function} fn - Функция для вычисления значения.
-     * @param {string} [signalName] - Имя сигнала.
-     * @returns {Computed<T>} - Вычисляемое значение с методом destroy.
-     * @source
-     */
-    computed<T>(fn: () => T, signalName?: string): Computed<T>;
-    /**
-     * Создание реактивного объекта (Proxy).
-     * @template T
-     * @function reactive
-     * @param {T} target - Целевой объект для проксирования.
-     * @param {string} [name] - Имя проксируемого объекта.
-     * @returns {T} - Реактивный объект.
-     * @source
-     */
-    reactive<T extends object>(target: T, name?: string): T;
-    /**
-     * Группировка изменений. (Оставил для обратной совместимости)
-     * @function batch
-     * @param {Function} fn - Функция для выполнения в группе.
-     * @returns {void}
-     * @source
-     */
-    batch(fn: () => void): void;
-    /**
-     * Вспомогательная функция для задержки (sleep), чувствительная к AbortSignal
-     *
-     * Вызов new DOMException('Aborted', 'AbortError') гарантирует,
-     * что ваша кастомная пауза между ретраями this.delay притворяется для движка JavaScript
-     * точно таким же нативным процессом отмены, как и fetch().
-     * Это делает реактивное ядро бесшовным и избавляет от необходимости
-     * писать кучу разных проверок под каждый тип ошибки.
-     */
-    private delay;
-    /**
-     * Создание асинхронного ресурса. Типы на входе: <T - формат ответа, S - источник изменений (сигнал либо computed-кортеж из зачений сигналов через конструкцию `.value`)>
-     *
-     * Explained 👉 {@link https://github.com/garage-13/reactive-engine/blob/main/README_EN.md#1-async-resources-dependent-on-multiple-signals}
-     *
-     * @template T, S
-     * @see {@link https://github.com/garage-13/reactive-engine/blob/main/examples/200-resource/Example200.tsx Реализация базового компонента Example200}
-     * @see {@link https://github.com/garage-13/reactive-engine/blob/main/examples/201-multi-resource/service.secondary.ts Сложный пример зависимости ресурсов через computed}
-     * @function resource
-     * @param {Function} fetcher - Асинхронная функция для загрузки данных.
-     * @param {{ value: S }} [source] - Источник данных.
-     * @param {string | ResourceOptions<T>} [optionsOrName] - Имя сигнала или объект конфигурации `{ name: string; validate: (res) => boolean | string; resetDataOnSourceChange?: boolean }`.
-     * @returns {Resource<T>} - Асинхронный ресурс.
-     *
-     * @example
-     * // Базовый вызов со строкой (обратная совместимость):
-     * const res = engine.resource(fetcher, source, 'my-resource-name');
-     *
-     * @example
-     * // Современный вызов с валидацией ответа:
-     * const res = engine.resource(fetcher, source, {
-     *   name: 'my-resource-name',
-     *   resetDataOnSourceChange: true, // true by default
-     *   responseValidate: (data) => !!data || 'Данные пусты', // Проверяйте формат в соотв. с дженериком
-     * });
-     *
-     * @example
-     * // (Экспериментальная фича)
-     * // В теле fetcher можно выкинуть ошибку в виде
-     * // `throw new Error('[THROW_CUSTOM_VALIDATION_ERROR_NO_RETRY=1][MESSAGE=Your msg]')`
-     * // Причина: Особенности внутренней реализации определения харакрера ошибки и необходимость делать retry (если такая опция передана)
-     * // Рекомендуем вместо этого использовать `validateBeforeFetch` в опциях при создании ресурса.
-     * const res = engine.resource(
-     *   async (counterValue, abortSignal) => {
-     *     if (counterValue === 0)
-     *       throw new Error([
-     *         '[THROW_CUSTOM_VALIDATION_ERROR_NO_RETRY=1]', // Иначе запустится механизм retry (напр. по причине отсутствия сети, далее в этом же примере)
-     *         `[MESSAGE=Stop for count value ${counterValue} - excepted from fetcher fn body]`,
-     *       ].join(' '))
-     *     const res = await fetch(
-     *       [
-     *         `${BASE_API_URL}/profile/search`,
-     *         '?',
-     *         [
-     *           `counter=${counterValue}`,
-     *           '_responseDelay=2000',
-     *         ].join('&')
-     *       ].join(''),
-     *       { signal: abortSignal }
-     *     )
-     *     if (!res.ok) throw new Error(`HTTP error! status: ${res.status}`)
-     *     return res.json()
-     *   },
-     *   this.counter,
-     * )
-     * @source
-     */
-    resource<T, S = void>(fetcher: (source: S, signal: AbortSignal) => Promise<T>, source?: {
-        value: S;
-    }, optionsOrName?: string | ResourceOptions<T, S>): Resource<T>;
-    /**
-     * Выполняет функцию без отслеживания зависимостей.
-     * @template T
-     * @function untrack
-     * @param {Function} fn - Функция для выполнения.
-     * @returns {T} - Результат выполнения функции.
-     * @source
-     */
-    untrack<T>(fn: () => T): T;
-    /**
-     * Установка адаптеров React.
-     * @function setReactAdapters
-     * @param {Function} useState - Функция useState из React.
-     * @param {Function} useEffect - Функция useEffect из React.
-     * @returns {void}
-     * @source
-     */
-    setReactAdapters(useState: typeof useState, useEffect: typeof useEffect): void;
-    /**
-     * Использование реактивного значения в React компоненте.
-     * @template T
-     * @function use
-     * @param {{ value: T; subscribe: (cb: (v: T) => void) => CleanupFn }} item - Реактивный объект.
-     * @returns {T} - Значение реактивного объекта.
-     * @source
-     */
-    use<T>(item: {
-        value: T;
-        subscribe: (cb: (v: T) => void) => CleanupFn;
-    }): T;
-    /**
-     * Безопасное выполнение функции.
-     * @private
-     * @function safeRun
-     * @param {IEffect} effect - Эффект.
-     * @param {Function} fn - Функция для выполнения.
-     * @returns {void}
-     * @source
-     */
-    private safeRun;
-}
-
-declare type ReactiveInput<T> = ObservableItem<T> | (() => ObservableItem<T>);
-
-declare type ReactiveInput_2<T> = ObservableItem_2<T> | (() => ObservableItem_2<T>);
-
-/**
- * Интерфейс для ресурса.
- * @template T
- * @interface Resource<T>
- */
-export declare interface Resource<T> extends ResourceState<T> {
-    /**
-     * Перезагрузка ресурса.
-     * @function refetch
-     * @returns {void}
-     */
-    refetch: () => void;
-    /**
-     * Подписка на изменение состояния ресурса.
-     * @function subscribe
-     * @param {Function} cb - Коллбек функция для обработки изменения.
-     * @returns {CleanupFn} - Функция для очистки подписки.
-     */
-    subscribe: (cb: (val: ResourceState<T>) => void) => CleanupFn;
-    /**
-     * Только читаемое состояние ресурса.
-     * @type {ResourceState<T>}
-     */
-    readonly value: ResourceState<T>;
-}
-
-export declare interface ResourceOptions<T, S> {
-    name: string;
-    /** Автоматически сбрасывать data в null при изменении source. По умолчанию: true */
-    resetDataOnSourceChange?: boolean;
-    /** Функция для валидации успешного ответа сервера перед его сохранением в стейт.
-     *
-     * Варианты возвращаемого значения:
-     * - true 👉 все ок
-     * - false 👉 в error попадет стандартный текст ошибки
-     * - string 👉 попадет в поле error
-     * */
-    responseValidate?: (responseData: T) => boolean | string;
-    /** Функция валидации входных зависимостей (source) перед запуском fetch.
-     * Если возвращает false или string (текст ошибки) — запрос и ретраи блокируются. */
-    validateBeforeFetch?: (sourceValue: S) => boolean | string;
-    /** Настройка лимита повторов retry. */
-    retryCount?: number;
-    /** Настройка задержки первого повтора retry. */
-    retryDelay?: number;
-    /** Включить экспоненциальное увеличение задержки (каждая попытка ждет в 2 раза дольше). По умолчанию: false */
-    isExponentialBackoffEnabled?: boolean;
-    /** Максимальный лимит ожидания между попытками в миллисекундах. По умолчанию: 30000 (30 секунд) */
-    maxRetryDelay?: number;
-    /** Максимальное время ожидания ответа сервера в миллисекундах. По умолчанию: отсутствует (бесконечно) */
-    timeout?: number;
-}
-
-export declare interface ResourceState<T> {
-    data: T | null;
-    loading: boolean;
-    error: any | null;
-}
-
-/**
- * Интерфейс для состояния ресурса.
- * @template T Data format
- * @interface ResourceState<T>
- */
-export declare interface ResourceState<T> {
-    /**
-     * Данные ресурса.
-     * @type {T | null}
-     */
-    data: T | null;
-    /**
-     * Состояние загрузки ресурса.
-     * @type {boolean}
-     */
-    loading: boolean;
-    /**
-     * Ошибка ресурса.
-     * @type {any | null}
-     */
-    error: any | null;
-    /** Флаг активного процесса повторных попыток после сбоя сети */
-    isRetrying: boolean;
-}
-
-/**
- * Интерфейс для сигнала.
- * @template T
- * @interface Signal<T>
- */
-export declare interface Signal<T> {
-    /**
-     * Значение сигнала.
-     * @type {T}
-     */
-    value: T;
-    /**
-     * Подписка на изменение значения сигнала.
-     * @function subscribe
-     * @param {Function} cb - Коллбек функция для обработки изменения.
-     * @returns {CleanupFn} - Функция для очистки подписки.
-     */
-    subscribe: (cb: (val: T) => void) => CleanupFn;
-}
-
-/**
- * Интерфейс для опций сигнала.
- * @template T
- * @interface SignalOptions<T>
- */
-export declare interface SignalOptions<T> {
-    /**
-     * Имя сигнала.
-     * @type {string}
-     */
-    name?: string;
-    /**
-     * Валидатор значения сигнала.
-     * @function validate
-     * @param {T} val - Значение для валидации.
-     * @returns {boolean | string} - Результат валидации.
-     */
-    validate?: (val: T) => boolean | string;
-}
-
-declare interface ThrottleAndCacheOptions {
-    /** Интервал троттлинга в миллисекундах. По умолчанию 300 мс */
-    limit?: number;
-    /** Время жизни кэша в миллисекундах. По умолчанию 5 минут (300000 мс) */
-    ttl?: number;
-}
-
-declare interface ThrottleOptions {
-    /** Интервал троттлинга в миллисекундах. По умолчанию 300 мс */
-    limit?: number;
-}
-
-export declare type Token<T> = string | symbol | {
-    new (engine: ReactiveEngine, ...args: any[]): T;
-};
-
-/**
- * Универсальный хук для подписки на изменения Signal, Computed или Resource.
- * @template T Тип данных внутри реактивного контейнера
- * @param {Signal<T> | { subscribe: (cb: (val: T) => void) => CleanupFn }} signal Объект подписки
- * @param {(val: T) => void} callback Функция обратного вызова, принимающая новое значение
- * @source
- */
-export declare const useReactiveSubscription: <T>(signal: Pick<Signal<T>, "subscribe">, callback: (val: T) => void) => void;
-
-/**
- * Хук для извлечения значения из Signal/Computed/Resource и авто-ререндера компонента.
- * Поддерживает React 18+ и ленивые фабрики без утечек памяти.
- *
- * @source
- */
-export declare const useReactiveValue: <T>(input: ReactiveInput<T>) => T;
-
-/**
- * Fallback хук для извлечения значения из сигналов. Поддерживает React 16.8+.
- *
- * @source
- */
-export declare const useReactiveValue0: <T>(input: ReactiveInput_2<T>) => T;
-
-/**
- * Декоратор для создания кэширующего fetcher-а для engine.resource
- * @param fetcher Оригинальная асинхронная функция запроса
- * @param options Настройки кэширования
- * @source
- */
-export declare const withCache: <S, T>(fetcher: (source: S, signal: AbortSignal) => Promise<T>, options?: CacheOptions) => (source: S, signal: AbortSignal) => Promise<T>;
-
-/**
- * Декоратор для создания дебаунсящего fetcher-а для engine.resource
- * @param fetcher Оригинальная асинхронная функция запроса
- * @param options Настройки дебаунса
- */
-export declare const withDebounce: <S, T>(fetcher: (source: S, signal: AbortSignal) => Promise<T>, options?: DebounceOptions) => (source: S, signal: AbortSignal) => Promise<T>;
-
-/**
- * Адаптированный декоратор лонг-поллинга для engine.resource.
- * Принимает строго два аргумента: асинхронную функцию и конфиг-объект.
- */
-export declare const withLongPolling: <S, T>(fetcher: (source: S, signal: AbortSignal) => Promise<T>, options: LongPollingOptions) => (source: S, signal: AbortSignal) => Promise<T>;
-
-/**
- * Декоратор для создания троттлящего fetcher-а для engine.resource
- * @param fetcher Оригинальная асинхронная функция запроса
- * @param options Настройки троттлинга
- */
-export declare const withThrottle: <S, T>(fetcher: (source: S, signal: AbortSignal) => Promise<T>, options?: ThrottleOptions) => (source: S, signal: AbortSignal) => Promise<T>;
-
-/**
- * Комбинированный декоратор: сначала применяет троттлинг к частоте вызовов,
- * а затем проверяет кэш перед отправкой реального fetcher-запроса.
- */
-export declare const withThrottleAndCache: <S, T>(fetcher: (source: S, signal: AbortSignal) => Promise<T>, options?: ThrottleAndCacheOptions) => (source: S, signal: AbortSignal) => Promise<T>;
-
-export { }
+export * from './core/index.js'
+export {}

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,QAAQ,CAAA;AACtB,cAAc,cAAc,CAAA"}