@asaidimu/utils-artifacts 3.1.2 → 3.1.4

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,46 +109,95 @@ 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>>;
 }
 
 /**
- * Defines the lifecycle and sharing strategy for an artifact.
+ * Defines the lifecycle and sharing strategy for an artifact within the container.
  */
 
+/**
+ * Defines the lifecycle and sharing strategy for an artifact.
+ */
 type ArtifactScope = 
 /**
- * A single instance of the artifact is created and shared across all resolutions
- * within the container. It is created once and reused.
+ * **Singleton:** A single instance of the artifact is created and shared across all resolutions
+ * within the container. It is created once (often lazily) and reused until invalidated.
  */
 "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:** A new instance of the artifact is created every time it is resolved.
+ * Transient artifacts do not participate in caching or shared state management.
  */
  | "transient";
+/**
+ * Enumeration of standard artifact scopes for strongly typed configuration.
+ */
 declare enum ArtifactScopes {
+    /** A single instance is shared globally. */
     Singleton = "singleton",
+    /** A new instance is created on every resolution. */
     Transient = "transient"
 }
 /**
@@ -120,19 +211,20 @@ interface ArtifactDebugNode {
     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" | "pending" /** A list of artifact keys that this artifact directly depends on. */;
+     * - `'active'`: The artifact is successfully built and its instance is available.
+     * - `'error'`: The artifact failed to build due to an external (runtime) error.
+     * - `'idle'`: The artifact has not yet been built (for lazy singletons) or has been disposed.
+     * - `'building'`: The artifact's factory is currently executing.
+     * - `'pending'`: The artifact is waiting to be built, often after an invalidation and before any debounce.
+     */
+    status: "active" | "error" | "idle" | "building" | "pending" | "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. */
+    /** A list of artifact keys that directly depend on this artifact (its consumers). */
     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. */
+    /** The number of times this artifact's factory has been successfully executed/rebuilt. */
     renderCount: number;
 }
 /**
@@ -143,54 +235,62 @@ interface ArtifactDebugNode {
  */
 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.
+     * Resolves another artifact from the container and registers a dependency on it.
+     * If the dependency changes, the current 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.
+     * 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.
+     * Selects a slice of the global state and registers a dependency on it.
+     * If the selected state slice changes (based on a deep comparison), the current
+     * 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.
+     * @param selector A function that takes the full state and returns a slice of state.
      * @returns The selected slice of state.
      */
     select<S>(selector: (state: TState) => S): S;
 }
 /**
- * Context object provided to an artifact stream producer function.
- * It contains methods and properties necessary for managing the stream
- * and communicating new artifact values.
+ * Context object provided to an artifact stream producer function (`ctx.stream` callback).
+ * It contains methods and properties necessary for managing the stream and communicating
+ * new artifact values to the container and its consumers.
  *
+ * @template TState The type of the global state.
  * @template TArtifact The type of the artifact being streamed.
  */
 type ArtifactStreamContext<TState, TArtifact> = {
     /**
      * The current value of the artifact. This is `undefined` before the first value is emitted.
      * Useful for diffing or migrating state during an update.
+     * @returns The current artifact value or `undefined`.
      */
     value: () => TArtifact | undefined;
     /**
      * An AbortSignal that indicates if the stream has been cancelled or aborted
-     * from the consumer side. Producers should check this signal and stop
-     * processing when it is set.
+     * from the consumer side (e.g., due to container disposal or artifact invalidation).
+     * Producers should check this signal and stop processing when it is set to prevent leaks.
      */
     signal: AbortSignal;
     /**
-     * A function to asynchronously emit a new value of the artifact to the consumer.
-     * Calling this function updates the `value` and `previous` properties in the
-     * context for subsequent emissions.
+     * A function to asynchronously emit a new value of the artifact to the container.
+     * Calling this function updates the artifact's resolved value, triggers invalidation
+     * for its dependents, and updates the `value()` property for subsequent emissions.
      *
      * @param value The new artifact value to emit.
-     * @returns A Promise that resolves when the value has been sent.
+     * @returns A Promise that resolves when the value has been sent and dependents have been notified.
      */
     emit: (value: TArtifact) => Promise<void>;
+    /**
+     * Dispatches a state update to the global store, analogous to a standard `setState`.
+     * **Note:** This does not automatically register a dependency for the current artifact.
+     * @param update A `StateUpdater` function or a partial state object.
+     * @param options Optional settings for the update, including `force` and `actionId`.
+     * @returns A Promise that resolves when the state update is complete.
+     */
     set(update: StateUpdater<TState>, options?: {
         force?: boolean;
         actionId?: string;
@@ -208,13 +308,14 @@ interface ArtifactFactoryContext<TRegistry extends Record<string, any>, TState e
     /**
      * 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()`.
+     * unless explicitly selected via `ctx.use` and `ctx.select`.
      * @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.
+     * The previous instance of the artifact if it's a Singleton and is being rebuilt
+     * after an invalidation. This is `undefined` on the initial build.
+     * Useful for diffing, migrating state, or reusing resources during an update.
      */
     previous?: TArtifact;
     /**
@@ -223,81 +324,123 @@ interface ArtifactFactoryContext<TRegistry extends Record<string, any>, TState e
      * 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>): 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.
+     * Registers a cleanup function to be executed when the **current instance** of the
+     * artifact is invalidated and before its new instance is built. This is useful
+     * for releasing resources (e.g., event listeners) 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.
+     * This is for final, permanent 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.
+     * Starts a stream process for a Singleton artifact, allowing it to emit
+     * multiple values over time. The callback receives an `ArtifactStreamContext`
+     * for emitting values and managing the stream lifecycle.
+     * @param callback The function that implements the streaming logic.
      * @throws {SystemError} if called on a Transient artifact, as Transient artifacts
-     *         do not maintain a persistent value.
+     * do not maintain a persistent value.
      */
     stream(callback: (ctx: ArtifactStreamContext<TState, TArtifact>) => void | Promise<void>): void;
 }
 /**
- * A function that performs cleanup logic for an artifact, potentially asynchronously.
+ * A function that performs cleanup or disposal 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.
+ * Common properties shared across all possible states of a resolved artifact.
  * @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;
+interface ResolvedArtifactBase {
     /**
      * A function to manually trigger cleanup associated with this specific
-     * resolved instance. This is typically only relevant for Transient artifacts.
+     * resolved instance. This is typically only relevant for Transient artifacts
+     * where the consumer is responsible for cleanup.
      */
     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;
-    ready: boolean;
     /**
      * Manually invalidates this artifact, triggering its rebuild and
      * cascading invalidations to its dependents.
-     * @param replace If `true`, forces immediate rebuild without debounce.
+     * @param replace If `true`, forces immediate rebuild without debounce delay.
+     * @param fatal If `true`, the artifact will not be rebuilt until next resolve
+     * regardless of the lazy option during registration.
      */
-    invalidate(replace?: boolean): Promise<void>;
+    invalidate(replace?: boolean, fatal?: boolean): Promise<void>;
+}
+/**
+ * State of an artifact that is successfully built and ready for use.
+ * The instance is guaranteed to be present.
+ * @template TArtifact The type of the resolved artifact instance.
+ */
+interface ReadyArtifact<TArtifact> extends ResolvedArtifactBase {
+    /** The successfully resolved instance of the artifact. */
+    instance: TArtifact;
+    /** Indicates that the artifact is ready and has an instance. Always true. */
+    ready: true;
+    /** Must be undefined in a ready state. */
+    error?: undefined;
 }
+/**
+ * State of an artifact that failed to build due to an external error.
+ * The instance is guaranteed to be absent.
+ */
+interface ErrorArtifact extends ResolvedArtifactBase {
+    /** The instance is absent when an error occurs. Always undefined. */
+    instance?: undefined;
+    /** Indicates that the artifact failed to build. Always false. */
+    ready: false;
+    /**
+     * Any runtime or external error that occurred during the artifact's factory
+     * execution (e.g., network fetch failed).
+     */
+    error: any;
+}
+/**
+ * State of an artifact that is pending, idle, or currently building.
+ * Both instance and error are absent.
+ */
+interface PendingArtifact extends ResolvedArtifactBase {
+    /** The instance is absent while pending or idle. Always undefined. */
+    instance?: undefined;
+    /** Indicates that the artifact is not yet ready. Always false. */
+    ready: false;
+    /** Must be undefined in a pending state. */
+    error?: undefined;
+}
+/**
+ * The result of an artifact resolution. This is a union type representing
+ * the artifact in one of three possible states: Ready, Error, or Pending/Idle.
+ *
+ * This structure allows consuming code to narrow the type based on the
+ * boolean flag `ready` or the presence of the `error` property.
+ *
+ * @template TArtifact The type of the resolved artifact instance.
+ */
+type ResolvedArtifact<TArtifact> = ReadyArtifact<TArtifact> | ErrorArtifact | PendingArtifact;
 /**
  * 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.
+ * @template TArtifact The type 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, TArtifact> = (context: ArtifactFactoryContext<TRegistry, TState, TArtifact>) => TArtifact | Promise<TArtifact>;
 type ArtifactInstance<R> = R extends PromiseLike<infer T> ? T : R;
 /**
- * An interface for observing changes to an artifact without direct resolution.
+ * An interface for observing changes to an artifact without direct resolution,
+ * typically used for UI binding or monitoring.
  * Provides a way to get the current resolved artifact and subscribe to updates.
  * @template TArtifact The type of the artifact being watched.
  */
@@ -305,36 +448,38 @@ interface ArtifactObserver<TArtifact> {
     /** The unique identifier (key) of the artifact being watched. */
     id: string;
     /**
-     * Number of active references to this watcher.
+     * Number of active references (watchers) to this observer instance.
      * Incremented on each `watch()` call, decremented on each `dispose()` call.
      */
     count: number;
     /**
      * Retrieves the current `ResolvedArtifact` for the watched key.
-     * @returns The resolved artifact.
+     * @returns The resolved artifact, including its instance and status.
      */
     get(): ResolvedArtifact<TArtifact>;
     /**
      * 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.
+     * state (instance, error, or readiness) changes.
+     * @param callback The function to call on updates. It receives the new `ResolvedArtifact`.
+     * @returns A function to unsubscribe the callback and stop receiving updates.
      */
     subscribe(callback: (artifact: ResolvedArtifact<TArtifact>) => void): () => void;
     /**
-     * Disposes of this watcher reference, decrementing the reference count.
-     * When the count reaches zero, cleans up all associated resources.
-     * For transient artifacts that were cloned to singletons for watching,
-     * this will unregister the cloned singleton when the last reference is disposed.
+     * Disposes of this specific observer reference, decrementing the reference count.
+     * When the count reaches zero, associated resources (like cloned singletons for Transient artifacts)
+     * are cleaned up.
      */
     dispose(): Promise<void>;
 }
 /**
  * Configuration options for defining an artifact. These options control
  * its lifecycle, instantiation, and error handling behavior.
+ * @template TState The type of the global state.
+ * @template TArtifact The resolved type of the artifact instance.
+ * @template TRegistry The type mapping of all artifacts in the container.
  */
 interface ArtifactTemplate<TState extends object, TArtifact, TRegistry extends object = any> {
-    /** The unique key identifying this artifact. */
+    /** The unique key identifying this artifact within the registry. */
     key: keyof TRegistry;
     /** The factory function responsible for creating the artifact's instance. */
     factory: ArtifactFactory<TRegistry, TState, TArtifact>;
@@ -345,8 +490,8 @@ interface ArtifactTemplate<TState extends object, TArtifact, TRegistry extends o
     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).
+     * is first requested (lazy instantiation). If `false`, the artifact is built
+     * immediately upon registration (only applies to Singleton scopes).
      */
     lazy?: boolean;
     /**
@@ -356,60 +501,60 @@ interface ArtifactTemplate<TState extends object, TArtifact, TRegistry extends o
     timeout?: 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`.
+     * external (runtime) error (e.g., an exception in an async dependency).
+     * SystemErrors (e.g., key not found) 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`.
+     * from this artifact's dependencies. This delays the rebuild process to
+     * aggregate multiple rapid changes.
      */
     debounce?: number;
 }
 /**
- * Extracts the state type from an ArtifactTemplate
+ * Extracts the global state type (`TState`) from an `ArtifactTemplate`.
  */
 type ArtifactStateType<T> = T extends ArtifactTemplate<infer TState, any, any> ? TState : never;
 /**
- * Extracts the registry type from an ArtifactTemplate
+ * Extracts the full artifact registry type (`TRegistry`) from an `ArtifactTemplate`.
  */
 type ArtifactRegistryType<T> = T extends ArtifactTemplate<any, any, infer TRegistry> ? TRegistry : never;
 /**
- * Extracts the key from an ArtifactTemplate (as a string literal if possible)
+ * Extracts the key type (`K`) from an `ArtifactTemplate` (as a string literal if possible).
  */
 type ArtifactKey<T> = T extends {
     key: infer K;
 } ? K : never;
 /**
- * Extracts the scope from an ArtifactTemplate
+ * Extracts the scope type (`S`) from an `ArtifactTemplate`, defaulting to `ArtifactScope` if undefined.
  */
 type ArtifactScopeType<T> = T extends {
     scope: infer S;
 } ? S extends ArtifactScope ? S : ArtifactScope : ArtifactScope;
 /**
- * Helper type that creates a properly typed template map.
- * Use this as a type annotation when defining your templates object.
+ * Helper type that creates a properly typed template map where keys correspond to artifact names
+ * and values are their corresponding templates.
+ * @template TState The type of the global state.
+ * @template TRegistry The map of all artifact keys to their resolved types.
  */
 type ArtifactTemplateMap<TState extends object, TRegistry extends Record<string, any> = any> = {
     [K in keyof TRegistry]: ArtifactTemplate<TState, TRegistry[K], TRegistry>;
 };
 /**
- * Extracts the artifact's resolved value type from an object that structurally
- * resembles an ArtifactTemplate (or a variation where properties are omitted).
- *
- * It infers TArtifact from the second generic argument of the factory function,
- * which is the resolved artifact type.
+ * Extracts the artifact's resolved value type (`TArtifact`) from an object that structurally
+ * resembles an `ArtifactTemplate` (by inspecting the `factory` function's generic arguments).
  *
- * @template T The type that is structurally an ArtifactTemplate or an omitted version of it.
+ * @template T The type that contains a factory property.
  */
 type ArtifactValue<T> = T extends {
     factory: ArtifactFactory<any, any, infer TArtifact>;
 } ? TArtifact : never;
 /**
- * Infers the complete Artifact Registry type from a map of artifact configurations.
+ * Infers the complete Artifact Registry type from a map of artifact configuration objects.
  *
- * This works for both the full ArtifactTemplate (if key is present) or
- * ArtifactDefinition (if key is omitted), as it only relies on the presence
- * of the 'factory' property to determine the final type.
+ * This utility uses the `ArtifactValue` type to determine the resolved type for each key
+ * based on the `factory` function defined in the configuration.
  *
  * @template T A map where keys are artifact names and values are their configurations.
  */
@@ -527,4 +672,4 @@ declare class ArtifactContainer<TRegistry extends Record<string, any> = Record<s
     dispose(): void;
 }
 
-export { type ArtifactCleanup, ArtifactContainer, type ArtifactDebugNode, type ArtifactFactory, type ArtifactFactoryContext, type ArtifactInstance, type ArtifactKey, type ArtifactObserver, type ArtifactRegistryType, type ArtifactScope, type ArtifactScopeType, ArtifactScopes, type ArtifactStateType, type ArtifactStreamContext, type ArtifactTemplate, type ArtifactTemplateMap, type ArtifactValue, type InferRegistry, type ResolvedArtifact, type UseDependencyContext };
+export { type ArtifactCleanup, ArtifactContainer, type ArtifactDebugNode, type ArtifactFactory, type ArtifactFactoryContext, type ArtifactInstance, type ArtifactKey, type ArtifactObserver, type ArtifactRegistryType, type ArtifactScope, type ArtifactScopeType, ArtifactScopes, type ArtifactStateType, type ArtifactStreamContext, type ArtifactTemplate, type ArtifactTemplateMap, type ArtifactValue, type ErrorArtifact, type InferRegistry, type PendingArtifact, type ReadyArtifact, type ResolvedArtifact, type ResolvedArtifactBase, type UseDependencyContext };