@fozy-labs/rx-toolkit 0.5.3 → 0.6.0

package/dist/query/types/Command.types.d.ts

@@ -1,154 +0,0 @@
-import { ReadableSignalLike } from "../../signals/types";
-import { ResourceDefinition, ResourceInstance } from "./Resource.types";
-import { FallbackOnNever, OnCacheEntryAdded, OnQueryStarted } from "./shared.types";
-/**
- * Функция создания команды
- */
-export type CommandCreateFn<ARGS, RESULT, SELECTED = never> = (options: CommandCreateOptions<CommandDefinition<ARGS, RESULT, SELECTED>>) => CommandInstance<CommandDefinition<ARGS, RESULT, SELECTED>>;
-/**
- * Опции создания команды
- */
-export type CommandCreateOptions<D extends CommandDefinition> = {
-    /** Функция селектора для преобразования результата команды */
-    select?: (data: D["Result"]) => D["Selected"];
-    /** Функция выполнения команды */
-    queryFn: (args: D["Args"]) => Promise<D["Result"]>;
-    /** Связанные ресурсы */
-    link?: (link: <RD extends ResourceDefinition>(options: LinkOptions<D, RD>) => void) => void;
-    /**
-     * Время жизни кеша в миллисекундах. По умолчанию 1_000 (1 секунда).
-     * Если указано false - кеш не удаляется автоматически.
-     */
-    cacheLifetime?: number | false;
-    /**
-     * Хук, вызываемый при добавлении нового элемента в кеш.
-     * Также позволяет отследить:
-     *  - когда данные были загружены (впервые)
-     *  - когда элемент был удален из кеша
-     */
-    onCacheEntryAdded?: OnCacheEntryAdded<D["Args"], D["Data"]>;
-    /**
-     * Хук, вызываемый при старте запроса.
-     * Также позволяет отследить:
-     * - завершение запроса с результатом или ошибкой
-     */
-    onQueryStarted?: OnQueryStarted<D["Args"], D["Result"]>;
-    /**
-     * Настройка отображения в devtools
-     */
-    devtoolsName?: string | false;
-};
-/**
- * Настройки связи команды с ресурсом
- */
-export type LinkOptions<D extends CommandDefinition, RD extends ResourceDefinition> = {
-    /**
-     * Целевой ресурс, с которым связывается команда
-     * @required
-     */
-    resource: ResourceInstance<RD>;
-    /**
-     * Функция для получения аргументов ресурса из аргументов команды.
-     * Используется для определения какой именно элемент в кэше ресурса нужно обновить
-     * @required
-     */
-    forwardArgs: (args: D["Args"]) => RD["Args"];
-    /**
-     * Флаг для инвалидации (очистки) кэша ресурса после выполнения команды.
-     * При true - кэш будет очищен и ресурс будет перезагружен при следующем обращении
-     * @optional @default false
-     */
-    invalidate?: boolean;
-    /**
-     * Флаг для блокировки ресурса во время выполнения команды.
-     * При true - ресурс будет заблокирован и не сможет выполнять новые запросы
-     * @optional @default false
-     */
-    lock?: boolean;
-    /**
-     * Функция для обновления кэша ресурса после успешного выполнения команды.
-     * Получает draft объект для мутации, аргументы команды и результат команды
-     * @optional
-     */
-    update?: (tools: {
-        /** Immer draft объект для мутации кэша ресурса */
-        draft: RD["Data"];
-        /** Аргументы, с которыми была вызвана команда */
-        args: D["Args"];
-        /** Результат выполнения команды */
-        data: D["Data"];
-    }) => void | RD["Data"] | Promise<RD["Data"]>;
-    /**
-     * Функция для оптимистичного обновления кэша ресурса ДО выполнения команды.
-     * Позволяет обновить UI немедленно, до получения ответа от сервера
-     * @optional
-     */
-    optimisticUpdate?: (tools: {
-        /** Immer draft объект для мутации кэша ресурса */
-        draft: RD["Data"];
-        /** Аргументы, с которыми была вызвана команда */
-        args: D["Args"];
-    }) => void | RD["Data"] | Promise<RD["Data"]>;
-    /**
-     * Функция для создания нового элемента в кэше ресурса.
-     * Используется когда команда создает новую сущность, которую нужно добавить в кэш
-     * @optional
-     */
-    create?: (tools: {
-        /** Аргументы, с которыми была вызвана команда */
-        args: D["Args"];
-        /** Результат выполнения команды */
-        data: D["Data"];
-    }) => RD["Data"] | Promise<RD["Data"]>;
-};
-/**
- * Определение типов команды
- */
-export type CommandDefinition<A = any, R = any, S = any> = {
-    Args: A;
-    Result: R;
-    Selected: S;
-    Data: FallbackOnNever<S, R>;
-};
-/**
- * Экземпляр команды
- */
-export type CommandInstance<D extends CommandDefinition> = {
-    /** Создает агента для выполнения команды */
-    createAgent(): CommandAgentInstance<D>;
-    /**
-     * Выполняет команду с указанными аргументами
-     * @deprecated
-     */
-    mutate: (args: D["Args"]) => Promise<D["Data"]>;
-};
-/**
- * Агент для выполнения команды
- */
-export type CommandAgentInstance<D extends CommandDefinition> = {
-    /** Observable состояния выполнения команды */
-    state$: ReadableSignalLike<CommandQueryState<D>>;
-    /** Инициирует выполнение команды с указанными аргументами */
-    initiate(args: D["Args"]): void;
-    /** Создает новый агент команды */
-    createAgent(): CommandAgentInstance<D>;
-};
-/**
- * Состояние выполнения команды
- */
-export type CommandQueryState<D extends CommandDefinition> = {
-    /** Выполняется ли команда в данный момент */
-    isLoading: boolean;
-    /** Завершена ли команда */
-    isDone: boolean;
-    /** Успешно ли завершена команда (false по умолчанию) */
-    isSuccess: boolean;
-    /** Произошла ли ошибка при выполнении команды (false по умолчанию) */
-    isError: boolean;
-    /** Оригинал ошибки, если есть */
-    error: unknown | undefined;
-    /** Результат выполнения команды */
-    data: D["Data"] | undefined;
-    /** Аргументы команды */
-    args: D["Args"];
-};

package/dist/query/types/Command.types.js

@@ -1 +0,0 @@
-export {};

package/dist/query/types/Operation.types.d.ts

@@ -1,13 +0,0 @@
-import { CommandAgentInstance, CommandCreateFn, CommandCreateOptions, CommandDefinition, CommandInstance, CommandQueryState } from "./Command.types";
-/** @deprecated Use `CommandCreateFn` instead. Will be removed in v0.6.0. */
-export type OperationCreateFn<ARGS, RESULT, SELECTED = never> = CommandCreateFn<ARGS, RESULT, SELECTED>;
-/** @deprecated Use `CommandCreateOptions` instead. Will be removed in v0.6.0. */
-export type OperationCreateOptions<D extends CommandDefinition> = CommandCreateOptions<D>;
-/** @deprecated Use `CommandDefinition` instead. Will be removed in v0.6.0. */
-export type OperationDefinition<A = any, R = any, S = any> = CommandDefinition<A, R, S>;
-/** @deprecated Use `CommandInstance` instead. Will be removed in v0.6.0. */
-export type OperationInstance<D extends CommandDefinition> = CommandInstance<D>;
-/** @deprecated Use `CommandAgentInstance` instead. Will be removed in v0.6.0. */
-export type OperationAgentInstanse<D extends CommandDefinition> = CommandAgentInstance<D>;
-/** @deprecated Use `CommandQueryState` instead. Will be removed in v0.6.0. */
-export type OperationQueryState<D extends CommandDefinition> = CommandQueryState<D>;

package/dist/query/types/Operation.types.js

@@ -1 +0,0 @@
-export {};

package/dist/query/types/Resource.types.d.ts

@@ -1,129 +0,0 @@
-import { Patch as ImmerPatch } from "immer";
-import { ReadableSignalLike } from "../../signals/types";
-import { FallbackOnNever, OnCacheEntryAdded, OnQueryStarted } from "./shared.types";
-/**
- * Функция создания ресурса
- */
-export type ResourceCreateFn<ARGS, RESULT, SELECTED = never> = (options: ResourceCreateOptions<ResourceDefinition<ARGS, RESULT, SELECTED>>) => ResourceInstance<ResourceDefinition<ARGS, RESULT, SELECTED>>;
-/**
- * Опции создания ресурса
- */
-export type ResourceCreateOptions<D extends ResourceDefinition> = {
-    /** Функция селектора для преобразования данных */
-    select?: (data: D["Result"]) => D["Selected"];
-    /** Функция запроса данных */
-    queryFn: (args: D["Args"], tools: ResourceQueryFnTools) => Promise<D["Result"]>;
-    /**
-     * Время жизни кеша в миллисекундах. По умолчанию 60_000 (1 минута).
-     * Если указано false - кеш не удаляется автоматически.
-     */
-    cacheLifetime?: number | false;
-    /**
-     * Хук, вызываемый при добавлении нового элемента в кеш.
-     * Также позволяет отследить:
-     *  - когда данные были загружены (впервые)
-     *  - когда элемент был удален из кеша
-     */
-    onCacheEntryAdded?: OnCacheEntryAdded<D["Args"], D["Data"]>;
-    /**
-     * Хук, вызываемый при старте запроса.
-     * Также позволяет отследить:
-     * - завершение запроса с результатом или ошибкой
-     */
-    onQueryStarted?: OnQueryStarted<D["Args"], D["Result"]>;
-    /**
-     * Настройка отображения в devtools
-     */
-    devtoolsName?: string | false;
-    /**
-     * Сравнение аргументов между собой
-     */
-    compareArgsFn?: (args1: D["Args"], args2: D["Args"]) => boolean;
-};
-/**
- * Определение типов ресурса
- */
-export type ResourceDefinition<A = any, R = any, S = any> = {
-    Args: A;
-    Result: R;
-    Selected: S;
-    Data: FallbackOnNever<S, R>;
-};
-/** Инструменты для функции запроса */
-export type ResourceQueryFnTools = {
-    /** Сигнал для отмены запроса */
-    abortSignal?: AbortSignal;
-};
-/**
- * Экземпляр ресурса
- */
-export type ResourceInstance<D extends ResourceDefinition> = {
-    /** Создает агента для работы с ресурсом */
-    createAgent(): ResourceAgentInstance<D>;
-    /** Создает ссылку на ресурс с указанными аргументами */
-    createRef(args: D["Args"]): ResourceRefInstance<D>;
-};
-/**
- * Агент для работы с ресурсом
- */
-export type ResourceAgentInstance<D extends ResourceDefinition> = {
-    /** Observable состояния запроса */
-    state$: ReadableSignalLike<ResourceQueryState<D>>;
-    /** Инициирует запрос с указанными аргументами */
-    initiate(args: D["Args"], force?: boolean): void;
-    /** Сравнивает аргументы между собой */
-    compareArgs(args1: D["Args"], args2: D["Args"]): boolean;
-};
-/**
- * Состояние запроса ресурса
- */
-export type ResourceQueryState<D extends ResourceDefinition> = {
-    /** Инициализирован ли хотя бы один запрос */
-    isInitiated: boolean;
-    /** Загрузка */
-    isLoading: boolean;
-    /** Первая загрузка */
-    isInitialLoading: boolean;
-    /** Завершен ли запрос */
-    isDone: boolean;
-    /** Успешно ли завершен последний запрос (false по умолчанию) */
-    isSuccess: boolean;
-    /** Произошла ли ошибка последнего запроса (false по умолчанию) */
-    isError: boolean;
-    /** Заблокирован ли ресурс */
-    isLocked: boolean;
-    /** Перезагружается ли ресурс */
-    isReloading: boolean;
-    /** Оригинал ошибки, если есть */
-    error: unknown | undefined;
-    /** Данные, полученные в результате запроса (или select данных) */
-    data: D["Data"] | undefined;
-    /** Аргументы запроса */
-    args: D["Args"] | undefined;
-};
-/**
- * Транзакция ресурса
- */
-export type ResourceTransaction = {
-    patches: ImmerPatch[];
-    inversePatches: ImmerPatch[];
-    status: "pending" | "committed" | "aborted";
-    abort(): void;
-    commit(): void;
-};
-/**
- * Эте не ссылка в "классическом" понимании, а абстракция
- * для работы с элементом кеша ресурса.
- */
-export type ResourceRefInstance<D extends ResourceDefinition> = {
-    get has(): boolean;
-    lock(): {
-        unlock: () => void;
-    };
-    unlockOne(): void;
-    patch(patchFn: (data: D["Data"]) => void): ResourceTransaction | null;
-    invalidate(): void;
-    create(data: D["Data"]): void;
-};
-/** @deprecated Use ResourceRefInstance. Will be removed in v0.6.0 */
-export type ResourceRefInstanse<D extends ResourceDefinition> = ResourceRefInstance<D>;

package/dist/query/types/Resource.types.js

@@ -1 +0,0 @@
-export {};

package/dist/query/types/shared.types.d.ts

@@ -1,26 +0,0 @@
-import { Subject } from "rxjs";
-export type Prettify<T> = {
-    [KeyType in keyof T]: T[KeyType];
-} & {};
-export type FallbackOnNever<T, F> = [T] extends [never] ? F : T;
-export type CacheEntryAddedTools<DATA> = {
-    /** Функция для ожидания загрузки данных в кеш */
-    $cacheDataLoaded: Promise<void>;
-    /** Функция для ожидания удаления кеша */
-    $cacheEntryRemoved: Promise<void>;
-    dataChanged$: Subject<DATA>;
-};
-export type QueryStartedTools<DATA> = {
-    /** Функция для уведомления об успешном завершении запроса */
-    $queryFulfilled: Promise<{
-        data: DATA;
-        error: undefined;
-        isError: false;
-    } | {
-        data: undefined;
-        error: unknown;
-        isError: true;
-    }>;
-};
-export type OnCacheEntryAdded<ARGS, DATA> = (args: ARGS, tools: CacheEntryAddedTools<DATA>) => void;
-export type OnQueryStarted<ARGS, DATA> = (args: ARGS, tools: QueryStartedTools<DATA>) => void;

package/dist/query/types/shared.types.js

@@ -1 +0,0 @@
-export {};

package/dist/query-v2/api/createApi.d.ts

@@ -1,10 +0,0 @@
-import type { IApi, ICreateApiOptions } from "../../query-v2/types/api.types";
-import type { IPlugin } from "../../query-v2/types/plugin.types";
-/**
- * Create a query-v2 API instance — the root entry point for managing resources, snapshots, and plugins.
- *
- * @param options - Configuration for the API instance (keyPrefix, plugins, snapshot, cache settings).
- * @returns API instance with `createResource`, `resetAll`, and `getSnapshot` methods.
- * @see docs/query-v2/README.md
- */
-export declare function createApi<TPlugins extends IPlugin[] = []>(options?: ICreateApiOptions<TPlugins>): IApi<TPlugins>;

package/dist/query-v2/api/createApi.js

@@ -1,83 +0,0 @@
-import { ResourceV2 } from "../../query-v2/core/resource/ResourceV2";
-import { getSnapshot, hydrateSnapshot } from "../../query-v2/snapshot/Snapshot";
-const DEFAULT_CACHE_LIFETIME = 60_000;
-const DEFAULT_MAX_SNAPSHOT_DATA_AGE = 300_000; // 5 minutes
-/**
- * Create a query-v2 API instance — the root entry point for managing resources, snapshots, and plugins.
- *
- * @param options - Configuration for the API instance (keyPrefix, plugins, snapshot, cache settings).
- * @returns API instance with `createResource`, `resetAll`, and `getSnapshot` methods.
- * @see docs/query-v2/README.md
- */
-export function createApi(options = {}) {
-    const { keyPrefix = null, keyStrategy = "serialize", serializeArgs, compareArg, initialSnapshot = null, cacheLifetime = DEFAULT_CACHE_LIFETIME, plugins = [], maxSnapshotDataAge = DEFAULT_MAX_SNAPSHOT_DATA_AGE, doCacheArgs = false, } = options;
-    // ADR-6: Generic registry (Map, not typed to resources only)
-    const registry = new Map();
-    // Plugin initialization: call install() once per plugin
-    const pluginContext = {
-        get api() {
-            return api;
-        },
-        keyStrategy,
-    };
-    for (const plugin of plugins) {
-        plugin.install(pluginContext);
-    }
-    const api = {
-        createResource(resourceOptions) {
-            // Merge: resource options override API defaults
-            const mergedConfig = {
-                key: resourceOptions.key,
-                keyPrefix: keyPrefix ?? undefined,
-                keyStrategy,
-                queryFn: resourceOptions.queryFn,
-                onCacheEntryAdded: resourceOptions.onCacheEntryAdded,
-                onQueryStarted: resourceOptions.onQueryStarted,
-                serializeArgs: resourceOptions.serializeArgs ?? serializeArgs,
-                compareArg: resourceOptions.compareArg ?? compareArg,
-                cacheLifetime: resourceOptions.cacheLifetime ?? cacheLifetime,
-                beforeDevtoolsPush: resourceOptions.beforeDevtoolsPush,
-                maxSnapshotDataAge: resourceOptions.maxSnapshotDataAge ?? maxSnapshotDataAge,
-                doCacheArgs: resourceOptions.doCacheArgs ?? doCacheArgs,
-            };
-            // Validate unique key (for serialize strategy, key is expected for snapshot)
-            const resourceKey = mergedConfig.key;
-            if (resourceKey != null) {
-                if (registry.has(resourceKey)) {
-                    throw new Error(`Duplicate resource key "${resourceKey}". Each resource must have a unique key.`);
-                }
-            }
-            // Create resource
-            const resource = new ResourceV2(mergedConfig);
-            // Apply plugin augmentations
-            const augmentations = {};
-            for (const plugin of plugins) {
-                const pluginContributions = plugin.augmentResource(resource, resourceOptions);
-                Object.assign(augmentations, pluginContributions);
-            }
-            // Create the augmented resource
-            const augmentedResource = Object.assign(resource, augmentations);
-            // Register resource
-            if (resourceKey != null) {
-                registry.set(resourceKey, resource);
-            }
-            // Hydrate from initial snapshot if available
-            if (initialSnapshot && resourceKey != null) {
-                const snapshotMaxAge = mergedConfig.maxSnapshotDataAge ?? maxSnapshotDataAge;
-                const singleResourceRegistry = new Map();
-                singleResourceRegistry.set(resourceKey, resource);
-                hydrateSnapshot(initialSnapshot, singleResourceRegistry, keyPrefix, snapshotMaxAge);
-            }
-            return augmentedResource;
-        },
-        resetAll() {
-            for (const [, resource] of registry) {
-                resource.resetCache();
-            }
-        },
-        getSnapshot() {
-            return getSnapshot(registry, keyPrefix, keyStrategy);
-        },
-    };
-    return api;
-}

package/dist/query-v2/core/common/CacheEntry.d.ts

@@ -1,29 +0,0 @@
-import type { TBeforeDevtoolsPushFn } from "../../../query-v2/types/shared.types";
-import type { TMachineInstance } from "../machines/Machine";
-export interface CacheEntryOptions {
-    keyParts?: string[];
-    beforeDevtoolsPush?: TBeforeDevtoolsPushFn<unknown>;
-}
-/**
- * Cache entry wrapping a reactive signal over a state machine instance.
- * Represents a single cached query result with its full lifecycle (idle → pending → success/error).
- */
-export declare class CacheEntry<TData = unknown, TError = Error> {
-    private readonly _signal;
-    private readonly _onClean$;
-    private _completed;
-    constructor(initialMachine: TMachineInstance<TData, TError>, options?: CacheEntryOptions);
-    /** Reactive accessor for the current machine state — reading this registers a signal dependency. */
-    get machine$(): () => TMachineInstance<TData, TError>;
-    /** Non-reactive read of the current machine state (does not register a signal dependency). */
-    peek(): TMachineInstance<TData, TError>;
-    /** Transition to a new machine state. No-op if the entry has been completed. */
-    set(machine: TMachineInstance<TData, TError>): void;
-    get onClean$(): {
-        subscribe: (cb: () => void) => {
-            unsubscribe: () => void;
-        };
-    };
-    /** Complete the entry — aborts pending patches, resets to idle, and notifies cleanup listeners. */
-    complete(): void;
-}

package/dist/query-v2/core/common/CacheEntry.js

@@ -1,71 +0,0 @@
-import { Subject } from "rxjs";
-import { Signal } from "../../../signals";
-import { MachineIdle } from "../machines/MachineIdle";
-import { MachineWithData } from "../machines/MachineWithData";
-/**
- * Cache entry wrapping a reactive signal over a state machine instance.
- * Represents a single cached query result with its full lifecycle (idle → pending → success/error).
- */
-export class CacheEntry {
-    _signal;
-    _onClean$ = new Subject();
-    _completed = false;
-    constructor(initialMachine, options) {
-        const userCallback = options?.beforeDevtoolsPush;
-        // Default beforeDevtoolsPush projects machine → machine.state for devtools (ADR-8).
-        // The push function types are mismatched intentionally: we push plain state objects
-        // instead of machine instances to keep devtools output JSON-friendly.
-        const beforeDevtoolsPush = ((newValue, push) => {
-            const machine = newValue;
-            const state = machine.state;
-            if (userCallback) {
-                userCallback(state, push);
-            }
-            else {
-                push(state);
-            }
-        });
-        this._signal = Signal.state(initialMachine, {
-            key: options?.keyParts?.join("/"),
-            beforeDevtoolsPush,
-        });
-    }
-    /** Reactive accessor for the current machine state — reading this registers a signal dependency. */
-    get machine$() {
-        return this._signal;
-    }
-    /** Non-reactive read of the current machine state (does not register a signal dependency). */
-    peek() {
-        return this._signal.peek();
-    }
-    /** Transition to a new machine state. No-op if the entry has been completed. */
-    set(machine) {
-        if (this._completed)
-            return;
-        this._signal.set(machine);
-    }
-    get onClean$() {
-        return {
-            subscribe: (cb) => {
-                const sub = this._onClean$.subscribe(cb);
-                return { unsubscribe: () => sub.unsubscribe() };
-            },
-        };
-    }
-    /** Complete the entry — aborts pending patches, resets to idle, and notifies cleanup listeners. */
-    complete() {
-        if (this._completed)
-            return;
-        this._completed = true;
-        // Layer 3 (ADR-4): Abort all pending patches on MachineWithData instances
-        const current = this._signal.peek();
-        if (current instanceof MachineWithData) {
-            current.abortAllPendingPatches();
-        }
-        // Set to idle to release data references
-        this._signal.set(MachineIdle.create());
-        // Notify cleanup listeners
-        this._onClean$.next();
-        this._onClean$.complete();
-    }
-}

package/dist/query-v2/core/common/CacheMap.d.ts

@@ -1,38 +0,0 @@
-import type { ICacheMapOptions } from "../../../query-v2/types/cache.types";
-import type { CacheEntry } from "./CacheEntry";
-declare class SerializedCacheMap<TArgs, TData, TError = Error> {
-    private readonly _map;
-    private readonly _serializeArgs;
-    private readonly _argsMemo;
-    constructor(serializeArgs: (args: unknown) => string, doCacheArgs: boolean);
-    private _serialize;
-    get(args: TArgs): CacheEntry<TData, TError> | undefined;
-    set(args: TArgs, entry: CacheEntry<TData, TError>): void;
-    getOrCreate(args: TArgs, factory: () => CacheEntry<TData, TError>): CacheEntry<TData, TError>;
-    delete(args: TArgs): boolean;
-    has(args: TArgs): boolean;
-    values(): Iterable<CacheEntry<TData, TError>>;
-    entries(): Iterable<[string, CacheEntry<TData, TError>]>;
-    clear(): void;
-    get size(): number;
-}
-declare class CompareCacheMap<TArgs, TData, TError = Error> {
-    private readonly _items;
-    private readonly _compareArg;
-    constructor(compareArg: (a: unknown, b: unknown) => boolean);
-    private _findIndex;
-    get(args: TArgs): CacheEntry<TData, TError> | undefined;
-    set(args: TArgs, entry: CacheEntry<TData, TError>): void;
-    getOrCreate(args: TArgs, factory: () => CacheEntry<TData, TError>): CacheEntry<TData, TError>;
-    delete(args: TArgs): boolean;
-    has(args: TArgs): boolean;
-    values(): Iterable<CacheEntry<TData, TError>>;
-    entries(): Iterable<[TArgs, CacheEntry<TData, TError>]>;
-    clear(): void;
-    get size(): number;
-}
-export type TCacheMapInstance<TArgs, TData, TError = Error> = SerializedCacheMap<TArgs, TData, TError> | CompareCacheMap<TArgs, TData, TError>;
-export declare const CacheMap: {
-    create<TArgs, TData, TError = Error>(options: ICacheMapOptions<TArgs>): TCacheMapInstance<TArgs, TData, TError>;
-};
-export {};