@asaidimu/utils-artifacts 3.1.3 → 3.1.4

package/index.d.mts

@@ -1,38 +1,57 @@
 /**
- * Utility type for representing partial updates to the state.
+ * Utility type for representing partial updates to the state, allowing deep nesting.
+ * It makes all properties optional and applies the same transformation recursively
+ * to nested objects and array elements, allowing for selective updates while
+ * preserving the original structure. It also includes the original type T and
+ * undefined as possibilities for the top level and nested values.
  */
 type DeepPartial<T> = T extends object ? T extends readonly (infer U)[] ? readonly (DeepPartial<U> | undefined)[] | undefined | T : T extends (infer U)[] ? (DeepPartial<U> | undefined)[] | undefined | T : {
     [K in keyof T]?: T[K] extends object ? DeepPartial<T[K]> | undefined : T[K] | undefined;
 } | undefined | T : T | undefined;
 /**
- * Extended store state for monitoring execution status
+ * Extended store state for monitoring the current execution status (e.g., if an update is in progress).
  */
 interface StoreExecutionState<T> {
+    /** Indicates if a state update process is currently executing. */
     executing: boolean;
+    /** The changes (DeepPartial) currently being processed in the execution cycle. Null if none. */
     changes: DeepPartial<T> | null;
+    /** A queue of pending state update functions/objects to be applied sequentially. */
     pendingChanges: Array<StateUpdater<T>>;
+    /** Names of all currently registered middlewares. */
     middlewares: string[];
+    /** Details of the middleware currently running. Null if none. */
     runningMiddleware: {
         id: string;
         name: string;
         startTime: number;
     } | null;
+    /** Indicates if the store is currently within an active transaction block. */
     transactionActive: boolean;
 }
 /**
- * Event types emitted by the state for observability
+ * Event types emitted by the state store for observability and debugging.
  */
 type StoreEvent = "update:start" | "update:complete" | "middleware:start" | "middleware:complete" | "middleware:error" | "middleware:blocked" | "middleware:executed" | "transaction:start" | "transaction:complete" | "transaction:error" | "persistence:ready" | "persistence:queued" | "persistence:success" | "persistence:retry" | "persistence:failed" | "persistence:queue_cleared" | "persistence:init_error" | "action:start" | "action:complete" | "action:error" | "selector:accessed" | "selector:changed";
 /**
- * Represents a state update, which can be either a partial state object or a function.
+ * Represents a state update, which can be:
+ * 1. The full new state (`T`).
+ * 2. A partial update object (`DeepPartial<T>`).
+ * 3. A function that receives the current state and returns a partial update (sync or async).
  */
 type StateUpdater<T> = T | DeepPartial<T> | ((state: T) => DeepPartial<T> | Promise<DeepPartial<T>>);
 /**
 * Core types for the reactive data store
 */
+/**
+ * Type for a Transform Middleware function.
+ * It modifies (transforms) the incoming changes and must return a `DeepPartial<T>`.
+ */
 type TransformMiddleware<T> = (state: T, changes: DeepPartial<T>) => Promise<DeepPartial<T>> | DeepPartial<T>;
 /**
- * Type for blocking middleware functions that can prevent updates.
+ * Type for a Blocking Middleware function.
+ * It determines whether the state update should proceed or be blocked.
+ * It returns a boolean or an object containing a `block` boolean and an optional `error`.
  */
 type BlockingMiddleware<T> = (state: T, changes: DeepPartial<T>) => Promise<boolean | {
     block: boolean;
@@ -42,23 +61,46 @@ type BlockingMiddleware<T> = (state: T, changes: DeepPartial<T>) => Promise<bool
     error?: Error;
 };
 /**
- * Type representing the configuration object passed to `use`.
+ * Type representing the configuration object passed to the `use` method to register a middleware.
  */
 interface MiddlewareConfig<T> {
+    /** The middleware function (can be a transform or blocking middleware). */
     action: TransformMiddleware<T> | BlockingMiddleware<T>;
+    /** An optional, human-readable name for the middleware. */
     name?: string;
+    /** If true, the middleware is treated as a blocking middleware (must return a boolean or `{ block: boolean }`). */
     block?: boolean;
 }
+/**
+ * Interface for a reactive selector result, providing access to the value and subscription capabilities.
+ */
 interface ReactiveSelector<S> {
+    /** Unique identifier for the selector. */
     id: string;
+    /** Function to get the current computed value of the selector. */
     get: () => S;
+    /**
+     * Subscribes a callback function to run whenever the selector's result changes.
+     * Returns an unsubscribe function.
+     */
     subscribe: (callback: (state: S) => void) => () => void;
 }
 /**
- * Interface defining the contract for the data state.
+ * Interface defining the contract for the core data state store.
+ * T must be an object type.
  */
 interface DataStore<T extends object> {
+    /**
+     * Gets the current state of the store.
+     * @param clone If true, returns a deep clone of the state; otherwise, returns the internal state reference.
+     * @returns The current state T.
+     */
     get(clone?: boolean): T;
+    /**
+     * Registers a named action function that can modify the state.
+     * @param action The action configuration object.
+     * @returns A function to unregister the action.
+     */
     register<R extends any[]>(action: {
         name: string;
         fn: (state: T, ...args: R) => DeepPartial<T> | Promise<DeepPartial<T>>;
@@ -67,26 +109,67 @@ interface DataStore<T extends object> {
             condition?: (previous: R, current: R) => boolean;
         };
     }): () => void;
+    /**
+     * Executes (dispatches) a previously registered action by its name.
+     * @param name The name of the action.
+     * @param args The parameters to pass to the action function.
+     * @returns A promise that resolves to the final state after the action and subsequent updates are complete.
+     */
     dispatch<R extends any[]>(name: string, ...args: R): Promise<T>;
+    /**
+     * Sets or updates the state using a StateUpdater.
+     * @param update The new state, partial state, or a function returning a partial state.
+     * @param options Configuration options for the set operation.
+     * @returns A promise that resolves to the current state when the update is complete.
+     */
     set(update: StateUpdater<T>, options?: {
         force?: boolean;
         actionId?: string;
-    }): Promise<any>;
+    }): Promise<T>;
+    /**
+     * Creates a reactive selector that computes a derived value and tracks dependencies.
+     * @param selector A function to compute the derived state value S from the full state T.
+     * @returns A `ReactiveSelector<S>` object.
+     */
     select<S>(selector: (state: T) => S): ReactiveSelector<S>;
-    /** @deprecated
-     * Use watch instead will be removed in next major version
-     * **/
-    subscribe(path: string | Array<string>, callback: (state: T) => void): () => void;
+    /**
+     * Subscribes a callback to run when the data at the specified path(s) changes.
+     * @param path A single path string or an array of path strings to watch.
+     * @param callback The function to execute when a change occurs in the watched path(s).
+     * @returns An unsubscribe function.
+     */
     watch(path: string | Array<string>, callback: (state: T) => void): () => void;
+    /**
+     * Executes an operation function within a transaction block.
+     * All state updates (`set` or actions) within the transaction are batched and applied atomically (all or nothing).
+     * @param operation The function containing the state updates.
+     * @returns A promise that resolves to the return value of the operation function.
+     */
     transaction<R>(operation: () => R | Promise<R>): Promise<R>;
+    /**
+     * Registers a middleware function to intercept state updates.
+     * @param props The middleware configuration.
+     * @returns A function to unregister the middleware.
+     */
     use(props: MiddlewareConfig<T>): () => boolean;
-    /** @deprecated
-     * Use on instead will be removed in next majow version
-     * **/
-    onStoreEvent(event: StoreEvent, listener: (data: any) => void): () => void;
+    /**
+     * Subscribes a listener to a specific store event type.
+     * @param event The type of store event to listen for.
+     * @param listener The callback function to execute when the event fires.
+     * @returns An unsubscribe function.
+     */
     on(event: StoreEvent, listener: (data: any) => void): () => void;
+    /**
+     * Returns the unique identifier of the store instance.
+     */
     id(): string;
+    /**
+     * Checks whether the store is fully initialized and ready for use.
+     */
     isReady(): boolean;
+    /**
+     * Returns a readonly snapshot of the current execution state of the store.
+     */
     state(): Readonly<StoreExecutionState<T>>;
 }
 

package/index.d.ts

@@ -1,38 +1,57 @@
 /**
- * Utility type for representing partial updates to the state.
+ * Utility type for representing partial updates to the state, allowing deep nesting.
+ * It makes all properties optional and applies the same transformation recursively
+ * to nested objects and array elements, allowing for selective updates while
+ * preserving the original structure. It also includes the original type T and
+ * undefined as possibilities for the top level and nested values.
  */
 type DeepPartial<T> = T extends object ? T extends readonly (infer U)[] ? readonly (DeepPartial<U> | undefined)[] | undefined | T : T extends (infer U)[] ? (DeepPartial<U> | undefined)[] | undefined | T : {
     [K in keyof T]?: T[K] extends object ? DeepPartial<T[K]> | undefined : T[K] | undefined;
 } | undefined | T : T | undefined;
 /**
- * Extended store state for monitoring execution status
+ * Extended store state for monitoring the current execution status (e.g., if an update is in progress).
  */
 interface StoreExecutionState<T> {
+    /** Indicates if a state update process is currently executing. */
     executing: boolean;
+    /** The changes (DeepPartial) currently being processed in the execution cycle. Null if none. */
     changes: DeepPartial<T> | null;
+    /** A queue of pending state update functions/objects to be applied sequentially. */
     pendingChanges: Array<StateUpdater<T>>;
+    /** Names of all currently registered middlewares. */
     middlewares: string[];
+    /** Details of the middleware currently running. Null if none. */
     runningMiddleware: {
         id: string;
         name: string;
         startTime: number;
     } | null;
+    /** Indicates if the store is currently within an active transaction block. */
     transactionActive: boolean;
 }
 /**
- * Event types emitted by the state for observability
+ * Event types emitted by the state store for observability and debugging.
  */
 type StoreEvent = "update:start" | "update:complete" | "middleware:start" | "middleware:complete" | "middleware:error" | "middleware:blocked" | "middleware:executed" | "transaction:start" | "transaction:complete" | "transaction:error" | "persistence:ready" | "persistence:queued" | "persistence:success" | "persistence:retry" | "persistence:failed" | "persistence:queue_cleared" | "persistence:init_error" | "action:start" | "action:complete" | "action:error" | "selector:accessed" | "selector:changed";
 /**
- * Represents a state update, which can be either a partial state object or a function.
+ * Represents a state update, which can be:
+ * 1. The full new state (`T`).
+ * 2. A partial update object (`DeepPartial<T>`).
+ * 3. A function that receives the current state and returns a partial update (sync or async).
  */
 type StateUpdater<T> = T | DeepPartial<T> | ((state: T) => DeepPartial<T> | Promise<DeepPartial<T>>);
 /**
 * Core types for the reactive data store
 */
+/**
+ * Type for a Transform Middleware function.
+ * It modifies (transforms) the incoming changes and must return a `DeepPartial<T>`.
+ */
 type TransformMiddleware<T> = (state: T, changes: DeepPartial<T>) => Promise<DeepPartial<T>> | DeepPartial<T>;
 /**
- * Type for blocking middleware functions that can prevent updates.
+ * Type for a Blocking Middleware function.
+ * It determines whether the state update should proceed or be blocked.
+ * It returns a boolean or an object containing a `block` boolean and an optional `error`.
  */
 type BlockingMiddleware<T> = (state: T, changes: DeepPartial<T>) => Promise<boolean | {
     block: boolean;
@@ -42,23 +61,46 @@ type BlockingMiddleware<T> = (state: T, changes: DeepPartial<T>) => Promise<bool
     error?: Error;
 };
 /**
- * Type representing the configuration object passed to `use`.
+ * Type representing the configuration object passed to the `use` method to register a middleware.
  */
 interface MiddlewareConfig<T> {
+    /** The middleware function (can be a transform or blocking middleware). */
     action: TransformMiddleware<T> | BlockingMiddleware<T>;
+    /** An optional, human-readable name for the middleware. */
     name?: string;
+    /** If true, the middleware is treated as a blocking middleware (must return a boolean or `{ block: boolean }`). */
     block?: boolean;
 }
+/**
+ * Interface for a reactive selector result, providing access to the value and subscription capabilities.
+ */
 interface ReactiveSelector<S> {
+    /** Unique identifier for the selector. */
     id: string;
+    /** Function to get the current computed value of the selector. */
     get: () => S;
+    /**
+     * Subscribes a callback function to run whenever the selector's result changes.
+     * Returns an unsubscribe function.
+     */
     subscribe: (callback: (state: S) => void) => () => void;
 }
 /**
- * Interface defining the contract for the data state.
+ * Interface defining the contract for the core data state store.
+ * T must be an object type.
  */
 interface DataStore<T extends object> {
+    /**
+     * Gets the current state of the store.
+     * @param clone If true, returns a deep clone of the state; otherwise, returns the internal state reference.
+     * @returns The current state T.
+     */
     get(clone?: boolean): T;
+    /**
+     * Registers a named action function that can modify the state.
+     * @param action The action configuration object.
+     * @returns A function to unregister the action.
+     */
     register<R extends any[]>(action: {
         name: string;
         fn: (state: T, ...args: R) => DeepPartial<T> | Promise<DeepPartial<T>>;
@@ -67,26 +109,67 @@ interface DataStore<T extends object> {
             condition?: (previous: R, current: R) => boolean;
         };
     }): () => void;
+    /**
+     * Executes (dispatches) a previously registered action by its name.
+     * @param name The name of the action.
+     * @param args The parameters to pass to the action function.
+     * @returns A promise that resolves to the final state after the action and subsequent updates are complete.
+     */
     dispatch<R extends any[]>(name: string, ...args: R): Promise<T>;
+    /**
+     * Sets or updates the state using a StateUpdater.
+     * @param update The new state, partial state, or a function returning a partial state.
+     * @param options Configuration options for the set operation.
+     * @returns A promise that resolves to the current state when the update is complete.
+     */
     set(update: StateUpdater<T>, options?: {
         force?: boolean;
         actionId?: string;
-    }): Promise<any>;
+    }): Promise<T>;
+    /**
+     * Creates a reactive selector that computes a derived value and tracks dependencies.
+     * @param selector A function to compute the derived state value S from the full state T.
+     * @returns A `ReactiveSelector<S>` object.
+     */
     select<S>(selector: (state: T) => S): ReactiveSelector<S>;
-    /** @deprecated
-     * Use watch instead will be removed in next major version
-     * **/
-    subscribe(path: string | Array<string>, callback: (state: T) => void): () => void;
+    /**
+     * Subscribes a callback to run when the data at the specified path(s) changes.
+     * @param path A single path string or an array of path strings to watch.
+     * @param callback The function to execute when a change occurs in the watched path(s).
+     * @returns An unsubscribe function.
+     */
     watch(path: string | Array<string>, callback: (state: T) => void): () => void;
+    /**
+     * Executes an operation function within a transaction block.
+     * All state updates (`set` or actions) within the transaction are batched and applied atomically (all or nothing).
+     * @param operation The function containing the state updates.
+     * @returns A promise that resolves to the return value of the operation function.
+     */
     transaction<R>(operation: () => R | Promise<R>): Promise<R>;
+    /**
+     * Registers a middleware function to intercept state updates.
+     * @param props The middleware configuration.
+     * @returns A function to unregister the middleware.
+     */
     use(props: MiddlewareConfig<T>): () => boolean;
-    /** @deprecated
-     * Use on instead will be removed in next majow version
-     * **/
-    onStoreEvent(event: StoreEvent, listener: (data: any) => void): () => void;
+    /**
+     * Subscribes a listener to a specific store event type.
+     * @param event The type of store event to listen for.
+     * @param listener The callback function to execute when the event fires.
+     * @returns An unsubscribe function.
+     */
     on(event: StoreEvent, listener: (data: any) => void): () => void;
+    /**
+     * Returns the unique identifier of the store instance.
+     */
     id(): string;
+    /**
+     * Checks whether the store is fully initialized and ready for use.
+     */
     isReady(): boolean;
+    /**
+     * Returns a readonly snapshot of the current execution state of the store.
+     */
     state(): Readonly<StoreExecutionState<T>>;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@asaidimu/utils-artifacts",
-  "version": "3.1.3",
+  "version": "3.1.4",
   "description": "Reactive artifact container.",
   "main": "index.js",
   "module": "index.mjs",