@superutils/rx 0.1.4 → 0.1.5

package/dist/index.d.ts

@@ -143,50 +143,71 @@ declare namespace copyRxSubject {
     var IGNORE_UPDATE_SYMBOL: typeof IGNORE_UPDATE_SYMBOL;
 }
 
+/** Throttle & debounce related options */
 type DelayOptions = ({
     throttle: true;
 } & Omit<ThrottleOptions, 'onError' | 'thisArg'>) | ({
     throttle?: false;
 } & Omit<DebounceOptions, 'onError' | 'thisArg'>);
-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
+ * Categorizes errors encountered during DataStorage operations.
+ *
+ * These types are passed to the `onError` callback to help identify which phase of the
+ * data lifecycle (reading, writing, or processing) failed.
  */
-type StorageOnChangeFn<K, V extends StorageValue> = (data: Map<K, V>) => ValueOrPromise<void | Map<K, V>>;
-type StorageOnErrorFn = (err: unknown, type: OnErrorType) => ValueOrPromise<void>;
+declare enum OnErrorType {
+    /** Occurs when the user-provided `onChange` callback throws an exception. */
+    onChange = "onChange",
+    /** Occurs when the user-provided `parse` function fails to process the raw storage string. */
+    parse = "parse",
+    /**
+     * Occurs when the default `JSON.parse` fallback fails.
+     * This usually happens if the data in the underlying storage is corrupted or not valid JSON.
+     */
+    parse_json = "parse-json",
+    /** Occurs when the user-provided `stringify` function fails to serialize the data Map. */
+    stringify = "stringify",
+    /**
+     * Occurs when the default `JSON.stringify` fallback fails.
+     * This may happen if the Map contains circular references or other non-serializable values.
+     */
+    stringify_json = "stringify-json",
+    /** Occurs when the attempt to save data to the underlying storage (e.g., `localStorage.setItem`) fails. */
+    write = "write"
+}
+/** Storage type with only properties that are used by `DataStorage` */
+type StorageCompact = Pick<Storage, 'getItem' | 'setItem'>;
+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 extends StorageKey, Value extends StorageValue, CacheDisabled extends boolean = false> = {
+type StorageOptions<Key, Value, 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> = [
+type StorageParseFn<K, V, CD extends boolean = false> = (this: IDataStorage<K, V, CD>, data: string) => Map<K, V>;
+type StorageSearch<K, V, MatchExact extends boolean = false, AsMap extends boolean = true> = (...args: DropFirst<Parameters<typeof search<K, V, MatchExact, AsMap>>>) => ReturnType<typeof search<K, V, MatchExact, AsMap>>;
+type StorageSort<K, V> = (...args: StorageSortByComparator<K, V> | StorageSortByPropertyName<V> | StorageSortByKey) => Map<K, V>;
+type StorageSortByComparator<K, V> = [
     comparator: Parameters<typeof sort<K, V>>[1],
     options?: StorageSortOptions
 ];
 type StorageSortByKey = [byKey: true, options?: StorageSortOptions];
-type StorageSortByPropertyName<V extends StorageValue> = [
+type StorageSortByPropertyName<V> = [
     propertyName: keyof V & string,
     options?: StorageSortOptions
 ];
 type StorageSortOptions = SortOptions & {
     save?: boolean;
 };
-type StorageStringifyFn<K, V extends StorageValue> = (data: Map<K, V>) => string;
+type StorageStringifyFn<K, V, CD extends boolean = false> = (this: IDataStorage<K, V, CD>, 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 StorageKey = string;
-type StorageValue = object;
-interface IDataStorage<Key extends StorageKey, Value extends StorageValue, CacheDisabled extends boolean = false> {
+interface IDataStorage<Key, Value, CacheDisabled extends boolean = false> {
     /** Disable in-memory cache and only directly read/write from storage (local storage or JSON fle) */
     readonly cacheDisabled: CacheDisabled;
     /**
@@ -273,25 +294,43 @@ interface IDataStorage<Key extends StorageKey, Value extends StorageValue, Cache
     /** Map each item on the data to an Array */
     readonly map: StorageMap<Key, Value>;
     /**
-     * Callback to be invoked  whenever value change is triggered.
+     * A callback function executed whenever a data change occurs within the storage.
      *
-     * If `onChange` invocation fails, it will be ignored gracefully.
+     * 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?: StorageOnChangeFn<Key, Value>;
+    onChange?: StorageOnChangeFn<Key, Value, CacheDisabled>;
     /**
-     * Callback to be invoked whenever read/write operation fails.
+     * 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}.
      *
-     * If `onError` invocation failure will be ignored gracefully.
+     * **Note:** If this handler itself throws an error, the exception is
+     * ignored gracefully to prevent application crashes during storage cycles.
      */
-    onError?: StorageOnErrorFn;
+    onError?: StorageOnErrorFn<Key, Value, CacheDisabled>;
     /**
      * 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.
+     * 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, throws an error, or returns a non-Map value,
+     * the system falls back to internal `JSON.parse` logic.
+     *
+     * **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}.
      */
-    readonly parse?: StorageParseFn<Key, Value>;
+    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 */
@@ -323,41 +362,44 @@ interface IDataStorage<Key extends StorageKey, Value extends StorageValue, Cache
      */
     readonly sort: StorageSort<Key, Value>;
     /**
-     * Callback function to customize the serialization of data to be stored to 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, throws an error, or returns a non-string value,
+     * the system falls back to internal `JSON.stringify` logic.
      *
-     * Useful when data needs to be sanitised before storing and/or remove circlar references.
+     * **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 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())
-     * ```
+     * 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>;
+    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: () => Record<Key, Value>;
+    readonly toObject: (data?: Map<Key, Value>) => Record<Key & string, Value>;
     /** Convert list of items (Map) to JSON string of 2D Array */
     readonly toString: () => string;
     /**
@@ -403,7 +445,7 @@ interface IDataStorage<Key extends StorageKey, Value extends StorageValue, Cache
  * ```
  */
 declare const forceUpdateCache$: Subject<string | boolean | string[]>;
-declare class DataStorage<Key extends StorageKey, Value extends StorageValue, CacheDisabled extends boolean = false> implements IDataStorage<Key, Value, CacheDisabled> {
+declare class DataStorage<Key, Value, CacheDisabled extends boolean = false> implements IDataStorage<Key, Value, CacheDisabled> {
     readonly cacheDisabled: CacheDisabled;
     readonly delay: number;
     /** Debounce and throttle related options */
@@ -504,10 +546,59 @@ declare class DataStorage<Key extends StorageKey, Value extends StorageValue, Ca
      * ```
      */
     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>;
+    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>;
+    /**
+     * Creates a {@link DataStorage} instance initialized from a plain object.
+     *
+     * This factory method automatically configures `parse` and `stringify` logic to
+     * treat the underlying storage as a serialized object, while providing a
+     * type-safe Map-like interface for individual properties.
+     *
+     * @param name (optional) The name for the storage (e.g., localStorage key or filename).
+     * @param options (optional) Configuration options for the storage instance.
+     * @param options.initialValue (optional) An optional object to populate the storage if it's currently empty.
+     *
+     * @template T (optional) The structure of the object being stored. Can auto-infer from `options.initialValue`.
+     * @template CacheDisabled (optional) Literal type determining whether to disable in-memory caching.
+     *
+     * @returns A new DataStorage instance mapped to the object's keys and values.
+     *
+     * @example
+     * #### Store and access a User object
+     * ```typescript
+     * import { DataStorage } from '@superutils/rx'
+     *
+     * interface User {
+     *   age: number;
+     *   name: string;
+     * }
+     *
+     * const initialValue: User = {
+     *   age: 99,
+     *   name: 'Ninety Nine'
+     * }
+     *
+     * // Initialize storage from the object
+     * const storage = DataStorage.fromObject<User>('user-profile', { initialValue })
+     *
+     * // Keys are inferred from the User interface
+     * const name = storage.get('name') // Inferred as: string | undefined
+     * console.log(name) // Prints: 'Ninety Nine'
+     *
+     * // Update properties safely
+     * storage.set('age', 100)
+     *
+     * // Reconstruct the updated object
+     * const userObj = storage.toObject<User>()
+     * console.log(userObj) // { age: 100, name: 'Ninety Nine' }
+     * ```
+     */
+    static fromObject: <T extends object, CacheDisabled_1 extends boolean = false>(name?: string, options?: Omit<StorageOptions<keyof T, T[keyof T], CacheDisabled_1>, "initialValue"> & {
+        initialValue?: T;
+    }) => DataStorage<keyof T, T[keyof T], CacheDisabled_1>;
     /**
      * Trigger forced update of cached data from storage.
      *
@@ -528,29 +619,31 @@ declare class DataStorage<Key extends StorageKey, Value extends StorageValue, Ca
      * ```
      */
     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 toObject: () => Record<Key, Value>;
-    readonly toString: (data?: Map<Key, Value>) => string;
+    get(key: Key): Value | undefined;
+    getAll(forceRead?: boolean): Map<Key, Value>;
+    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;
     private triggerOnError;
-    readonly unsubscribe: () => void;
-    readonly values: () => Value[];
-    readonly write: (data?: Map<Key, Value>) => boolean;
+    unsubscribe(): void;
+    values(): Value[];
+    write(data?: Map<Key, Value>): boolean;
 }
 
 /**
@@ -740,4 +833,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, type OnErrorType, type OnResultType, type StorageCompact, type StorageFilter, type StorageFind, type StorageKey, 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 };
+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 };