@asaidimu/utils-store 6.0.0 → 7.0.0

package/index.d.mts

@@ -382,490 +382,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 +710,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 };