@asaidimu/utils-artifacts 1.0.0 → 2.0.0

package/index.d.mts

@@ -90,59 +90,6 @@ interface DataStore<T extends object> {
     state(): Readonly<StoreExecutionState<T>>;
 }
 
-/**
- * Represents all errors within the ArtifactContainer system, categorized
- * into "system" (internal structural), "external" (runtime failures),
- * or "cycle" (circular dependencies). This unified error class simplifies
- * error handling and provides clear semantics.
- */
-declare class ArtifactError extends Error {
-    category: "system" | "external";
-    constructor(message: string, category: "system" | "external", cause?: unknown);
-}
-/**
- * Error thrown when a circular dependency is detected during artifact resolution.
- * This indicates a structural problem in the artifact graph.
- */
-declare class CircularDependencyError extends ArtifactError {
-    /**
-     * 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 ArtifactError {
-    /**
-     * 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 ArtifactError {
-    /**
-     * Creates an instance of IllegalScopeError.
-     * @param message A descriptive message about the illegal operation.
-     */
-    constructor(message: string);
-}
-/**
- * Error returned when all a watched instance is disposed
- */
-declare class WatcherDisposedError extends ArtifactError {
-    /**
-     * Creates an instance of IllegalScopeError.
-     * @param message A descriptive message about the illegal operation.
-     */
-    constructor(key: string);
-}
 /**
  * Defines the lifecycle and sharing strategy for an artifact.
  */
@@ -161,50 +108,6 @@ declare enum ArtifactScopes {
     Singleton = "singleton",
     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 `ArtifactScopes.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.
@@ -259,6 +162,11 @@ interface UseDependencyContext<TRegistry extends Record<string, any>, TState ext
      */
     select<S>(selector: (state: TState) => S): S;
 }
+type ArtifactStreamContext<TArtifact> = {
+    value: TArtifact | undefined;
+    signal: AbortSignal;
+    emit: (value: TArtifact) => Promise<void>;
+};
 /**
  * The full context provided to an artifact's factory function.
  * This context allows the artifact to interact with the container,
@@ -289,7 +197,7 @@ interface ArtifactFactoryContext<TRegistry extends Record<string, any>, TState e
      * @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>;
+    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
@@ -313,7 +221,7 @@ interface ArtifactFactoryContext<TRegistry extends Record<string, any>, TState e
      * @throws {SystemError} if called on a Transient artifact, as Transient artifacts
      *         do not maintain a persistent value.
      */
-    yield(value: TArtifact): void;
+    stream(callback: (ctx: ArtifactStreamContext<TArtifact>) => void | Promise<void>): void;
 }
 /**
  * A function that performs cleanup logic for an artifact, potentially asynchronously.
@@ -363,7 +271,7 @@ type ArtifactFactory<TRegistry extends Record<string, any>, TState extends objec
  * 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> {
+interface ArtifactObserver<TArtifact> {
     /** The unique identifier (key) of the artifact being watched. */
     id: string;
     /**
@@ -382,7 +290,7 @@ interface ArtifactWatcher<TArtifact> {
      * @param callback The function to call on updates.
      * @returns A function to unsubscribe the callback.
      */
-    subscribe(callback: () => void): () => void;
+    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.
@@ -396,218 +304,155 @@ interface ArtifactWatcher<TArtifact> {
  * depends on another or is depended upon by another, potentially across
  * different `ArtifactContainer` instances (e.g., parent/child containers).
  */
-interface DependencyLink {
+interface DependencyLink<T> {
     /** The key of the artifact involved in the dependency. */
     key: string;
     /** The `ArtifactContainer` instance that owns the linked artifact. */
-    container: ArtifactContainer<any, any>;
+    container: T;
+}
+
+/**
+ * Configuration options for defining an artifact. These options control
+ * its lifecycle, instantiation, and error handling behavior.
+ */
+interface ArtifactTemplate<TRegistry extends Record<string, any>, TState extends object, K extends keyof TRegistry> {
+    /** The unique key identifying this artifact. */
+    key: K;
+    /** The factory function responsible for creating the artifact's instance. */
+    factory: ArtifactFactory<TRegistry, TState, K>;
+    /**
+     * 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. 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. 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;
 }
+
 /**
  * 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.
+ * Refactored to separate concerns:
+ * - ArtifactRegistry: Stores artifact templates (factories + options)
+ * - ArtifactCache: Stores resolved singleton instances
+ * - ArtifactDependencyGraph: Tracks artifact dependencies using DependencyGraph
+ * - ArtifactManager: Handles lifecycle (build, invalidate, dispose)
+ * - ArtifactObserver: 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 artifacts;
-    private readonly resolvingStack;
-    private readonly listeners;
-    private readonly watcherCache;
-    private readonly props;
-    private readonly parent?;
-    private isDisposed;
-    private resolvedArtifacts;
+    private readonly registry;
+    private readonly cache;
+    private readonly graph;
+    private readonly manager;
+    private readonly observer;
+    private readonly store;
     /**
      * 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(store: 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.
+     *
+     * @param store An object providing functions to interact with a global data store
      */
-    createChild(): ArtifactContainer<TRegistry, TState>;
+    constructor(store: Pick<DataStore<TState>, "watch" | "get">);
     /**
      * 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.
+     *
+     * @returns An array of ArtifactDebugNode objects
      */
-    getDebugInfo(): ArtifactDebugNode[];
+    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.
-     * @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;
+     *
+     * @param params The registration parameters
+     * @returns A cleanup function that unregisters the artifact
+     */
+    register<K extends keyof TRegistry>(params: ArtifactTemplate<TRegistry, TState, K>): () => 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.
+     *
+     * @param key The unique identifier of the artifact
      */
     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
+     * This method handles dependency resolution, cycle detection (via graph),
+     * caching, and retry logic. 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.
+     *
+     * @param key The unique identifier for the artifact
+     * @returns A Promise that resolves to a ResolvedArtifact
+     * @throws {ArtifactNotFoundError} if the artifact is not found
+     * @throws {ArtifactError} if a cycle is detected or other system errors occur
      */
     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
-     * @template K The key of the artifact to watch.
-     * @param key The unique identifier for the artifact.
-     * @returns An `ArtifactWatcher` instance.
+     * Returns an ArtifactWatcher for a given artifact key.
+     * The watcher allows subscribing to changes in the artifact's resolved value.
+     *
+     * @param key The unique identifier for the artifact
+     * @returns An ArtifactWatcher instance
      */
-    watch<K extends keyof TRegistry>(key: K): ArtifactWatcher<TRegistry[K]>;
+    watch<K extends keyof TRegistry>(key: K): ArtifactObserver<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`.
+     * if it's lazy, or registering a dependency.
+     *
+     * @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.
+    /**
+     * Invalidates an artifact, triggering rebuild and cascade to dependents.
+     *
+     * @param key The artifact key to invalidate
+     * @param replace If true, forces immediate rebuild bypassing debounce
+     */
+    invalidate<K extends keyof TRegistry>(key: K, replace?: boolean): 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 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;
 }
 
-export { type ArtifactCleanup, ArtifactContainer, type ArtifactDebugNode, ArtifactError, type ArtifactFactory, type ArtifactFactoryContext, ArtifactNotFoundError, type ArtifactOptions, type ArtifactScope, ArtifactScopes, type ArtifactWatcher, CircularDependencyError, type DependencyLink, IllegalScopeError, type ResolvedArtifact, type UseDependencyContext, type UseOptions, WatcherDisposedError };
+export { type ArtifactCleanup, ArtifactContainer, type ArtifactDebugNode, type ArtifactFactory, type ArtifactFactoryContext, type ArtifactObserver, type ArtifactScope, ArtifactScopes, type ArtifactStreamContext, type DependencyLink, type ResolvedArtifact, type UseDependencyContext };