@fozy-labs/rx-toolkit 0.4.1

package/dist/signal/base/Signal.d.ts

@@ -0,0 +1,30 @@
+import { BehaviorSubject, Observable } from "rxjs";
+import { type ReadableSignalLike, UnaryFunction } from "./types";
+export declare class Signal<T> extends BehaviorSubject<T> implements ReadableSignalLike<T> {
+    constructor(initialValue: T);
+    protected _onChange(value: T): void;
+    get value(): T;
+    set value(value: T);
+    next(value: T): void;
+    peek(): T;
+    /**
+     * @deprecated use `value` instead.
+     */
+    get(): T;
+    /**
+     * @deprecated use `next(value)` instead.
+     */
+    set(value: T): void;
+    pipe(): Signal<T>;
+    pipe<A extends Observable<any>>(op1: UnaryFunction<ReadableSignalLike<T>, A>): A;
+    pipe<A extends Observable<any>, B extends Observable<any>>(op1: UnaryFunction<Signal<T>, A>, op2: UnaryFunction<A, B>): B;
+    pipe<A extends Observable<any>, B extends Observable<any>, C extends Observable<any>>(op1: UnaryFunction<Signal<T>, A>, op2: UnaryFunction<A, B>, op3: UnaryFunction<B, C>): C;
+    pipe<A extends Observable<any>, B extends Observable<any>, C extends Observable<any>, D extends Observable<any>>(op1: UnaryFunction<Signal<T>, A>, op2: UnaryFunction<A, B>, op3: UnaryFunction<B, C>, op4: UnaryFunction<C, D>): D;
+    pipe<A extends Observable<any>, B extends Observable<any>, C extends Observable<any>, D extends Observable<any>, E extends Observable<any>>(op1: UnaryFunction<Signal<T>, A>, op2: UnaryFunction<A, B>, op3: UnaryFunction<B, C>, op4: UnaryFunction<C, D>, op5: UnaryFunction<D, E>): E;
+    pipe<A extends Observable<any>, B extends Observable<any>, C extends Observable<any>, D extends Observable<any>, E extends Observable<any>, F extends Observable<any>>(op1: UnaryFunction<Signal<T>, A>, op2: UnaryFunction<A, B>, op3: UnaryFunction<B, C>, op4: UnaryFunction<C, D>, op5: UnaryFunction<D, E>, op6: UnaryFunction<E, F>): F;
+    pipe<A extends Observable<any>, B extends Observable<any>, C extends Observable<any>, D extends Observable<any>, E extends Observable<any>, F extends Observable<any>, G extends Observable<any>>(op1: UnaryFunction<Signal<T>, A>, op2: UnaryFunction<A, B>, op3: UnaryFunction<B, C>, op4: UnaryFunction<C, D>, op5: UnaryFunction<D, E>, op6: UnaryFunction<E, F>, op7: UnaryFunction<F, G>): G;
+    pipe<A extends Observable<any>, B extends Observable<any>, C extends Observable<any>, D extends Observable<any>, E extends Observable<any>, F extends Observable<any>, G extends Observable<any>, H extends Observable<any>>(op1: UnaryFunction<Signal<T>, A>, op2: UnaryFunction<A, B>, op3: UnaryFunction<B, C>, op4: UnaryFunction<C, D>, op5: UnaryFunction<D, E>, op6: UnaryFunction<E, F>, op7: UnaryFunction<F, G>, op8: UnaryFunction<G, H>): H;
+    pipe<A extends Observable<any>, B extends Observable<any>, C extends Observable<any>, D extends Observable<any>, E extends Observable<any>, F extends Observable<any>, G extends Observable<any>, H extends Observable<any>, I extends Observable<any>>(op1: UnaryFunction<Signal<T>, A>, op2: UnaryFunction<A, B>, op3: UnaryFunction<B, C>, op4: UnaryFunction<C, D>, op5: UnaryFunction<D, E>, op6: UnaryFunction<E, F>, op7: UnaryFunction<F, G>, op8: UnaryFunction<G, H>, op9: UnaryFunction<H, I>): I;
+    pipe<A extends Observable<any>, B extends Observable<any>, C extends Observable<any>, D extends Observable<any>, E extends Observable<any>, F extends Observable<any>, G extends Observable<any>, H extends Observable<any>, I extends Observable<any>>(op1: UnaryFunction<Signal<T>, A>, op2: UnaryFunction<A, B>, op3: UnaryFunction<B, C>, op4: UnaryFunction<C, D>, op5: UnaryFunction<D, E>, op6: UnaryFunction<E, F>, op7: UnaryFunction<F, G>, op8: UnaryFunction<G, H>, op9: UnaryFunction<H, I>, ...operations: UnaryFunction<Observable<any>, Observable<any>>[]): Observable<unknown>;
+    asReadonly(): ReadableSignalLike<T>;
+}

package/dist/signal/base/Signal.js

@@ -0,0 +1,44 @@
+import { BehaviorSubject } from "rxjs";
+import { Tracker } from "./Tracker";
+export class Signal extends BehaviorSubject {
+    constructor(initialValue) {
+        super(initialValue);
+    }
+    _onChange(value) {
+        super.next(value);
+    }
+    get value() {
+        Tracker.next(this);
+        return super.value;
+    }
+    set value(value) {
+        this._onChange(value);
+    }
+    next(value) {
+        this._onChange(value);
+    }
+    peek() {
+        return super.value;
+    }
+    /**
+     * @deprecated use `value` instead.
+     */
+    get() {
+        return this.value;
+    }
+    /**
+     * @deprecated use `next(value)` instead.
+     */
+    set(value) {
+        return this.next(value);
+    }
+    pipe(...operations) {
+        return operations.reduce(pipeReducer, this);
+    }
+    asReadonly() {
+        return this;
+    }
+}
+function pipeReducer(prev, fn) {
+    return fn(prev);
+}

package/dist/signal/base/SyncObservable.d.ts

@@ -0,0 +1,5 @@
+import { Observable, Subscriber, TeardownLogic } from "rxjs";
+export declare class SyncObservable<T> extends Observable<T> {
+    constructor(subscribe?: (subscriber: Subscriber<T>) => TeardownLogic);
+    get value(): T;
+}

package/dist/signal/base/SyncObservable.js

@@ -0,0 +1,18 @@
+import { Observable } from "rxjs";
+const empty = Symbol('EMPTY');
+export class SyncObservable extends Observable {
+    constructor(subscribe) {
+        super(subscribe);
+    }
+    get value() {
+        let value = empty;
+        const sub = this.subscribe((v) => {
+            value = v;
+        });
+        sub.unsubscribe();
+        if (value === empty) {
+            throw new Error('No value emitted');
+        }
+        return value;
+    }
+}

package/dist/signal/base/Tracker.d.ts

@@ -0,0 +1,5 @@
+import { type Observable, Subject } from "rxjs";
+export declare const Tracker: {
+    tracked$: Subject<Observable<unknown>>;
+    next(value: Observable<unknown>): void;
+};

package/dist/signal/base/Tracker.js

@@ -0,0 +1,7 @@
+import { Subject } from "rxjs";
+export const Tracker = {
+    tracked$: new Subject(),
+    next(value) {
+        Tracker.tracked$.next(value);
+    },
+};

package/dist/signal/base/index.d.ts

@@ -0,0 +1,8 @@
+export * from './Batcher';
+export * from './Computed';
+export * from './Effect';
+export * from './ReadonlySignal';
+export * from './Signal';
+export * from './SyncObservable';
+export * from './Tracker';
+export * from './types';

package/dist/signal/base/index.js

@@ -0,0 +1,8 @@
+export * from './Batcher';
+export * from './Computed';
+export * from './Effect';
+export * from './ReadonlySignal';
+export * from './Signal';
+export * from './SyncObservable';
+export * from './Tracker';
+export * from './types';

package/dist/signal/base/types.d.ts

@@ -0,0 +1,15 @@
+import type { Observable } from "rxjs";
+export interface ReadableSignalLike<T = unknown> extends Observable<T> {
+    get value(): T;
+    peek(): T;
+    /**
+     * @deprecated use `value` instead.
+     */
+    get(): T;
+}
+export interface UnaryFunction<T, R> {
+    (source: T): R;
+}
+export type SignalOperatorFn<T, R> = UnaryFunction<ReadableSignalLike<T>, ReadableSignalLike<R>>;
+export type MonoTypeSignalOperatorFn<T> = SignalOperatorFn<T, T>;
+export type ObservableToSignalFn<T> = UnaryFunction<Observable<T>, ReadableSignalLike<T>>;

package/dist/signal/base/types.js

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

package/dist/signal/extends/LocalSignal.d.ts

@@ -0,0 +1,24 @@
+import { ZodType } from "zod/v4";
+import { Observable } from "rxjs";
+import { Computed } from "../../signal/base";
+type Options<T> = {
+    zodSchema?: ZodType<T>;
+    key: string;
+    userId?: string;
+    /**
+     * @deprecated use checkEffect instead
+     */
+    validator$?: Observable<(value: T) => boolean>;
+    checkEffect?: (value: T) => boolean;
+    defaultValue: T;
+};
+export declare class LocalSignal<T = string | null | number | undefined> extends Computed<T> {
+    private _options;
+    static KEY_PREFIX: string;
+    static DRIVER: Storage;
+    private static _getStorageValue;
+    private static _setStorageValue;
+    constructor(_options: Options<T>);
+    protected _onChange(value: T): void;
+}
+export {};

package/dist/signal/extends/LocalSignal.js

@@ -0,0 +1,66 @@
+import { signalize } from "../../signal/operators";
+import { z } from "zod/v4";
+import { Computed } from "../../signal/base";
+const NullOrString = z.string().nullable();
+const NONE = Symbol('NONE');
+export class LocalSignal extends Computed {
+    _options;
+    static KEY_PREFIX = '__LSValue__';
+    static DRIVER = localStorage;
+    static _getStorageValue(options) {
+        const storageKey = `${LocalSignal.KEY_PREFIX}:${options.key}`;
+        const item = LocalSignal.DRIVER.getItem(storageKey);
+        if (!item)
+            return NONE;
+        const schema = z.record(z.string(), options.zodSchema || NullOrString);
+        const parsed = schema.safeParse(JSON.parse(item));
+        if (!parsed.success) {
+            console.warn(`Invalid value for key "${options.key}" in localStorage`, parsed.error);
+            return NONE;
+        }
+        const subKey = options.userId ? `user:${options.userId}` : 'common';
+        if (!(subKey in parsed.data)) {
+            return NONE;
+        }
+        return parsed.data[subKey];
+    }
+    static _setStorageValue(options, value) {
+        const storageKey = `${LocalSignal.KEY_PREFIX}:${options.key}`;
+        const item = LocalSignal.DRIVER.getItem(storageKey) || '{}';
+        const schema = z.record(z.string(), options.zodSchema || NullOrString);
+        const parsed = schema.safeParse(JSON.parse(item));
+        let data = parsed.data ?? {};
+        if (!parsed.success) {
+            data = {};
+        }
+        const subKey = options.userId ? `user:${options.userId}` : 'common';
+        data[subKey] = value;
+        LocalSignal.DRIVER.setItem(storageKey, JSON.stringify(data));
+    }
+    constructor(_options) {
+        const validator$ = _options.validator$;
+        const checkEffect = _options.checkEffect;
+        const defaultValue = _options.defaultValue;
+        const validatorSignal$ = validator$ && signalize(validator$);
+        super(() => {
+            const value = LocalSignal._getStorageValue(_options);
+            if (value === NONE)
+                return defaultValue;
+            if (validatorSignal$) {
+                const validator = validatorSignal$.value;
+                if (!validator(value)) {
+                    return defaultValue;
+                }
+            }
+            if (checkEffect) {
+                return checkEffect(value) ? value : defaultValue;
+            }
+            return value;
+        });
+        this._options = _options;
+    }
+    _onChange(value) {
+        LocalSignal._setStorageValue(this._options, value);
+        return super._onChange(value);
+    }
+}

package/dist/signal/extends/index.d.ts

@@ -0,0 +1 @@
+export * from './LocalSignal';

package/dist/signal/extends/index.js

@@ -0,0 +1 @@
+export * from './LocalSignal';

package/dist/signal/index.d.ts

@@ -0,0 +1,3 @@
+export * from './base';
+export * from './extends';
+export * from './operators';

package/dist/signal/index.js

@@ -0,0 +1,3 @@
+export * from './base';
+export * from './extends';
+export * from './operators';

package/dist/signal/operators/batch.d.ts

@@ -0,0 +1,2 @@
+import { MonoTypeOperatorFunction } from "rxjs";
+export declare function batched<T>(): MonoTypeOperatorFunction<T>;

package/dist/signal/operators/batch.js

@@ -0,0 +1,27 @@
+import { createOperatorSubscriber } from "rxjs/internal/operators/OperatorSubscriber";
+import { ReadonlySignal, Batcher } from "../base";
+export function batched() {
+    return (source) => {
+        let lockSubscription = null;
+        let lastResult = undefined;
+        return new ReadonlySignal((destination) => source.subscribe(createOperatorSubscriber(destination, (value) => {
+            if (lockSubscription) {
+                lastResult = value;
+                return;
+            }
+            if (Batcher.isLocked$.value) {
+                lastResult = value;
+                lockSubscription = Batcher.isLocked$.subscribe((isLocked) => {
+                    if (!isLocked) {
+                        lockSubscription.unsubscribe();
+                        lockSubscription = null;
+                        destination.next(lastResult);
+                        lastResult = undefined;
+                    }
+                });
+                return;
+            }
+            destination.next(value);
+        })));
+    };
+}

package/dist/signal/operators/filterUpdates.d.ts

@@ -0,0 +1,5 @@
+import { type TruthyTypesOf } from "rxjs";
+import type { MonoTypeSignalOperatorFn, SignalOperatorFn } from "../base";
+export declare function filterUpdates<T, S extends T>(predicate: (value: T, index: number) => value is S): SignalOperatorFn<T, S>;
+export declare function filterUpdates<T>(predicate: BooleanConstructor): SignalOperatorFn<T, TruthyTypesOf<T>>;
+export declare function filterUpdates<T>(predicate: (value: T, index: number) => boolean): MonoTypeSignalOperatorFn<T>;

package/dist/signal/operators/filterUpdates.js

@@ -0,0 +1,18 @@
+import { createOperatorSubscriber } from "rxjs/internal/operators/OperatorSubscriber";
+import { ReadonlySignal } from "../../signal/base/ReadonlySignal";
+export function filterUpdates(predicate, thisArg) {
+    return (source) => new ReadonlySignal((destination) => {
+        let index = 0;
+        let isFirst = true;
+        source.subscribe(createOperatorSubscriber(destination, (value) => {
+            if (isFirst) {
+                isFirst = false;
+                destination.next(value);
+                return;
+            }
+            const result = predicate.call(thisArg, value, index++);
+            if (result)
+                destination.next(value);
+        }));
+    });
+}

package/dist/signal/operators/index.d.ts

@@ -0,0 +1,4 @@
+export * from './batch';
+export * from './filterUpdates';
+export * from '../../signal/operators/mapSignals';
+export * from './signalize';

package/dist/signal/operators/index.js

@@ -0,0 +1,4 @@
+export * from './batch';
+export * from './filterUpdates';
+export * from '../../signal/operators/mapSignals';
+export * from './signalize';

package/dist/signal/operators/mapSignals.d.ts

@@ -0,0 +1,3 @@
+import type { SignalOperatorFn } from "../base";
+export declare function mapSignals<T, R, A>(project: (this: A, value: T, index: number) => R): SignalOperatorFn<T, R>;
+export declare function mapSignals<T, R, A>(project: (this: A, value: T, index: number) => R, thisArg: A): SignalOperatorFn<T, R>;

package/dist/signal/operators/mapSignals.js

@@ -0,0 +1,10 @@
+import { createOperatorSubscriber } from "rxjs/internal/operators/OperatorSubscriber";
+import { ReadonlySignal } from "../../signal/base/ReadonlySignal";
+export function mapSignals(project, thisArg) {
+    return (source) => new ReadonlySignal((destination) => {
+        let index = 0;
+        source.subscribe(createOperatorSubscriber(destination, (value) => {
+            destination.next(project.call(thisArg, value, index++));
+        }));
+    });
+}

package/dist/signal/operators/signalize.d.ts

@@ -0,0 +1,3 @@
+import { Observable } from "rxjs";
+import { ReadonlySignal } from "../../signal/base";
+export declare function signalize<T>(observable: Observable<T>): ReadonlySignal<T>;

package/dist/signal/operators/signalize.js

@@ -0,0 +1,6 @@
+import { ReadonlySignal } from "../../signal/base";
+export function signalize(observable) {
+    return new ReadonlySignal((destination) => {
+        return observable.subscribe(destination);
+    });
+}

package/docs/query/README.md

@@ -0,0 +1,224 @@
+# RxQuery
+
+RxQuery - система для управления запросами и кэшированием данных в RxToolkit. Она состоит из двух основных компонентов: **Resources** и **Operations**.
+
+## Основные концепции
+
+### Resources (Ресурсы)
+
+Resources предназначены для реактивного кэширования повторяемых запросов. Они автоматически управляют состоянием загрузки, кэшируют результаты и обеспечивают эффективную инвалидацию данных.
+
+**Ключевые особенности:**
+- Автоматическое кэширование по аргументам запроса
+- Поддержка AbortController для отмены запросов
+- Реактивные обновления состояния
+- Оптимистичные обновления
+
+### Operations (Операции)
+
+Operations представляют одноразовые операции или мутации. Они не кэшируются, но предоставляют состояние выполнения и могут связываться с ресурсами для их обновления.
+
+**Ключевые особенности:**
+- Отслеживание состояния выполнения
+- Связывание с ресурсами для их обновления
+- Поддержка оптимистичных обновлений
+- Возможность блокировки связанных ресурсов
+
+### Agents (Агенты)
+Agents представляют собой интеллектуальные обертки над ресурсами (или операциями), 
+которые обеспечивают более удобную работу с состояниями запросов для потребителей.
+
+#### Основная проблема, которую решают агенты
+
+Кэш ресурсов (или операций) содержит "сырые" состояния отдельных запросов, но потребителям нужна более высокоуровневая логика. 
+Например:
+- `isInitialLoading` должно быть true только при первой загрузке ресурса, но не при переключении между разными аргументами
+- При смене аргументов запроса нужно показывать данные предыдущего запроса, пока загружается новый
+- Состояние загрузки должно отражать контекст использования, а не просто состояние кэша
+
+## API
+
+### createResource
+
+Создает новый ресурс для кэширования данных.
+
+```typescript
+const userResource = createResource<{ id: string }, User>({
+  async queryFn(args, tools) {
+    const response = await fetch(`/api/users/${args.id}`, {
+      signal: tools.abortSignal
+    });
+    return response.json();
+  },
+  select: (data) => ({
+    id: data.id,
+    name: data.name,
+    email: data.email
+  })
+});
+```
+
+**Параметры:**
+- `queryFn(args, tools)` — функция выполнения запроса
+- `select(data)` — опциональная функция трансформации данных
+
+### createOperation
+
+Создает новую операцию для выполнения мутаций.
+
+```typescript
+const updateUser = createOperation<
+    { id: string; data: Partial<User> },
+    User
+>({
+    async queryFn(args) {
+        const response = await fetch(`/api/users/${args.id}`, {
+            method: 'PATCH',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(args.data)
+        });
+        return response.json();
+    },
+    link(add) {
+        add({
+            resource: userResource,
+            forwardArgs: (args) => ({ id: args.id }),
+            optimisticUpdate(draft, args) {
+                Object.assign(draft, args.data);
+            },
+        });
+    }
+});
+```
+
+**Параметры:**
+- `queryFn(args)` — функция выполнения операции
+- `link(ref)` — опциональная функция связывания с ресурсами
+
+
+## Свойства Link
+```typescript
+/**
+ * Настройки связи операции с ресурсом
+ */
+export type LinkOptions<D extends OperationDefinition, 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<D["Data"]>;
+    
+    /**
+     * Функция для создания нового элемента в кэше ресурса
+     * Используется когда операция создает новую сущность, которую нужно добавить в кэш
+     * @optional
+     */
+    create?: (tools: {
+        /** Аргументы, с которыми была вызвана операция */
+        args: D["Args"];
+        /** Результат выполнения операции */
+        data: D["Data"];
+    }) => RD["Data"] | Promise<RD["Data"]>;
+};
+```
+
+
+## Состояния запросов
+
+Каждый ресурс и операция предоставляют следующие состояния:
+
+```typescript
+/**
+ * Состояние запроса ресурса
+ */
+export type ResourceQueryState<D extends ResourceDefinition> = {
+    /** Инициализирован ли хотя бы один запрос */
+    isInitiated: boolean;
+    /** Первая загрузка */
+    isLoading: 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; // TODO undefined - это костыль для сведения типов, его быть не должно
+}
+
+/**
+ * Состояние выполнения операции
+ */
+export type OperationQueryState<D extends OperationDefinition> = {
+    /** Выполняется ли операция в данный момент */
+    isLoading: boolean;
+    /** Завершена ли операция */
+    isDone: boolean;
+    /** Успешно ли завершена операция (false по умолчанию) */
+    isSuccess: boolean;
+    /** Произошла ли ошибка при выполнении операции (false по умолчанию) */
+    isError: boolean;
+    /** Оригинал ошибки, если есть */
+    error: unknown | undefined;
+    /** Результат выполнения операции */
+    data: D["Data"] | undefined;
+    /** Аргументы операции */
+    args: D["Args"];
+}
+
+```