@superutils/rx 0.1.6 → 0.1.7

package/dist/index.d.ts

@@ -1,7 +1,8 @@
 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';
+import { DeferredOptions, ThrottleOptions, DebounceOptions, ValueOrPromise, DropFirst, filter, FindOptions, find, search, sort, SortOptions, TypedMap } from '@superutils/core';
+export { TypedMap, objToMap } from '@superutils/core';
 
 interface SubjectLike<T = unknown> {
     next: (value: T) => void;
@@ -177,20 +178,31 @@ declare enum OnErrorType {
 }
 /** Storage type with only properties that are used by `DataStorage` */
 type StorageCompact = Pick<Storage, 'getItem' | 'setItem'>;
-type StorageFilter<K, V, AsArray extends boolean = false> = (...args: DropFirst<Parameters<typeof filter<K, V, AsArray>>>) => ReturnType<typeof filter<K, V>>;
-type StorageFind<K, V, AsArray extends boolean = false> = (predicateOrOptions: Parameters<StorageFilter<K, V, AsArray>>[0] | Parameters<StorageSearch<K, V>>[0]) => V | undefined;
-type StorageMap<K, V, T = unknown> = (callback: (value: V, key: K, data: [K, V][], index: number) => T) => T[];
-type StorageOnChangeFn<K, V, CD extends boolean = false> = (this: IDataStorage<K, V, CD>, data: Map<K, V>) => ValueOrPromise<void | Map<K, V>>;
-type StorageOnErrorFn<K, V, CD extends boolean = false> = (this: IDataStorage<K, V, CD>, err: unknown, type: OnErrorType) => ValueOrPromise<void>;
 /** Initial options provided through the constructor */
 type StorageOptions<Key, Value, CacheDisabled extends boolean = false> = {
-    /** value to set, only if storage is empty. Default: `new Map()` */
+    /**
+     * 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<K, V, CD extends boolean = false> = (this: IDataStorage<K, V, CD>, data: string) => Map<K, V>;
+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> = [
@@ -205,7 +217,7 @@ type StorageSortByPropertyName<V> = [
 type StorageSortOptions = SortOptions & {
     save?: boolean;
 };
-type StorageStringifyFn<K, V, CD extends boolean = false> = (this: IDataStorage<K, V, CD>, data: Map<K, V>) => string;
+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) */
@@ -230,7 +242,46 @@ interface IDataStorage<Key, Value, CacheDisabled extends boolean = false> {
      *
      * Default: `''`
      */
-    readonly name?: string;
+    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` */
@@ -249,6 +300,45 @@ interface IDataStorage<Key, Value, CacheDisabled extends boolean = false> {
      * - 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.
      *
@@ -263,18 +353,19 @@ interface IDataStorage<Key, Value, CacheDisabled extends boolean = false> {
     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>;
+    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>;
+    readonly getAll: (forceUpdate?: boolean) => Map<Key, Value>;
     /** Check if key exists */
     readonly has: (key: Key) => boolean;
     /**
@@ -292,51 +383,46 @@ interface IDataStorage<Key, Value, CacheDisabled extends boolean = false> {
     /** Get all keys */
     readonly keys: () => Key[];
     /** Map each item on the data to an Array */
-    readonly map: StorageMap<Key, Value>;
+    readonly map: <T = unknown>(callback: (value: Value, key: Key, entries: [Key, Value][], index: number) => T) => T[];
     /**
-     * A callback function executed whenever a data change occurs within the storage.
+     * Reads and parses data directly from the persistent storage medium.
      *
-     * 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}.
+     * This operation is synchronous and does not trigger reactive updates via `subject`.
+     * It is useful for debugging custom `parse` logic or manual data retrieval.
      *
-     * Note: Execution of this callback is managed by internal subscriptions and will stop
-     * firing once {@link unsubscribe} is called.
+     * @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`.
      */
-    onChange?: StorageOnChangeFn<Key, Value, CacheDisabled>;
+    readonly read: (dataStr?: string | null) => Map<Key, Value>;
     /**
-     * A global error handler invoked whenever an internal operation fails.
+     * 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.
      *
-     * 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}.
+     * @param options The search criteria. See {@link SearchOptions} for available properties.
      *
-     * **Note:** If this handler itself throws an error, the exception is
-     * ignored gracefully to prevent application crashes during storage cycles.
-     */
-    onError?: StorageOnErrorFn<Key, Value, CacheDisabled>;
-    /**
-     * A callback to customize the deserialization of data read from storage.
+     * @returns A `Map` or an `Array` containing the matched items, based on the `asMap` option.
      *
-     * 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}.
+     * @example
+     * #### Search for users in a specific city
+     * ```typescript
+     * import { DataStorage } from '@superutils/rx'
      *
-     * **Fallback Behavior:**
-     * If this function is not defined, throws an error, or returns a non-Map value,
-     * the system falls back to internal `JSON.parse` logic.
+     * 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' }],
+     *   ])
+     * })
      *
-     * **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}.
+     * const nyUsers = storage.search({ query: { city: 'New York' } })
+     * console.log(nyUsers.size) // 2
+     * ```
      */
-    readonly parse?: StorageParseFn<Key, Value, CacheDisabled>;
-    /** 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>;
+    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: (key: Key, value: Value) => IDataStorage<Key, Value, CacheDisabled>;
+    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
      *
@@ -361,48 +447,14 @@ interface IDataStorage<Key, Value, CacheDisabled extends boolean = false> {
      * @returns The sorted Map.
      */
     readonly sort: StorageSort<Key, Value>;
-    /**
-     * 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 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}.
-     *
-     * @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 })
-     * ```
-     */
-    readonly stringify?: StorageStringifyFn<Key, Value, CacheDisabled>;
     /** 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: (data?: Map<Key, Value>) => Record<Key & string, Value>;
+    readonly toObject: <T extends object = object>(data?: Map<Key, Value>) => T;
     /** Convert list of items (Map) to JSON string of 2D Array */
-    readonly toString: () => string;
+    readonly toString: (data?: Map<Key, Value>) => string;
     /**
      * Unsubscribe from all internal subscriptions.
      *
@@ -420,137 +472,231 @@ interface IDataStorage<Key, Value, CacheDisabled extends boolean = false> {
      * @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;
+    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;
 }
 
 /**
- * Force all or specific instances of DataStorage to reload data from storage
+ * 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'
  *
- * // Update all DataStorage instances with specific name(s)
- * const name = 'products'
- * forceUpdateCache$.next([name])
+ * 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')
  *
- * // 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, CacheDisabled extends boolean = false> implements IDataStorage<Key, Value, CacheDisabled> {
-    readonly cacheDisabled: CacheDisabled;
-    readonly delay: number;
+/**
+ *
+ *
+ * @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('[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('[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' })
+ * ```
+ */
+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?: DelayOptions;
-    readonly initialized: boolean;
-    readonly name: string;
+    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?: number;
-    readonly storage?: StorageCompact | null;
-    readonly subject: CacheDisabled extends true ? Subject<Map<Key, Value>> : BehaviorSubject<Map<Key, Value>>;
+    spaces?: This['spaces'];
+    readonly storage?: This['storage'];
+    stringify?: This['stringify'];
+    readonly subject: This['subject'];
     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>);
-    clear(): this;
-    delete(keys: Key | Key[]): this;
-    find(predicateOrOptions: Parameters<StorageFind<Key, Value>>[0]): Value | undefined;
-    filter<AsArray extends boolean = false>(...args: Parameters<StorageFilter<Key, Value, AsArray>>): AsArray extends true ? Value[] : Map<Key, Value>;
+    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.
      *
@@ -597,54 +743,40 @@ declare class DataStorage<Key, Value, CacheDisabled extends boolean = false> imp
      * console.log(userObj) // { age: 100, name: 'Ninety Nine' }
      * ```
      */
-    static fromObject: <T extends object, CacheDisabled_1 extends boolean = false>(name?: string, options?: Omit<StorageOptions<keyof T, T[keyof T], CacheDisabled_1>, "initialValue"> & {
+    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;
-    }) => DataStorage<keyof T, T[keyof T], CacheDisabled_1>;
+    }) => IObjectStorage<T, CacheDisabled_1>;
     /**
      * Trigger forced update of cached data from storage.
      *
-     * @param name determines which storage instances to be updated.
+     * @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
      *
-     * @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)
-     * ```
+     * See {@link forceUpdateCache$} for more details.
      */
     static forceUpdateCache: (name: string | string[] | true) => void;
-    get(key: Key): Value | undefined;
-    getAll(forceRead?: boolean): Map<Key, Value>;
+    get: This['get'];
+    getAll: This['getAll'];
     private handleForceUpdateCacheChange;
     private handleSubjectChange;
-    has(key: Key): boolean;
-    init(initialValue?: Map<Key, Value>): boolean;
-    keys(): Key[];
-    map<T>(callback: Parameters<StorageMap<Key, Value, T>>[0]): T[];
-    onChange?: StorageOnChangeFn<Key, Value, CacheDisabled>;
-    onError?: StorageOnErrorFn<Key, Value, CacheDisabled>;
-    readonly parse?: StorageParseFn<Key, Value, CacheDisabled>;
-    read(): Map<Key, Value>;
-    search<MatchExact extends boolean = false, AsMap extends boolean = true>(options: Parameters<StorageSearch<Key, Value, MatchExact, AsMap>>[0]): AsMap extends true ? Map<Key, Value> : Value[];
-    set(key: Key, value: Value): this;
-    setAll(data?: Map<Key, Value>, replace?: boolean): this;
-    sort(...args: Parameters<StorageSort<Key, Value>>): Map<Key, Value>;
-    readonly stringify?: StorageStringifyFn<Key, Value, CacheDisabled>;
-    toArray(): [Key, Value][];
-    toJSON(...[replacer, spacing, data]: Parameters<StorageToJSON<Key, Value>>): string;
-    toObject<T extends object = object>(data?: Map<Key, Value>): T;
-    toString(data?: Map<Key, Value>): string;
+    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(): void;
-    values(): Value[];
-    write(data?: Map<Key, Value>): boolean;
+    unsubscribe: This['unsubscribe'];
+    values: This['values'];
+    write: This['write'];
 }
 
 /**
@@ -834,4 +966,4 @@ declare const isSubscriptionLike: (value: unknown, strict?: boolean) => value is
  */
 declare const unsubscribeAll: (unsub?: UnsubscribeCandidates, onError?: (err: unknown) => void) => void;
 
-export { type CopyRxSubjectOptions, DataStorage, type DelayOptions, type IDataStorage, IGNORE_UPDATE_SYMBOL, IntervalRunner, IntervalSubject, 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 SubjectLike, type SubscriptionLike, type Unsubscribe, type UnsubscribeCandidates, type UnwrapSubjectValue, type ValueModifier, asPromise, copyRxSubject, forceUpdateCache$, isSubjectLike, isSubscriptionLike, type onBeforeExecType, unsubscribeAll };
+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 };