@superutils/store 0.1.15 → 0.1.17

package/dist/index.d.cts

@@ -2,9 +2,58 @@ 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` */
+/**
+ * Literal union of all operations that can be intercepted by a validator.
+ */
+type Store_ValidateAction = 'clear' | 'delete' | 'set' | 'setAll' | 'write';
+/**
+ * Function signature for an operation-specific validation hook.
+ *
+ * **Behavior:**
+ * - Invoked immediately before the store's internal state is updated.
+ * - If validation fails (throw error), the write operation is aborted and error is propagated to the caller.
+ *
+ * @param params - The specific payload for the action:
+ *   - `clear`: `[]`
+ *   - `delete`: `[keys: Key[]]`
+ *   - `set`: `[key: Key, value: Value]`
+ *   - `setAll`: `[data: Map<Key, Value>, replace: boolean]`
+ *   - 'write': `[data: Map<Key, Value>]`
+ * @param action - The literal name of the action being performed.
+ *
+ * @template Key - The type of keys in the store.
+ * @template Value - The type of values in the store.
+ * @template CacheDisabled - Whether caching is disabled.
+ */
+type Store_ValidateFn<Key, Value, CacheDisabled extends boolean, Action extends keyof IStore<Key, Value> & Store_ValidateAction> = (this: IStore<Key, Value, CacheDisabled>, params: 'clear' extends Action ? [] : 'delete' extends Action ? [keys: Key[]] : 'set' extends Action ? [key: Key, value: Value] : 'setAll' extends Action ? [data?: Map<Key, Value>, replace?: boolean] : 'write' extends Action ? [data: Map<Key, Value>] : [], action: Action) => void | undefined | boolean;
+/**
+ * A configuration object containing optional validation hooks for specific store operations.
+ *
+ * This structure allows for granular control over write operations, enabling you
+ * to define custom logic to intercept and prevent invalid state updates.
+ *
+ * @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 the store.
+ */
+type Store_Validate<Key, Value, CacheDisabled extends boolean> = {
+    clear?: Store_ValidateFn<Key, Value, CacheDisabled, 'clear'>;
+    delete?: Store_ValidateFn<Key, Value, CacheDisabled, 'delete'>;
+    set?: Store_ValidateFn<Key, Value, CacheDisabled, 'set'>;
+    setAll?: Store_ValidateFn<Key, Value, CacheDisabled, 'setAll'>;
+    write?: Store_ValidateFn<Key, Value, CacheDisabled, 'write'>;
+};
+
+/**
+ * Represents the minimal subset of the `Storage` interface required for persistence.
+ *
+ * Any object implementing this type can be used as a storage engine, making the Store
+ * compatible with `localStorage`, `sessionStorage`, or custom file-based implementations.
+ */
 type StorageCompact = Pick<Storage, 'getItem' | 'setItem'>;
-/** Throttle & debounce related options */
+/**
+ * Configuration for the timing strategy used when writing data to persistent storage.
+ */
 type Store_DelayOptions = ({
     throttle: true;
 } & Omit<ThrottleOptions, 'onError' | 'thisArg'>) | ({
@@ -36,7 +85,11 @@ declare enum Store_OnErrorType {
     /** Occurs when the attempt to save data to the underlying storage (e.g., `localStorage.setItem`) fails. */
     write = "write"
 }
-/** Initial options provided through the constructor */
+/**
+ * Configuration options for initializing a {@link Store} or {@link ObjectStore}.
+ *
+ * These options define the behavior of caching, persistence, error handling, and validation.
+ */
 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.
@@ -56,25 +109,35 @@ type Store_Options<Key, Value, CacheDisabled extends boolean = false> = {
      * 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'> : {
+} & Pick<Partial<IStore<Key, Value, CacheDisabled>>, 'cacheDisabled' | 'onChange' | 'onError' | 'parse' | 'spaces' | 'storage' | 'stringify' | 'validate'> & (CacheDisabled extends false ? Pick<Partial<IStore<Key, Value, CacheDisabled>>, 'delay' | 'delayOptions'> : {
     delay?: never;
     delayOptions?: never;
 });
+/**
+ * Function signature for custom data deserialization.
+ *
+ * @param text The raw string retrieved from the underlying storage.
+ * @returns The parsed data structure (usually a Map) or `void` to trigger fallback behavior.
+ */
 type Store_Parse<ResultMap, ThisArg> = (this: ThisArg, text: string | null | undefined) => ResultMap | void;
+/**
+ * Function signature for the internal search utility.
+ *
+ * @template K - The type of keys.
+ * @template V - The type of values.
+ * @template MatchExact - Whether to perform exact matching.
+ * @template AsMap - Whether to return results as a Map.
+ */
 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>>;
+/**
+ * Function Signature for the sort utility, supporting multiple sorting strategies:
+ * 1. By a custom comparator function.
+ * 2. By a specific property name (for object-like values).
+ * 3. By the map keys.
+ *
+ * @template K - The type of keys.
+ * @template V - The type of values.
+ */
 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],
@@ -85,10 +148,27 @@ type Store_SortByPropertyName<V> = [
     propertyName: keyof V & string,
     options?: Store_SortOptions
 ];
+/** Configuration options for sorting, including whether to persist the result. */
 type Store_SortOptions = SortOptions & {
     save?: boolean;
 };
+/**
+ * Function signature for custom data serialization.
+ *
+ * @param data The current data structure to be serialized.
+ * @returns A string representation of the data, or `void/undefined` to trigger fallback behavior.
+ */
 type Store_Stringify<Data, ThisArg> = (this: ThisArg, data: Data) => string | undefined | void;
+/**
+ * Function signature for exporting the store content as a JSON string.
+ *
+ * @param replacer - A function or array that transforms the results.
+ * @param spacing - Indentation or whitespace formatting.
+ * @param data - The specific Map to stringify (defaults to all entries).
+ *
+ * @template K - The type of keys.
+ * @template V - The type of values.
+ */
 type Store_ToJSON<K, V> = (replacer?: null | ((key: K, value: V) => unknown), spacing?: string | number, data?: Map<K, V>) => string;
 
 /**
@@ -130,12 +210,6 @@ interface IStore<Key, Value, CacheDisabled extends boolean = false> {
      * 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.
      *
@@ -186,14 +260,19 @@ interface IStore<Key, Value, CacheDisabled extends boolean = false> {
      * 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.
      *
+     * Fallback behavior:
+     * - `undefined`: will attempt to use `globalThis.localStorage`, if available
+     * - `null`, will defer storage check until initialization on first read/write or when `init()` invoked manually.
+     *   - If storage is `undefined` or `null` will attempt to assign `globalTihs.localStorage` again
+     *   - If storage is still falsy, will throw an error.
+     *
      * Default:
      * - browser: `localStorage`
      * - node: `undefined` (in-memory mode)
      */
-    readonly storage?: StorageCompact | Storage;
+    readonly storage?: StorageCompact | Storage | null;
     /**
      * A callback function to customize the serialization of data before it is written to storage.
      *
@@ -234,6 +313,13 @@ interface IStore<Key, Value, CacheDisabled extends boolean = false> {
      * ```
      */
     stringify?: Store_Stringify<Map<Key, Value>, IStore<Key, Value, CacheDisabled>>;
+    /**
+     * Indicates type of data parsed as
+     *
+     * Default: 'map'
+     */
+    type: string;
+    validate?: Store_Validate<Key, Value, CacheDisabled>;
     /**
      * The underlying RxJS Subject that serves as the primary reactive interface for observing data modifications.
      *
@@ -403,6 +489,24 @@ interface IObjectStore<T extends object, CacheDisabled extends boolean = false,
     stringify?: Store_Stringify<ObjectMap, IObjectStore<T, CacheDisabled>>;
     toObject<O extends object = T>(data?: Map<keyof T, T[keyof T]>): O;
 }
+/**
+ * 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 IObjectStore} 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);
+type ObjectStore_Options<T extends object, CacheDisabled extends boolean, Context extends ObjectStore_Context<T, CacheDisabled>> = Omit<Store_Options<keyof T, T[keyof T], CacheDisabled>, 'initialValue'> & {
+    context?: Context;
+    initialValue?: T;
+};
 
 /**
  * RxJS Subject to trigger forced update of cached data from underlying storage of {@link Store} instances.
@@ -598,13 +702,15 @@ This extends IStore<Key, Value, CacheDisabled> = IStore<Key, Value, CacheDisable
     stringify?: This['stringify'];
     readonly subject$: This['subject$'];
     private subscriptions;
-    type: string;
+    type: This['type'];
+    validate?: This['validate'];
     constructor(name?: This['name'], options?: Store_Options<Key, Value, CacheDisabled>);
     clear: This['clear'];
     delete: This['delete'];
     static messages: {
         invalidJsonEntries: string;
-        invalidOptionsStorage: string;
+        invalidStorageOptions: string;
+        validationError: string;
     };
     filter: This['filter'];
     find: This['find'];
@@ -646,7 +752,7 @@ This extends IStore<Key, Value, CacheDisabled> = IStore<Key, Value, CacheDisable
  *
  * 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.
+ * - A factory function that receives the {@link IStore} 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.
  *
@@ -658,95 +764,9 @@ type Store_Context<Key, Value, CacheDisabled extends boolean = false> = undefine
 type Store_ContextReturn<T> = {
     context: undefined extends T ? never : 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> & Store_ContextReturn<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>;
+type IStoreWithContext<Key, Value, CacheDisabled extends boolean, Context extends Store_Context<Key, Value, CacheDisabled>> = IStore<Key, Value, CacheDisabled> & Store_ContextReturn<Context>;
+type IObjectStoreWithContext<T extends object, CacheDisabled extends boolean, Context extends Store_Context<keyof T, T[keyof T], CacheDisabled>> = IObjectStore<T, CacheDisabled> & Store_ContextReturn<Context>;
 
-/**
- * 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.
  *
@@ -759,6 +779,16 @@ type ObjectStore_Context<T extends object, CacheDisabled extends boolean = false
  * @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.
+ * @param options.context - (optional) A plain object or a factory function that returns an object.
+ *
+ * **Purpose:**
+ * Use `context` to encapsulate domain-specific business logic, helper methods, or non-reactive state
+ * directly alongside the store instance.
+ *
+ * **Behavior:**
+ * - **Non-Reactive:** Updates to context properties do **not** trigger `onChange` or RxJS emissions.
+ * - **Non-Persistent:** Context data is purely in-memory and is **not** saved to persistent storage.
+ * - **Access to Store:** When a factory function is used, it receives the store instance as an argument.
  *
  * @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.
@@ -820,13 +850,123 @@ type ObjectStore_Context<T extends object, CacheDisabled extends boolean = false
  * ```
  *
  */
-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> & Store_ContextReturn<Context>;
+declare function createObjectStore<T extends object = Record<string, unknown>, CacheDisabled extends boolean = false, Context extends ObjectStore_Context<T, CacheDisabled> = ObjectStore_Context<T, CacheDisabled>>(name?: string | null, options?: ObjectStore_Options<T, CacheDisabled, Context>): IObjectStoreWithContext<T, CacheDisabled, Context>;
+declare function createObjectStore<T extends object = Record<string, unknown>, CacheDisabled extends boolean = false, Context extends ObjectStore_Context<T, CacheDisabled> = ObjectStore_Context<T, CacheDisabled>>(options: ObjectStore_Options<T, CacheDisabled, Context>): IObjectStoreWithContext<T, CacheDisabled, 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 StorageCompact, Store, type Store_Context, type Store_ContextReturn, 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$ };
+/**
+ * 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
+ * @param options.context - (optional) A plain object or a factory function that returns an object.
+ *
+ * **Purpose:**
+ * Use `context` to encapsulate domain-specific business logic, helper methods, or non-reactive state
+ * directly alongside the store instance.
+ *
+ * **Behavior:**
+ * - **Non-Reactive:** Updates to context properties do **not** trigger `onChange` or RxJS emissions.
+ * - **Non-Persistent:** Context data is purely in-memory and is **not** saved to persistent storage.
+ * - **Access to Store:** When a factory function is used, it receives the store instance as an argument.
+ *
+ * @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
+ * #### In-memory store
+ * ```javascript
+ * import fetch from '@superutils/fetch'
+ * import { createStore } from '@superutils/store'
+ *
+ * const store = createStore({
+ *   context: store => ({
+ *     async getProducts() {
+ *       const { products } = await fetch.get('https://dummyjson.com/products')
+ *
+ *       const productsMap = new Map(products.map(p => [p.id, p]))
+ *       store.setAll(productsMap)
+ *
+ *       return productsMap
+ *     },
+ *   }),
+ * })
+ *
+ * store.context.getProducts().then(() => {
+ *   console.log(store.getAll())
+ * })
+ * ```
+ *
+ * @example
+ * #### Store with a functional context (access to store instance)
+ * ```javascript
+ * 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;
+}): IStoreWithContext<Key, Value, CacheDisabled, Context>;
+declare function createStore<Context extends Store_Context<Key, Value, CacheDisabled>, Key, Value, CacheDisabled extends boolean = false>(options: Store_Options<Key, Value, CacheDisabled> & {
+    context?: Context;
+}): IStoreWithContext<Key, Value, CacheDisabled, 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>;
+
+export { type IObjectStore, type IStore, type ObjectStore_Context, type ObjectStore_Options, type StorageCompact, Store, 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$ };