@asaidimu/utils-store 6.0.0 → 7.0.1

package/index.d.mts

@@ -50,132 +50,237 @@ interface SimplePersistence<T> {
 }
 
 /**
- * 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;
 /**
- * Interface for performance metrics of the state.
+ * Interface for performance and execution metrics of the state store.
  */
 interface StoreMetrics {
+    /** The number of times the state has been successfully updated. */
     updateCount: number;
+    /** The total number of listener functions executed in response to state changes. */
     listenerExecutions: number;
+    /** The average time taken for a state update process to complete (in milliseconds). */
     averageUpdateTime: number;
+    /** The size (e.g., number of paths changed) of the largest single state update. */
     largestUpdateSize: number;
+    /** List of state paths that trigger the most listener executions. */
     mostActiveListenerPaths: string[];
+    /** The total number of update attempts (including blocked ones). */
     totalUpdates: number;
+    /** The number of updates that were blocked by blocking middleware. */
     blockedUpdates: number;
+    /** The average duration of a state update cycle (in milliseconds). */
     averageUpdateDuration: number;
+    /** The total number of middleware functions executed. */
     middlewareExecutions: number;
+    /** The total number of transactions initiated. */
     transactionCount: number;
+    /** The total number of store events fired. */
     totalEventsFired: number;
+    /** The total number of actions dispatched. */
     totalActionsDispatched: number;
+    /** The total number of actions that completed successfully. */
     totalActionsSucceeded: number;
+    /** The total number of actions that failed with an error. */
     totalActionsFailed: number;
+    /** The average duration of an action execution (in milliseconds). */
     averageActionDuration: number;
 }
 /**
- * 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";
+/**
+ * Payload for the 'selector:changed' event.
+ */
 interface SelectorChangedPayload<S> {
+    /** Unique identifier of the selector. */
     selectorId: string;
+    /** The new computed result of the selector. */
     newResult: S;
+    /** Timestamp of when the change occurred. */
     timestamp: number;
 }
+/**
+ * Maps each `StoreEvent` type to its corresponding event payload interface.
+ * Uses conditional types to ensure type safety for event listeners.
+ */
 type StoreEvents = {
     [K in StoreEvent]: K extends "update:complete" ? {
+        /** List of state changes (deltas) applied in the update. */
         deltas: StateDelta[];
+        /** Total duration of the update process (in milliseconds). */
         duration: number;
+        /** Timestamp of the update completion. */
         timestamp: number;
+        /** Optional ID of the action that triggered the update. */
         actionId?: string;
+        /** The resulting new state after the update (may be a partial/transformed state). */
         newState: any;
+        /** True if the update was blocked by a middleware. */
         blocked?: boolean;
+        /** Any error that occurred during the update. */
         error?: any;
     } : K extends "selector:accessed" ? SelectorAccessedPayload : K extends "selector:changed" ? SelectorChangedPayload<any> : K extends "action:start" ? ActionStartPayload : K extends "action:complete" ? ActionCompletePayload : K extends "action:error" ? ActionErrorPayload : K extends "middleware:start" | "middleware:complete" | "middleware:error" | "middleware:blocked" | "middleware:executed" ? MiddlewareExecution : K extends "transaction:start" | "transaction:complete" | "transaction:error" ? {
         transactionId: string;
         timestamp: number;
     } : K extends "persistence:queued" ? PersistenceQueuedPayload : K extends "persistence:success" ? PersistenceSuccessPayload : K extends "persistence:retry" ? PersistenceRetryPayload : K extends "persistence:failed" ? PersistenceFailedPayload : K extends "persistence:queue_cleared" ? PersistenceQueueClearedPayload : K extends "persistence:init_error" ? PersistenceInitErrorPayload : any;
 };
+/**
+ * Payload for the 'selector:accessed' event.
+ */
 interface SelectorAccessedPayload {
+    /** Unique identifier of the selector. */
     selectorId: string;
+    /** List of state paths accessed during the selector computation. */
     accessedPaths: string[];
+    /** Duration of the selector computation (in milliseconds). */
     duration: number;
+    /** Timestamp of the access. */
     timestamp: number;
 }
+/**
+ * Payload for the 'action:start' event.
+ */
 interface ActionStartPayload {
+    /** Unique identifier for the action execution. */
     actionId: string;
+    /** Name of the action function. */
     name: string;
+    /** The parameters passed to the action function. */
     params: any[];
+    /** Timestamp of when the action execution started. */
     timestamp: number;
 }
+/**
+ * Payload for the 'action:complete' event (successful action execution).
+ */
 interface ActionCompletePayload {
+    /** Unique identifier for the action execution. */
     actionId: string;
+    /** Name of the action function. */
     name: string;
+    /** The parameters passed to the action function. */
     params: any[];
+    /** Timestamp of when the action execution started. */
     startTime: number;
+    /** Timestamp of when the action execution completed. */
     endTime: number;
+    /** Total duration of the action execution (in milliseconds). */
     duration: number;
+    /** The result returned by the action function. */
     result: any;
 }
+/**
+ * Payload for the 'action:error' event (failed action execution).
+ */
 interface ActionErrorPayload {
+    /** Unique identifier for the action execution. */
     actionId: string;
+    /** Name of the action function. */
     name: string;
+    /** The parameters passed to the action function. */
     params: any[];
+    /** Timestamp of when the action execution started. */
     startTime: number;
+    /** Timestamp of when the action execution ended (with error). */
     endTime: number;
+    /** Total duration of the action execution (in milliseconds). */
     duration: number;
+    /** The error object. */
     error: any;
 }
 /**
- * Type for middleware functions. Return a partial state to transform the update.
+ * Type for a generic middleware function.
+ * It receives the current state and the incoming update, and can return
+ * a modified `DeepPartial<T>` (transforming the update) or `void`.
  */
 type Middleware<T> = (state: T, update: DeepPartial<T>) => Promise<DeepPartial<T>> | Promise<void> | DeepPartial<T> | void;
 /**
- * Middleware execution information for event emissions
+ * Middleware execution information for event emissions and tracking.
  */
 interface MiddlewareExecution {
+    /** Unique identifier for the middleware instance. */
     id: string;
+    /** Name of the middleware. */
     name: string;
+    /** Timestamp of when the middleware execution started. */
     startTime: number;
+    /** Timestamp of when the middleware execution completed. */
     endTime: number;
+    /** Total duration of the middleware execution (in milliseconds). */
     duration: number;
+    /** True if the middleware blocked the update. */
     blocked: boolean;
+    /** Error object if the middleware failed. */
     error?: Error;
+    /** List of state changes (deltas) that resulted from this middleware's transformation. */
     deltas: StateDelta[];
 }
+/**
+ * Represents a single change to the state, detailing the path, old value, and new value.
+ */
 interface StateDelta {
+    /** Dot-separated path to the changed property (e.g., "user.profile.name"). */
     path: string;
+    /** The value of the property *before* the update. */
     oldValue: any;
+    /** The value of the property *after* the update. */
     newValue: any;
 }
 /**
- * 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>>);
+/**
+ * A unique symbol used within DeepPartial objects to explicitly signal that a property
+ * should be deleted from the state object.
+ */
 declare const DELETE_SYMBOL: unique symbol;
 /**
 * 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;
@@ -185,23 +290,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>>;
@@ -210,67 +338,144 @@ 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>>;
 }
+/** Payload for the 'persistence:queued' event. */
 interface PersistenceQueuedPayload {
+    /** Unique ID for the persistence task. */
     taskId: string;
+    /** Paths that were changed and triggered persistence. */
     changedPaths: string[];
+    /** The current number of tasks waiting in the persistence queue. */
     queueSize: number;
+    /** Timestamp of when the task was queued. */
     timestamp: number;
 }
+/** Payload for the 'persistence:success' event. */
 interface PersistenceSuccessPayload {
+    /** Unique ID for the persistence task. */
     taskId: string;
+    /** Paths that were successfully persisted. */
     changedPaths: string[];
+    /** Duration of the persistence operation (in milliseconds). */
     duration: number;
+    /** Timestamp of the success. */
     timestamp: number;
 }
+/** Payload for the 'persistence:retry' event. */
 interface PersistenceRetryPayload {
+    /** Unique ID for the persistence task. */
     taskId: string;
+    /** Current retry attempt number. */
     attempt: number;
+    /** Maximum allowed retries. */
     maxRetries: number;
+    /** Time until the next retry attempt (in milliseconds). */
     nextRetryIn: number;
+    /** The error that triggered the retry. */
     error: any;
+    /** Timestamp of the retry event. */
     timestamp: number;
 }
+/** Payload for the 'persistence:failed' event. */
 interface PersistenceFailedPayload {
+    /** Unique ID for the persistence task. */
     taskId: string;
+    /** Paths that failed to persist. */
     changedPaths: string[];
+    /** Total number of attempts made. */
     attempts: number;
+    /** The final error object. */
     error: any;
+    /** Timestamp of the final failure. */
     timestamp: number;
 }
+/** Payload for the 'persistence:queue_cleared' event. */
 interface PersistenceQueueClearedPayload {
+    /** The number of persistence tasks that were cleared from the queue. */
     clearedTasks: number;
+    /** Timestamp of when the queue was cleared. */
     timestamp: number;
 }
+/** Payload for the 'persistence:init_error' event. */
 interface PersistenceInitErrorPayload {
+    /** The error that occurred during persistence initialization. */
     error: any;
+    /** Timestamp of the error. */
     timestamp: number;
 }
+/**
+ * Interface describing a registered state action, including its metadata and debounce configuration.
+ */
 type StoreAction<T, R extends any[] = any[]> = {
+    /** Unique identifier for the action definition. */
     id: string;
+    /** Name of the action, used for dispatching. */
     name: string;
+    /** The actual function that takes state and arguments, and returns a state update. */
     action: (state: T, ...args: R) => DeepPartial<T> | Promise<DeepPartial<T>>;
+    /** Optional configuration for debouncing action execution. */
     debounce?: {
         /** Active timer reference, if debouncing */
         timer?: ReturnType<typeof setTimeout>;
@@ -355,7 +560,7 @@ declare class ReactiveDataStore<T extends object> implements DataStore<T> {
     set(update: StateUpdater<T>, options?: {
         force?: boolean;
         actionId?: string;
-    }): Promise<any>;
+    }): Promise<T>;
     /**
      * Internal logic for performing a single, sequential state update.
      */
@@ -382,490 +587,6 @@ declare class ReactiveDataStore<T extends object> implements DataStore<T> {
     private emit;
 }
 
-/**
- * Base class for structural/configuration errors within the ArtifactContainer.
- * These errors indicate fundamental issues (e.g., circular dependencies, missing artifacts)
- * that prevent successful resolution and should bypass any retry mechanisms,
- * causing an immediate strict failure.
- */
-declare class SystemError extends Error {
-    constructor(message: string);
-}
-/**
- * Error thrown when a circular dependency is detected during artifact resolution.
- * This indicates a structural problem in the artifact graph.
- */
-declare class CircularDependencyError extends SystemError {
-    /**
-     * Creates an instance of CircularDependencyError.
-     * @param path The dependency path that caused the cycle.
-     */
-    constructor(path: string[]);
-}
-/**
- * Error thrown when an artifact requested for resolution is not found
- * within the current container or its parent hierarchy.
- */
-declare class ArtifactNotFoundError extends SystemError {
-    /**
-     * Creates an instance of ArtifactNotFoundError.
-     * @param key The key of the artifact that was not found.
-     */
-    constructor(key: string);
-}
-/**
- * Error thrown when an operation is attempted that is not permitted
- * due to the artifact's scope or current state (e.g., calling `yield` on a Transient artifact).
- */
-declare class IllegalScopeError extends SystemError {
-    /**
-     * Creates an instance of IllegalScopeError.
-     * @param message A descriptive message about the illegal operation.
-     */
-    constructor(message: string);
-}
-/**
- * Defines the lifecycle and sharing strategy for an artifact.
- */
-declare enum ArtifactScope {
-    /**
-     * A single instance of the artifact is created and shared across all resolutions
-     * within the container. It is created once and reused.
-     */
-    Singleton = "singleton",
-    /**
-     * A new instance of the artifact is created every time it is resolved.
-     * Transient artifacts do not participate in caching or shared state.
-     */
-    Transient = "transient"
-}
-/**
- * Configuration options for defining an artifact. These options control
- * its lifecycle, instantiation, and error handling behavior.
- */
-interface ArtifactOptions {
-    /**
-     * The scope of the artifact, determining its lifecycle and sharing strategy.
-     * Defaults to `ArtifactScope.Singleton`.
-     */
-    scope?: ArtifactScope;
-    /**
-     * If `true` (default), the artifact's factory is executed only when the artifact
-     * is first requested. If `false`, the artifact is built immediately upon registration
-     * (only applies to Singleton scopes).
-     */
-    lazy?: boolean;
-    /**
-     * Maximum time in milliseconds allowed for the artifact's factory function
-     * to complete execution. If exceeded, the factory will time out.
-     */
-    timeoutMs?: number;
-    /**
-     * Number of times to retry the artifact's factory on failure due to an
-     * external (runtime) error. SystemErrors are not retried. Defaults to `0`.
-     */
-    retries?: number;
-    /**
-     * Base debounce time in milliseconds for invalidation events originating
-     * from this artifact. This can be overridden by `UseOptions.debounce`.
-     */
-    debounce?: number;
-}
-/**
- * Options that can be applied to dependency resolutions within an artifact's factory,
- * allowing for fine-grained control over how dependencies affect the current artifact.
- */
-interface UseOptions {
-    /**
-     * Applies a specific debounce time in milliseconds to dependencies resolved
-     * within the `use` block. If this value is higher than the artifact's
-     * `baseDebounceMs` (or `activeDebounceMs`), it will be used for subsequent invalidations.
-     */
-    debounce?: number;
-}
-/**
- * Represents a snapshot of an artifact's state and dependencies for debugging purposes.
- * Provides insight into the artifact's current status and its position within the dependency graph.
- */
-interface ArtifactDebugNode {
-    /** The unique identifier (key) of the artifact. */
-    id: string;
-    /** The scope of the artifact (Singleton or Transient). */
-    scope: ArtifactScope;
-    /**
-     * The current status of the artifact, indicating its lifecycle phase.
-     * - 'active': The artifact is built and available.
-     * - 'error': The artifact failed to build due to an external error.
-     * - 'idle': The artifact has not yet been built (lazy singleton) or has been disposed.
-     * - 'building': The artifact's factory is currently executing.
-     * - 'debouncing': The artifact is currently in a debounced invalidation state.
-     */
-    status: "active" | "error" | "idle" | "building" | "debouncing";
-    /** A list of artifact keys that this artifact directly depends on. */
-    dependencies: string[];
-    /** A list of artifact keys that directly depend on this artifact. */
-    dependents: string[];
-    /** A list of state paths (selectors) that this artifact depends on. */
-    stateDependencies: string[];
-    /** The number of times this artifact's factory has been successfully executed. */
-    renderCount: number;
-}
-/**
- * Context provided to the `use` callback within an artifact factory.
- * It allows an artifact to declare dependencies on other artifacts and state slices.
- * @template TRegistry The type mapping artifact keys to their artifact types.
- * @template TState The type of the global state managed by the DataStore.
- */
-interface UseDependencyContext<TRegistry extends Record<string, any>, TState extends object> {
-    /**
-     * Resolves another artifact from the container.
-     * Declares a dependency on the resolved artifact, meaning that if the dependency
-     * changes, this artifact will be invalidated and rebuilt.
-     * @template K The key of the artifact to resolve.
-     * @param key The key of the artifact to resolve.
-     * @returns A Promise that resolves to a `ResolvedArtifact` containing the instance
-     *          or an external error.
-     * @throws {SystemError} if the key is missing or if resolving creates a circular dependency.
-     */
-    resolve<K extends keyof TRegistry>(key: K): Promise<ResolvedArtifact<TRegistry[K]>>;
-    /**
-     * Selects a slice of the global state.
-     * Declares a dependency on the selected state paths, meaning that if the selected
-     * state changes, this artifact will be invalidated and rebuilt.
-     * @template S The type of the selected state slice.
-     * @param selector A function that takes the full state and returns a slice.
-     * @returns The selected slice of state.
-     */
-    select<S>(selector: (state: TState) => S): S;
-}
-/**
- * The full context provided to an artifact's factory function.
- * This context allows the artifact to interact with the container,
- * declare dependencies, manage its lifecycle, and update its value.
- * @template TRegistry The type mapping artifact keys to their artifact types.
- * @template TState The type of the global state managed by the DataStore.
- * @template TArtifact The type of the artifact being created by the factory.
- */
-interface ArtifactFactoryContext<TRegistry extends Record<string, any>, TState extends object, TArtifact> {
-    /**
-     * Returns the current global state object. This is a non-reactive read;
-     * changes to the state will not automatically invalidate the artifact
-     * unless explicitly selected via `ctx.select in use()`.
-     * @returns The current global state.
-     */
-    state(): TState;
-    /**
-     * The previous instance of the artifact if it's a Singleton and is being rebuilt.
-     * Useful for diffing or migrating state during an update.
-     */
-    current?: TArtifact;
-    /**
-     * Executes a callback within a dependency tracking context.
-     * Any `resolve` or `select` calls made inside this callback will register
-     * dependencies for the current artifact.
-     * @template R The return type of the callback.
-     * @param callback The function to execute to resolve dependencies.
-     * @param options Optional settings for this dependency block, like debounce.
-     * @returns A Promise resolving to the result of the callback.
-     */
-    use<R>(callback: (ctx: UseDependencyContext<TRegistry, TState>) => R | Promise<R>, options?: UseOptions): Promise<R>;
-    /**
-     * Registers a cleanup function to be executed when the artifact is
-     * invalidated and before its new instance is built. This is useful
-     * for releasing resources specific to the *previous* instance.
-     * @param cleanup The cleanup function.
-     */
-    onCleanup(cleanup: ArtifactCleanup): void;
-    /**
-     * Registers a dispose function to be executed when the artifact is
-     * permanently removed from the container or the container itself is disposed.
-     * This is for final resource release.
-     * @param callback The dispose function.
-     */
-    onDispose(callback: ArtifactCleanup): void;
-    /**
-     * Updates the value of a Singleton artifact from within its own factory.
-     * This immediately makes the new value available and triggers invalidation
-     * for all dependents. Can be used for long-running processes that produce
-     * intermediate results.
-     * @param value The new value for the artifact.
-     * @throws {SystemError} if called on a Transient artifact, as Transient artifacts
-     *         do not maintain a persistent value.
-     */
-    yield(value: TArtifact): void;
-}
-/**
- * A function that performs cleanup logic for an artifact, potentially asynchronously.
- * Used for `onCleanup` and `onDispose` callbacks.
- */
-type ArtifactCleanup = () => void | Promise<void>;
-/**
- * The result of an artifact resolution, providing the instance,
- * cleanup functionality, and details about any external errors.
- * @template TArtifact The type of the resolved artifact instance.
- */
-interface ResolvedArtifact<TArtifact> {
-    /** The successfully resolved instance of the artifact, if no error occurred. */
-    instance?: TArtifact;
-    /**
-     * A function to manually trigger cleanup associated with this specific
-     * resolved instance. This is typically only relevant for Transient artifacts.
-     */
-    cleanup?: ArtifactCleanup;
-    /**
-     * Any runtime or external error that occurred during the artifact's factory
-     * execution (e.g., fetch failed, timeout). SystemErrors are explicitly
-     * thrown and will not appear here.
-     */
-    error?: any;
-    /**
-     * Manually invalidates this artifact, triggering its rebuild and
-     * cascading invalidations to its dependents.
-     * @param replace If `true`, forces immediate rebuild without debounce.
-     */
-    invalidate(replace?: boolean): Promise<void>;
-}
-/**
- * The factory function responsible for creating an artifact's instance.
- * It receives an `ArtifactFactoryContext` to interact with the container
- * and declare dependencies.
- * @template TRegistry The type mapping artifact keys to their artifact types.
- * @template TState The type of the global state managed by the DataStore.
- * @template K The key of the artifact this factory produces.
- * @param context The context for creating the artifact.
- * @returns The artifact instance or a Promise resolving to it.
- */
-type ArtifactFactory<TRegistry extends Record<string, any>, TState extends object, K extends keyof TRegistry> = (context: ArtifactFactoryContext<TRegistry, TState, TRegistry[K]>) => TRegistry[K] | Promise<TRegistry[K]>;
-/**
- * An interface for observing changes to an artifact without direct resolution.
- * Provides a way to get the current resolved artifact and subscribe to updates.
- * @template TArtifact The type of the artifact being watched.
- */
-interface ArtifactWatcher<TArtifact> {
-    /** The unique identifier (key) of the artifact being watched. */
-    id: string;
-    /**
-     * Retrieves the current `ResolvedArtifact` for the watched key.
-     * Returns `null` if the artifact has not yet been built or has no instance/error.
-     * @returns The resolved artifact or `null`.
-     */
-    get(): ResolvedArtifact<TArtifact> | null;
-    /**
-     * Subscribes a callback function to be invoked whenever the artifact's
-     * state (instance or error) changes.
-     * @param callback The function to call on updates.
-     * @returns A function to unsubscribe the callback.
-     */
-    subscribe(callback: () => void): () => void;
-}
-/**
- * A dependency injection container for managing the lifecycle, dependencies,
- * and instances of "artifacts" (any JavaScript/TypeScript object or value).
- * It supports hierarchical containers, different scopes (singleton, transient),
- * dependency resolution, state-based invalidation, and debounced rebuilding.
- *
- * @template TRegistry A type that maps artifact keys (strings) to their
- *                     corresponding artifact types. This provides strong
- *                     typing for `resolve`, `register`, and other operations.
- * @template TState The type of the global state object that artifacts can depend on.
- */
-declare class ArtifactContainer<TRegistry extends Record<string, any> = Record<string, any>, TState extends object = any> {
-    private readonly artifacts;
-    private readonly resolvingStack;
-    private readonly listeners;
-    private readonly watcherCache;
-    private readonly props;
-    private readonly parent?;
-    private isDisposed;
-    /**
-     * Creates a new ArtifactContainer instance.
-     * @param props An object providing functions to interact with a global data store,
-     *              specifically `watch` for state changes and `get` for current state.
-     * @param parent An optional parent `ArtifactContainer`. If provided, this container
-     *               can resolve artifacts registered in its parent.
-     */
-    constructor({ watch, get }: Pick<DataStore<TState>, "watch" | "get">, parent?: ArtifactContainer<TRegistry, TState>);
-    /**
-     * Creates a new child `ArtifactContainer` that inherits from the current container.
-     * Child containers can resolve artifacts registered in their parent, but
-     * artifacts registered in the child are local to that child.
-     * @returns A new `ArtifactContainer` instance.
-     */
-    createChild(): ArtifactContainer<TRegistry, TState>;
-    /**
-     * Provides debug information about all artifacts currently registered in this container.
-     * This is useful for inspecting the state, scope, dependencies, and activity of artifacts.
-     * @returns An array of `ArtifactDebugNode` objects, each representing a registered artifact.
-     */
-    getDebugInfo(): ArtifactDebugNode[];
-    /**
-     * Registers a new artifact with the container.
-     * If an artifact with the same key already exists, it will be overwritten and disposed.
-     * For Singleton, non-lazy artifacts, the factory will be immediately invoked.
-     * @template K The key of the artifact to register.
-     * @param {object} params The registration parameters.
-     * @param {K} params.key The unique identifier for the artifact.
-     * @param {ArtifactFactory<TRegistry, TState, K>} params.factory The function that creates the artifact instance.
-     * @param {ArtifactOptions} params.options Optional configuration for the artifact's lifecycle.
-     * @returns A cleanup function that, when called, unregisters the artifact.
-     */
-    register<K extends keyof TRegistry>({ key, factory, ...options }: {
-        key: K;
-        factory: ArtifactFactory<TRegistry, TState, K>;
-    } & ArtifactOptions): () => void;
-    /**
-     * Unregisters an artifact from the container, disposing of its current instance
-     * and removing all associated resources and dependency links.
-     * @template K The key of the artifact to unregister.
-     * @param key The unique identifier of the artifact.
-     * @returns A Promise that resolves when the artifact has been fully unregistered and disposed.
-     */
-    unregister<K extends keyof TRegistry>(key: K): Promise<void>;
-    /**
-     * Resolves an artifact by its key, returning its instance or an error.
-     * This method handles dependency resolution, cycle detection, caching,
-     * and retry logic. It traverses the container hierarchy if the artifact
-     * is not found locally.
-     * @template K The key of the artifact to resolve.
-     * @param key The unique identifier for the artifact.
-     * @returns A Promise that resolves to a `ResolvedArtifact`. This object
-     *          will contain either the `instance` (if successful) or an `error`
-     *          (if an external error occurred during factory execution).
-     * @throws {CircularDependencyError} if a circular dependency is detected during resolution.
-     * @throws {ArtifactNotFoundError} if the artifact with the given key is not found
-     *                                  in the current container or any parent containers.
-     * @throws {SystemError} for any other critical structural or configuration issues.
-     */
-    resolve<K extends keyof TRegistry>(key: K): Promise<ResolvedArtifact<TRegistry[K]>>;
-    /**
-     * Returns an `ArtifactWatcher` for a given artifact key.
-     * The watcher allows subscribing to changes in the artifact's resolved value
-     * without directly resolving it or becoming a direct dependent.
-     * @template K The key of the artifact to watch.
-     * @param key The unique identifier for the artifact.
-     * @returns An `ArtifactWatcher` instance.
-     */
-    watch<K extends keyof TRegistry>(key: K): ArtifactWatcher<TRegistry[K]>;
-    /**
-     * Peeks at the resolved instance of an artifact without triggering its resolution
-     * if it's lazy, or registering a dependency. It simply returns the currently
-     * available instance (if any).
-     * @template K The key of the artifact to peek at.
-     * @param key The unique identifier for the artifact.
-     * @returns The artifact instance if it's already built, otherwise `undefined`.
-     */
-    peek<K extends keyof TRegistry>(key: K): TRegistry[K] | undefined;
-    private findDefinition;
-    /**
-     * Packages an `ArtifactDefinition` into a `ResolvedArtifact` for public consumption.
-     * This abstracts away internal details and provides the external API for interacting
-     * with a resolved artifact (e.g., `invalidate`).
-     * @template T The expected type of the artifact instance.
-     * @param def The internal `ArtifactDefinition`.
-     * @returns A `ResolvedArtifact` object.
-     */
-    private packageArtifact;
-    /**
-     * Core logic for executing an artifact's factory and capturing its dependencies.
-     * This method is responsible for setting up the factory context, running the
-     * factory (with retries and timeouts), and collecting all declared dependencies
-     * (both artifact and state).
-     * @template K The key of the artifact being created.
-     * @param def The `ArtifactDefinition` for the artifact.
-     * @param outArtifactDeps A Set to capture discovered artifact dependencies.
-     * @param outStateDeps A Set to capture discovered state dependencies.
-     * @returns A Promise resolving to an object containing the instance, cleanup function, and any external error.
-     * @throws {SystemError} if a critical internal error occurs (e.g., circular dependency detected).
-     */
-    private createArtifactInstance;
-    /**
-     * Handles the propagation of a `yield` event from a Singleton artifact.
-     * This involves invalidating all direct dependents and notifying any listeners.
-     * @param key The key of the artifact that yielded a new value.
-     */
-    private processYieldPropagation;
-    /**
-     * Registers a dependency from a `dependent` artifact on a `target` artifact.
-     * This builds the inverse dependency graph, allowing for efficient cascade invalidations.
-     * This method is public so that child containers can register dependents on artifacts
-     * owned by a parent container.
-     * @param targetKey The key of the artifact being depended upon.
-     * @param dependentKey The key of the artifact that depends on the target.
-     * @param dependentContainer The container instance where the dependent artifact is registered.
-     */
-    registerDependent(targetKey: string, dependentKey: string, dependentContainer: ArtifactContainer<any, any>): void;
-    /**
-     * Removes a previously registered dependency link.
-     * This method is public so that child containers can remove dependents on artifacts
-     * owned by a parent container when their artifacts are disposed.
-     * @param targetKey The key of the artifact that was depended upon.
-     * @param dependentKey The key of the artifact that previously depended on the target.
-     * @param dependentContainer The container instance where the dependent artifact was registered.
-     */
-    removeDependent(targetKey: string, dependentKey: string, dependentContainer: ArtifactContainer<any, any>): void;
-    /**
-     * Initiates the invalidation process for an artifact, potentially debouncing the rebuild.
-     * Invalidation marks an artifact as needing to be rebuilt on its next resolution.
-     * @template K The key of the artifact to invalidate.
-     * @param key The unique identifier for the artifact.
-     * @param replace If `true`, bypasses debouncing and forces an immediate execution of `executeInvalidation`.
-     * @returns A Promise that resolves when the invalidation (and potential debounced rebuild) is complete.
-     */
-    private invalidate;
-    /**
-     * Executes the actual invalidation and rebuild logic for an artifact.
-     * This includes disposing the old instance, invalidating dependents, and (optionally) resolving a new instance.
-     * @template K The key of the artifact to invalidate.
-     * @param key The unique identifier for the artifact.
-     * @param replace If `true`, forces immediate disposal and rebuild without waiting for existing rebuild promises.
-     * @returns A Promise that resolves when the invalidation and rebuild process is complete.
-     */
-    private executeInvalidation;
-    /**
-     * Disposes of an artifact's instance by running its cleanup and dispose functions,
-     * unsubscribing from state changes, and clearing its cached instance and error.
-     * This prepares the artifact for a rebuild or removal.
-     * @param def The `ArtifactDefinition` of the instance to dispose.
-     */
-    private disposeInstance;
-    /**
-     * Fully disposes of an artifact, including its instance and all its associated
-     * dependency graph links and resources. This is typically called when an artifact
-     * is unregistered or the container itself is disposed.
-     * @param key The unique identifier of the artifact to dispose.
-     */
-    private disposeArtifact;
-    /**
-     * Updates the dependency graph for an artifact based on newly discovered dependencies
-     * during its factory execution. This involves adding and removing dependent links,
-     * and setting up or tearing down state subscriptions.
-     * @param def The `ArtifactDefinition` whose graph is being updated.
-     * @param newArtifactDeps The set of artifact dependencies discovered during the latest build.
-     * @param newStateDeps The set of state path dependencies discovered during the latest build.
-     */
-    private updateGraph;
-    /**
-     * Creates a single composite cleanup function from an array of individual cleanup functions.
-     * The composite function executes all provided cleanups in reverse order of registration,
-     * ensuring proper resource release, and handles potential asynchronous cleanups.
-     * @param fns An array of `ArtifactCleanup` functions.
-     * @returns A composite `ArtifactCleanup` function, or `undefined` if the array is empty.
-     */
-    private createCompositeCleanup;
-    /**
-     * Notifies all registered listeners (watchers) for a specific artifact that
-     * its state (instance or error) has potentially changed.
-     * @param key The key of the artifact whose listeners should be notified.
-     */
-    private notifyListeners;
-    /**
-     * Disposes of the entire `ArtifactContainer` and all artifacts registered within it.
-     * This releases all resources, stops all watchers, and clears all internal state.
-     * After disposal, the container should no longer be used.
-     */
-    dispose(): void;
-}
-
 /**
  * @fileoverview Store Observer Module
  * @description A comprehensive module to add advanced debugging, observability, and time-travel
@@ -1194,4 +915,4 @@ declare class ActionManager<T extends object> {
     private emit;
 }
 
-export { type ActionCompletePayload, type ActionErrorPayload, ActionManager, type ActionStartPayload, type ArtifactCleanup, ArtifactContainer, type ArtifactDebugNode, type ArtifactFactory, type ArtifactFactoryContext, ArtifactNotFoundError, type ArtifactOptions, ArtifactScope, type ArtifactWatcher, type BlockingMiddleware, CircularDependencyError, DELETE_SYMBOL, type DataStore, type DeepPartial, type DiffFunction, IllegalScopeError, type MergeFunction, type Middleware, type MiddlewareConfig, type MiddlewareExecution, type ObserverOptions, type PersistenceFailedPayload, type PersistenceInitErrorPayload, type PersistenceQueueClearedPayload, type PersistenceQueuedPayload, type PersistenceRetryPayload, type PersistenceSuccessPayload, ReactiveDataStore, type ReactiveSelector, type ResolvedArtifact, type SelectorAccessedPayload, type SelectorChangedPayload, type StateDelta, type StateUpdater, type StoreAction, type StoreEvent, type StoreEvents, type StoreExecutionState, type StoreMetrics, StoreObserver, SystemError, type TransformMiddleware, type UseDependencyContext, type UseOptions, createDerivePaths, createDiff, createMerge, derivePaths, diff, merge, shallowClone };
+export { type ActionCompletePayload, type ActionErrorPayload, ActionManager, type ActionStartPayload, type BlockingMiddleware, DELETE_SYMBOL, type DataStore, type DeepPartial, type DiffFunction, type MergeFunction, type Middleware, type MiddlewareConfig, type MiddlewareExecution, type ObserverOptions, type PersistenceFailedPayload, type PersistenceInitErrorPayload, type PersistenceQueueClearedPayload, type PersistenceQueuedPayload, type PersistenceRetryPayload, type PersistenceSuccessPayload, ReactiveDataStore, type ReactiveSelector, type SelectorAccessedPayload, type SelectorChangedPayload, type StateDelta, type StateUpdater, type StoreAction, type StoreEvent, type StoreEvents, type StoreExecutionState, type StoreMetrics, StoreObserver, type TransformMiddleware, createDerivePaths, createDiff, createMerge, derivePaths, diff, merge, shallowClone };