@asaidimu/utils-artifacts 8.0.0 → 8.1.0

package/README.md

@@ -14,23 +14,23 @@ The `@asaidimu/utils-artifacts` library empowers developers to build highly orga
 
 ## 🚀 Quick Links
 
--   [Overview & Features](#-overview--features)
--   [Why Use This Library? (Power & Use Cases)](#-why-use-this-library-power--use-cases)
--   [Installation & Setup](#-installation--setup)
--   [Usage Documentation](#-usage-documentation)
-    -   [Basic Usage](#basic-usage)
-    -   [Registering Artifacts](#registering-artifacts)
-    -   [Resolving & Requiring Artifacts](#resolving--requiring-artifacts)
-    -   [Watching Artifact Changes](#watching-artifact-changes)
-    -   [Reactive Dependencies (State Selection)](#reactive-dependencies-state-selection)
-    -   [Artifact Lifecycle (Cleanup & Dispose)](#artifact-lifecycle-cleanup--dispose)
-    -   [Streaming Artifacts](#streaming-artifacts)
-    -   [Invalidating Artifacts](#invalidating-artifacts)
-    -   [Debugging Artifacts](#debugging-artifacts)
--   [Project Architecture](#-project-architecture)
--   [Considerations & Potential Pitfalls](#-considerations--potential-pitfalls)
--   [Development & Contributing](#-development--contributing)
--   [Additional Information](#-additional-information)
+- [Overview & Features](#-overview--features)
+- [Why Use This Library? (Power & Use Cases)](#-why-use-this-library-power--use-cases)
+- [Installation & Setup](#-installation--setup)
+- [Usage Documentation](#-usage-documentation)
+  - [Basic Usage](#basic-usage)
+  - [Registering Artifacts](#registering-artifacts)
+  - [Resolving & Requiring Artifacts](#resolving--requiring-artifacts)
+  - [Watching Artifact Changes](#watching-artifact-changes)
+  - [Reactive Dependencies (State Selection)](#reactive-dependencies-state-selection)
+  - [Artifact Lifecycle (Cleanup & Dispose)](#artifact-lifecycle-cleanup--dispose)
+  - [Streaming Artifacts](#streaming-artifacts)
+  - [Invalidating Artifacts](#invalidating-artifacts)
+  - [Debugging Artifacts](#debugging-artifacts)
+- [Project Architecture](#-project-architecture)
+- [Considerations & Potential Pitfalls](#-considerations--potential-pitfalls)
+- [Development & Contributing](#-development--contributing)
+- [Additional Information](#-additional-information)
 
 ---
 
@@ -40,16 +40,16 @@ The `@asaidimu/utils-artifacts` library empowers developers to build highly orga
 
 ### Key Features
 
-*   **Declarative Dependency Injection (DI)**: Define artifact dependencies implicitly through factory context methods (`ctx.use`, `ctx.resolve`, `ctx.require`).
-*   **Reactive State Management**: Automatically re-evaluate artifacts when slices of a global `DataStore` change via `ctx.select`, enabling highly reactive applications.
-*   **Flexible Scoping**: Supports `Singleton` (single, cached instance) and `Transient` (new instance per resolution) artifact scopes.
-*   **Advanced Lifecycle Management**: `onCleanup` for instance-specific resource release and `onDispose` for permanent artifact teardown.
-*   **Streaming Artifacts**: Use `ctx.stream` to build long-lived artifacts that continuously emit new values, ideal for real-time data, web sockets, or periodic tasks.
-*   **Robust Error Handling & Retries**: Integrated retry logic for resilient operations and a comprehensive `ArtifactError` hierarchy for clear diagnostics.
-*   **Concurrency Primitives**: Internal utilities for managing race conditions and sequential execution of async operations.
-*   **Debuggability**: `container.debugInfo()` provides a snapshot of the artifact graph, statuses, and dependencies for easy troubleshooting.
-*   **Watcher API**: `container.watch()` allows external consumers to subscribe to artifact changes without directly resolving them.
-*   **Circular Dependency Detection**: Prevents infinite loops during resolution by detecting and reporting cycles in the dependency graph.
+- **Declarative Dependency Injection (DI)**: Define artifact dependencies implicitly through factory context methods (`ctx.use`, `ctx.resolve`, `ctx.require`).
+- **Reactive State Management**: Automatically re-evaluate artifacts when slices of a global `DataStore` change via `ctx.select`, enabling highly reactive applications.
+- **Flexible Scoping**: Supports `Singleton` (single, cached instance) and `Transient` (new instance per resolution) artifact scopes.
+- **Advanced Lifecycle Management**: `onCleanup` for instance-specific resource release and `onDispose` for permanent artifact teardown.
+- **Streaming Artifacts**: Use `ctx.stream` to build long-lived artifacts that continuously emit new values, ideal for real-time data, web sockets, or periodic tasks.
+- **Robust Error Handling & Retries**: Integrated retry logic for resilient operations and a comprehensive `ArtifactError` hierarchy for clear diagnostics.
+- **Concurrency Primitives**: Internal utilities for managing race conditions and sequential execution of async operations.
+- **Debuggability**: `container.debugInfo()` provides a snapshot of the artifact graph, statuses, and dependencies for easy troubleshooting.
+- **Watcher API**: `container.watch()` allows external consumers to subscribe to artifact changes without directly resolving them.
+- **Circular Dependency Detection**: Prevents infinite loops during resolution by detecting and reporting cycles in the dependency graph.
 
 ---
 
@@ -59,18 +59,18 @@ The `@asaidimu/utils-artifacts` library is designed to tackle the complexities o
 
 ### Core Power
 
-*   **Automatic Reactivity**: Effortlessly build applications where components automatically update when underlying data or services change. This dramatically simplifies state synchronization and UI updates.
-*   **Sophisticated Dependency Management**: Declaring dependencies is natural and integrated. The library handles complex resolution graphs, including cycles, and ensures dependencies are met before an artifact is built.
-*   **Lifecycle Control**: Fine-grained control over artifact lifecycles (`Singleton`, `Transient`) with explicit hooks for cleanup and disposal ensures proper resource management, preventing leaks.
-*   **Decoupled Architecture**: Promotes a clean separation of concerns, making code more modular, testable, and easier to maintain.
+- **Automatic Reactivity**: Effortlessly build applications where components automatically update when underlying data or services change. This dramatically simplifies state synchronization and UI updates.
+- **Sophisticated Dependency Management**: Declaring dependencies is natural and integrated. The library handles complex resolution graphs, including cycles, and ensures dependencies are met before an artifact is built.
+- **Lifecycle Control**: Fine-grained control over artifact lifecycles (`Singleton`, `Transient`) with explicit hooks for cleanup and disposal ensures proper resource management, preventing leaks.
+- **Decoupled Architecture**: Promotes a clean separation of concerns, making code more modular, testable, and easier to maintain.
 
 ### Key Use Cases
 
-*   **Complex Front-End Applications**: Ideal for managing intricate application state, services, and UI components in large-scale SPAs where reactivity and component lifecycles are paramount.
-*   **Microservice Orchestration**: Coordinating services that depend on each other, managing their initialization, and handling their inter-service communication dependencies.
-*   **Real-time Data Pipelines & Dashboards**: The streaming API (`ctx.stream`) is perfect for artifacts that continuously produce data, such as WebSocket clients, data feeders, or background processing agents.
-*   **Shared Resource Management**: Managing singleton instances of expensive resources like API clients, database connections, or global caches with predictable lifecycles.
-*   **Feature Toggling & Configuration**: Dynamically loading or updating configurations and feature flags that affect multiple parts of the application.
+- **Complex Front-End Applications**: Ideal for managing intricate application state, services, and UI components in large-scale SPAs where reactivity and component lifecycles are paramount.
+- **Microservice Orchestration**: Coordinating services that depend on each other, managing their initialization, and handling their inter-service communication dependencies.
+- **Real-time Data Pipelines & Dashboards**: The streaming API (`ctx.stream`) is perfect for artifacts that continuously produce data, such as WebSocket clients, data feeders, or background processing agents.
+- **Shared Resource Management**: Managing singleton instances of expensive resources like API clients, database connections, or global caches with predictable lifecycles.
+- **Feature Toggling & Configuration**: Dynamically loading or updating configurations and feature flags that affect multiple parts of the application.
 
 ---
 
@@ -78,9 +78,9 @@ The `@asaidimu/utils-artifacts` library is designed to tackle the complexities o
 
 ### Prerequisites
 
-*   Node.js (LTS recommended)
-*   npm or Yarn (package manager)
-*   A compatible reactive data store library (e.g., `@asaidimu/utils-store`) that adheres to the `DataStore` interface (providing `watch`, `get`, `set` methods).
+- Node.js (LTS recommended)
+- npm or Yarn (package manager)
+- A compatible reactive data store library (e.g., `@asaidimu/utils-store`) that adheres to the `DataStore` interface (providing `watch`, `get`, `set` methods).
 
 ### Installation Steps
 
@@ -101,26 +101,26 @@ yarn add @asaidimu/utils-artifacts
 You can verify the installation by attempting to import and register a basic artifact:
 
 ```typescript
-import { ArtifactContainer } from '@asaidimu/utils-artifacts';
-import { ReactiveDataStore } from '@asaidimu/utils-store'; // Assuming you have this store
+import { ArtifactContainer } from "@asaidimu/utils-artifacts";
+import { ReactiveDataStore } from "@asaidimu/utils-store"; // Assuming you have this store
 
 // Define your application's global state and artifact registry types
-type AppState = { count: number; };
-type AppRegistry = { myService: string; };
+type AppState = { count: number };
+type AppRegistry = { myService: string };
 
 const store = new ReactiveDataStore<AppState>({ count: 0 });
 const container = new ArtifactContainer<AppRegistry, AppState>(store);
 
 container.register({
-  key: 'myService',
+  key: "myService",
   factory: async ({ use }) => {
-    const currentCount = await use(({ select }) => select(s => s.count));
+    const currentCount = await use(({ select }) => select((s) => s.count));
     return `Service is running with count: ${currentCount}`;
   },
 });
 
 async function runExample() {
-  const service = await container.resolve('myService');
+  const service = await container.resolve("myService");
   console.log(service.instance); // Expected: Service is running with count: 0
 }
 
@@ -259,32 +259,38 @@ main();
 Use `container.register()` to define an artifact. Each artifact requires a unique `key` and a `factory` function.
 
 ```typescript
-import { ArtifactScopes, ArtifactTemplate } from '@asaidimu/utils-artifacts';
+import { ArtifactScopes, ArtifactTemplate } from "@asaidimu/utils-artifacts";
 
 // Define your app's state and registry types for better type safety
-interface MyAppState { /* ... */ }
-interface MyAppRegistry { myService: string; }
+interface MyAppState {
+  /* ... */
+}
+interface MyAppRegistry {
+  myService: string;
+}
 
 // Type assertion for the container
 const container = new ArtifactContainer<MyAppRegistry, MyAppState>(myStore);
 
 // Example of registering an artifact
-container.register<MyAppRegistry, MyAppState, 'myService'>({
-  key: 'myService',
+container.register<MyAppRegistry, MyAppState, "myService">({
+  key: "myService",
   factory: async (ctx) => {
     // Access dependencies using ctx.use()
-    const logger = await ctx.use(({ require }) => require('logger'));
-    const apiUrl = await ctx.use(({ select }) => select(state => state.config.apiUrl));
+    const logger = await ctx.use(({ require }) => require("logger"));
+    const apiUrl = await ctx.use(({ select }) =>
+      select((state) => state.config.apiUrl),
+    );
 
     logger.log(`Initializing myService with API URL: ${apiUrl}`);
     return `Initialized: ${apiUrl}`;
   },
   // Optional parameters:
   scope: ArtifactScopes.Singleton, // 'singleton' (default) or 'transient'
-  lazy: true,                      // For singletons: true (default) to build on first resolve, false to build on registration.
-  timeout: 5000,                   // Max time in ms for the factory to complete.
-  retries: 3,                      // Number of retries on factory failure (external errors only).
-  debounce: 100,                   // Delay in ms before rebuilding after dependency changes.
+  lazy: true, // For singletons: true (default) to build on first resolve, false to build on registration.
+  timeout: 5000, // Max time in ms for the factory to complete.
+  retries: 3, // Number of retries on factory failure (external errors only).
+  debounce: 100, // Delay in ms before rebuilding after dependency changes.
 });
 ```
 
@@ -329,26 +335,26 @@ interface UseDependencyContext<TRegistry, TState> {
 
 ### Resolving & Requiring Artifacts
 
-*   `container.resolve(key)`: Returns a `Promise<ResolvedArtifact<T>>`. This union type represents the artifact's state: `ReadyArtifact`, `ErrorArtifact`, or `PendingArtifact`. Check `.ready` and `.error` properties for robust handling.
-*   `container.require(key)`: Returns a `Promise<T>` directly. It throws an error if resolution fails. Use this when you expect success and prefer exception-based error handling.
+- `container.resolve(key)`: Returns a `Promise<ResolvedArtifact<T>>`. This union type represents the artifact's state: `ReadyArtifact`, `ErrorArtifact`, or `PendingArtifact`. Check `.ready` and `.error` properties for robust handling.
+- `container.require(key)`: Returns a `Promise<T>` directly. It throws an error if resolution fails. Use this when you expect success and prefer exception-based error handling.
 
 ```typescript
 // Using resolve for defensive programming
-const myServiceResult = await container.resolve('myService');
+const myServiceResult = await container.resolve("myService");
 if (myServiceResult.ready) {
-  console.log('Service instance:', myServiceResult.instance);
+  console.log("Service instance:", myServiceResult.instance);
 } else if (myServiceResult.error) {
-  console.error('Service failed:', myServiceResult.error);
+  console.error("Service failed:", myServiceResult.error);
 } else {
-  console.log('Service is pending or idle.');
+  console.log("Service is pending or idle.");
 }
 
 // Using require for direct access when errors are handled upstream
 try {
-  const myServiceInstance = await container.require('myService');
-  console.log('Service instance:', myServiceInstance);
+  const myServiceInstance = await container.require("myService");
+  console.log("Service instance:", myServiceInstance);
 } catch (error) {
-  console.error('Failed to get service:', error);
+  console.error("Failed to get service:", error);
 }
 ```
 
@@ -357,17 +363,17 @@ try {
 The `container.watch(key)` method returns an `ArtifactObserver`. This allows you to subscribe to artifact state changes without directly resolving them, ideal for UI updates.
 
 ```typescript
-const loggerWatcher = container.watch('logger');
+const loggerWatcher = container.watch("logger");
 
 const unsubscribe = loggerWatcher.subscribe((resolvedArtifact) => {
   if (resolvedArtifact.ready) {
-    console.log('Logger updated:', resolvedArtifact.instance);
+    console.log("Logger updated:", resolvedArtifact.instance);
   } else if (resolvedArtifact.error) {
-    console.error('Logger error:', resolvedArtifact.error);
+    console.error("Logger error:", resolvedArtifact.error);
   }
   // `get()` retrieves the current resolved artifact state without subscribing.
   const currentLogger = loggerWatcher.get();
-  console.log('Current logger:', currentLogger.instance);
+  console.log("Current logger:", currentLogger.instance);
 });
 
 // To stop listening for updates:
@@ -380,42 +386,54 @@ Artifacts can automatically react to changes in your application's global state
 
 ```typescript
 interface AppState {
-  user: { name: string; theme: 'light' | 'dark'; };
+  user: { name: string; theme: "light" | "dark" };
+}
+interface AppRegistry {
+  userGreeting: string;
 }
-interface AppRegistry { userGreeting: string; }
 
 // Assume appStore is an instance of DataStore<AppState>
 const container = new ArtifactContainer<AppRegistry, AppState>(appStore);
 
 container.register({
-  key: 'userGreeting',
+  key: "userGreeting",
   factory: async ({ use }) => {
     // This artifact will rebuild if appStore.user.theme changes.
-    const theme = await use(({ select }) => select(state => state.user.theme));
-    const userName = await use(({ select }) => select(state => state.user.name));
+    const theme = await use(({ select }) =>
+      select((state) => state.user.theme),
+    );
+    const userName = await use(({ select }) =>
+      select((state) => state.user.name),
+    );
     return `Hello, ${userName}! Your theme is ${theme}.`;
   },
 });
 
 // Example of state change triggering rebuild
-await appStore.set(state => ({ ...state, user: { ...state.user, theme: 'dark' } }));
-const greeting = await container.resolve('userGreeting');
+await appStore.set((state) => ({
+  ...state,
+  user: { ...state.user, theme: "dark" },
+}));
+const greeting = await container.resolve("userGreeting");
 console.log(greeting.instance); // Output will reflect the new theme.
 ```
 
 ### Artifact Lifecycle (Cleanup & Dispose)
 
-*   `ctx.onCleanup(fn)`: Registers a function to be executed *before* a singleton artifact's instance is replaced or before a transient artifact instance is discarded. Useful for releasing resources tied to the *current instance* (e.g., clearing timers, unsubscribing local event listeners).
-*   `ctx.onDispose(fn)`: Registers a function to be executed *only when the artifact is permanently unregistered* from the container or when the container itself is disposed. Use this for final resource cleanup (e.g., closing database connections).
+- `ctx.onCleanup(fn)`: Registers a function to be executed _before_ a singleton artifact's instance is replaced or before a transient artifact instance is discarded. Useful for releasing resources tied to the _current instance_ (e.g., clearing timers, unsubscribing local event listeners).
+- `ctx.onDispose(fn)`: Registers a function to be executed _only when the artifact is permanently unregistered_ from the container or when the container itself is disposed. Use this for final resource cleanup (e.g., closing database connections).
 
 ```typescript
 container.register({
-  key: 'resourceArtifact',
+  key: "resourceArtifact",
   scope: ArtifactScopes.Singleton,
   factory: ({ onCleanup, onDispose, use }) => {
     const resourceId = Math.random();
     console.log(`Resource ${resourceId} created.`);
-    const timerId = setInterval(() => console.log(`Resource ${resourceId} heartbeat...`), 1000);
+    const timerId = setInterval(
+      () => console.log(`Resource ${resourceId} heartbeat...`),
+      1000,
+    );
 
     // Cleanup for the current instance (e.g., on rebuild or if transient)
     onCleanup(() => {
@@ -425,7 +443,9 @@ container.register({
 
     // Dispose for permanent removal from container
     onDispose(() => {
-      console.log(`Disposing artifact 'resourceArtifact' (resource ${resourceId}).`);
+      console.log(
+        `Disposing artifact 'resourceArtifact' (resource ${resourceId}).`,
+      );
       // Final resource release
     });
 
@@ -434,16 +454,16 @@ container.register({
 });
 
 async function lifecycleExample() {
-  await container.resolve('resourceArtifact'); // Instance created and logs "heartbeat..."
-  console.log('Artifact resolved.');
+  await container.resolve("resourceArtifact"); // Instance created and logs "heartbeat..."
+  console.log("Artifact resolved.");
 
   // Simulate invalidation: will trigger onCleanup for the current instance, then rebuild.
-  await container.invalidate('resourceArtifact');
-  console.log('Artifact invalidated and rebuilt.');
+  await container.invalidate("resourceArtifact");
+  console.log("Artifact invalidated and rebuilt.");
 
   // Manually dispose the artifact and container
-  await container.unregister('resourceArtifact'); // Triggers onDispose
-  console.log('Artifact unregistered.');
+  await container.unregister("resourceArtifact"); // Triggers onDispose
+  console.log("Artifact unregistered.");
 }
 lifecycleExample();
 ```
@@ -454,20 +474,20 @@ For artifacts that continuously emit values (e.g., real-time data, streams), use
 
 ```typescript
 container.register({
-  key: 'dataStream',
+  key: "dataStream",
   scope: ArtifactScopes.Singleton,
   factory: ({ stream, onCleanup, use }) => {
     let counter = 0;
     let intervalId: ReturnType<typeof setInterval> | undefined;
 
     stream(async ({ emit, signal, value }) => {
-      console.log('Data stream started...');
-      const logger = await use(({ require }) => require('logger')); // Example dependency
-      logger.log('Stream active. Emitting values.');
+      console.log("Data stream started...");
+      const logger = await use(({ require }) => require("logger")); // Example dependency
+      logger.log("Stream active. Emitting values.");
 
       intervalId = setInterval(() => {
         if (signal.aborted) {
-          console.log('Stream signal aborted. Clearing interval.');
+          console.log("Stream signal aborted. Clearing interval.");
           clearInterval(intervalId);
           return;
         }
@@ -476,7 +496,7 @@ container.register({
         console.log(`Emitting: ${newValue}`);
         emit(newValue); // Emit the new value to the container
         if (counter >= 5) {
-          console.log('Stream reached limit, stopping.');
+          console.log("Stream reached limit, stopping.");
           clearInterval(intervalId);
           // The factory function can return to stop the stream producer.
         }
@@ -484,25 +504,25 @@ container.register({
     });
 
     onCleanup(() => {
-      console.log('Cleaning up data stream instance...');
+      console.log("Cleaning up data stream instance...");
       // Ensure interval is cleared if stream is aborted or rebuilt.
       if (intervalId) clearInterval(intervalId);
     });
 
-    return 'Initial stream value'; // Initial value before first emission
+    return "Initial stream value"; // Initial value before first emission
   },
 });
 
 async function streamExample() {
-  const watcher = container.watch('dataStream');
+  const watcher = container.watch("dataStream");
   const unsubscribe = watcher.subscribe((art) => {
-    if (art.ready) console.log('Stream received:', art.instance);
+    if (art.ready) console.log("Stream received:", art.instance);
   });
 
   // Keep alive for a few seconds to observe stream emissions
-  await new Promise(res => setTimeout(res, 3000));
+  await new Promise((res) => setTimeout(res, 3000));
   unsubscribe();
-  console.log('Stream watcher unsubscribed.');
+  console.log("Stream watcher unsubscribed.");
 }
 streamExample();
 ```
@@ -513,10 +533,10 @@ Manually trigger an artifact to rebuild and cascade invalidations to its depende
 
 ```typescript
 // Invalidate an artifact; it will rebuild if it has dependents, is lazy and watched, or eagerly.
-await container.invalidate('myArtifact');
+await container.invalidate("myArtifact");
 
 // Force immediate rebuild, bypassing any debounce delay.
-await container.invalidate('myArtifact', true);
+await container.invalidate("myArtifact", true);
 ```
 
 ### Debugging Artifacts
@@ -525,14 +545,18 @@ The `container.debugInfo()` method provides a snapshot of the container's intern
 
 ```typescript
 const debugNodes = container.debugInfo();
-debugNodes.forEach(node => {
+debugNodes.forEach((node) => {
   console.log(`
 Artifact ID: ${node.id}`);
   console.log(`  Scope: ${node.scope}`);
   console.log(`  Status: ${node.status}`); // e.g., 'active', 'error', 'idle', 'building', 'pending', 'debouncing'
-  console.log(`  Dependencies (Artifacts): ${node.dependencies.join(', ') || 'None'}`);
-  console.log(`  Dependencies (State Paths): ${node.stateDependencies.join(', ') || 'None'}`);
-  console.log(`  Dependents: ${node.dependents.join(', ') || 'None'}`);
+  console.log(
+    `  Dependencies (Artifacts): ${node.dependencies.join(", ") || "None"}`,
+  );
+  console.log(
+    `  Dependencies (State Paths): ${node.stateDependencies.join(", ") || "None"}`,
+  );
+  console.log(`  Dependents: ${node.dependents.join(", ") || "None"}`);
   console.log(`  Build Count: ${node.buildCount}`);
 });
 ```
@@ -543,41 +567,41 @@ Artifact ID: ${node.id}`);
 
 The `@asaidimu/utils-artifacts` library is architected around a central `ArtifactContainer` that orchestrates several specialized internal components:
 
-*   **`ArtifactContainer`**: The main public API. It aggregates and coordinates the other components, providing methods for registering, resolving, watching, invalidating, and disposing artifacts.
-*   **`ArtifactRegistry`**: Stores the definitions (`ArtifactTemplate`s) for all artifacts. It maps artifact keys to their factories and configuration options.
-*   **`ArtifactCache`**: Manages the lifecycle and instances of resolved artifacts. It stores singleton instances, tracks artifact versions, and caches results.
-*   **`ArtifactDependencyGraph`**: Maintains the relationships between artifacts and their dependencies on global state paths. This graph is critical for detecting circular dependencies and for efficiently cascading invalidations.
-*   **`ArtifactManager`**: The core engine responsible for artifact lifecycle management. It handles artifact building (executing factories), managing retries, timeouts, stream propagation, and the reactive invalidation process. It utilizes the other components for dependency resolution and state observation.
-*   **`ArtifactObserverManager`**: Implements the `container.watch()` API. It manages subscriptions from external consumers, notifies them of artifact state changes, and tracks active watchers to manage lazy loading and resource cleanup.
+- **`ArtifactContainer`**: The main public API. It aggregates and coordinates the other components, providing methods for registering, resolving, watching, invalidating, and disposing artifacts.
+- **`ArtifactRegistry`**: Stores the definitions (`ArtifactTemplate`s) for all artifacts. It maps artifact keys to their factories and configuration options.
+- **`ArtifactCache`**: Manages the lifecycle and instances of resolved artifacts. It stores singleton instances, tracks artifact versions, and caches results.
+- **`ArtifactDependencyGraph`**: Maintains the relationships between artifacts and their dependencies on global state paths. This graph is critical for detecting circular dependencies and for efficiently cascading invalidations.
+- **`ArtifactManager`**: The core engine responsible for artifact lifecycle management. It handles artifact building (executing factories), managing retries, timeouts, stream propagation, and the reactive invalidation process. It utilizes the other components for dependency resolution and state observation.
+- **`ArtifactObserverManager`**: Implements the `container.watch()` API. It manages subscriptions from external consumers, notifies them of artifact state changes, and tracks active watchers to manage lazy loading and resource cleanup.
 
 ### Data Flow Example (Resolution & Reactivity)
 
 1.  **Registration**: An artifact (`key`, `factory`, `scope`, etc.) is registered with the `ArtifactRegistry`. The `ArtifactDependencyGraph` registers a node for this artifact.
 2.  **Resolution (`container.resolve`)**:
-    *   The `ArtifactContainer` delegates to `ArtifactManager`.
-    *   The `Manager` checks the `ArtifactCache`. If a `Singleton` is already built and valid, its instance is returned.
-    *   If not cached or if an invalidation occurred, the `Manager` retrieves the artifact's `ArtifactTemplate` from the `Registry`.
-    *   The `Manager` prepares the `ArtifactFactoryContext` and executes the artifact's `factory` function.
-    *   **Dependency Declaration**:
-        *   Inside the factory, `ctx.use(({ resolve/require }) => ...)` calls recursively trigger artifact resolution, updating the `ArtifactDependencyGraph`.
-        *   `ctx.use(({ select }) => ...)` registers state path dependencies. The `Manager` sets up listeners on the `DataStore` for these paths.
-    *   **Build Execution**: The `Manager` handles potential retries, timeouts, and cleanup logic.
-    *   **Cache Update**: Upon successful build, the instance is stored in the `ArtifactCache`. The `ArtifactDependencyGraph` is updated with the artifact's declared dependencies.
+    - The `ArtifactContainer` delegates to `ArtifactManager`.
+    - The `Manager` checks the `ArtifactCache`. If a `Singleton` is already built and valid, its instance is returned.
+    - If not cached or if an invalidation occurred, the `Manager` retrieves the artifact's `ArtifactTemplate` from the `Registry`.
+    - The `Manager` prepares the `ArtifactFactoryContext` and executes the artifact's `factory` function.
+    - **Dependency Declaration**:
+      - Inside the factory, `ctx.use(({ resolve/require }) => ...)` calls recursively trigger artifact resolution, updating the `ArtifactDependencyGraph`.
+      - `ctx.use(({ select }) => ...)` registers state path dependencies. The `Manager` sets up listeners on the `DataStore` for these paths.
+    - **Build Execution**: The `Manager` handles potential retries, timeouts, and cleanup logic.
+    - **Cache Update**: Upon successful build, the instance is stored in the `ArtifactCache`. The `ArtifactDependencyGraph` is updated with the artifact's declared dependencies.
 3.  **Reactivity & Invalidation**:
-    *   If a `DataStore` path watched by an artifact changes, the `Manager` is notified.
-    *   The `Manager` identifies artifacts dependent on that path using the `ArtifactDependencyGraph`.
-    *   These dependent artifacts are marked as invalid. If they are `Singleton`s, their `onCleanup` hooks are called, and they are scheduled for rebuild (potentially with debouncing).
-    *   If a dependency artifact is rebuilt or invalidated, its dependents are similarly cascaded.
-    *   When an artifact rebuilds, its `factory` is executed again, re-evaluating its dependencies and state selections.
-    *   `ArtifactObserverManager` is notified of changes to update any watching consumers.
+    - If a `DataStore` path watched by an artifact changes, the `Manager` is notified.
+    - The `Manager` identifies artifacts dependent on that path using the `ArtifactDependencyGraph`.
+    - These dependent artifacts are marked as invalid. If they are `Singleton`s, their `onCleanup` hooks are called, and they are scheduled for rebuild (potentially with debouncing).
+    - If a dependency artifact is rebuilt or invalidated, its dependents are similarly cascaded.
+    - When an artifact rebuilds, its `factory` is executed again, re-evaluating its dependencies and state selections.
+    - `ArtifactObserverManager` is notified of changes to update any watching consumers.
 
 ### Core Concepts
 
-*   **Artifact**: A unit of work or data within the application, defined by a `key` and a `factory` function.
-*   **Scope**: Determines the lifecycle: `Singleton` (one instance) or `Transient` (new instance per resolution).
-*   **Factory**: A function that creates an artifact's instance, declaring its dependencies and side effects.
-*   **Dependencies**: Artifacts can depend on other artifacts (`resolve`/`require`) or state slices (`select`).
-*   **Reactivity**: Artifacts automatically update when their declared dependencies change.
+- **Artifact**: A unit of work or data within the application, defined by a `key` and a `factory` function.
+- **Scope**: Determines the lifecycle: `Singleton` (one instance) or `Transient` (new instance per resolution).
+- **Factory**: A function that creates an artifact's instance, declaring its dependencies and side effects.
+- **Dependencies**: Artifacts can depend on other artifacts (`resolve`/`require`) or state slices (`select`).
+- **Reactivity**: Artifacts automatically update when their declared dependencies change.
 
 ---
 
@@ -587,36 +611,36 @@ While `@asaidimu/utils-artifacts` offers powerful features, understanding its op
 
 ### Debouncing Latency
 
-*   **Issue**: The `debounce` option allows delaying artifact rebuilds after dependency changes to aggregate rapid updates. However, overly large debounce values or frequent invalidation cascades can introduce noticeable latency in reflecting updates, especially in UI-critical paths.
-*   **Recommendation**: Carefully tune `debounce` values. Consider the trade-off between reducing update churn and responsiveness. For high-frequency updates, explore streaming or alternative reactivity patterns if latency becomes an issue.
+- **Issue**: The `debounce` option allows delaying artifact rebuilds after dependency changes to aggregate rapid updates. However, overly large debounce values or frequent invalidation cascades can introduce noticeable latency in reflecting updates, especially in UI-critical paths.
+- **Recommendation**: Carefully tune `debounce` values. Consider the trade-off between reducing update churn and responsiveness. For high-frequency updates, explore streaming or alternative reactivity patterns if latency becomes an issue.
 
 ### Wasted Build Effort from Late Staleness Detection
 
-*   **Issue**: The library detects if dependencies have changed *after* an artifact's factory has already executed. This means significant computation might be discarded if a dependency was updated mid-build, leading to wasted effort.
-*   **Recommendation**: Optimize artifact factories to be as performant as possible. For critical, long-running builds, consider architecting them to check for dependency validity more proactively if feasible, or accept this as a trade-off for a simpler dependency tracking mechanism.
+- **Issue**: The library detects if dependencies have changed _after_ an artifact's factory has already executed. This means significant computation might be discarded if a dependency was updated mid-build, leading to wasted effort.
+- **Recommendation**: Optimize artifact factories to be as performant as possible. For critical, long-running builds, consider architecting them to check for dependency validity more proactively if feasible, or accept this as a trade-off for a simpler dependency tracking mechanism.
 
 ### Efficiency of Global State Watching
 
-*   **Observation**: The library's reactivity relies heavily on the underlying `DataStore`'s `watch` mechanism. Inefficient state selectors or overly broad subscriptions can lead to excessive artifact rebuilds and impact application performance.
-*   **Recommendation**:
-    *   Write granular and performant state selectors using `ctx.select()`.
-    *   Minimize the number of state paths an artifact subscribes to.
-    *   Ensure the `DataStore` implementation itself is optimized for change detection and notification.
+- **Observation**: The library's reactivity relies heavily on the underlying `DataStore`'s `watch` mechanism. Inefficient state selectors or overly broad subscriptions can lead to excessive artifact rebuilds and impact application performance.
+- **Recommendation**:
+  - Write granular and performant state selectors using `ctx.select()`.
+  - Minimize the number of state paths an artifact subscribes to.
+  - Ensure the `DataStore` implementation itself is optimized for change detection and notification.
 
 ### Startup Cost of Eager Loading
 
-*   **Issue**: Singletons registered with `lazy: false` are eagerly instantiated upon container setup. If many such artifacts are registered, this can lead to a substantial upfront cost during application startup, impacting initial load times.
-*   **Recommendation**: Favor `lazy: true` (the default for singletons) whenever possible. Only use eager loading for artifacts that are truly required immediately at startup or where their initialization cost is negligible.
+- **Issue**: Singletons registered with `lazy: false` are eagerly instantiated upon container setup. If many such artifacts are registered, this can lead to a substantial upfront cost during application startup, impacting initial load times.
+- **Recommendation**: Favor `lazy: true` (the default for singletons) whenever possible. Only use eager loading for artifacts that are truly required immediately at startup or where their initialization cost is negligible.
 
 ### Sequential Cleanup/Dispose Execution
 
-*   **Observation**: Cleanup and dispose functions are executed sequentially. If an artifact has many dependencies with complex or time-consuming teardown routines, this sequential execution can slow down the overall teardown process for an artifact or the entire container.
-*   **Recommendation**: For artifacts with numerous or computationally intensive cleanup tasks, evaluate if these tasks can be safely executed concurrently (e.g., using `Promise.all` within the cleanup/dispose logic) to improve teardown performance.
+- **Observation**: Cleanup and dispose functions are executed sequentially. If an artifact has many dependencies with complex or time-consuming teardown routines, this sequential execution can slow down the overall teardown process for an artifact or the entire container.
+- **Recommendation**: For artifacts with numerous or computationally intensive cleanup tasks, evaluate if these tasks can be safely executed concurrently (e.g., using `Promise.all` within the cleanup/dispose logic) to improve teardown performance.
 
 ### Dependency Graph Complexity
 
-*   **Observation**: While the dependency graph implementation is optimized, operations on extremely large graphs (hundreds or thousands of artifacts with complex interdependencies) can incur significant computational costs during resolution, invalidation, or cycle detection.
-*   **Recommendation**: For applications with exceptionally large artifact graphs, consider strategies for modularizing the container or pruning less critical dependencies if performance becomes a bottleneck.
+- **Observation**: While the dependency graph implementation is optimized, operations on extremely large graphs (hundreds or thousands of artifacts with complex interdependencies) can incur significant computational costs during resolution, invalidation, or cycle detection.
+- **Recommendation**: For applications with exceptionally large artifact graphs, consider strategies for modularizing the container or pruning less critical dependencies if performance becomes a bottleneck.
 
 ---
 
@@ -638,8 +662,8 @@ While `@asaidimu/utils-artifacts` offers powerful features, understanding its op
 
 ### Scripts
 
-*   `npm test`: Runs all tests once.
-*   `npm test:watch`: Runs tests in watch mode, rerunning on file changes.
+- `npm test`: Runs all tests once.
+- `npm test:watch`: Runs tests in watch mode, rerunning on file changes.
 
 ### Testing
 
@@ -659,26 +683,26 @@ The project uses `vitest` for testing. All new code should be accompanied by tes
 
 ### Troubleshooting
 
-*   **`ArtifactNotFoundError`**: You are trying to `resolve` or `watch` an artifact that hasn't been registered. Verify artifact keys and ensure registration order.
-*   **`CircularDependencyError`**: The dependency graph contains a loop. Check the error message's path and redesign dependencies to break the cycle. `container.debugInfo()` is helpful here.
-*   **`TimeoutError`**: An artifact factory took too long to execute. Increase the `timeout` option or optimize the factory function and its dependencies.
-*   **Unexpected Rebuilds/No Rebuilds**:
-    *   Inspect artifact status and dependencies using `container.debugInfo()`.
-    *   Ensure `ctx.select()` selectors correctly capture reactive state slices.
-    *   Review `debounce` settings if rebuilds are too frequent or delayed.
-    *   Verify `onCleanup`/`onDispose` hooks are correctly implemented.
+- **`ArtifactNotFoundError`**: You are trying to `resolve` or `watch` an artifact that hasn't been registered. Verify artifact keys and ensure registration order.
+- **`CircularDependencyError`**: The dependency graph contains a loop. Check the error message's path and redesign dependencies to break the cycle. `container.debugInfo()` is helpful here.
+- **`TimeoutError`**: An artifact factory took too long to execute. Increase the `timeout` option or optimize the factory function and its dependencies.
+- **Unexpected Rebuilds/No Rebuilds**:
+  - Inspect artifact status and dependencies using `container.debugInfo()`.
+  - Ensure `ctx.select()` selectors correctly capture reactive state slices.
+  - Review `debounce` settings if rebuilds are too frequent or delayed.
+  - Verify `onCleanup`/`onDispose` hooks are correctly implemented.
 
 ### FAQ
 
-*   **`Singleton` vs. `Transient` Scope**:
-    *   **`Singleton`**: Only one instance is ever created and shared across all resolutions. Ideal for services, configurations, or shared resources. Supports lifecycle hooks (`onCleanup`, `onDispose`) and streaming.
-    *   **`Transient`**: A new instance is created every time the artifact is resolved. Useful for ephemeral objects. Does not support streaming or persistent `onDispose`.
-*   **`resolve` vs. `require`**:
-    *   Use `resolve` for robust handling of artifact states (ready, error, pending) via the `ResolvedArtifact` object.
-    *   Use `require` when you expect immediate success and want errors to propagate as exceptions.
-*   **`onCleanup` vs. `onDispose`**:
-    *   `onCleanup`: Runs before an instance is replaced (Singleton rebuild) or discarded (Transient). Use for instance-specific resource cleanup.
-    *   `onDispose`: Runs only when the artifact is permanently removed from the container. Use for global resource cleanup.
+- **`Singleton` vs. `Transient` Scope**:
+  - **`Singleton`**: Only one instance is ever created and shared across all resolutions. Ideal for services, configurations, or shared resources. Supports lifecycle hooks (`onCleanup`, `onDispose`) and streaming.
+  - **`Transient`**: A new instance is created every time the artifact is resolved. Useful for ephemeral objects. Does not support streaming or persistent `onDispose`.
+- **`resolve` vs. `require`**:
+  - Use `resolve` for robust handling of artifact states (ready, error, pending) via the `ResolvedArtifact` object.
+  - Use `require` when you expect immediate success and want errors to propagate as exceptions.
+- **`onCleanup` vs. `onDispose`**:
+  - `onCleanup`: Runs before an instance is replaced (Singleton rebuild) or discarded (Transient). Use for instance-specific resource cleanup.
+  - `onDispose`: Runs only when the artifact is permanently removed from the container. Use for global resource cleanup.
 
 ---
 

package/index.d.mts

@@ -364,17 +364,17 @@ interface ArtifactFactoryContext<TRegistry extends Record<string, any>, TState e
      */
     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.
-    */
+     * 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;
-    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
      */

package/index.d.ts

@@ -364,17 +364,17 @@ interface ArtifactFactoryContext<TRegistry extends Record<string, any>, TState e
      */
     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.
-    */
+     * 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;
-    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
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@asaidimu/utils-artifacts",
-  "version": "8.0.0",
+  "version": "8.1.0",
   "description": "Reactive artifact container.",
   "main": "index.js",
   "module": "index.mjs",