@fozy-labs/rx-toolkit 0.4.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 fozykit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,131 @@
+# RxToolkit
+
+> Фреймворк агностик набор инструментов для **реактивного** управления состоянием, построенный поверх RxJS.
+
+[![npm version](https://badge.fury.io/js/%40fozy-labs%2Frx-toolkit.svg)](https://badge.fury.io/js/%40fozy-labs%2Frx-toolkit)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue.svg)](https://www.typescriptlang.org/)
+[![RxJS](https://img.shields.io/badge/RxJS-7.8-purple.svg)](https://rxjs.dev/)
+## 📦 Установка
+
+```bash
+npm install @fozy-labs/rx-toolkit rxjs
+```
+
+## 🎯 Цель
+
+RxJS действительно мощный инструмент реактивного программирования, 
+он удобен когда мы работаем с потоком событий, но когда речь заходит о состоянии приложения,
+из-за асинхронной природы rx'а, его использование становится сложным и громоздким, не говоря уже о кешировании данных
+(хотя некоторые разработчики "продают" rxjs, как альтернативу Query библиотекам,
+на самом деле реализация подобного функционала выльется в создание отдельной библиотеки).
+
+RxToolkit решает эти проблемы, предоставляя свою реализацию сигналов и кеш-менеджера.
+
+## ✨ Особенности
+
+- 🧩 **Реактивные примитивы** — Привычные Signal, Computed и Effect.
+- 🔧 **Framework-agnostic** — Стройте систему и описывайте логику в изолированном месте.
+- ⚡ **Built on RxJS** — Наследует всю мощь RxJS.
+- 💾 **Кеш-менеджер** — Предоставляет Query реализацию для работы с данными.
+- 🔷 **TypeScript-first** — Полная типизация из коробки.
+- 🔗 **Интеграция с фреймворками** — Как и RxJS напрямую работает в Angular, Svelte и SolidJS. 
+Для React предоставляет хуки из коробки.
+
+## 📚 Документация
+- [**RxSignals**](./docs/signals/README.md) - реактивные примитивы
+- [**RxQuery**](./docs/query/README.md) - кеш-менеджер для работы с данными
+- [**React**](./docs/usage/react/README.md) - интеграция с React
+
+## 🌟 Примеры
+
+###### Создаем сигнал
+```typescript
+// Описываете логику в обычном JavaScript
+const store = {
+  count$: new Signal(0),
+  doubled$: new Computed(() => store.count$.value * 2),
+  increment: () => store.count$.next(store.count$.value + 1)
+};
+```
+
+###### Подключаем к фреймворку
+```typescript
+// React
+const count = useSignal(store.count$);
+
+// Angular signal
+count$ = toSignal(store.count$);
+
+// Angular pipe
+{{ store.count$ | async }}
+
+// Svelte
+$: count = store.count$;
+```
+
+###### Работаем с RxJS
+```typescript
+// Создаем Observable
+const clicker$ = fromEvent(document, 'click').pipe(
+    debounceTime(300),
+    scan(count => count + 1, 0)
+);
+
+// Получаем сигнал из Observable
+const clickCount$ = new ReadonlySignal(clicker$);
+const doubled$ = new Computed(() => clickCount$.value * 2);
+
+console.log(doubled$.value); // Всегда актуальное значение
+
+// Или наоборот, получаем событие из сигнала
+const on10click$ = doubled$.pipe(
+    filter(value => value === 10),
+    take(1)
+);
+
+on10click$.subscribe(() => {
+    console.log('Great! That you first reached 10 clicks');
+});
+
+```
+
+###### RxQuery (Корзина покупок)
+```tsx
+const getCart = createResource({
+  queryFn: fetchCart,
+});
+
+const toggleCardItem = createOperation({
+    queryFn: fetchToggleItem,
+  link(add) {
+      add({
+          resource: getCart,
+          forwardArgs: () => undefined,
+          optimisticUpdate: ({ draft, data, args }) => {
+              const item = draft.items.find(i => i.id === data.id);
+              if (!item) return;
+              item.enabled = args.enabled;
+          }
+      })
+  }  
+});
+
+function ShoppingCart() {
+  const cartQuery = useResourceAgent(getCart);
+  const [toggleItem] = useOperationAgent(toggleCardItem);
+  const cart = cartQuery.data;
+  
+  return (
+    <Container isLoading={cartQuery.isLoading}>
+      {cart?.items.map(item => (
+        <CartItem 
+          key={item.id}
+          item={item}
+          onToggle={() => toggleItem({ id: item.id, enabled: !item.enabled })}
+        />
+      ))}
+      <Total amount={cart?.total} />
+    </Container>
+  );
+}
+```

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from './query';
+export * from './signal';
+export * from './react-hooks';

package/dist/index.js

@@ -0,0 +1,3 @@
+export * from './query';
+export * from './signal';
+export * from './react-hooks';

package/dist/query/SKIP_TOKEN.d.ts

@@ -0,0 +1 @@
+export declare const SKIP: unique symbol;

package/dist/query/SKIP_TOKEN.js

@@ -0,0 +1 @@
+export const SKIP = Symbol('SKIP');

package/dist/query/api/DefaultOptions.d.ts

@@ -0,0 +1,9 @@
+import { Devtools } from "@reatom/devtools";
+type Update = Partial<{
+    DEVTOOLS: Devtools | null;
+    onError: (error: unknown) => void;
+}>;
+export declare class DefaultOptions {
+    static update(part: Update): void;
+}
+export {};

package/dist/query/api/DefaultOptions.js

@@ -0,0 +1,9 @@
+import { SharedOptions } from "../../query/core/SharedOptions";
+export class DefaultOptions {
+    static update(part) {
+        if (part.DEVTOOLS !== undefined)
+            SharedOptions.DEVTOOLS = part.DEVTOOLS;
+        if (part.onError !== undefined)
+            SharedOptions.onError = part.onError;
+    }
+}

package/dist/query/api/createDevtools.d.ts

@@ -0,0 +1 @@
+export declare function createDevtools(): import("@reatom/devtools").Devtools;

package/dist/query/api/createDevtools.js

@@ -0,0 +1,6 @@
+import { createDevtools as createRaDevtools } from "@reatom/devtools";
+export function createDevtools() {
+    return createRaDevtools({
+        initVisibility: true,
+    });
+}

package/dist/query/api/createOperation.d.ts

@@ -0,0 +1,7 @@
+import type { OperationCreateOptions, OperationDefinition } from "../../query/types/Operation.types";
+import { Operation } from "../../query/core/Opertation/Operation";
+export declare const createOperation: <ARGS, RESULT, SELECTED = never>(options: OperationCreateOptions<OperationDefinition<ARGS, RESULT, SELECTED>>) => Operation<OperationDefinition<ARGS, RESULT, SELECTED>>;
+/**
+ * @deprecated Use `createOperation` instead.
+ */
+export declare const createMutationApi: <ARGS, RESULT, SELECTED = never>(options: OperationCreateOptions<OperationDefinition<ARGS, RESULT, SELECTED>>) => Operation<OperationDefinition<ARGS, RESULT, SELECTED>>;

package/dist/query/api/createOperation.js

@@ -0,0 +1,6 @@
+import { Operation } from "../../query/core/Opertation/Operation";
+export const createOperation = ((options) => new Operation(options));
+/**
+ * @deprecated Use `createOperation` instead.
+ */
+export const createMutationApi = createOperation;

package/dist/query/api/createResource.d.ts

@@ -0,0 +1,3 @@
+import type { ResourceCreateOptions, ResourceDefinition } from "../../query/types/Resource.types";
+import { Resource } from "../../query/core/Resource/Resource";
+export declare const createResource: <ARGS, RESULT, SELECTED = never>(options: ResourceCreateOptions<ResourceDefinition<ARGS, RESULT, SELECTED>>) => Resource<ResourceDefinition<ARGS, RESULT, SELECTED>>;

package/dist/query/api/createResource.js

@@ -0,0 +1,2 @@
+import { Resource } from "../../query/core/Resource/Resource";
+export const createResource = ((options) => new Resource(options));

package/dist/query/api/createSubResource.js

@@ -0,0 +1 @@
+"use strict";

package/dist/query/core/Opertation/Operation.d.ts

@@ -0,0 +1,34 @@
+import { ReactiveCache } from "../../../query/lib/ReactiveCache";
+import { FallbackOnNever } from "../../../query/types/shared.types";
+import { OperationCreateOptions, OperationDefinition, OperationInstance } from "../../../query/types/Operation.types";
+import { QueriesCache } from "../QueriesCache";
+import { OperationAgent } from "./OperationAgent";
+export type CoreOperationQueryState<D extends OperationDefinition> = {
+    arg: D['Args'] | null;
+    data: FallbackOnNever<D['Selected'], D['Result']> | null;
+    error: unknown | null;
+    isError: boolean;
+    isLoading: boolean;
+    isRepeating: boolean;
+    isDone: boolean;
+    isSuccess: boolean;
+    isInitiated: boolean;
+};
+export declare class Operation<D extends OperationDefinition> implements OperationInstance<D> {
+    private readonly _options;
+    readonly _queriesCache: QueriesCache<D["Args"], CoreOperationQueryState<D>>;
+    private _links;
+    constructor(_options: OperationCreateOptions<D>);
+    private _createLinks;
+    createAgent(): OperationAgent<D>;
+    getQueryCache(args: D['Args']): ReactiveCache<CoreOperationQueryState<D>> | undefined;
+    createQueryCache(args: D['Args']): ReactiveCache<CoreOperationQueryState<D>>;
+    initiate(args: D['Args'], options?: {
+        cache?: ReactiveCache<CoreOperationQueryState<D>>;
+    }): ReactiveCache<CoreOperationQueryState<D>>;
+    /**
+     * Используеются для обртной совместимости, а надо ли менять что-то - хз
+     * @deprecated
+     */
+    mutate(args: D['Args']): Promise<D['Data']>;
+}

package/dist/query/core/Opertation/Operation.js

@@ -0,0 +1,176 @@
+import { QueriesCache } from "../QueriesCache";
+import { SharedOptions } from "../SharedOptions";
+import { OperationAgent } from "./OperationAgent";
+class OperationQueryState {
+    static create() {
+        return {
+            arg: null,
+            data: null,
+            error: null,
+            isError: false,
+            isRepeating: false,
+            isDone: false,
+            isSuccess: false,
+            isLoading: false,
+            isInitiated: false,
+        };
+    }
+    static load(state = OperationQueryState.create(), args) {
+        return {
+            ...state,
+            arg: args,
+            isLoading: true,
+            isRepeating: state.isDone,
+            isInitiated: true,
+        };
+    }
+    static success(state, data) {
+        return {
+            ...state,
+            data,
+            isLoading: false,
+            isRepeating: false,
+            isDone: true,
+            isSuccess: true,
+            isError: false,
+            error: null,
+        };
+    }
+    static error(state, error) {
+        return {
+            ...state,
+            isLoading: false,
+            isRepeating: false,
+            isDone: true,
+            isSuccess: false,
+            isError: true,
+            error,
+        };
+    }
+}
+export class Operation {
+    _options;
+    _queriesCache = new QueriesCache('opr');
+    _links = [];
+    constructor(_options) {
+        this._options = _options;
+        this._createLinks();
+    }
+    _createLinks() {
+        this._options.link?.((linkOptions) => {
+            this._links.push(linkOptions);
+        });
+    }
+    createAgent() {
+        return new OperationAgent(this);
+    }
+    getQueryCache(args) {
+        return this._queriesCache.getQueryCache(args);
+    }
+    createQueryCache(args) {
+        return this._queriesCache.createQueryCache(args, OperationQueryState.create());
+    }
+    initiate(args, options) {
+        let cache = options?.cache ?? this._queriesCache.getQueryCache(args);
+        const state = OperationQueryState.load(cache?.value, args);
+        if (!cache) {
+            cache = this._queriesCache.createQueryCache(args, state);
+        }
+        else {
+            cache.next(state);
+        }
+        const linksMeta = this._links.map(link => {
+            const forwardedArgs = link.forwardArgs(args);
+            const ref = link.resource.createRef(forwardedArgs);
+            return { link, ref, state: {} };
+        });
+        linksMeta.forEach(({ link, ref, state }) => {
+            if (link.lock) {
+                state.unlocker = ref.lock();
+            }
+            if (link.optimisticUpdate && ref.has) {
+                state.patch = ref.update((draft) => {
+                    return link.optimisticUpdate({ draft, args });
+                });
+            }
+        });
+        const query = this._options.queryFn(args);
+        query
+            .then((result) => {
+            const data = this._options.select ? this._options.select(result) : result;
+            cache.next(OperationQueryState.success(state, data));
+            /**
+             * Обновляем связанные ресурсы
+             */
+            linksMeta.forEach(({ link, ref }) => {
+                if (link.update && ref.has) {
+                    ref.update((draft) => {
+                        return link.update({ draft, args, data });
+                    });
+                }
+                if (link.create && !ref.has) {
+                    ref.create(link.create({ args, data }));
+                }
+            });
+        })
+            .catch((error) => {
+            SharedOptions.onError?.(error);
+            cache.next(OperationQueryState.error(state, error));
+            /**
+             * Обновляем связанные ресурсы
+             */
+            linksMeta.forEach(({ state }) => {
+                state.patch?.rollback();
+            });
+        })
+            .finally(() => {
+            /**
+             * Обновляем связанные ресурсы
+             */
+            linksMeta.forEach(({ state }) => {
+                state.unlocker?.unlock();
+            });
+        });
+        return cache;
+    }
+    /**
+     * Используеются для обртной совместимости, а надо ли менять что-то - хз
+     * @deprecated
+     */
+    mutate(args) {
+        const cache = this.initiate(args);
+        const resolver = new PromiseResolver();
+        const subscription = cache.value$.subscribe((state) => {
+            if (!state.isInitiated || state.isLoading || state.isRepeating)
+                return;
+            if (state.isError) {
+                resolver.reject(state.error);
+                return;
+            }
+            if (!state.isSuccess) {
+                console.error("Unexpected state in mutation:", state);
+                resolver.reject(new Error("Unexpected state in mutation"));
+                return;
+            }
+            resolver.resolve(state.data);
+        });
+        resolver.promise.finally(() => {
+            subscription.unsubscribe();
+        });
+        return resolver.promise;
+    }
+}
+class PromiseResolver {
+    _resolve;
+    _reject;
+    promise = new Promise((resolve, reject) => {
+        this._resolve = resolve;
+        this._reject = reject;
+    });
+    resolve(value) {
+        this._resolve(value);
+    }
+    reject(reason) {
+        this._reject(reason);
+    }
+}

package/dist/query/core/Opertation/OperationAgent.d.ts

@@ -0,0 +1,20 @@
+import { Computed } from "../../../signal";
+import { OperationAgentInstanse, OperationDefinition } from "../../../query/types/Operation.types";
+import type { Operation } from "./Operation";
+export declare class OperationAgent<D extends OperationDefinition> implements OperationAgentInstanse<D> {
+    private _operation;
+    private _operations$;
+    state$: Computed<{
+        isLoading: boolean;
+        isDone: boolean;
+        isSuccess: boolean;
+        isError: boolean;
+        error: {} | undefined;
+        data: NonNullable<import("../../types/shared.types").FallbackOnNever<D["Selected"], D["Result"]>> | undefined;
+        args: D["Args"];
+    }>;
+    constructor(_operation: Operation<D>);
+    private _next;
+    initiate(args: D["Args"]): void;
+    createAgent(): OperationAgentInstanse<D>;
+}

package/dist/query/core/Opertation/OperationAgent.js

@@ -0,0 +1,54 @@
+import { Computed, Signal } from "../../../signal";
+export class OperationAgent {
+    _operation;
+    _operations$ = new Signal({
+        current$: null,
+    });
+    state$ = new Computed(() => {
+        const operations = this._operations$.value;
+        const currState = operations.current$?.value;
+        // Нет текущего состояния — дефолт
+        if (!currState) {
+            return {
+                isLoading: false,
+                isDone: false,
+                isSuccess: false,
+                isError: false,
+                error: undefined,
+                data: undefined,
+                args: undefined,
+            };
+        }
+        return {
+            isLoading: currState.isLoading,
+            isDone: currState.isDone,
+            isSuccess: currState.isSuccess,
+            isError: currState.isError,
+            error: currState.error ?? undefined,
+            data: currState.data ?? undefined,
+            args: currState.arg,
+        };
+    });
+    constructor(_operation) {
+        this._operation = _operation;
+    }
+    _next(newCache) {
+        this._operations$.next({
+            current$: newCache,
+        });
+    }
+    initiate(args) {
+        const cache = this._operation.getQueryCache(args);
+        if (!cache) {
+            const newCache = this._operation.initiate(args);
+            this._next(newCache);
+            return;
+        }
+        // Всегда запускаем операцию заново, так как операции обычно не кэшируются как ресурсы
+        const newCache = this._operation.initiate(args, { cache });
+        this._next(newCache);
+    }
+    createAgent() {
+        return new OperationAgent(this._operation);
+    }
+}

package/dist/query/core/QueriesCache.d.ts

@@ -0,0 +1,8 @@
+import { ReactiveCache } from "../../query/lib/ReactiveCache";
+export declare class QueriesCache<KEY, VALUE> {
+    private _logname;
+    private readonly _cache;
+    constructor(_logname?: string);
+    getQueryCache(args: KEY): ReactiveCache<VALUE> | undefined;
+    createQueryCache(args: KEY, initialState: VALUE): ReactiveCache<VALUE>;
+}

package/dist/query/core/QueriesCache.js

@@ -0,0 +1,31 @@
+import { IndirectMap } from "../../query/lib/IndirectMap";
+import { ReactiveCache } from "../../query/lib/ReactiveCache";
+import { SharedOptions } from "./SharedOptions";
+export class QueriesCache {
+    _logname;
+    _cache = new IndirectMap();
+    constructor(_logname = 'query') {
+        this._logname = _logname;
+    }
+    getQueryCache(args) {
+        return this._cache.get(args);
+    }
+    createQueryCache(args, initialState) {
+        const cache = new ReactiveCache({
+            initialState,
+        });
+        const devtoolsState = SharedOptions.DEVTOOLS?.state;
+        if (devtoolsState) {
+            const randomId = Math.random().toString(36).substring(2, 16);
+            const key = `rxt:${this._logname}:${JSON.stringify(args)}:${randomId}`;
+            cache.spy$.subscribe((state) => {
+                devtoolsState(key, state);
+            });
+        }
+        cache.onClean$.subscribe(() => {
+            this._cache.delete(args);
+        });
+        this._cache.set(args, cache);
+        return cache;
+    }
+}

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

@@ -0,0 +1,40 @@
+import { ReactiveCache } from "../../../query/lib/ReactiveCache";
+import type { ResourceCreateOptions, ResourceDefinition, ResourceInstance, ResourceRefInstanse } from "../../../query/types/Resource.types";
+import { QueriesCache } from "../QueriesCache";
+import { ResourceAgent } from "./ResourceAgent";
+export type CoreResourceQueryState<D extends ResourceDefinition> = {
+    abortController: AbortController | null;
+    args: D['Args'] | null;
+    data: D['Data'] | null;
+    error: unknown | null;
+    isError: boolean;
+    isLoading: boolean;
+    isReloading: boolean;
+    isDone: boolean;
+    isSuccess: boolean;
+    isLocked: boolean;
+    isInitiated: boolean;
+    lockCount: number;
+};
+export type CoreResourceQueryCache<D extends ResourceDefinition> = ReactiveCache<CoreResourceQueryState<D>>;
+export declare class Resource<D extends ResourceDefinition> implements ResourceInstance<D> {
+    private readonly _options;
+    readonly _queriesCache: QueriesCache<D["Args"], CoreResourceQueryState<D>>;
+    constructor(_options: ResourceCreateOptions<D>);
+    createAgent: () => ResourceAgent<D>;
+    createRef: (args: D["Args"]) => ResourceRefInstanse<D>;
+    getQueryCache(args: D['Args']): CoreResourceQueryCache<D> | undefined;
+    createQueryCache(args: D['Args']): CoreResourceQueryCache<D>;
+    incrementLock(args: D['Args'], options?: {
+        cache?: CoreResourceQueryCache<D>;
+    }): CoreResourceQueryCache<D>;
+    decrementLock(args: D['Args'], options?: {
+        cache?: CoreResourceQueryCache<D>;
+    }): CoreResourceQueryCache<D> | null;
+    updateData(args: D['Args'], updateFn: (data: D['Data']) => D['Data'], options?: {
+        cache?: CoreResourceQueryCache<D>;
+    }): CoreResourceQueryCache<D> | null;
+    initiate(args: D['Args'], options?: {
+        cache?: CoreResourceQueryCache<D>;
+    }): CoreResourceQueryCache<D>;
+}