@superutils/store 0.1.17 → 0.1.19

package/dist/index.d.ts

@@ -1,48 +1,6 @@
-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';
-
-/**
- * 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'>;
-};
+import { Subject, BehaviorSubject } from 'rxjs';
 
 /**
  * Represents the minimal subset of the `Storage` interface required for persistence.
@@ -85,34 +43,6 @@ declare enum Store_OnErrorType {
     /** Occurs when the attempt to save data to the underlying storage (e.g., `localStorage.setItem`) fails. */
     write = "write"
 }
-/**
- * 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.
-     *
-     * **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' | 'validate'> & (CacheDisabled extends false ? Pick<Partial<IStore<Key, Value, CacheDisabled>>, 'delay' | 'delayOptions'> : {
-    delay?: never;
-    delayOptions?: never;
-});
 /**
  * Function signature for custom data deserialization.
  *
@@ -171,6 +101,36 @@ type Store_Stringify<Data, ThisArg> = (this: ThisArg, data: Data) => string | un
  */
 type Store_ToJSON<K, V> = (replacer?: null | ((key: K, value: V) => unknown), spacing?: string | number, data?: Map<K, V>) => string;
 
+/** Store properties accepted in {@link Store_Options} */
+type Store_OptionKeys = 'cacheDisabled' | 'delay' | 'delayOptions' | 'name' | 'onChange' | 'onError' | 'parse' | 'spaces' | 'storage' | 'stringify' | 'validate';
+/**
+ * Configuration options for initializing {@link IStore} instances.
+ *
+ * These options define the behavior of caching, persistence, error handling, and validation.
+ */
+type Store_Options<Key = unknown, Value = unknown, 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>>, Store_OptionKeys> & (CacheDisabled extends false ? Pick<Partial<IStore<Key, Value, CacheDisabled>>, 'delay' | 'delayOptions'> : {
+    delay?: never;
+    delayOptions?: never;
+});
 /**
  * Represents a generic, reactive, and persistent Map-like data store.
  *
@@ -186,9 +146,9 @@ type Store_ToJSON<K, V> = (replacer?: null | ((key: K, value: V) => unknown), sp
  * @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> {
+interface IStore<Key, Value, CD extends boolean = false> {
     /** Disable in-memory cache and only directly read/write from storage (local storage or JSON fle) */
-    readonly cacheDisabled: CacheDisabled;
+    readonly cacheDisabled: CD;
     /**
      * Debounce/throttle delay duration in milliseconds for writing to storage when caching is enabled.
      *
@@ -220,7 +180,7 @@ interface IStore<Key, Value, CacheDisabled extends boolean = false> {
      * 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>>;
+    onChange?: (this: IStore<Key, Value, CD>, data: Map<Key, Value>) => ValueOrPromise<void | Map<Key, Value>>;
     /**
      * A global error handler invoked whenever an internal operation fails.
      *
@@ -232,7 +192,7 @@ interface IStore<Key, Value, CacheDisabled extends boolean = false> {
      * **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>;
+    onError?: (this: IStore<Key, Value, CD>, err: unknown, type: Store_OnErrorType) => ValueOrPromise<void>;
     /**
      * A callback to customize the deserialization of data read from storage.
      *
@@ -249,7 +209,7 @@ interface IStore<Key, Value, CacheDisabled extends boolean = false> {
      * - 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>>;
+    parse?: Store_Parse<Map<Key, Value>, IStore<Key, Value, CD>>;
     /** Get the number of items */
     readonly size: number;
     /** Number of spaces to use when stringifying. Default: `undefined` */
@@ -312,16 +272,15 @@ interface IStore<Key, Value, CacheDisabled extends boolean = false> {
      * const storage = new Store('users', { stringify })
      * ```
      */
-    stringify?: Store_Stringify<Map<Key, Value>, IStore<Key, Value, CacheDisabled>>;
+    stringify?: Store_Stringify<Map<Key, Value>, IStore<Key, Value, CD>>;
     /**
      * 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.
+     * 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.
@@ -329,15 +288,15 @@ interface IStore<Key, Value, CacheDisabled extends boolean = false> {
      * - **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>>;
+    readonly subject$: CD extends true ? Subject<Map<Key, Value>> : BehaviorSubject<Map<Key, Value>>;
     /** Clear all items */
-    readonly clear: () => IStore<Key, Value, CacheDisabled>;
+    readonly clear: () => IStore<Key, Value, CD>;
     /** Delete one or more items by their respective keys */
-    readonly delete: (key: Key | Key[]) => IStore<Key, Value, CacheDisabled>;
+    readonly delete: (key: Key | Key[]) => IStore<Key, Value, CD>;
     /** 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>>;
+    readonly find: <IncludeKey extends boolean = false>(predicateOrOptions: FindOptions<Key, Value, IncludeKey> | Parameters<IStore<Key, Value, CD>['filter']>[0]) => ReturnType<typeof find<Key, Value, IncludeKey>>;
     /** Get item by key */
     readonly get: (key: Key) => Value | undefined;
     /**
@@ -421,7 +380,7 @@ interface IStore<Key, Value, CacheDisabled extends boolean = false> {
      * store.set('count', (prevCount = 0) => prevCount + 1)
      * ```
      */
-    readonly set: (key: Key, value: Value | ((currentValue?: Value) => Value)) => IStore<Key, Value, CacheDisabled>;
+    readonly set: (key: Key, value: Value | ((currentValue?: Value) => Value)) => IStore<Key, Value, CD>;
     /**
      * Set multiple entries at once and/or replace the storage entries
      *
@@ -432,7 +391,7 @@ interface IStore<Key, Value, CacheDisabled extends boolean = false> {
      *
      * Default: `false`
      */
-    readonly setAll: (data?: Map<Key, Value>, replace?: boolean) => IStore<Key, Value, CacheDisabled>;
+    readonly setAll: (data?: Map<Key, Value>, replace?: boolean) => IStore<Key, Value, CD>;
     /**
      * Sort items in the storage.
      *
@@ -473,40 +432,400 @@ interface IStore<Key, Value, CacheDisabled extends boolean = false> {
      * - 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;
+    readonly write: (data?: Map<Key, Value>) => boolean;
 }
 
-interface IObjectStore<T extends object, CacheDisabled extends boolean = false, ObjectMap extends TypedMap<T> = TypedMap<T>> extends IStore<keyof T, T[keyof T], CacheDisabled> {
+/** Utility to exclude store props & o in context */
+type ContextExcludeProps<Context> = Context extends object ? {
+    [K in keyof Context]: K extends keyof IStore<any, any, any> ? never : Context[K];
+} : never;
+/** Extract context return type */
+type ContextReturn<Context> = Context extends (...args: any[]) => infer R ? R : Context extends object ? Context : unknown;
+/** Validate and exclude store properties from context   */
+type ContextValidate<Context, Store> = Context extends (...args: unknown[]) => infer R ? (store: Store) => ContextExcludeProps<R> : ContextExcludeProps<Context>;
+
+interface IObjectStore<T extends object = object, CacheDisabled extends boolean = false> 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>>;
+    parse?: Store_Parse<TypedMap<T>, 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;
+    setAll(data?: T | TypedMap<T>, replace?: boolean): IObjectStore<T, CacheDisabled>;
+    stringify?: Store_Stringify<TypedMap<T>, IObjectStore<T, CacheDisabled>>;
+    /** Convert data/object to typed map */
+    toMap(data?: T): TypedMap<T>;
+    toObject<O extends object = T>(data?: Map<keyof T, T[keyof T]> | TypedMap<T>): O;
+}
+/**
+ * Configuration options for initializing {@link IStore} instances.
+ *
+ * These options define the behavior of caching, persistence, error handling, and validation.
+ */
+type ObjectStore_Options<T extends object = Record<PropertyKey, unknown>, 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?: T;
+} & Pick<Partial<IObjectStore<T, CacheDisabled>>, Store_OptionKeys> & (CacheDisabled extends false ? Pick<Partial<IObjectStore<T, CacheDisabled>>, 'delay' | 'delayOptions'> : {
+    delay?: never;
+    delayOptions?: never;
+});
+
+declare module './IStore' {
+    interface IStore<Key, Value, CD extends boolean = false> {
+        /**
+         * 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.
+         *
+         * **Behavior:**
+         * - Invoked immediately before the store's internal state is updated.
+         * - If validation fails (throw error), the operation is aborted and the error is propagated to the caller.
+         * - The `write` validator is invoked during every persistence cycle, serving as a final check
+         * after operation-specific hooks (e.g., `set` or `delete`).
+         * - For reference-type values (e.g., Objects, Maps, Arrays), validators can be used to mutate the data
+         * (e.g., for normalization) before it is committed.
+         * - `thisArg`: all validators are bound to the store instance.
+         *
+         * @example
+         * ```javascript
+         * import { createObjectStore } from '@superutils/store'
+         *
+         * const settingsStore = createObjectStore({
+         *   name: 'app-settings',
+         *   initialValue: {
+         *     theme: 'light',
+         *     version: '1.0.0',
+         *   },
+         *   validate: {
+         *     set([key, value]) {
+         *       console.log(this.size) // "this" refers to the store instance
+         *       if (key !== 'theme' || ['light', 'dark', 'system'].includes(value)) return
+         *
+         *       // throw error to abort operation
+         *       throw new Error(`Invalid theme: ${value}`)
+         *     },
+         *     delete: ([keys]) => {
+         *       if (!keys.includes('version')) return
+         *
+         *       throw new Error('The "version" key is protected and cannot be deleted')
+         *     },
+         *   },
+         * })
+         *
+         * settingsStore.set('theme', 'system')
+         * console.log(settingsStore.get('theme')) // 'system'
+         * try {
+         *   settingsStore.set('theme', 'invalid') // throws error
+         * } catch (err) {
+         *   console.error(err.message)
+         * }
+         * ```
+         */
+        validate?: Store_Validate<Key, Value, CD>;
+    }
 }
 /**
- * Defines the shape of the context object that can be attached to {@link IObjectStore} instance.
+ * A configuration object containing optional validation hooks for specific store operations.
  *
- * 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.
+ * See {@link IStore.validate} or inidivdual actions for more details.
  *
  * @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.
+ * @template CacheDisabled - Whether caching is disabled for the 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;
+type Store_Validate<Key, Value, CacheDisabled extends boolean, ThisArg extends IStore<Key, Value, CacheDisabled> = IStore<Key, Value, CacheDisabled>> = {
+    /**
+     * Validator for the `clear()` operation.
+     * Invoked before all entries are removed from the store.
+     *
+     * **Throw an error to invalidate and abort the operation.**
+     *
+     * @param actionParams - Empty array for this action.
+     * @param action - The literal action name: `'clear'`.
+     */
+    clear?: (this: ThisArg, actionParams: [], action: 'clear') => void;
+    /**
+     * Validator for the `delete()` operation.
+     * Invoked before one or more entries are removed by their keys.
+     *
+     * **Throw an error to invalidate and abort the operation.**
+     *
+     * @param actionParams - Tuple containing the array of keys: `[keys: Key[]]`.
+     * @param action - The literal action name: `'delete'`.
+     */
+    delete?: (this: ThisArg, actionParams: [keys: Key[]], action: 'delete') => void;
+    /**
+     * Validator for the `set()` operation.
+     * Invoked before a single key-value pair is added or updated.
+     *
+     * **Throw an error to invalidate and abort the operation.**
+     *
+     * @param actionParams - Tuple containing the key and value: `[key: Key, value: Value]`.
+     * @param action - The literal action name: `'set'`.
+     */
+    set?: (this: ThisArg, actionParams: [key: Key, value: Value], action: 'set') => void;
+    /**
+     * Validator for the `setAll()` operation.
+     * Invoked before merging or replacing the entire dataset.
+     *
+     * **Throw an error to invalidate and abort the operation.**
+     *
+     * @param actionParams - Tuple containing the data Map and replace flag:
+     *   `[data?: Map<Key, Value>, replace?: boolean]`.
+     * @param action - The literal action name: `'setAll'`.
+     */
+    setAll?: (this: ThisArg, actionParams: [data?: Map<Key, Value>, replace?: boolean], action: 'setAll') => void;
+    /**
+     * Validator for the `write()` operation.
+     * Invoked immediately before data is serialized and committed to the underlying storage.
+     * This acts as a final gatekeeper for the entire state during persistence.
+     *
+     * The `write` validator is invoked during every persistence cycle, serving as a final check
+     * after operation-specific hooks (like `set` or `delete`).
+     *
+     * **Throw an error to invalidate and abort the operation.**
+     *
+     * @param actionParams - Tuple containing the full data Map to be persisted: `[data: Map<Key, Value>]`.
+     * @param action - The literal action name: `'write'`.
+     */
+    write?: (this: ThisArg, actionParams: [data: Map<Key, Value>], action: 'write') => void;
 };
+/**
+ * Literal union of all operations that can be intercepted by a validator.
+ */
+type Store_ValidateAction = 'clear' | 'delete' | 'set' | 'setAll' | 'write';
+
+/**
+ * Creates a {@link IObjectStore} 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 options (optional) Configuration options for the storage instance. See {@link ObjectStore_Options} for more.
+ * @param options.initialValue (optional) An optional object to populate the storage if it's currently empty.
+ * @param options.name (optional) locaStorage key (or JSON filename in NodeJS) for persistence storage.
+ * @param 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 into the store instance.
+ *
+ * **Behavior:** See {@link createStore}.
+ *
+ * @template T (optional) The structure of the object being stored. Can auto-infer from `options.initialValue`.
+ * @template CacheDisabled - Whether store data caching is disabled.
+ * @template Context - The type of the context object or factory function.
+ *
+ * @returns A new Store instance mapped to the object's keys and values.
+ *
+ * @example
+ * #### Basic property-based access
+ *
+ * ```javascript
+ * import { createObjectStore } from '@superutils/store'
+ *
+ * const userStore = createObjectStore('user', {
+ *   initialValue: {
+ *     age: 99,
+ *     name: 'Ninety Nine'
+ *   }
+ * })
+ *
+ * // Keys are strictly inferred from the interface
+ * const name = userStore.get('name') // Type: string | undefined
+ * console.log(name) // Prints: 'Ninety Nine'
+ *
+ * // Update properties with type safety
+ * userStore.set('age', 100) // Only numbers are accepted for 'age'
+ *
+ * // Export the underlying data back to a plain object
+ * const user = userStore.toObject()
+ * console.log(user) // { age: 100, name: 'Ninety Nine' }
+ * ```
+ *
+ * @example
+ * #### Usage with context
+ *
+ * ```javascript
+ * import { createObjectStore } from '@superutils/store'
+ *
+ * const getContext = 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'])
+ *     }
+ *   }
+ * // Functional context allows you to attach business logic directly to the store
+ * const userStore = createObjectStore(
+ *   'user',
+ *   {
+ *     initialValue: {
+ *       age: 25,
+ *       name: 'Jane Doe',
+ *       roles: ['guest']
+ *     },
+ *   },
+ *   getContext
+ * )
+ *
+ * // Logic is encapsulated and easy to invoke
+ * userStore.promoteToAdmin()
+ * console.log(userStore.get('roles')) // ['guest', 'admin']
+ * ```
+ *
+ */
+declare function createObjectStore<Context extends object | ((store: IObjectStore<T, CacheDisabled>) => object), T extends object = Record<string, unknown>, CacheDisabled extends boolean = false>(options: undefined | null | ObjectStore_Options<T, CacheDisabled>, context: Context & ContextValidate<Context, IObjectStore<T, CacheDisabled>>): IObjectStore<T, CacheDisabled> & ContextReturn<Context>;
+declare function createObjectStore<T extends object = Record<string, unknown>, CacheDisabled extends boolean = false>(options?: ObjectStore_Options<T, CacheDisabled>): IObjectStore<T, CacheDisabled>;
+
+/**
+ * Store property names that are optional/user-provided and should not be allowed in context.
+ *
+ * This is used to avoid optional store properties being overriden by context properties
+ */
+declare const OPTIONAL_STORE_PROPS: readonly ["delayOptions", "name", "onChange", "onError", "parse", "spaces", "storage", "stringify", "validate"];
+/**
+ * Factory function to create a {@link Store} instance with optional business logic augmented into the store instance.
+ *
+ * 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 options - (optional) Configuration options for the store.
+ * @param context - (optional) A plain object or a factory function that returns an object.
+ * If function provided, it is executed only once during instantiation.
+ *
+ * **Purpose:**
+ * Use `context` to encapsulate domain-specific business logic, helper methods, or non-reactive state
+ * directly into 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.
+ * - **Notes**:
+ *   - Built-in store properties are not allowed
+ *   - Augmented methods' "thisArg" will be the context as per default JavaScript behavior.
+ *   - Custom class instances are supported as context. Built-in {@link Store} properties take precedence
+ * in the event of a naming conflict.
+ *
+ * @template Key - The type of keys stored in the map.
+ * @template Value - The type of values stored in the map.
+ * @template CacheDisabled - Whether store data caching is disabled.
+ * @template Context - The type of the context object or factory function.
+ *
+ * @returns A {@link Store} instance with augmented properties (if any).
+ *
+ * @example
+ * #### Basic usage
+ * ```javascript
+ * import { createStore } from '@superutils/store'
+ *
+ * const store = createStore({ initialValue: new Map([['count', 0]])})
+ * store.set('count', 1)
+ * store.set('count', prevCount => prevCount + 1)
+ * console.log(store.get('count')) // 2
+ * ```
+ *
+ * @example
+ * #### Store augmented with custom business logic
+ * ```javascript
+ * import { createStore } from '@superutils/store'
+ *
+ * const store = createStore({ name: 'user-settings'}, {
+ *   count: 0,
+ *   log(msg) {
+ *     console.log(`[${++this.count}] ${msg}`)
+ *   }
+ * })
+ *
+ * store.log('Settings updated')
+ * console.log(store.count)
+ * ```
+ *
+ * @example
+ * #### In-memory store
+ * ```javascript
+ * import fetch from '@superutils/fetch'
+ * import { createStore } from '@superutils/store'
+ *
+ * // Bypass the name property to create an in-memory store
+ * const store = createStore()
+ *
+ * // This will NOT save the data to localStorage
+ * store.set('key', 'value')
+ * ```
+ *
+ * @example
+ * #### Store with a functional context
+ * ```javascript
+ * import { createStore } from '@superutils/store'
+ *
+ * const authStore = createStore(null, store => ({
+ *   isAuthenticated: () => store.has('token'),
+ *   logout: () => {
+ *     store.delete('token')
+ *     console.log('logged out')
+ *   }
+ * }))
+ *
+ * if (authStore.isAuthenticated()) {
+ *   authStore.logout()
+ * }
+ * ```
+ *
+ * @example
+ * #### Augmenting with a custom class instance
+ *
+ * ```typescript
+ * import { createStore } from '@superutils/store'
+ *
+ * class MyCustomClass {
+ *   private _count = 0
+ *   get count() {
+ *     return this._count
+ *   }
+ *   increment = () => this._count++
+ *   decrement() {
+ *     return --this._count
+ *   }
+ * }
+ *
+ * const store = createStore(null, new MyCustomClass())
+ * console.log(
+ *   store.count,     // 0
+ *   store.increment(),// function
+ *   store.count,	 // 1
+ *   store.decrement(), // undefined
+ * )
+ *```
+ */
+declare function createStore<Context extends object | ((store: IStore<Key, Value, CacheDisabled>) => object), Key, Value, CacheDisabled extends boolean = false>(options: undefined | null | Store_Options<Key, Value, CacheDisabled>, context: Context & ContextValidate<Context, IStore<Key, Value, CacheDisabled>>): IStore<Key, Value, CacheDisabled> & ContextReturn<Context>;
+declare function createStore<Key, Value, CacheDisabled extends boolean = false>(options?: Store_Options<Key, Value, CacheDisabled>): IStore<Key, Value, CacheDisabled>;
 
 /**
  * RxJS Subject to trigger forced update of cached data from underlying storage of {@link Store} instances.
@@ -584,16 +903,15 @@ declare const forceUpdateCache$: Subject<string | boolean | string[]>;
  *   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)
+ * const userStore = new Store('users')
+ * userStore.set(1, { name: 'Alice', age: 30 })
+ * const user = userStore.get(1)
  * console.log(user) // prints: {name: 'Alice', age: 30}
  * ```
  *
@@ -704,7 +1022,7 @@ This extends IStore<Key, Value, CacheDisabled> = IStore<Key, Value, CacheDisable
     private subscriptions;
     type: This['type'];
     validate?: This['validate'];
-    constructor(name?: This['name'], options?: Store_Options<Key, Value, CacheDisabled>);
+    constructor(name?: This['name'], options?: Store_Options<Key, Value, CacheDisabled> | null);
     clear: This['clear'];
     delete: This['delete'];
     static messages: {
@@ -747,226 +1065,4 @@ This extends IStore<Key, Value, CacheDisabled> = IStore<Key, Value, CacheDisable
     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 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.
- *
- * @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> = undefined | object | ((store: IStore<Key, Value, CacheDisabled>) => object);
-type Store_ContextReturn<T> = {
-    context: undefined extends T ? never : T extends (...args: any[]) => infer R ? R : T;
-};
-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>;
-
-/**
- * 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.
- * @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.
- *
- * @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>, 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>;
-
-/**
- * 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$ };
+export { type ContextExcludeProps, type ContextReturn, type ContextValidate, type IObjectStore, type IStore, OPTIONAL_STORE_PROPS, type ObjectStore_Options, type StorageCompact, Store, type Store_DelayOptions, Store_OnErrorType, type Store_OptionKeys, 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, type Store_Validate, type Store_ValidateAction, createObjectStore, createStore, Store as default, forceUpdateCache$ };