@superutils/store 0.1.14

package/dist/index.d.ts

@@ -0,0 +1,834 @@
+import { Subject, BehaviorSubject } from 'rxjs';
+import { ThrottleOptions, DebounceOptions, sort, SortOptions, DropFirst, search, ValueOrPromise, filter, FindOptions, find, TypedMap } from '@superutils/core';
+export { TypedMap, objToMap } from '@superutils/core';
+
+/** Bare miminal storage with only properties that are used by `Store` */
+type StorageCompact = Pick<Storage, 'getItem' | 'setItem'>;
+/** Throttle & debounce related options */
+type Store_DelayOptions = ({
+    throttle: true;
+} & Omit<ThrottleOptions, 'onError' | 'thisArg'>) | ({
+    throttle?: false;
+} & Omit<DebounceOptions, 'onError' | 'thisArg'>);
+/**
+ * Categorizes errors encountered during Store 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 Store_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"
+}
+/** Initial options provided through the constructor */
+type Store_Options<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<IStore<Key, Value, CacheDisabled>>, 'cacheDisabled' | 'onChange' | 'onError' | 'parse' | 'spaces' | 'storage' | 'stringify'> & {
+    /**
+     * If `true`, storage validation is delayed until initialization.
+     *
+     * By default, if a `name` is provided, the constructor throws an error if no valid
+     * storage mechanism (like `localStorage`) is found. Enabling this allows the
+     * instance to be created even if storage is temporarily missing, throwing the error
+     * only when `init()` is called - manually, on first read/write, or automatically
+     * when non-empty `initialValue` is provided..
+     *
+     * Default: `false`
+     */
+    checkStorageOnInit?: boolean;
+} & (CacheDisabled extends false ? Pick<Partial<IStore<Key, Value, CacheDisabled>>, 'delay' | 'delayOptions'> : {
+    delay?: never;
+    delayOptions?: never;
+});
+type Store_Parse<ResultMap, ThisArg> = (this: ThisArg, text: string | null | undefined) => ResultMap | void;
+type Store_Search<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 Store_Sort<K, V> = (...args: Store_SortByComparator<K, V> | Store_SortByPropertyName<V> | Store_SortByKey) => Map<K, V>;
+type Store_SortByComparator<K, V> = [
+    comparator: Parameters<typeof sort<K, V>>[1],
+    options?: Store_SortOptions
+];
+type Store_SortByKey = [byKey: true, options?: Store_SortOptions];
+type Store_SortByPropertyName<V> = [
+    propertyName: keyof V & string,
+    options?: Store_SortOptions
+];
+type Store_SortOptions = SortOptions & {
+    save?: boolean;
+};
+type Store_Stringify<Data, ThisArg> = (this: ThisArg, data: Data) => string | undefined | void;
+type Store_ToJSON<K, V> = (replacer?: null | ((key: K, value: V) => unknown), spacing?: string | number, data?: Map<K, V>) => string;
+
+/**
+ * Represents a generic, reactive, and persistent Map-like data store.
+ *
+ * The `IStore` interface defines the contract for a data structure that combines the standard
+ * functionality of a JavaScript `Map` with advanced features such as RxJS-powered reactivity,
+ * optional persistence (e.g., to LocalStorage or a JSON file), and built-in search, sorting, and filtering.
+ *
+ * It is designed to be framework-agnostic but provides features that integrate well with
+ * reactive systems and modern UI libraries like React.
+ *
+ * @template Key - The type of keys used to identify values in the store.
+ * @template Value - The type of values stored in the store.
+ * @template CacheDisabled - A boolean flag; if `true`, the store operates without an in-memory cache,
+ * reading and writing directly to the underlying storage on every operation.
+ */
+interface IStore<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?: Store_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: `null`
+     */
+    readonly name?: string | null;
+    /**
+     * Indicates type of data parsed as
+     *
+     * Default: 'map'
+     */
+    type: string;
+    /**
+     * 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 Store_OnErrorType.onChange}.
+     *
+     * Note: Execution of this callback is managed by internal subscriptions and will stop
+     * firing once {@link unsubscribe} is called.
+     */
+    onChange?: (this: IStore<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: IStore<Key, Value, CacheDisabled>, err: unknown, type: Store_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:**
+     * - If this function is not defined, or returns `undefined` or a non-map value,
+     * the system falls back to internal `JSON.parse` logic.
+     * - If the function throws an error, it will use and empty map.
+     *
+     * **Error Triggers:**
+     * - If this custom `parse` function fails: {@link onError} is triggered with {@link Store_OnErrorType.parse}.
+     * - If the default `JSON.parse` fallback fails: {@link onError} is triggered with {@link Store_OnErrorType.parse_json}.
+     */
+    parse?: Store_Parse<Map<Key, Value>, IStore<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 attempt to use `globalThis.localStorage`, if available
+     * - A custom storage that implements {@link StorageCompact} interface can also be used both in browser and NodeJS.
+     *
+     * Default:
+     * - browser: `localStorage`
+     * - node: `undefined` (in-memory mode)
+     */
+    readonly storage?: StorageCompact | Storage;
+    /**
+     * 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, or returns `undefined` or a non-string value,
+     * the system falls back to internal `JSON.stringify` logic.
+     * - If the function throws an error, it will use and empty string.
+     *
+     * **Error Triggers:**
+     * - If this custom `stringify` function fails: {@link onError} is triggered with {@link Store_OnErrorType.stringify}.
+     * - If the default `JSON.stringify` fallback fails: {@link onError} is triggered with
+     * {@link Store_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 { Store } from '@superutils/store'
+     *
+     * 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 Store('users', { stringify })
+     * ```
+     */
+    stringify?: Store_Stringify<Map<Key, Value>, IStore<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: () => IStore<Key, Value, CacheDisabled>;
+    /** Delete one or more items by their respective keys */
+    readonly delete: (key: Key | Key[]) => IStore<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<IStore<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.
+     *
+     * If `instance.parse` function is provided and invokation fails, an empty Map will be returned.
+     *
+     * @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 { Store } from '@superutils/store'
+     *
+     * const storage = new Store('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
+     *
+     * @param key
+     * @param value
+     *
+     * @example
+     *
+     * ```javascript
+     * import { Store } from '@superutils/store'
+     *
+     * const store = new Store<string, number>()
+     * store.set('count', 1)
+     * store.set('count', (prevCount = 0) => prevCount + 1)
+     * ```
+     */
+    readonly set: (key: Key, value: Value | ((currentValue?: Value) => Value)) => IStore<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) => IStore<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: Store_Sort<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: Store_ToJSON<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 IObjectStore<T extends object, CacheDisabled extends boolean = false, ObjectMap extends TypedMap<T> = TypedMap<T>> extends IStore<keyof T, T[keyof T], CacheDisabled> {
+    /**
+     * Default: `object`
+     */
+    type: string;
+    get<Key extends keyof T>(key: Key): T[Key] | undefined;
+    getAll(forceRead?: boolean): TypedMap<T>;
+    parse?: Store_Parse<ObjectMap, IObjectStore<T, CacheDisabled>>;
+    set<Key extends keyof T, Value extends T[Key]>(key: Key, value: Value | ((currentValue?: Value) => Value)): IObjectStore<T, CacheDisabled>;
+    setAll(data?: ObjectMap, replace?: boolean): IObjectStore<T, CacheDisabled>;
+    stringify?: Store_Stringify<ObjectMap, IObjectStore<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 Store} instances.
+ *
+ * Accepted values:
+ * - `string`: Updates the cache for the instance with the matching name.
+ * - `string[]`: Updates the cache for all instances whose names are included in the array.
+ * - `true`: Triggers a global cache update for all instances that have a `name` defined.
+ * - `false`: No-op.
+ *
+ * @example
+ * ```javascript
+ * import { Store, forceUpdateCache$ } from '@superutils/store'
+ *
+ * const names = ['products', 'users']
+ *
+ * // Update all Store instances by a list of their names
+ * forceUpdateCache$.next(names)
+ * // alternatively: Store.forceUpdateCache(names)
+ *
+ * // Update all Store instances with a specific name
+ * forceUpdateCache$.next(names[0])
+ * // alternatively: Store.forceUpdateCache(names[0])
+ *
+ * // Update every single instance of Store that uses storage (has a "name" property)
+ * forceUpdateCache$(true)
+ * // alternatively: Store.forceUpdateCache(true)
+ * ```
+ *
+ * @example
+ *
+ * #### Practical example
+ * ```typescript
+ * import { createStore, forceUpdateCache$ } from '@superutils/store'
+ *
+ * const name = 'user-profile'
+ * const delay = 0 // delay is set to zero to simplify the example
+ *
+ * const userStore = createStore(name, { delay })
+ * const userStore2 = createStore(name, { delay })
+ *
+ * userStore.init()
+ * userStore2.init()
+ *
+ * userStore.set('name', 'John Doe')
+ * console.log(userStore2.get('name')) // Prints: undefined
+ *
+ * forceUpdateCache$.next(name)
+ * console.log(userStore2.get('name')) // Prints: 'John Doe'
+ * ```
+ */
+declare const forceUpdateCache$: Subject<string | boolean | string[]>;
+/**
+ * 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**: `Store` 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.
+ *   - For one-off operations or standalone scripts, data size is constrained only by available system memory
+ *   and processing power.
+ * - **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 IStore} 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 Store.fromObject} for object-oriented storage initialization.
+ *
+ * @example
+ * #### Browser Usage 1: use like a map
+ * ```javascript
+ * import { Store } from '@superutils/store'
+ *
+ * const userStorage = new Store('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 { Store } from '@superutils/store'
+ * import fetch from '@superutils/fetch'
+ *
+ * const { products } = await fetch.get('[DUMMYJSON-DOT-COM]/products')
+ * const storage = new Store('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 { Store } from '@superutils/store'
+ * 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 Store('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, `Store` 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 { Store } from '@superutils/store'
+ *
+ * const storage = new Store('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 Store<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 IStore<Key, Value, CacheDisabled> = IStore<Key, Value, CacheDisabled>> implements IStore<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;
+    type: string;
+    constructor(name?: This['name'], options?: Store_Options<Key, Value, CacheDisabled>);
+    clear: This['clear'];
+    delete: This['delete'];
+    static messages: {
+        invalidJsonEntries: string;
+        invalidOptionsStorage: string;
+    };
+    filter: This['filter'];
+    find: This['find'];
+    /**
+     * 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 handleForceUpdateCache;
+    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 triggerOnErrorCb;
+    unsubscribe: This['unsubscribe'];
+    values: This['values'];
+    write: This['write'];
+}
+
+/**
+ * Defines the shape of the context object that can be attached to a {@link Store}.
+ *
+ * A context can be:
+ * - A plain object containing utility methods or properties.
+ * - A factory function that receives the {@link Store} instance and returns an object.
+ *   This is useful for creating methods that need to interact with the store's data
+ *   using the store instance itself.
+ *
+ * @template Key - The type of keys in the store.
+ * @template Value - The type of values in the store.
+ * @template CacheDisabled - Whether caching is disabled for this store.
+ */
+type Store_Context<Key, Value, CacheDisabled extends boolean = false> = object | ((store: IStore<Key, Value, CacheDisabled>) => object);
+type ReturnTypeOrSelf<T> = T extends (...args: any[]) => infer R ? R : T;
+/**
+ * Factory function to create a {@link Store} instance with optional context.
+ *
+ * This function provides a convenient way to instantiate a store and attach supplemental
+ * logic (context) to it. It supports full type inference for both the store's data
+ * and the attached context.
+ *
+ * @param name - The name of the storage (e.g., localStorage key). If null/undefined, the store remains in-memory.
+ * @param options - Configuration options for the store, including the optional `context`.
+ *
+ * @template Context - The type of the context object or factory function.
+ * @template Key - The type of keys stored in the map.
+ * @template Value - The type of values stored in the map.
+ * @template CacheDisabled - Literal type determining whether to disable in-memory caching.
+ *
+ * @returns A {@link Store} instance augmented with a `context` property.
+ *
+ * @example
+ * #### Basic store without context
+ * ```javascript
+ * import { createStore } from '@superutils/store'
+ *
+ * const store = createStore<string, number>()
+ * store.set('count', 1)
+ * store.set('count', prevCount => prevCount + 1)
+ * ```
+ *
+ * @example
+ * #### Store with a static context object
+ * ```javascript
+ * import { createStore } from '@superutils/store'
+ *
+ * const store = createStore('user-settings', {
+ *   context: {
+ *     count: 0,
+ *     log(msg) {
+ *         console.log(`[${++this.count}] ${msg}`)
+ *     }
+ *   }
+ * })
+ *
+ * store.context.log('Setting updated')
+ * console.log(store.context.count)
+ * ```
+ *
+ * @example
+ * #### Store with a functional context (access to store instance)
+ * ```typescript
+ * import { createStore } from '@superutils/store'
+ *
+ * const authStore = createStore('auth', {
+ *   context: (store) => ({
+ *     isAuthenticated: () => store.has('token'),
+ *     logout: () => store.delete('token')
+ *   })
+ * })
+ *
+ * if (authStore.context.isAuthenticated()) {
+ *   authStore.context.logout()
+ * }
+ * ```
+ */
+declare function createStore<Context extends Store_Context<Key, Value, CacheDisabled>, Key, Value, CacheDisabled extends boolean = false>(name?: ConstructorParameters<typeof Store<Key, Value, CacheDisabled>>[0], options?: Store_Options<Key, Value, CacheDisabled> & {
+    context?: Context;
+}): IStore<Key, Value, CacheDisabled> & {
+    context: ReturnTypeOrSelf<Context>;
+};
+/**
+ * Factory method to create a {@link Store} instance.
+ *
+ * @param args - Arguments passed directly to the {@link Store} constructor.
+ * @template Key - The type of keys stored in the map.
+ * @template Value - The type of values stored in the map.
+ * @template CacheDisabled - Whether to disable in-memory caching.
+ */
+declare function createStore<Key, Value, CacheDisabled extends boolean = false>(...args: ConstructorParameters<typeof Store<Key, Value, CacheDisabled>>): Store<Key, Value, CacheDisabled>;
+
+/**
+ * Defines the shape of the context object that can be attached to {@link IObjectStore} instance.
+ *
+ * A context can be:
+ * - A plain object containing utility methods or properties.
+ * - A factory function that receives the {@link Store} instance and returns an object.
+ *   This is useful for creating methods that need to interact with the store's data
+ *   using the store instance itself.
+ *
+ * @template Key - The type of keys in the store.
+ * @template Value - The type of values in the store.
+ * @template CacheDisabled - Whether caching is disabled for this store.
+ */
+type ObjectStore_Context<T extends object, CacheDisabled extends boolean = false> = object | ((store: IObjectStore<T, CacheDisabled>) => object);
+/**
+ * Creates a {@link Store} 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 Store instance mapped to the object's keys and values.
+ *
+ * @example
+ * #### Basic property-based access
+ *
+ * ```typescript
+ * import { createObjectStore } from '@superutils/store'
+ *
+ * const storage = createObjectStore('user-profile', {
+ *   initialValue: {
+ *     age: 99,
+ *     name: 'Ninety Nine'
+ *   }
+ * })
+ *
+ * // Keys are strictly inferred from the interface
+ * const name = storage.get('name') // Type: string | undefined
+ * console.log(name) // Prints: 'Ninety Nine'
+ *
+ * // Update properties with type safety
+ * storage.set('age', 100) // Only numbers are accepted for 'age'
+ *
+ * // Export the underlying data back to a plain object
+ * const userObj = storage.toObject<User>()
+ * console.log(userObj) // { age: 100, name: 'Ninety Nine' }
+ * ```
+ *
+ * @example
+ * #### Usage with context
+ *
+ * ```javascript
+ * import { createObjectStore } from '@superutils/store'
+ *
+ * // Functional context allows you to attach business logic directly to the store
+ * const userStore = createObjectStore('user-profile', {
+ *   initialValue: {
+ *     age: 25,
+ *     name: 'Jane Doe',
+ *     roles: ['guest']
+ *   },
+ *   context: store => ({
+ *     isAdmin: () => !!store.get('roles')?.includes('admin'),
+ *     promoteToAdmin() {
+ *       if (this.isAdmin()) return
+ *
+ *       // Use functional updates to safely modify the roles array
+ *       store.set('roles', (prev = []) => [...prev, 'admin'])
+ *     }
+ *   })
+ * })
+ *
+ * // Logic is encapsulated and easy to invoke
+ * userStore.context.promoteToAdmin()
+ * console.log(userStore.get('roles')) // ['guest', 'admin']
+ * ```
+ *
+ */
+declare function createObjectStore<T extends object = Record<string, unknown>, Key extends keyof T = keyof T, Value extends T[Key] = T[Key], CacheDisabled extends boolean = false, Context extends ObjectStore_Context<T, CacheDisabled> = ObjectStore_Context<T, CacheDisabled>>(name?: string | null, options?: Omit<Store_Options<Key, Value, CacheDisabled>, 'initialValue'> & {
+    context?: Context;
+    initialValue?: T;
+}): IObjectStore<T, CacheDisabled> & {
+    context: ReturnTypeOrSelf<Context>;
+};
+/**
+ * Create a {@link Store} instance from an object using `options.initialValue`.
+ */
+declare function createObjectStore<T extends object = Record<string, unknown>, Key extends keyof T = keyof T, Value extends T[Key] = T[Key], CacheDisabled extends boolean = false>(...args: ConstructorParameters<typeof Store<Key, Value, CacheDisabled>>): IObjectStore<T, CacheDisabled>;
+
+export { type IObjectStore, type IStore, type ObjectStore_Context, type ReturnTypeOrSelf, type StorageCompact, Store, type Store_Context, type Store_DelayOptions, Store_OnErrorType, type Store_Options, type Store_Parse, type Store_Search, type Store_Sort, type Store_SortByComparator, type Store_SortByKey, type Store_SortByPropertyName, type Store_SortOptions, type Store_Stringify, type Store_ToJSON, createObjectStore, createStore, Store as default, forceUpdateCache$ };