@asaidimu/utils-artifacts 8.2.11 → 8.2.12

package/index.d.mts

@@ -1,842 +0,0 @@
-interface SubscribeOptions {
-    /**
-     * Debounce delay in milliseconds. When multiple events arrive in quick
-     * succession, the callback runs only after the quiet period ends, using the
-     * latest payload. Default = no debouncing.
-     */
-    debounce?: number;
-}
-
-/**
- * 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, 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 | symbol;
-/**
- * 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 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:
- * 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 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;
-    error?: Error;
-}> | boolean | {
-    block: boolean;
-    error?: Error;
-};
-/**
- * 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 ActionWatcher {
-    /** Unique identifier for the action */
-    name: string;
-    /** Function to get the current computed value of the action. */
-    status: () => boolean;
-    /**
-     * Subscribes a callback function to run whenever the action's status changes.
-     * Returns an unsubscribe function.
-     */
-    subscribe: (callback: () => void) => () => void;
-}
-interface TransactionOptions {
-    /** If true, blocks resolution until changes are fully committed to the database row */
-    flush?: boolean;
-}
-/**
- * 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;
-    /**
-     * Gets a subset of the store.
-     * @param paths The paths which to include in the returned object.
-     * @param separator Optional separator for paths. Defaults to `.` .
-     * @returns An object of the shape K mapping paths to their current values.
-     */
-    subset<K extends Record<string, any> = Record<string, any>>(paths: Array<string>, separator?: string): K;
-    /**
-     * 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>>;
-        debounce?: {
-            delay: number;
-            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<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>;
-    /**
-     * 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).
-     * @param options Extra options to pass to the event bus
-     * @returns An unsubscribe function.
-     */
-    watch(path: string | Array<string>, callback: (state: T) => void, options?: SubscribeOptions): () => void;
-    /**
-     * Subscribes to execution‑status changes of a registered action.
-     *
-     * The provided callback is called **every time** the action transitions
-     * between idle and running (i.e. on `action:start`, `action:complete`, or
-     * `action:error` for the given name). The current status can also be read
-     * synchronously with `isActionRunning(name)`.
-     *
-     * **Deferred listener teardown**
-     * To avoid unnecessary churn when subscriptions are rapidly created and
-     * destroyed, the underlying event listeners are not removed immediately
-     * on unsubscribe. Instead, a *pending reset* is queued via `queueMicrotask`.
-     * If a new subscription for the same action arrives before that microtask
-     * executes, the reset is silently cancelled and the already‑established
-     * listeners are reused. This keeps the subscription infrastructure stable
-     * and prevents cascading notifications that could otherwise arise from
-     * repeated subscribe‑unsubscribe‑subscribe cycles.
-     *
-     * @param name - The name of the action to watch.
-     * @returns An ActionWatcher
-     */
-    watchAction(name: string): ActionWatcher;
-    /**
-     * 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>, options?: TransactionOptions): 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;
-    /**
-     * 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 promise that resolves once the store is fully initialised.
-     * Safe to call multiple times — all callers share the same latch.
-     *
-     * @param timeout - Optional maximum wait time in milliseconds.
-     * @throws {TimeoutError} If the store does not become ready within the timeout.
-     *
-     * @example
-     * await store.ready();
-     * const state = store.get();
-     */
-    ready(timeout?: number): Promise<void>;
-    /**
-     * Returns a readonly snapshot of the current execution state of the store.
-     */
-    state(): Readonly<StoreExecutionState<T>>;
-    /**
-     * Releases all resources held by the store and renders it unusable
-     */
-    dispose(): Promise<void>;
-}
-
-/**
- * Defines the lifecycle and sharing strategy for an artifact within the container.
- */
-
-/**
- * Defines the lifecycle and sharing strategy for an artifact.
- */
-type ArtifactScope = 
-/**
- * **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"
-/**
- * **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"
-}
-/**
- * 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 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 (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/rebuilt. */
-    buildCount: 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 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.
-     * @param params Parameters with which to resolve the artifact
-     * @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, params?: any): Promise<ResolvedArtifact<TRegistry[K]>>;
-    /**
-     * 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.
-     * @param params Parameters with which to resolve the artifact
-     * @returns A Promise that resolves to a the resolved instance, unlike
-     * resolve, this will throw an error if resolution fails.
-     * @throws {SystemError} if any error occurs during resolution.
-     */
-    require<K extends keyof TRegistry>(key: K, params?: any): Promise<TRegistry[K]>;
-    /**
-     * 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 of state.
-     * @returns The selected slice of state.
-     */
-    select<S>(selector: (state: TState) => S, options?: SubscribeOptions): S;
-}
-/**
- * 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 (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 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 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;
-    }): Promise<any>;
-};
-/**
- * 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.
- */
-type ArtifactFactoryContext<TRegistry extends Record<string, any>, TState extends object, TArtifact, TExtra extends Record<string, any> = {}> = TExtra & {
-    /**
-     * 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.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
-     * after an invalidation. This is `undefined` on the initial build.
-     * Useful for diffing, migrating state, or reusing resources during an update.
-     */
-    previous?: 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.
-     * @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 **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, permanent resource release.
-     * @param callback The dispose function.
-     */
-    onDispose(callback: ArtifactCleanup): void;
-    /**
-     * Starts a streaming process for a Singleton artifact.
-     * The callback receives an `ArtifactStreamContext` to emit values and manage the
-     * stream's lifecycle. It can return a cleanup function (or a Promise resolving
-     * to one) to handle resource disposal.
-     * * @param callback - The streaming logic implementation. Can be synchronous or
-     * asynchronous, optionally returning a cleanup function.
-     * @throws {SystemError} If called on a Transient artifact, as they do not
-     * support persistent streaming states.
-     */
-    stream(callback: (ctx: ArtifactStreamContext<TState, TArtifact>) => (void | (() => void | Promise<void>)) | Promise<void | (() => void | Promise<void>)>): void;
-    stream(callback: (ctx: ArtifactStreamContext<TState, TArtifact>) => (void | (() => void | Promise<void>)) | Promise<void | (() => void | Promise<void>)>): void;
-    /**
-     * An AbortSignal that indicates if the artifacts has been unregistered
-     */
-    signal: AbortSignal;
-    /** For parameterized artifacts: the parameters that were passed during resolve/watch. */
-    params?: any;
-};
-/**
- * A function that performs cleanup or disposal logic for an artifact, potentially asynchronously.
- * Used for `onCleanup` and `onDispose` callbacks.
- */
-type ArtifactCleanup = () => void | Promise<void>;
-/**
- * Common properties shared across all possible states of a resolved artifact.
- * @template TArtifact The type of the resolved artifact instance.
- */
-interface ResolvedArtifactBase {
-    /**
-     * A function to manually trigger cleanup associated with this specific
-     * resolved instance. This is typically only relevant for Transient artifacts
-     * where the consumer is responsible for cleanup.
-     */
-    cleanup?: ArtifactCleanup;
-    /**
-     * Manually invalidates this artifact, triggering its rebuild and
-     * cascading invalidations to its dependents.
-     * @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, 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 whether the artifact is ready and has an instance. */
-    ready: true;
-    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 {
-    instance?: undefined;
-    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;
-    ready: false;
-    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;
-type KeyedResolvedArtifact<TRegistry, K extends keyof TRegistry> = ResolvedArtifact<TRegistry[K]> & {
-    [P in K]?: TRegistry[K];
-};
-/**
- * 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 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, TExtra extends Record<string, any> = {}> = (context: ArtifactFactoryContext<TRegistry, TState, TArtifact, TExtra>) => TArtifact | Promise<TArtifact>;
-type ArtifactInstance<R> = R extends PromiseLike<infer T> ? T : R;
-/**
- * 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.
- */
-interface ArtifactObserver<TRegistry, K extends keyof TRegistry> {
-    /** The unique identifier (key) of the artifact being watched. */
-    id: string;
-    /**
-     * 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.
-     * @param resolve Flag indicating whether we should resolve the artifact
-     * immediately. Defaults to `false`
-     * @returns The resolved artifact, including its instance and status.
-     */
-    get(resolve?: boolean): KeyedResolvedArtifact<TRegistry, K>;
-    /**
-     * Subscribes a callback function to be invoked whenever the artifact's
-     * state (instance, error, or readiness) changes.
-     * @param callback The function to call on updates. It receives the new `ResolvedArtifact`.
-     * @param eager a boolean indicating whether we should immediately call the
-     * callback after subscription. Defaults to `true`
-     * @returns A function to unsubscribe the callback and stop receiving updates.
-     */
-    subscribe(callback: (artifact: KeyedResolvedArtifact<TRegistry, K>) => void, eager?: boolean): () => void;
-    /**
-     * Resolves another artifact from the container and registers a dependency on it.
-     * If the dependency changes, the current artifact will be invalidated and rebuilt.
-     * @returns A Promise that resolves to a `ResolvedArtifact` containing the instance
-     * or an external error.
-     * @throws {SystemError} if resolution fails.
-     */
-    resolve(): Promise<KeyedResolvedArtifact<TRegistry, K>>;
-}
-/**
- * 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 Record<string, any> = Record<string, any>, TExtra extends Record<string, any> = {}> {
-    /** 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, TExtra>;
-    /**
-     * The scope of the artifact, determining its lifecycle and sharing strategy.
-     * Defaults to `ArtifactScopes.Singleton`.
-     */
-    scope?: ArtifactScope;
-    /**
-     * If `true` (default), the artifact's factory is executed only when the artifact
-     * is first requested (lazy instantiation). 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.
-     */
-    timeout?: number;
-    /**
-     * Number of times to retry the artifact's factory on failure due to an
-     * 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's dependencies. This delays the rebuild process to
-     * aggregate multiple rapid changes.
-     */
-    debounce?: number;
-    /** If defined, the artifact is parameterized. Receives the user‑supplied params and returns a unique string key. */
-    paramKey?: (params: Record<string, unknown>) => string;
-    virtual?: true;
-}
-/**
- * Extracts the global state type (`TState`) from an `ArtifactTemplate`.
- */
-type ArtifactStateType<T> = T extends ArtifactTemplate<infer TState, any, any> ? TState : never;
-/**
- * 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 type (`K`) from an `ArtifactTemplate` (as a string literal if possible).
- */
-type ArtifactKey<T> = T extends {
-    key: infer K;
-} ? K : never;
-/**
- * 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 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> = Record<string, any>> = {
-    [K in keyof TRegistry]: ArtifactTemplate<TState, TRegistry[K], TRegistry>;
-};
-/**
- * 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 contains a factory property.
- */
-type ArtifactValue<T> = T extends {
-    factory: ArtifactFactory<any, any, infer TArtifact, any>;
-} ? TArtifact : never;
-/**
- * Infers the complete Artifact Registry type from a map of artifact configuration objects.
- *
- * 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.
- */
-type InferRegistry<T extends Record<string, {
-    factory: (...args: any[]) => any;
-    [key: string]: any;
-}>> = {
-    [K in keyof T]: ArtifactValue<T[K]>;
-};
-/**
- * State paths grouped by options passed to the store
- */
-interface StateGroup {
-    paths: string[];
-    options?: SubscribeOptions;
-}
-interface ExportedArtifact {
-    key: string;
-    instance: any;
-    state: {
-        groups: Array<{
-            paths: string[];
-            options?: SubscribeOptions;
-        }>;
-        hash: string;
-    };
-    dependencies: string[];
-}
-interface ExportedContainerState {
-    version: string;
-    timestamp: number;
-    artifacts: ExportedArtifact[];
-    checksum: string;
-}
-
-/**
- * A dependency injection container for managing the lifecycle, dependencies,
- * and instances of "artifacts" (any JavaScript/TypeScript object or value).
- *
- * Separated concerns:
- * - ArtifactRegistry: Stores artifact templates (factories + options)
- * - ArtifactCache: Stores resolved singleton instances
- * - ArtifactDependencyGraph: Tracks artifact dependencies using DependencyGraph
- * - ArtifactManager: Handles lifecycle (build, invalidate, dispose)
- * - ArtifactObserverManager: Manages watchers and subscriptions
- *
- * @template TRegistry A type that maps artifact keys to their types
- * @template TState The type of the global state object
- */
-declare class ArtifactContainer<TRegistry extends Record<string, any> = Record<string, any>, TState extends object = any> {
-    private readonly registry;
-    private readonly cache;
-    private readonly graph;
-    private readonly manager;
-    private readonly observer;
-    private readonly store;
-    /**
-     * Creates a new ArtifactContainer instance.
-     * @param store An object providing functions to interact with a global data store
-     */
-    constructor(store: Pick<DataStore<TState>, "watch" | "get" | "set" | "subset">);
-    /**
-     * Provides debug information about all artifacts currently registered in this container.
-     *
-     * Status mapping:
-     * - `"building"` — factory is currently executing (buildOnce.running())
-     * - `"debouncing"` — invalidation is pending behind a debounce timer
-     * - `"error"` — last build attempt failed
-     * - `"active"` — successfully built and instance is available
-     * - `"idle"` — not yet built (lazy) or has been disposed
-     *
-     * @returns An array of ArtifactDebugNode objects
-     */
-    debugInfo(): 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.
-     *
-     * @param params The registration parameters
-     * @returns A cleanup function that unregisters the artifact
-     */
-    register<K extends keyof TRegistry>(params: ArtifactTemplate<TState, TRegistry[K], TRegistry>): () => void;
-    /**
-     * Returns a boolean indicating whether a template exists for an artifact.
-     *
-     * @param key The unique identifier of the artifact.
-     * @returns boolean.
-     */
-    has<K extends keyof TRegistry>(key: K): boolean;
-    /**
-     * Unregisters an artifact from the container, disposing of its current instance
-     * and removing all associated resources and dependency links.
-     *
-     * Also evicts the observer watcher cache entry so singleton watchers do not
-     * outlive the artifact's registration.
-     *
-     * @param key The unique identifier of the artifact
-     */
-    unregister<K extends keyof TRegistry>(key: K, params?: Record<string, unknown>): Promise<void>;
-    /**
-     * Resolves an artifact by its key, returning its instance or an error.
-     * Handles dependency resolution, cycle detection, caching, and retry logic.
-     *
-     * The keyed index property (`artifact[key]`) is set inside `cache.package()`
-     * so it is always consistent with `artifact.instance`. No post-hoc mutation
-     * is needed here.
-     *
-     * @param key The unique identifier for the artifact
-     * @param params Parameters with which to resolve the artifact
-     * @returns A Promise that resolves to a ResolvedArtifact
-     * @throws {ArtifactNotFoundError} if the artifact is not found
-     */
-    resolve<K extends keyof TRegistry>(key: K, params?: Record<string, unknown>): Promise<KeyedResolvedArtifact<TRegistry, K>>;
-    /**
-     * Resolves an artifact by its key, returning its instance directly.
-     * Throws if resolution fails.
-     *
-     * @param key The unique identifier for the artifact
-     * @param params Parameters with which to resolve the artifact
-     * @returns A Promise that resolves to the artifact instance
-     * @throws {ArtifactNotFoundError} if the artifact is not found
-     * @throws the artifact's error if resolution failed
-     */
-    require<K extends keyof TRegistry>(key: K, params?: Record<string, unknown>): Promise<TRegistry[K]>;
-    /**
-     * Returns an ArtifactObserver for a given artifact key.
-     * The observer allows subscribing to changes in the artifact's resolved value.
-     *
-     * @param key The unique identifier for the artifact
-     * @param params Parameters with which to resolve the artifact
-     * @param ttl Delay before the watcher is cleaned up if we have no subscriber
-     * @returns An ArtifactObserver instance
-     */
-    watch<K extends keyof TRegistry>(key: K, params?: Record<string, unknown>, ttl?: number): ArtifactObserver<TRegistry, K>;
-    /**
-     * Peeks at the resolved instance of an artifact without triggering resolution
-     * or registering a dependency.
-     *
-     * @param key The unique identifier for the artifact
-     * @returns The artifact instance if already built, otherwise undefined
-     */
-    peek<K extends keyof TRegistry>(key: K, params?: Record<string, unknown>): TRegistry[K] | undefined;
-    /**
-     * Invalidates an artifact, triggering rebuild and cascade to dependents.
-     *
-     * @param key The artifact key to invalidate
-     * @param options.replace If true, forces immediate rebuild bypassing debounce
-     * @param options.params for parametized artifacts
-     */
-    invalidate<K extends keyof TRegistry>(key: K, options?: {
-        replace?: boolean;
-        params?: Record<string, unknown>;
-    }): Promise<void>;
-    /**
-     * Notifies observers that an artifact has changed.
-     * Called by ArtifactManager during stream propagation.
-     *
-     * @param key The artifact key
-     */
-    notifyObservers(key: string): void;
-    /**
-     * Checks if an artifact has active watchers.
-     * Called by ArtifactManager to determine if lazy artifacts should rebuild.
-     *
-     * @param key The artifact key
-     * @returns True if the artifact has active watchers
-     */
-    hasWatchers(key: string): boolean;
-    /**
-     * Disposes of the entire container and all artifacts registered within it.
-     * Releases all resources, stops all watchers, and clears all internal state.
-     *
-     * Returns a Promise that resolves once all artifact teardowns have settled.
-     * Callers should await this method to guarantee full resource release.
-     */
-    dispose(): Promise<void>;
-    export(): Promise<ExportedContainerState>;
-    private restore;
-    static from<TRegistry extends Record<string, any> = Record<string, any>, TState extends object = any>(options: {
-        store: Pick<DataStore<TState>, "watch" | "get" | "set" | "subset">;
-        bundle?: ExportedContainerState;
-        templates: ArtifactTemplate<TState, any, TRegistry>[];
-    }): Promise<ArtifactContainer<TRegistry, TState>>;
-}
-
-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 ExportedArtifact, type ExportedContainerState, type InferRegistry, type KeyedResolvedArtifact, type PendingArtifact, type ReadyArtifact, type ResolvedArtifact, type ResolvedArtifactBase, type StateGroup, type UseDependencyContext };