@superutils/rx 0.1.1

package/dist/index.d.ts

@@ -0,0 +1,730 @@
+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, DropFirst, filter, search, ValueOrPromise, sort, SortOptions } 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]>;
+} : 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 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.
+ *
+ * @returns timeout promise
+ *
+ * @example
+ * #### Create a promise using RxJS subject
+ * ```typescript
+ * import { BehaviorSubject, subjectAsPromise } from '@superutils/rx'
+ *
+ * const subject = new BehaviorSubject(0)
+ * setInterval(() => subject.next(subject.value + 1), 1000)
+ *
+ * // resolve conditionally based on value received
+ * subjectAsPromise(subject, value => value >= 3)
+ * 	.then(value => console.log('Expected >= 3, received ', value))
+ *
+ * // resolve when only specific value is received
+ * 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>;
+
+/** Symbol used to signal to ignore an update when using a `valueModifier()` callback with {@link copyRxSubject} */
+declare const IGNORE_UPDATE_SYMBOL: unique symbol;
+type CopyRxSubjectOptions<ThisArg> = {
+    delay?: number;
+} & DeferredOptions<ThisArg>;
+/**
+ * Value modifier function definition for {@link copyRxSubject}
+ *
+ * Returning {@link IGNORE_UPDATE_SYMBOL} will ignore the update.
+ */
+type ValueModifier<T = unknown, TCopy = T> = (newValue: T, previousValue: TCopy | undefined, copy$: SubjectLike<TCopy>) => TCopy | typeof IGNORE_UPDATE_SYMBOL;
+/**
+ * @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
+ *
+ * @example
+ * #### Auto-copy values from a single subject
+ * ```typescript
+ * import { BehaviorSubject, copyRxSubject } 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$t
+ *   // {
+ *   //   delay: 300 //
+ *   //   throttle: false,
+ *   // }
+ * )
+ * // subscribe to even$ changes
+ * even$.subscribe(console.log)
+ * number$.next(2) // prints: true
+ * number$.next(3) // print: false
+ * ```
+ *
+ * @example
+ * #### Auto-copy from an array of subjects & values
+ * ```javascript
+ * import { BehaviorSubject, copyRxSubject } from '@superutils/rx'
+ *
+ * const theme$ = new BehaviorSubject('dark')
+ * const userId$ = new BehaviorSubject('username')
+ * const settings$ = copyRxSubject(
+ *   [
+ * 	   theme$,
+ * 	   userId$,
+ * 	   'my-fancy-app' // fixed/unobserved value
+ * 	 ]
+ * )
+ * // subscribe to the subject with reduced array values
+ * settings$.subscribe(([theme, user, appName]) =>
+ * 	 console.log({ theme, user, appName })
+ * )
+ * ```
+ */
+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: {
+        delay: number;
+    } & DeferredOptions<unknown>;
+    var IGNORE_UPDATE_SYMBOL: typeof IGNORE_UPDATE_SYMBOL;
+}
+
+type DelayOptions = ({
+    throttle: true;
+} & Omit<ThrottleOptions, 'onError' | 'thisArg'>) | ({
+    throttle?: false;
+} & Omit<DebounceOptions, 'onError' | 'thisArg'>);
+type OnErrorType = 'onChange' | 'parse' | 'parse-json' | 'stringify' | 'stringify-json' | 'write';
+/** Storage type with only properties that are used by `DataStorage` */
+type StorageCompact = Pick<Storage, 'getItem' | 'setItem'>;
+type StorageFilter<K, V extends StorageValue> = <IncludeKey extends boolean = false>(...args: DropFirst<Parameters<typeof filter<K, V, IncludeKey>>>) => ReturnType<typeof filter<K, V, IncludeKey>>;
+type StorageFind<K, V extends StorageValue> = (predicateOrOptions: Parameters<StorageFilter<K, V>>[0] | Parameters<StorageSearch<K, V>>[0]) => V | undefined;
+type StorageMap<K, V extends StorageValue> = <T>(callback: (value: V, key: K, data: [K, V][], index: number) => T) => T[];
+/**
+ * Callback triggered when value changes and/or a force read is triggered
+ */
+type StorageOnChangeFn<K, V extends StorageValue> = (data: Map<K, V>) => ValueOrPromise<void | Map<K, V>>;
+type StorageOnErrorFn = (err: unknown, type: OnErrorType) => ValueOrPromise<void>;
+/** Initial options provided through the constructor */
+type StorageOptions<Key, Value extends StorageValue, CacheDisabled extends boolean = false> = {
+    /** value to set, only if storage is empty. Default: `new Map()` */
+    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<K, V extends StorageValue> = (data: string) => Map<K, V>;
+type StorageSearch<K, V extends StorageValue> = <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 extends StorageValue> = (...args: StorageSortByComparator<K, V> | StorageSortByPropertyName<V> | StorageSortByKey) => Map<K, V>;
+type StorageSortByComparator<K, V extends StorageValue> = [
+    comparator: Parameters<typeof sort<K, V>>[1],
+    options?: StorageSortOptions
+];
+type StorageSortByKey = [byKey: true, options?: StorageSortOptions];
+type StorageSortByPropertyName<V extends StorageValue> = [
+    propertyName: keyof V & string,
+    options?: StorageSortOptions
+];
+type StorageSortOptions = SortOptions & {
+    save?: boolean;
+};
+type StorageStringifyFn<K, V extends StorageValue> = (data: Map<K, V>) => string;
+type StorageToJSON<K, V> = (replacer?: null | ((key: K, value: V) => unknown), spacing?: string | number, data?: Map<K, V>) => string;
+type StorageValue = Record<PropertyKey, unknown>;
+interface IDataStorage<Key, Value extends StorageValue, 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;
+    /** 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;
+    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>;
+    /** Find an item by predicate or search criteria */
+    readonly find: StorageFind<Key, Value>;
+    /** Filter items by predicate */
+    readonly filter: StorageFilter<Key, Value>;
+    /** 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
+     */
+    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: StorageMap<Key, Value>;
+    /**
+     * Callback to be invoked  whenever value change is triggered.
+     *
+     * If `onChange` invocation fails, it will be ignored gracefully.
+     */
+    onChange?: StorageOnChangeFn<Key, Value>;
+    /**
+     * Callback to be invoked whenever read/write operation fails.
+     *
+     * If `onError` invocation failure will be ignored gracefully.
+     */
+    onError?: StorageOnErrorFn;
+    /**
+     * A callback to customize the deserialization of data read from storage.
+     *
+     * This can be used to override the default `JSON.parse` behavior and serves as the counterpart to `stringify`.
+     * If this function is not provided, throws an error, or returns `undefined`, the default
+     * `JSON.parse` will be used as a fallback.
+     */
+    readonly parse?: StorageParseFn<Key, Value>;
+    /** Read directly from the localStorage (browser) or file (NodeJS) without triggering the `this.subject`. */
+    readonly read: () => Map<Key, Value>;
+    /** Search items */
+    readonly search: StorageSearch<Key, Value>;
+    /** Set item by key */
+    readonly set: (key: Key, value: Value) => 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>;
+    /**
+     * Callback function to customize the serialization of data to be stored to storage.
+     *
+     * Useful when data needs to be sanitised before storing and/or remove circlar references.
+     *
+     * @example
+     * ```javascript
+     * import fetch from '@superutils/fetch'
+     * import { DataStorage } from '@superutils/rx'
+     * import { LocalStorage } from 'node-localstorage'
+     *
+     * // Create a 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.json')
+     * storage.stringify = data => Array
+     * 	.from(data)
+     *  .map(([key, product]) => [
+     *    key,
+     *    { id: product.id, title: product.title } // only store what's needed
+     *  ])
+     *
+     * const { products } = await fetch('[DUMMYJSON-DOT-COM]/products)
+     * const productsMap = result.products.map(p => [p.id, p])
+     * storage.setAll(productsMap, true)
+     * console.log(storage.getAll())
+     * ```
+     */
+    readonly stringify?: StorageStringifyFn<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 (Map) to JSON string of 2D Array */
+    readonly toString: () => 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 */
+    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).
+     * @param silent (optional) Whether to suppress errors if the write operation fails.
+     * - `true`: Returns `false` on failure without throwing.
+     * - `false`: Throws an error on failure.
+     *
+     * Default: `this.silent`
+     * @returns `true` if the write was successful, `false` otherwise.
+     */
+    readonly write: (data?: Map<Key, Value>, silent?: boolean) => void;
+}
+
+/**
+ * Force all or specific instances of DataStorage to reload data from storage
+ *
+ * @example
+ * ```javascript
+ * import { DataStorage } from '@superutils/rx'
+ *
+ * // Update all DataStorage instances with specific name(s)
+ * const name = 'products'
+ * forceUpdateCache$.next([name])
+ *
+ * // Update every single instance of DataStorage that uses storage (has a "name")
+ * forceUpdateCache$.next(true)
+ * ```
+ */
+declare const forceUpdateCache$: Subject<string | boolean | string[]>;
+declare class DataStorage<Key, Value extends StorageValue, CacheDisabled extends boolean = false> implements IDataStorage<Key, Value, CacheDisabled> {
+    readonly cacheDisabled: CacheDisabled;
+    readonly delay: number;
+    readonly delayOptions?: DelayOptions;
+    /** Debounce and throttle related options */
+    readonly initialized: boolean;
+    readonly name: string;
+    get size(): number;
+    spaces?: number;
+    readonly storage?: StorageCompact | null;
+    readonly subject: CacheDisabled extends true ? Subject<Map<Key, Value>> : BehaviorSubject<Map<Key, Value>>;
+    private subscriptions;
+    /**
+     * A wrapper for reading and writing to LocalStorage (browser) or JSON files (NodeJS),
+     * providing a Map-like interface with advanced features like search, filtering, and sorting.
+     *
+     * #### 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.
+     *
+     * @example
+     * #### Browser Usage
+     * ```javascript
+     * import { DataStorage } from '@superutils/rx'
+     * import fetch from '@superutils/fetch'
+     *
+     * const storage = new DataStorage('products')
+     * const { products } = await fetch('[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
+     * #### 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('[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.unsbuscribe(), 1000)
+     *
+     * // add an entry to storage
+     * storage.set('bob', { age: 99, id: 'bob', name: 'Bob' })
+     * ```
+     */
+    constructor(name?: string | null, options?: StorageOptions<Key, Value, CacheDisabled>);
+    readonly clear: () => this;
+    readonly delete: (keys: Key | Key[]) => this;
+    readonly find: StorageFind<Key, Value>;
+    readonly filter: StorageFilter<Key, Value>;
+    /**
+     * Trigger forced update of cached data from storage.
+     *
+     * @param name determines which 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 } from '@superutils/rx'
+     *
+     * // Update all DataStorage instances with specific name(s)
+     * const name = 'products'
+     * DataStorage.forceUpdateCache([name])
+     *
+     * // Update every single instance of DataStorage that uses storage (has a "name")
+     * DataStorage.forceUpdateCache(true)
+     * ```
+     */
+    static forceUpdateCache: (name: string | string[] | true) => void;
+    readonly get: (key: Key) => Value | undefined;
+    readonly getAll: (forceRead?: boolean) => Map<Key, Value>;
+    readonly has: (key: Key) => boolean;
+    readonly init: (initialValue?: Map<Key, Value>) => boolean;
+    readonly keys: () => Key[];
+    readonly map: StorageMap<Key, Value>;
+    onChange?: StorageOnChangeFn<Key, Value>;
+    onError?: StorageOnErrorFn;
+    readonly parse?: StorageParseFn<Key, Value>;
+    readonly read: () => Map<Key, Value>;
+    readonly search: StorageSearch<Key, Value>;
+    readonly set: (key: Key, value: Value) => this;
+    readonly setAll: (data?: Map<Key, Value>, replace?: boolean) => this;
+    readonly sort: StorageSort<Key, Value>;
+    readonly stringify?: StorageStringifyFn<Key, Value>;
+    readonly toArray: () => [Key, Value][];
+    readonly toJSON: StorageToJSON<Key, Value>;
+    readonly toString: (data?: Map<Key, Value>) => string;
+    private triggerOnError;
+    readonly unsubscribe: () => void;
+    readonly values: () => Value[];
+    readonly write: (data?: Map<Key, Value>) => boolean;
+}
+
+/**
+ * @summary	Extention of a BehaviorSubject with interval function
+ *
+ * -----------------------------------------------
+ *
+ * @example
+ * #### Fetch data from API server every minute
+ * ```typescript
+ * import fetch from '@superutils/fetch'
+ * import { IntervalSubject } from '@superutils/rx'
+ *
+ * const initialValue = 0
+ * const interval$ = new IntervalSubject(
+ * 	true, // auto-start
+ * 	60 * 1000, // interval delay. increment counter every "x" milliseconds
+ *  initialValue, // initial counter value
+ * 	1, // increment by 1 at each interval
+ * )
+ *
+ * const onChange = (counter: number) => {
+ *   counter === initialValue && console.log('Counter started')
+ *   fetch.get('[DUMMYJSON-DOT-COM]/http/200').then(
+ *     () => console.log(new Date().toISOString(), 'Successful ping'),
+ *     (err: Error) => console.log('Ping failed.', err)
+ *   )
+ * }
+ *
+ * // BehaviorSubject automatically resolves with the initial value if subscribed immediately.
+ * // subscribe to the subject and execute `onChange`: first time immediately and then every 60 seconds
+ * interval$.subscribe(onChange)
+ * ```
+ */
+declare class IntervalSubject extends BehaviorSubject<number> {
+    autoStart: boolean;
+    private _delay;
+    readonly initialValue: number;
+    incrementBy: number;
+    private _intervalId;
+    private _running;
+    constructor(autoStart: boolean, _delay?: number, initialValue?: number, incrementBy?: number);
+    get delay(): number;
+    set delay(newDelay: number);
+    get running(): boolean;
+    pause: () => this;
+    resume: () => this;
+    start: () => this;
+    stop: () => this;
+}
+
+type OnResultType<TResult = unknown> = (error: Error | null, result: TResult | undefined, runCount: number, once: boolean) => void | Promise<void>;
+type onBeforeExecType = (runCount: number, once: boolean) => void | Promise<unknown>;
+/**
+ * @summary	a simple runner to execute a task periodically.
+ *
+ * When to use `IntervalRunner` instead of `IntervalSubject`?
+ *
+ * `IntervalRunner` is useful when the execution of the `onResult` time must be on the clock and/or must be excluded
+ * from the interval delay duration.
+ *
+ * Example use case:
+ * When an API call needs to be made periodically and there's a possibility of delayed response (due to network issues
+ * or longer backend execution time). In this case, using IntervalRunner with `sequential = true` will ensure the
+ * delay is consistent between completion of current and start of the next API call.
+ *
+ * @param	taskFn		task function to be executed periodically
+ * @param	taskArgs	arguments to be supplied to the task function.
+ * @param	intervalMs	timer delay in milliseconds.
+ * @param	sequential	true (default): will use setTimeout and will delay until execution is completed.
+ * This will ensure, in case the current execution takes longer, the following execution will not occur until current one is done and the interval delay is passed.
+ *
+ * false: will use setInterval and the delay time to execute task will not affected. This may cause unwanted issues if the execution takes longer than the interval delay time. Use with caution.
+ *
+ * Default: `true`
+ *
+ * @param	preExecute	(optional) if true, will pre-execute task before starting the timer.
+ *
+ * Default: `true`
+ *
+ * @example
+ * #### Execute a function sequentially
+ * Counting time will not start until function execution ends, maintaining the delay betweeen
+ * end of execution consistent.
+ * ```typescript
+ * import fetch from '@superutils/fetch'
+ * import { IntervalRunner } fro '@superutils/rx'
+ *
+ * const runner = new IntervalRunner(
+ *     fetch.get,
+ * 	   ['[DUMMYJSON-DOT-COM]/products'],
+ *     2000,
+ *  )
+ * runner.start(result => console.log({ result }))
+ * ```
+ *
+ * @example
+ * #### Execute a function at without enforcing sequential execution.
+ * Will start counting time even if function execution is unfinied, maintaining the delay betweeen
+ * start of execution consistent.
+ * ```typescript
+ * import fetch from '@superutils/fetch'
+ * import { IntervalRunner } fro '@superutils/rx'
+ *
+ * const runner = new IntervalRunner(
+ *   fetch.get,
+ * 	 ['[DUMMYJSON-DOT-COM]/products'],
+ *   2000,
+ *   false,
+ *  )
+ * runner.start(result => console.log({ result }))
+ * ```
+ */
+declare class IntervalRunner<TResult = unknown, TArgs extends unknown[] = unknown[]> {
+    readonly taskFn: (...args: TArgs) => TResult | Promise<TResult>;
+    readonly taskArgs: TArgs;
+    readonly sequential: boolean;
+    readonly preExecute: boolean;
+    private idInterval;
+    lastResult: TResult | undefined;
+    minIntervalMs: number;
+    private onBeforeExec?;
+    private onResult;
+    /**
+     * @summary RxJS BehaviorSubject to change timer delay and restart the timer
+     */
+    readonly intervalMs$: BehaviorSubject<number>;
+    private runCount;
+    private started;
+    private subscription;
+    constructor(taskFn: (...args: TArgs) => TResult | Promise<TResult>, taskArgs: TArgs, intervalMs: BehaviorSubject<number> | number, sequential?: boolean, // if true, timer will start start only after execution is finished
+    preExecute?: boolean);
+    private clearInterval;
+    private executeTask;
+    /** Execute the task function regardless of the interval runner state */
+    executeOnce: () => Promise<TResult | undefined>;
+    /** Check if interval is running*/
+    isStarted: () => boolean;
+    /**
+     * Restart interval
+     *
+     * @param resetRunCount (optional) whether to reset run count
+     *
+     * @returns {Boolean} indicates whether restart was successful
+     */
+    restart: (resetRunCount?: boolean) => boolean;
+    /**
+     * @summary set `onResult` & `onBeforeExec` callbacks and start execution.
+     *
+     * If it's already running, the callbacks will be used on the next execution.
+     *
+     * In order to start using callbacks immediately, invoke the `intervalRunner.stop()` function first.
+     *
+     * @returns {Boolean} indicates whether starting interveral waa successful
+     */
+    start: (onResult: OnResultType<TResult>, onBeforeExec?: onBeforeExecType) => boolean;
+    /**
+     * Stop interval runner
+     *
+     * @param	resetRunCount	(optional) whether to reset the run counter
+     */
+    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
+ *
+ * @param value
+ * @param strict (optional) if true, will only check if value is instance of Subscription. Default: `false`
+ */
+declare const isSubscriptionLike: (value: unknown, strict?: boolean) => value is Subscription;
+
+/**
+ * @function    unsubscribeAll
+ * @summary unsubscribe to multiple RxJS subscriptions
+ * @param   {Function|Unsubscribable|Array} unsub
+ */
+declare const unsubscribeAll: (unsub?: UnsubscribeCandidates, onError?: (err: unknown) => void) => void;
+
+export { type CopyRxSubjectOptions, DataStorage, type DelayOptions, type IDataStorage, IGNORE_UPDATE_SYMBOL, IntervalRunner, IntervalSubject, type OnErrorType, type OnResultType, type StorageCompact, type StorageFilter, type StorageFind, type StorageMap, type StorageOnChangeFn, type StorageOnErrorFn, type StorageOptions, type StorageParseFn, type StorageSearch, type StorageSort, type StorageSortByComparator, type StorageSortByKey, type StorageSortByPropertyName, type StorageSortOptions, type StorageStringifyFn, type StorageToJSON, type StorageValue, type SubjectLike, type SubscriptionLike, type Unsubscribe, type UnsubscribeCandidates, type UnwrapSubjectValue, type ValueModifier, asPromise, copyRxSubject, forceUpdateCache$, isSubjectLike, isSubscriptionLike, type onBeforeExecType, unsubscribeAll };