@superutils/rx 0.1.13 → 0.1.14

package/dist/index.d.ts

@@ -1,36 +1,50 @@
 import { TimeoutOptions, IPromisE_Timeout } from '@superutils/promise';
-import { Subscribable, BehaviorSubject, Subject, Subscription } from 'rxjs';
-export { BehaviorSubject, Subject, Subscribable, Subscription, Unsubscribable, isObservable, skip } from 'rxjs';
-import { DeferredOptions, ThrottleOptions, DebounceOptions, ValueOrPromise, DropFirst, filter, FindOptions, find, search, sort, SortOptions, TypedMap } from '@superutils/core';
-export { TypedMap, objToMap } from '@superutils/core';
+import { SubscriptionLike, Observable, BehaviorSubject, Subject, Subscription } from 'rxjs';
+import { DeferredOptions, ValueOrPromise } from '@superutils/core';
 
-interface SubjectLike<T = unknown> {
-    next: (value: T) => void;
-    subscribe: (next: (value: T) => void, ...args: unknown[]) => SubscriptionLike;
-    unsubscribe?: Unsubscribe;
-    closed?: boolean;
-    value?: T;
-}
-interface SubscriptionLike {
-    closed?: boolean;
-    unsubscribe: Unsubscribe;
-}
-/** Wrap a value from a signle subject or an array of subjects and values */
-type UnwrapSubjectValue<T> = T extends SubjectLike<infer V> ? V : T extends readonly unknown[] ? {
-    -readonly [K in keyof T]: UnwrapSubjectValue<T[K]>;
+type AsPromise_Defaults = Required<Pick<AsPromise_Options, 'invalidInputMsg' | 'timeoutMsg'>>;
+type AsPromise_Options = Omit<TimeoutOptions, 'batchFunc'> & {
+    /** Error message used when input is not a valid observable */
+    invalidInputMsg?: string;
+    /** Number of emit values to skip/ignore. Default: `0` */
+    skip?: number;
+    /** Error message to use when times out. */
+    timeoutMsg?: string | Error;
+};
+type Unsubscribe = SubscriptionLike['unsubscribe'];
+type UnsubscribeCandidate = Unsubscribe | SubscriptionLike | SubscriptionLike[] | unknown[] | object | undefined | null | boolean;
+/**
+ * Recursively extracts the emitted value type from an Observable, an array of Observables,
+ * or returns the type itself if it's a static value.
+ *
+ * @template T - The input type to unwrap.
+ */
+type UnwrapSourceValue<T> = T extends Observable<infer V> ? V : T extends readonly unknown[] ? {
+    -readonly [K in keyof T]: UnwrapSourceValue<T[K]>;
+} : T;
+/**
+ * Recursively extracts the emitted value type from an Observable or an array of Observables,
+ * similar to {@link UnwrapSourceValue}.
+ *
+ * However, if the Observable does not have a `.value` property (i.e., it is not a `BehaviorSubject`),
+ * the resulting type is unioned with `undefined` to reflect that an initial value may not be
+ * immediately available.
+ *
+ * @template T - The input type to unwrap.
+ */
+type UnwrapSourceValueStrict<T> = T extends Observable<infer V> ? T extends {
+    value: infer V;
+} ? V : V | undefined : T extends readonly unknown[] ? {
+    -readonly [K in keyof T]: UnwrapSourceValueStrict<T[K]>;
 } : T;
-type Unsubscribe = () => void;
-type UnsubscribeCandidates = Unsubscribe | SubscriptionLike | SubscriptionLike[] | unknown[] | Record<PropertyKey, unknown> | undefined | null | boolean;
 
 /**
  * @summary Create a promise using RxJS subject and wait until an expected value is received
  *
- * @param subject RxJS subject or observable
+ * @param input$ RxJS subject or observable
  * @param expectedValue	(optional) if undefined, will resolve as soon as any value is received.
  * If function, it should return true or false to indicate whether the value should be resolved.
- * @param timeoutOrOptions (optional)
- * @param timeoutOrOptions.timeout (optional) timeout duration in milliseconds if no value received within given time
- * @param timeoutOrOptions.timeoutMsg (optional) error message to use when times out.
+ * @param timeoutOrOptions (optional) timeout duration or options
  *
  * @returns timeout promise
  *
@@ -50,79 +64,108 @@ type UnsubscribeCandidates = Unsubscribe | SubscriptionLike | SubscriptionLike[]
  * subjectAsPromise(subject, 5).then(value => console.log('Expected 5, received ', value))
  * ```
  */
-declare const asPromise: <T = unknown>(subject: Subscribable<T> | SubjectLike<T>, expectedValue?: T | ((value: T) => boolean), timeoutOrOptions?: number | (Omit<TimeoutOptions, "batchFunc"> & {
-    timeoutMsg?: string | Error;
-})) => IPromisE_Timeout<T>;
+declare const asPromise: {
+    <T = unknown>(input$: Observable<T>, expectedValue?: T | ((value: T) => boolean), timeoutOrOptions?: number | AsPromise_Options): IPromisE_Timeout<T>;
+    defaults: Required<Pick<AsPromise_Options, "invalidInputMsg" | "timeoutMsg">>;
+};
 
-/** Symbol used to signal to ignore an update when using a `valueModifier()` callback with {@link copyRxSubject} */
+/** Symbol used to signal to ignore an update when using a `transform()` callback with {@link copyRx} */
 declare const IGNORE_UPDATE_SYMBOL: unique symbol;
-type CopyRxSubjectOptions<ThisArg> = {
+type CopyRx_Options<TOut, ThisArg> = {
+    /**
+     * Debounce or throttle delay in milliseconds.
+     * If provided, updates to the output subject will be delayed accordingly.
+     *
+     * Default: `undefined`
+     */
     delay?: number;
+    /**
+     * The initial value for the output subject.
+     * This is particularly useful when creating a new `BehaviorSubject` internally.
+     */
+    initialValue?: TOut;
+    /**
+     * An optional destination subject to which values will be copied.
+     * If provided, this subject will be returned by the function.
+     * If not provided, a new `BehaviorSubject` is created.
+     */
+    output?: BehaviorSubject<TOut> | Subject<TOut>;
+    /**
+     * Number of initial emissions to skip from the input observable(s).
+     *
+     * If an array is provided, each element corresponds to the observable at the same index.
+     *
+     * Default: `1` for `BehaviorSubject` (to avoid redundant updates of the initial value), otherwise `0`.
+     */
+    skipEmits?: number | (number | undefined | null)[];
+    /** Use this only if  */
+    transformSequentially?: boolean;
 } & DeferredOptions<ThisArg>;
 /**
- * Value modifier function definition for {@link copyRxSubject}
+ * Value modifier function definition for {@link copyRx}.
+ *
+ * This function is executed for each new value emitted by the input observable(s).
+ *
+ * - **`this` context**: The `this` context within the `transform` function can be set using the `options.thisArg`
+ * - **Ignoring updates**: Returning {@link copyRx.IGNORE} will prevent the output observable from emitting the current update.
+ * - **Asynchronous transformations**: If a `Promise` is returned, the output observable will only be updated once the promise resolves.
+ *   However, this can introduce race conditions if new input values arrive before the previous promise resolves.
+ *   To prevent such race conditions, enable the `transformSequentially` flag in `CopyRx_Options`.
+ * - **Error handling**: If the `transform` function throws an error, the update is gracefully ignored, and the `onError` callback (if provided in `CopyRx_Options`) will be invoked.
+ */
+type CopyRx_Transform<TIn = unknown, TOut = TIn, ThisArg = unknown> = (this: ThisArg, 
+/**
+ * The current value from the input observable (or an array of values if multiple sources are provided).
+ *
+ * - If `input` to `copyRx` is a single observable, `newValue` will be the value emitted by that observable.
+ * - If `input` is an array of observables/values, `newValue` will be an array containing the latest values from all sources.
  *
- * Returning {@link IGNORE_UPDATE_SYMBOL} will ignore the update.
+ * **Note:** If the transformation is asynchronous, a `BehaviorSubject` output will emit `undefined` (or the
+ * `initialValue`) immediately upon subscription until the first `transform` promise resolves.
  */
-type ValueModifier<T = unknown, TCopy = T> = (newValue: T, previousValue: TCopy | undefined, copy$: SubjectLike<TCopy>) => TCopy | typeof IGNORE_UPDATE_SYMBOL;
+newValue: TIn, 
 /**
- * @function    copyRxSubject
- * @summary returns a subject that automatically copies the value(s) of the source subject(s).
- *
- * The the changes are applied unidirectionally from the source subject to the destination subject.
- * Changes on the destination subject is NOT applied back into the source subject.
- *
- * @param source$  RxJS source subject(s). If Array provied, value of `copy$` will also be an Array by default,
- * unless a different type is provided by `copy$` or `valueModifier`.
- *
- * @param copy$    (optional) RxJS copy/destination subject.
- * If `undefined`, a new subject will be created.
- * Value type will be inferred automatically based on `copy$`, `valueModifier` and `source$`.
- * Default: `new BehaviorSubject()`
- * @param valueModifier (optional) callback to modify the value (an thus type) before copying from `source$`.
- * Accepts async functions. Function invocation errors will be gracefully ignored.
- * PS: If the very first invokation returns `IGNORE_UPDATE_SYMBOL`, the value of `copy$.value` will be undefined.
- * Args: `newValue, previousValue, copy$`
- * @param {CopyRxSubjectOptions} options (optional) options to enable debouce/throttling `copy$` value changes.
- * @param options.delay (optional) delay in milliseconds. Default: `0`
- * @param options.onError (optional) callback invoked whenever `valueModifier` execution fails.
- * @param options.throttle (optional) `true`: throttle, `false`: debounce. Default: `false`
- *
- * @returns `copy$` if provided, otherwise, a new `BehaviorSubject` instance
+ * The destination observable/subject where the results are being copied.
+ */
+output: Observable<TOut>) => ValueOrPromise<TOut> | typeof IGNORE_UPDATE_SYMBOL;
+/**
+ * Returns a subject that automatically copies the value(s) of the source subject(s).
+ *
+ * Established a unidirectional data flow from source(s) to a destination subject.
+ * Changes to the destination subject are NOT applied back to the source.
+ *
+ * @param source$     RxJS input observable(s) or static value(s). If an array is provided,
+ *                  the output subject will emit an array of values by default.
+ * @param transform (optional) A function to map or filter values before they are emitted by the output subject.
+ *                  Supports async functions. If it throws, the update is ignored.
+ * @param options   (optional) Configuration for timing (delay), initial state, and error handling.
+ *
+ * @returns The destination subject (either the one provided in `options.output` or a new `BehaviorSubject`).
  *
  * @example
  * #### Auto-copy values from a single subject
  * ```typescript
- * import { BehaviorSubject, copyRxSubject } from '@superutils/rx'
+ * import { BehaviorSubject, copyRx } from '@superutils/rx'
  *
  * const number$ = new BehaviorSubject(1)
- * const even$ = copyRxSubject(
- *   // source subject
- *   number$,
- *   // create and return a new BehaviorSubject. An existing RxJS subject can also be provided here.
- *   null,
- *   // copy and transform the value from number$
- *   newValue => newValue % 2 === 0,
- *   // debounce/throttle value changes to even$
- *   // {
- *   //   delay: 300 //
- *   //   throttle: false,
- *   // }
+ * const even$ = copyRx(
+ *   number$, // input observable
+ *   newValue => newValue % 2 === 0 ? newValue : copyRx.IGNORE,
  * )
  * // subscribe to even$ changes
- * even$.subscribe(console.log)
- * number$.next(2) // prints: true
- * number$.next(3) // print: false
+ * even$.subscribe(console.log) // prints: 2
+ * number$.next(2)
+ * number$.next(3) // (ignored)
  * ```
  *
  * @example
  * #### Auto-copy from an array of subjects & values
  * ```javascript
- * import { BehaviorSubject, copyRxSubject } from '@superutils/rx'
+ * import { BehaviorSubject, copyRx } from '@superutils/rx'
  *
  * const theme$ = new BehaviorSubject('dark')
  * const userId$ = new BehaviorSubject('username')
- * const settings$ = copyRxSubject(
+ * const settings$ = copyRx(
  *   [
  * 	   theme$,
  * 	   userId$,
@@ -135,649 +178,13 @@ type ValueModifier<T = unknown, TCopy = T> = (newValue: T, previousValue: TCopy
  * )
  * ```
  */
-declare function copyRxSubject<TCopy extends T, TSource$, T = UnwrapSubjectValue<TSource$>, TCopy$ extends SubjectLike<TCopy> = BehaviorSubject<TCopy>, ThisArg = unknown>(source$: TSource$, copy$?: TCopy$ | null, valueModifier?: ValueModifier<T, TCopy> | null, options?: CopyRxSubjectOptions<ThisArg>): TCopy$;
-declare function copyRxSubject<TCopy, TSource$, T = UnwrapSubjectValue<TSource$>, TCopy$ extends SubjectLike<TCopy> = BehaviorSubject<TCopy>, ThisArg = unknown>(source$: TSource$, copy$: TCopy$ | undefined | null, valueModifier: ValueModifier<T, TCopy> | null, options?: CopyRxSubjectOptions<ThisArg>): TCopy$;
-declare namespace copyRxSubject {
-    var defaults: {
+declare function copyRx<TOut, Source$ extends Observable<any> | unknown[] = Observable<any> | unknown[], TIn = UnwrapSourceValueStrict<Source$>, Copy$ extends BehaviorSubject<TOut> | Subject<TOut> = BehaviorSubject<TOut>, ThisArg = unknown>(source$: Source$, transform?: CopyRx_Transform<TIn, TOut, ThisArg> | null, options?: CopyRx_Options<TOut, ThisArg>): Copy$;
+declare function copyRx<TOut, Source$ extends Observable<any> | unknown[] = Observable<any> | unknown[], TIn = UnwrapSourceValueStrict<Source$>, Copy$ extends BehaviorSubject<TOut> | Subject<TOut> = BehaviorSubject<TOut>, ThisArg = unknown>(source$: Source$, transform: CopyRx_Transform<TIn, TOut, ThisArg>, options?: CopyRx_Options<TOut, ThisArg>): Copy$;
+declare namespace copyRx {
+    var defaults: Required<Omit<DeferredOptions<unknown>, "thisArg"> & {
         delay: number;
-    } & DeferredOptions<unknown>;
-    var IGNORE_UPDATE_SYMBOL: typeof IGNORE_UPDATE_SYMBOL;
-}
-
-/** Throttle & debounce related options */
-type DelayOptions = ({
-    throttle: true;
-} & Omit<ThrottleOptions, 'onError' | 'thisArg'>) | ({
-    throttle?: false;
-} & Omit<DebounceOptions, 'onError' | 'thisArg'>);
-/**
- * Categorizes errors encountered during DataStorage operations.
- *
- * These types are passed to the `onError` callback to help identify which phase of the
- * data lifecycle (reading, writing, or processing) failed.
- */
-declare enum OnErrorType {
-    /** Occurs when the user-provided `onChange` callback throws an exception. */
-    onChange = "onChange",
-    /** Occurs when the user-provided `parse` function fails to process the raw storage string. */
-    parse = "parse",
-    /**
-     * Occurs when the default `JSON.parse` fallback fails.
-     * This usually happens if the data in the underlying storage is corrupted or not valid JSON.
-     */
-    parse_json = "parse-json",
-    /** Occurs when the user-provided `stringify` function fails to serialize the data Map. */
-    stringify = "stringify",
-    /**
-     * Occurs when the default `JSON.stringify` fallback fails.
-     * This may happen if the Map contains circular references or other non-serializable values.
-     */
-    stringify_json = "stringify-json",
-    /** Occurs when the attempt to save data to the underlying storage (e.g., `localStorage.setItem`) fails. */
-    write = "write"
-}
-/** Storage type with only properties that are used by `DataStorage` */
-type StorageCompact = Pick<Storage, 'getItem' | 'setItem'>;
-/** Initial options provided through the constructor */
-type StorageOptions<Key, Value, CacheDisabled extends boolean = false> = {
-    /**
-     * An optional `Map` used to seed the storage if no persistent data is found for the instance.
-     *
-     * **Data Precedence:**
-     * Persistent data associated with the instance's specific `name` takes priority. This value is
-     * only utilized if the storage entry for that `name` does not exist (e.g., first-time use).
-     *
-     * **Initialization Behavior:**
-     * - If provided and non-empty, the instance initializes immediately during construction.
-     * - Otherwise, initialization is lazy, occurring upon an explicit `init()` call or the first read/write operation.
-     *
-     * **Type Inference:**
-     * When provided, it enables automatic inference of the `Key` and `Value` generic types.
-     * If omitted, these default to `unknown` and `object` respectively, unless explicitly defined.
-     *
-     * @default undefined
-     */
-    initialValue?: Map<Key, Value>;
-} & Pick<Partial<IDataStorage<Key, Value, CacheDisabled>>, 'cacheDisabled' | 'onChange' | 'onError' | 'parse' | 'spaces' | 'storage' | 'stringify'> & (CacheDisabled extends false ? Pick<Partial<IDataStorage<Key, Value, CacheDisabled>>, 'delay' | 'delayOptions'> : {
-    delay?: never;
-    delayOptions?: never;
-});
-type StorageParseFn<ResultMap, ThisArg> = (this: ThisArg, text: string | null | undefined) => ResultMap | void;
-type StorageSearch<K, V, MatchExact extends boolean = false, AsMap extends boolean = true> = (...args: DropFirst<Parameters<typeof search<K, V, MatchExact, AsMap>>>) => ReturnType<typeof search<K, V, MatchExact, AsMap>>;
-type StorageSort<K, V> = (...args: StorageSortByComparator<K, V> | StorageSortByPropertyName<V> | StorageSortByKey) => Map<K, V>;
-type StorageSortByComparator<K, V> = [
-    comparator: Parameters<typeof sort<K, V>>[1],
-    options?: StorageSortOptions
-];
-type StorageSortByKey = [byKey: true, options?: StorageSortOptions];
-type StorageSortByPropertyName<V> = [
-    propertyName: keyof V & string,
-    options?: StorageSortOptions
-];
-type StorageSortOptions = SortOptions & {
-    save?: boolean;
-};
-type StorageStringify<Data, ThisArg> = (this: ThisArg, data: Data) => string | undefined | void;
-type StorageToJSON<K, V> = (replacer?: null | ((key: K, value: V) => unknown), spacing?: string | number, data?: Map<K, V>) => string;
-interface IDataStorage<Key, Value, CacheDisabled extends boolean = false> {
-    /** Disable in-memory cache and only directly read/write from storage (local storage or JSON fle) */
-    readonly cacheDisabled: CacheDisabled;
-    /**
-     * Debounce/throttle delay duration in milliseconds for writing to storage when caching is enabled.
-     *
-     * Increasing this value can improve performance when dealing with large datasets
-     * or frequent updates by reducing the number of write operations.
-     *
-     * Default: `300`
-     */
-    readonly delay: number;
-    readonly delayOptions?: DelayOptions;
-    /**
-     * Indicates wherether storage has been initialized (`init()` function invoked).
-     */
-    readonly initialized: boolean;
-    /**
-     * Storage name. Filename (NodeJS) or property name (browser LocalStorage).
-     * If empty string or undefined, data will not be saved to storage and will only work in-memory.
-     *
-     * Default: `''`
-     */
-    readonly name?: string | null;
-    /**
-     * A callback function executed whenever a data change occurs within the storage.
-     *
-     * This hook allows for reactive side-effects. If the callback throws an error or returns a
-     * rejected Promise, the exception is caught gracefully and redirected to the {@link onError}
-     * callback with the type {@link OnErrorType.onChange}.
-     *
-     * Note: Execution of this callback is managed by internal subscriptions and will stop
-     * firing once {@link unsubscribe} is called.
-     */
-    onChange?: (this: IDataStorage<Key, Value, CacheDisabled>, data: Map<Key, Value>) => ValueOrPromise<void | Map<Key, Value>>;
-    /**
-     * A global error handler invoked whenever an internal operation fails.
-     *
-     * It captures failures in the following areas:
-     * - Data parsing and serialization (JSON or custom logic).
-     * - Storage access (e.g., `localStorage` quota or permission errors).
-     * - Execution of user-provided callbacks like {@link onChange}.
-     *
-     * **Note:** If this handler itself throws an error, the exception is
-     * ignored gracefully to prevent application crashes during storage cycles.
-     */
-    onError?: (this: IDataStorage<Key, Value, CacheDisabled>, err: unknown, type: OnErrorType) => ValueOrPromise<void>;
-    /**
-     * A callback to customize the deserialization of data read from storage.
-     *
-     * This allows you to transform the raw string from the underlying storage back into a
-     * `Map<Key, Value>`. It serves as the functional inverse of {@link stringify}.
-     *
-     * **Fallback Behavior:** The system falls back to internal `JSON.parse` logic if `parse`:
-     * - is not a non-function
-     * - throws an error
-     * - returns a non-Map value,
-     *
-     * **Error Triggers:**
-     * - If this custom `parse` function fails: {@link onError} is triggered with {@link OnErrorType.parse}.
-     * - If the default `JSON.parse` fallback fails: {@link onError} is triggered with {@link OnErrorType.parse_json}.
-     */
-    parse?: StorageParseFn<Map<Key, Value>, IDataStorage<Key, Value, CacheDisabled>>;
-    /** Get the number of items */
-    readonly size: number;
-    /** Number of spaces to use when stringifying. Default: `undefined` */
-    spaces?: number;
-    /**
-     * `LocalStorage` or equivalent storage instance to be used as the underlying storage and to read & write from.
-     *
-     * Notes:
-     * - Ignored when `name` is falsy (in-memory only mode)
-     * - For NodeJS or equivalent, an instance of `LocalStorage` from "node-localstoarge" NPM module can be used.
-     * - If `undefined`, will not attempt to use `globalThis.localStorage`, if available
-     * - If `null`, will not attempt to use `globalThis.localStorage`
-     *
-     * Default:
-     * - browser: `localStorage`
-     * - node: `undefined` (in-memory mode)
-     */
-    readonly storage?: StorageCompact | null;
-    /**
-     * A callback function to customize the serialization of data before it is written to storage.
-     *
-     * This allows you to transform the data `Map<Key, Value>` into a string format suitable
-     * for the underlying storage (e.g., JSON). It serves as the functional inverse of {@link parse}.
-     *
-     * Use this to sanitize data, remove circular references, or optimize the storage size by
-     * only persisting necessary fields.
-     *
-     * **Fallback Behavior:**
-     * If this function is not defined, throws an error, or returns `undefined` or a non-string value,
-     * the system falls back to internal `JSON.stringify` logic.
-     *
-     * **Error Triggers:**
-     * - If this custom `stringify` function fails: {@link onError} is triggered with {@link OnErrorType.stringify}.
-     * - If the default `JSON.stringify` fallback fails: {@link onError} is triggered with
-     * {@link OnErrorType.stringify_json}.
-     *
-     * @param data a map of all values stored in this storage
-     *
-     * @returns string or undefined
-     *
-     * @example
-     * #### Sanitize data before saving
-     * ```javascript
-     * import { DataStorage } from '@superutils/rx'
-     *
-     * const stringify = data => {
-     *   // Convert Map to an array of entries, removing sensitive fields
-     *   const entries = Array.from(data).map(([id, user]) => {
-     *     const { password, ...publicData } = user
-     *     return [id, publicData]
-     *   })
-     *   return JSON.stringify(entries)
-     * }
-     * const storage = new DataStorage('users', { stringify })
-     * ```
-     */
-    stringify?: StorageStringify<Map<Key, Value>, IDataStorage<Key, Value, CacheDisabled>>;
-    /**
-     * The underlying RxJS Subject that serves as the primary reactive interface for observing data modifications.
-     *
-     * Its implementation type is determined by the caching strategy:
-     * - **BehaviorSubject**: Used when caching is enabled.
-     * It maintains the current state and emits it immediately to new subscribers.
-     * - **Subject**: Used when caching is disabled.
-     * It acts as a pure event pipe, emitting updates only at the moment they occur without retaining an in-memory copy.
-     */
-    readonly subject: CacheDisabled extends true ? Subject<Map<Key, Value>> : BehaviorSubject<Map<Key, Value>>;
-    /** Clear all items */
-    readonly clear: () => IDataStorage<Key, Value, CacheDisabled>;
-    /** Delete one or more items by their respective keys */
-    readonly delete: (key: Key | Key[]) => IDataStorage<Key, Value, CacheDisabled>;
-    /** Filter items by predicate */
-    readonly filter: <AsArray extends boolean = false>(...args: DropFirst<Parameters<typeof filter<Key, Value, AsArray>>>) => ReturnType<typeof filter<Key, Value, AsArray>>;
-    /** Find an item by predicate or search criteria */
-    readonly find: <IncludeKey extends boolean = false>(predicateOrOptions: FindOptions<Key, Value, IncludeKey> | Parameters<IDataStorage<Key, Value, CacheDisabled>['filter']>[0]) => ReturnType<typeof find<Key, Value, IncludeKey>>;
-    /** Get item by key */
-    readonly get: (key: Key) => Value | undefined;
-    /**
-     * Get all items
-     *
-     * @param forceUpdate (optional) if `true` and cache is enabled, reads & updates data directly from storage
-     * Default: `false`
-     */
-    readonly getAll: (forceUpdate?: boolean) => Map<Key, Value>;
-    /** Check if key exists */
-    readonly has: (key: Key) => boolean;
-    /**
-     * Initializes storage and sets up internal subscriptions.
-     *
-     * Manual invocation is not typically necessary, as initialization occurs automatically
-     * in one of the following scenarios:
-     * - During construction, if an `initialValue` with at least one entry is provided.
-     * - On the first attempt to read or write data.
-     *
-     * @param initialValue An optional map to initialize the storage with if it's currently empty.
-     * @returns `true` if initialization was successful, or `false` if the storage was already initialized.
-     */
-    readonly init: (initialValue?: Map<Key, Value>) => boolean;
-    /** Get all keys */
-    readonly keys: () => Key[];
-    /** Map each item on the data to an Array */
-    readonly map: <T = unknown>(callback: (value: Value, key: Key, entries: [Key, Value][], index: number) => T) => T[];
-    /**
-     * Reads and parses data directly from the persistent storage medium.
-     *
-     * This operation is synchronous and does not trigger reactive updates via `subject`.
-     * It is useful for debugging custom `parse` logic or manual data retrieval.
-     *
-     * @param dataStr (optional) A raw string to parse. If omitted, the method fetches
-     * the current value associated with the instance `name` from the underlying `storage`.
-     */
-    readonly read: (dataStr?: string | null) => Map<Key, Value>;
-    /**
-     * Search through the stored data (`Map<Key, Value>`).
-     * It supports both a global search (using a string or RegExp) across all properties
-     * of an item, and a detailed, field-specific search using a query object.
-     *
-     * @param options The search criteria. See {@link SearchOptions} for available properties.
-     *
-     * @returns A `Map` or an `Array` containing the matched items, based on the `asMap` option.
-     *
-     * @example
-     * #### Search for users in a specific city
-     * ```javascript
-     * import { DataStorage } from '@superutils/rx'
-     *
-     * const storage = new DataStorage('users', {
-     *   initialValue: new Map([
-     *     [1, { name: 'John Doe', city: 'New York' }],
-     *     [2, { name: 'Jane Doe', city: 'London' }],
-     *     [3, { name: 'Peter Jones', city: 'New York' }],
-     *   ])
-     * })
-     *
-     * const nyUsers = storage.search({ query: { city: 'New York' } })
-     * console.log(nyUsers.size) // 2
-     * ```
-     */
-    readonly search: <MatchExact extends boolean = false, AsMap extends boolean = true>(...args: DropFirst<Parameters<typeof search<Key, Value, MatchExact, AsMap>>>) => ReturnType<typeof search<Key, Value, MatchExact, AsMap>>;
-    /** Set item by key */
-    readonly set: <K extends Key, V extends Value>(key: K, value: V) => IDataStorage<Key, Value, CacheDisabled>;
-    /**
-     * Set multiple entries at once and/or replace the storage entries
-     *
-     * @param data (optional) Data to add. Default: `new Map()`
-     * @param replace (optional) Whether to merge with or replace current data.
-     * - `true`: replace all entries with `data`
-     * - `false`: merge with current data (existing entries with matching keys will be overwritten)
-     *
-     * Default: `false`
-     */
-    readonly setAll: (data?: Map<Key, Value>, replace?: boolean) => IDataStorage<Key, Value, CacheDisabled>;
-    /**
-     * Sort items in the storage.
-     *
-     * @param nameOrComparator Criteria to sort by. Accepts one of the following:
-     * - `function`: A comparator function to sort the data.
-     * - `string`: A property name of the value object to sort by.
-     * - `true`: Sorts the map by its keys.
-     * @param options (optional) Sorting options.
-     * @param options.save (optional) Whether to save the sorted data back to storage (localStorage/file).
-     *
-     * @returns The sorted Map.
-     */
-    readonly sort: StorageSort<Key, Value>;
-    /** Convert list of items (Map) to 2D Array */
-    readonly toArray: () => [Key, Value][];
-    /** Convert list of items (Map) to JSON string of 2D Array */
-    readonly toJSON: StorageToJSON<Key, Value>;
-    /** Convert list of items into an object */
-    readonly toObject: <T extends object = object>(data?: Map<Key, Value>) => T;
-    /** Convert list of items (Map) to JSON string of 2D Array */
-    readonly toString: (data?: Map<Key, Value>) => string;
-    /**
-     * Unsubscribe from all internal subscriptions.
-     *
-     * This will result in:
-     * - Automatic writing to storage being disabled (manual writes via `instance.write()` will still work).
-     * - The `onChange` callback no longer being triggered.
-     * - The instance stopping listening to force update cache triggers.
-     */
-    readonly unsubscribe: () => void;
-    /** Get all values as an array */
-    readonly values: () => Value[];
-    /**
-     * Write data to the underlying storage (localStorage or file).
-     *
-     * @param data (optional) Data to write.
-     * - If provided, it overwrites the storage.
-     * - If not provided, the current in-memory data is used (if cache is enabled).
-     * @returns `true` if the write was successful, `false` otherwise.
-     */
-    readonly write: (data?: Map<Key, Value>) => void;
-}
-interface IObjectStorage<T extends object, CacheDisabled extends boolean = false, ObjectMap extends TypedMap<T> = TypedMap<T>> extends IDataStorage<keyof T, T[keyof T], CacheDisabled> {
-    get<Key extends keyof T>(key: Key): T[Key] | undefined;
-    getAll(forceRead?: boolean): TypedMap<T>;
-    parse?: StorageParseFn<ObjectMap, IObjectStorage<T, CacheDisabled>>;
-    set<Key extends keyof T, Value extends T[Key]>(key: Key, value: Value): IObjectStorage<T, CacheDisabled>;
-    setAll(data?: ObjectMap, replace?: boolean): IObjectStorage<T, CacheDisabled>;
-    stringify?: StorageStringify<ObjectMap, IObjectStorage<T, CacheDisabled>>;
-    toObject<O extends object = T>(data?: Map<keyof T, T[keyof T]>): O;
-}
-
-/**
- * RxJS Subject to trigger forced update of cached data from underlying storage of {@link DataStorage} instances.
- *
- * `value`: determines which cache-enabled storage instances to be updated
- * - name (`string` | `string[]`): update all instances with a specific name(s)
- * - global (`true`): update all instances globally
- *
- * @example
- * ```javascript
- * import { DataStorage, forceUpdateCache$ } from '@superutils/rx'
- *
- * const names = ['products', 'users']
- *
- * // Update all DataStorage instances by a list of their names
- * forceUpdateCache$.next(names)
- * // alternatively: DataStorage.forceUpdateCache(names)
- *
- * // Update all DataStorage instances with a specific name
- * forceUpdateCache$.next(names[0])
- * // alternatively: DataStorage.forceUpdateCache(names[0])
- *
- * // Update every single instance of DataStorage that uses storage (has a "name" property)
- * forceUpdateCache$(true)
- * // alternatively: DataStorage.forceUpdateCache(true)
- * ```
- *
- * @example
- *
- * #### Practical example
- * ```typescript
- * import { DataStorage } from '@superutils/rx'
- *
- * const name = 'user-profile'
- * type User = {
- *   age: number
- *   name: string
- *   roles?: string[]
- * }
- * const userStore = DataStorage.(name, { delay: 0 }) // delay is set to zero to simplify the example
- * userStore.set('name', 'John Doe')
- * userStore.set('name', 'John Doe')
- * ```
- */
-declare const forceUpdateCache$: Subject<string | boolean | string[]>;
-/**
- *
- *
- * @remarks
- * **On the `This` template parameter:**
- * Using `This` as a self-referential template is a **good practice** in this context because:
- * - It provides accurate **type inference** for method return types that depend on the generic parameters.
- * - It enables **type-safe property access** through `This['methodName']`, allowing the implementation
- *   to reference interface contracts without circular dependencies or casting issues.
- * - It allows **fluent API chains** (returning `this`) while maintaining proper generic type information.
- * - It prevents **type widening** that would occur if methods returned the concrete class type instead
- *   of the interface type, which is important for generic constraints and polymorphism.
- *
- * However, it increases **cognitive complexity** and is only warranted when:
- * - The class implements a complex generic interface with interdependent type parameters.
- * - Type-safe property references are essential to avoid runtime errors or casting.
- * - Fluent interfaces or chaining is a core API feature.
- *
- *
- */
-/**
- * A generic, reactive data storage class that provides a Map-like interface with advanced features
- * such as search, filtering, and sorting. Supports both in-memory caching and persistent storage
- * (LocalStorage in browsers, JSON files in NodeJS via `node-localstorage` NPM module).
- *
- * #### Notes:
- * - **Performance**: `DataStorage` is optimized for small to medium datasets.
- *   - For datasets > 1MB, consider increasing the `delay` option to reduce write frequency.
- *   - It is **NOT** recommended for datasets larger than 3MB due to synchronous serialization costs.
- * - **RxJS Integration**: Built on RxJS for reactive data handling, though no prior RxJS knowledge is required.
- * - **Storage Behavior**:
- *   - If `name` is omitted, the instance operates in-memory only and data is not persisted to storage.
- *   - If `cacheDisabled` is `true`, data is not kept in memory; every read/write operation accesses the underlying
- * storage directly.
- *
- * @template Key The type of keys stored in the map.
- * @template Value The type of values stored in the map.
- * @template CacheDisabled A literal boolean type indicating whether in-memory caching is disabled.
- * @template This A self-referential interface type extending {@link IDataStorage} used for accurate
- *   method signature inference and type-safe property access. This allows method implementations to
- *   reference their return types and other method signatures through the interface definition.
- *
- * @see {@link forceUpdateCache$} for cache invalidation across instances.
- * @see {@link DataStorage.fromObject} for object-oriented storage initialization.
- *
- * @example
- * #### Browser Usage 1: use like a map
- * ```javascript
- * import { DataStorage } from '@superutils/rx'
- *
- * const userStorage = new DataStorage('users')
- * userStorage.set(1, { name: 'Alice', age: 30 })
- * const user = userStorage.get(1)
- * console.log(user) // prints: {name: 'Alice', age: 30}
- * ```
- *
- * @example
- * #### Browser Usage 2:
- * ```javascript
- * import { DataStorage } from '@superutils/rx'
- * import fetch from '@superutils/fetch'
- *
- * const { products } = await fetch.get('[DUMMYJSON-DOT-COM]/products')
- * const storage = new DataStorage('products', {
- *   initialValue: new Map(products.map(p => [p.id, p])) // convert to Map
- * })
- *
- * // print product with id `1`
- * console.log(storage.get(1))
- *
- * // search for items
- * const searchResult = storage.search({
- *   query: { availabilityStatus: 'low' }
- * })
- * console.log(searchResult)
- * ```
- * @example
- * #### NodeJS Usage
- * ```javascript
- * import { DataStorage } from '@superutils/rx'
- * import fetch from '@superutils/fetch'
- * import { LocalStorage } from 'node-localstorage'
- *
- * // Add localStorage alternative for NodeJS that reads and writes to JSON files.
- * // This is not necessary for browsers.
- * globalThis.localStorage = new LocalStorage('./data', 1e7)
- *
- * const storage = new DataStorage('products')
- * const { products } = await fetch.get('[DUMMYJSON-DOT-COM]/products')
- * // save all items to storage
- * storage.setAll(
- *   new Map(products.map(p => [p.id, p])), // convert to Map
- * )
- *
- * // print product with id `1`
- * console.log(storage.get(1))
- *
- * // search for items
- * const searchResult = storage.search({
- *   query: { availabilityStatus: 'low' }
- * })
- * console.log(searchResult)
- * ```
- *
- * @example
- * #### Advanced: `onChange` and RxJS subject
- *
- * Internally, `DataStorage` uses RxJS subject which is exposed as `subject` property.
- * You can use this to subscribe to changes and do additional operations such as logging or sanitization etc.
- *
- * Alternatively, you can also set the `onChange` callback which is triggered whenever the subject changes and
- * does not require maintaining a subscription or knowledge of RxJS subject.
- *
- * ```javascript
- * import { DataStorage } from '@superutils/rx'
- *
- * const storage = new DataStorage('my-data')
- * const sub = storage.subject.subscribe(data => {
- *   // Write to the database whenever data changes
- *   console.log('Saving to database...', data)
- * })
- * // unsubscribe from subject
- * setTimeout(()=> sub.unsubscribe(), 1000)
- *
- * // add an entry to storage
- * storage.set('bob', { age: 99, id: 'bob', name: 'Bob' })
- * ```
- */
-declare class DataStorage<Key, Value, CacheDisabled extends boolean = false, 
-/**
- * @remarks
- * **On the `This` template parameter:**
- * Using `This` as a self-referential template is a **good practice** in this context because:
- * - It provides accurate **type inference** for method return types that depend on the generic parameters.
- * - It enables **type-safe property access** through `This['methodName']`, allowing the implementation
- *   to reference interface contracts without circular dependencies or casting issues.
- * - It allows **fluent API chains** (returning `this`) while maintaining proper generic type information.
- * - It prevents **type widening** that would occur if methods returned the concrete class type instead
- *   of the interface type, which is important for generic constraints and polymorphism.
- *
- * However, it increases **cognitive complexity** and is only warranted when:
- * - The class implements a complex generic interface with interdependent type parameters.
- * - Type-safe property references are essential to avoid runtime errors or casting.
- * - Fluent interfaces or chaining is a core API feature.
- */
-This extends IDataStorage<Key, Value, CacheDisabled> = IDataStorage<Key, Value, CacheDisabled>> implements IDataStorage<Key, Value, CacheDisabled> {
-    readonly cacheDisabled: This['cacheDisabled'];
-    readonly delay: This['delay'];
-    /** Debounce and throttle related options */
-    readonly delayOptions?: This['delayOptions'];
-    readonly initialized: This['initialized'];
-    readonly name: This['name'];
-    onChange?: This['onChange'];
-    onError?: This['onError'];
-    parse?: This['parse'];
-    get size(): number;
-    spaces?: This['spaces'];
-    readonly storage?: This['storage'];
-    stringify?: This['stringify'];
-    readonly subject: This['subject'];
-    private subscriptions;
-    constructor(name?: This['name'], options?: StorageOptions<Key, Value, CacheDisabled>);
-    clear: This['clear'];
-    delete: This['delete'];
-    filter: This['filter'];
-    find: This['find'];
-    /**
-     * Creates a {@link DataStorage} instance initialized from a plain object.
-     *
-     * This factory method automatically configures `parse` and `stringify` logic to
-     * treat the underlying storage as a serialized object, while providing a
-     * type-safe Map-like interface for individual properties.
-     *
-     * This default behavior can be overridden by providing custom `parse` and `stringify` implementations in `options`.
-     *
-     * @param name (optional) The name for the storage (e.g., localStorage key or filename).
-     * @param options (optional) Configuration options for the storage instance.
-     * @param options.initialValue (optional) An optional object to populate the storage if it's currently empty.
-     *
-     * @template T (optional) The structure of the object being stored. Can auto-infer from `options.initialValue`.
-     * @template CacheDisabled (optional) Literal type determining whether to disable in-memory caching.
-     *
-     * @returns A new DataStorage instance mapped to the object's keys and values.
-     *
-     * @example
-     * #### Store and access a User object
-     * ```typescript
-     * import { DataStorage } from '@superutils/rx'
-     *
-     * interface User {
-     *   age: number;
-     *   name: string;
-     * }
-     *
-     * const initialValue: User = {
-     *   age: 99,
-     *   name: 'Ninety Nine'
-     * }
-     *
-     * // Initialize storage from the object
-     * const storage = DataStorage.fromObject<User>('user-profile', { initialValue })
-     *
-     * // Keys are inferred from the User interface
-     * const name = storage.get('name') // Inferred as: string | undefined
-     * console.log(name) // Prints: 'Ninety Nine'
-     *
-     * // Update properties safely
-     * storage.set('age', 100)
-     *
-     * // Reconstruct the updated object
-     * const userObj = storage.toObject<User>()
-     * console.log(userObj) // { age: 100, name: 'Ninety Nine' }
-     * ```
-     */
-    static fromObject: <T extends object, Key_1 extends keyof T = keyof T, Value_1 extends T[Key_1] = T[Key_1], CacheDisabled_1 extends boolean = false>(name?: string | null, options?: Omit<StorageOptions<Key_1, Value_1, CacheDisabled_1>, "initialValue"> & {
-        initialValue?: T;
-    }) => IObjectStorage<T, CacheDisabled_1>;
-    /**
-     * Trigger forced update of cached data from storage.
-     *
-     * @param name determines which cache-enabled storage instances to be updated.
-     * - name (`string` | `string[]`): update all instances with a specific name(s)
-     * - global (`true`): update all instances globally
-     *
-     * See {@link forceUpdateCache$} for more details.
-     */
-    static forceUpdateCache: (name: string | string[] | true) => void;
-    get: This['get'];
-    getAll: This['getAll'];
-    private handleForceUpdateCacheChange;
-    private handleSubjectChange;
-    has: This['has'];
-    init: This['init'];
-    keys: This['keys'];
-    map: This['map'];
-    read: This['read'];
-    search: This['search'];
-    set: This['set'];
-    setAll: This['setAll'];
-    sort: This['sort'];
-    toArray: This['toArray'];
-    toJSON: This['toJSON'];
-    toObject: This['toObject'];
-    toString: This['toString'];
-    private triggerOnError;
-    unsubscribe: This['unsubscribe'];
-    values: This['values'];
-    write: This['write'];
+    }>;
+    var IGNORE: typeof IGNORE_UPDATE_SYMBOL;
 }
 
 /**
@@ -942,16 +349,6 @@ declare class IntervalRunner<TResult = unknown, TArgs extends unknown[] = unknow
     stop: (resetRunCount?: boolean) => this;
 }
 
-/**
- * Check if value is similar to a RxJS subject with .subscribe & .next functions
- *
- * @param x The value to check
- * @param withValue When `true`, also checks if `value` property exists in `x`
- *
- * @returns `true` if the value is subject-like, `false` otherwise.
- */
-declare const isSubjectLike: <T>(x: unknown, withValue?: boolean) => x is SubjectLike<T>;
-
 /**
  * Check if value is an instance of RxJS `Subscription` or subscription-like object
  *
@@ -961,10 +358,10 @@ declare const isSubjectLike: <T>(x: unknown, withValue?: boolean) => x is Subjec
 declare const isSubscriptionLike: (value: unknown, strict?: boolean) => value is Subscription;
 
 /**
- * @function    unsubscribeAll
- * @summary unsubscribe to multiple RxJS subscriptions
- * @param   {Function|Unsubscribable|Array} unsub
+ * Unsubscribe from one or mroe RxJS subscriptions
+ *
+ * @param candidate RxJS subscription, unsubscribe function or mix of both in array/object
  */
-declare const unsubscribeAll: (unsub?: UnsubscribeCandidates, onError?: (err: unknown) => void) => void;
+declare const unsubscribeAll: (candidate?: UnsubscribeCandidate, onError?: (err: unknown) => void) => void;
 
-export { type CopyRxSubjectOptions, DataStorage, type DelayOptions, type IDataStorage, IGNORE_UPDATE_SYMBOL, type IObjectStorage, IntervalRunner, IntervalSubject, OnErrorType, type OnResultType, type StorageCompact, type StorageOptions, type StorageParseFn, type StorageSearch, type StorageSort, type StorageSortByComparator, type StorageSortByKey, type StorageSortByPropertyName, type StorageSortOptions, type StorageStringify, type StorageToJSON, type SubjectLike, type SubscriptionLike, type Unsubscribe, type UnsubscribeCandidates, type UnwrapSubjectValue, type ValueModifier, asPromise, copyRxSubject, forceUpdateCache$, isSubjectLike, isSubscriptionLike, type onBeforeExecType, unsubscribeAll };
+export { type AsPromise_Defaults, type AsPromise_Options, type CopyRx_Options, type CopyRx_Transform, IGNORE_UPDATE_SYMBOL, IntervalRunner, IntervalSubject, type OnResultType, type Unsubscribe, type UnsubscribeCandidate, type UnwrapSourceValue, type UnwrapSourceValueStrict, asPromise, copyRx, isSubscriptionLike, type onBeforeExecType, unsubscribeAll };