@asaidimu/utils-artifacts 7.3.0 → 8.1.0

package/README.md

@@ -2,6 +2,10 @@
 
 A powerful TypeScript library for managing application components (artifacts) with dependency injection, reactive state updates, and robust lifecycle management. This library provides a flexible container to define, resolve, and orchestrate various parts of your application, each reacting dynamically to state changes and dependencies.
 
+## ✨ Unlocking Application Power with Reactive Artifacts
+
+The `@asaidimu/utils-artifacts` library empowers developers to build highly organized, maintainable, and performant applications by providing a sophisticated reactive dependency injection container. It excels at managing complex application states and component lifecycles, ensuring that your application's pieces stay synchronized and up-to-date with minimal manual effort. Its design focuses on **declarative dependency management** and **automatic reactivity**, allowing developers to concentrate on business logic rather than intricate synchronization and lifecycle plumbing.
+
 [![npm version](https://img.shields.io/npm/v/@asaidimu/utils-artifacts.svg?style=flat-square)](https://www.npmjs.com/package/@asaidimu/utils-artifacts)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
 [![Build Status](https://img.shields.io/github/actions/workflow/status/asaidimu/erp-utils/ci.yml?branch=main&style=flat-square)](https://github.com/asaidimu/erp-utils/actions/workflows/ci.yml)
@@ -10,23 +14,23 @@ A powerful TypeScript library for managing application components (artifacts) wi
 
 ## 🚀 Quick Links
 
--   [Overview & Features](#-overview--features)
--   [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)
-    -   [Retry Utility](#retry-utility)
-    -   [Concurrency Utilities (Once & Serializer)](#concurrency-utilities-once--serializer)
--   [Project Architecture](#-project-architecture)
--   [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)
 
 ---
 
@@ -36,16 +40,37 @@ A powerful TypeScript library for managing application components (artifacts) wi
 
 ### Key Features
 
-*   **Dependency Injection (DI)**: Declare dependencies within artifact factories using `ctx.use`, `ctx.resolve`, and `ctx.require`.
-*   **Reactive State Management**: Automatically re-evaluate artifacts when slices of a global `DataStore` (or any compatible state management system) change via `ctx.select`.
-*   **Flexible Scoping**: Supports `Singleton` (single, cached instance) and `Transient` (new instance per resolution) artifact scopes.
-*   **Advanced Lifecycle Management**: `onCleanup` for instance-specific cleanup and `onDispose` for permanent resource release.
-*   **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 (`Retry` utility) for resilient operations and a comprehensive `ArtifactError` hierarchy for clear diagnostics.
-*   **Concurrency Primitives**: Internal `Once` and `Serializer` 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 value 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.
+
+---
+
+## 🚀 Why Use This Library? (Power & Use Cases)
+
+The `@asaidimu/utils-artifacts` library is designed to tackle the complexities of modern application development by providing a robust, reactive, and well-structured approach to managing application components and their interdependencies.
+
+### 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.
+
+### 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.
 
 ---
 
@@ -53,9 +78,9 @@ A powerful TypeScript library for managing application components (artifacts) wi
 
 ### Prerequisites
 
-*   Node.js (LTS recommended)
-*   npm or Yarn (package manager)
-*   A reactive data store library that adheres to the `DataStore` interface (e.g., `@asaidimu/utils-store`).
+- 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
 
@@ -76,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
 }
 
@@ -112,7 +137,7 @@ The core of the library is the `ArtifactContainer`. You initialize it with a `Da
 
 ```typescript
 import { ArtifactContainer, ArtifactScopes } from '@asaidimu/utils-artifacts';
-import { ReactiveDataStore } from '@asaidimu/utils-store';
+import { ReactiveDataStore } from '@asaidimu/utils-store'; // Assuming this is your state store
 
 // 1. Define your application's global state and artifact registry types
 interface AppState {
@@ -131,7 +156,7 @@ interface AppRegistry {
   appInfo: string;
 }
 
-// Example DataStore (from @asaidimu/utils-store)
+// Example DataStore (from @asaidimu/utils-store or similar)
 const appStore = new ReactiveDataStore<AppState>({
   appName: 'My App',
   version: '1.0.0',
@@ -144,7 +169,7 @@ const appStore = new ReactiveDataStore<AppState>({
 // 2. Instantiate the ArtifactContainer
 const container = new ArtifactContainer<AppRegistry, AppState>(appStore);
 
-// 3. Define and register your artifact factories
+// Mock services for demonstration
 class LoggerService {
   constructor(private prefix: string) {}
   log(message: string) {
@@ -152,6 +177,11 @@ class LoggerService {
   }
 }
 
+interface ApiClient {
+  fetchData(path: string): Promise<{ message: string }>;
+}
+
+// 3. Define and register your artifact factories
 container.register({
   key: 'logger',
   scope: ArtifactScopes.Singleton, // Ensure only one instance of the logger
@@ -211,10 +241,11 @@ async function main() {
   console.log(appInfo.instance); // Logs the app information after API call
 
   // Example of reacting to state changes
-  console.log('\n--- Changing theme ---');
+  console.log('
+--- Changing theme ---');
   await appStore.set(s => ({ ...s, config: { ...s.config, theme: 'dark' } }));
 
-  // Because themeService depends on state.config.theme, it will be rebuilt
+  // Because themeService depends on state.config.theme, it will be rebuilt.
   // Any artifact that depends on themeService would also be rebuilt.
   const newTheme = await container.resolve('themeService');
   console.log('New Theme:', newTheme.instance); // Expected: dark
@@ -228,421 +259,388 @@ main();
 Use `container.register()` to define an artifact. Each artifact requires a unique `key` and a `factory` function.
 
 ```typescript
-import { ArtifactScopes } from '@asaidimu/utils-artifacts';
+import { ArtifactScopes, ArtifactTemplate } from "@asaidimu/utils-artifacts";
 
-container.register({
-  key: 'myArtifact',
-  factory: () => 'Hello, Artifact!',
+// Define your app's state and registry types for better type safety
+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",
+  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),
+    );
+
+    logger.log(`Initializing myService with API URL: ${apiUrl}`);
+    return `Initialized: ${apiUrl}`;
+  },
   // Optional parameters:
   scope: ArtifactScopes.Singleton, // 'singleton' (default) or 'transient'
-  lazy: true,                      // true (default) for singletons, false to build on registration
-  timeout: 5000,                   // Max time in ms for factory to complete
-  retries: 3,                      // Number of retries on factory failure
-  debounce: 100,                   // Delay in ms for rebuilding on 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.
 });
 ```
 
-The `factory` function receives an `ArtifactFactoryContext` object:
+The `factory` function receives an `ArtifactFactoryContext` object, providing access to dependencies, state, and lifecycle management:
 
 ```typescript
+/**
+ * Context provided to an artifact's factory function.
+ * @template TRegistry The full artifact registry type.
+ * @template TState The global state type.
+ * @template TArtifact The type of the artifact being created.
+ */
 interface ArtifactFactoryContext<TRegistry, TState, TArtifact> {
-  state(): TState; // Get current global state (non-reactive)
-  previous?: TArtifact; // Previous instance (for singletons on rebuild)
+  /** Returns the current global state object. Non-reactive. */
+  state(): TState;
+  /** The previous instance of a singleton artifact (if available). */
+  previous?: TArtifact;
+  /** Executes a callback within a dependency tracking context. */
   use<R>(callback: (ctx: UseDependencyContext<TRegistry, TState>) => R | Promise<R>): Promise<R>;
-  onCleanup(cleanup: ArtifactCleanup): void; // Register cleanup for current instance
-  onDispose(callback: ArtifactCleanup): void; // Register cleanup for artifact (permanent)
-  stream(callback: (ctx: ArtifactStreamContext<TState, TArtifact>) => ...): void; // Start streaming values (singletons only)
+  /** Registers a cleanup function for the current artifact instance. */
+  onCleanup(cleanup: ArtifactCleanup): void;
+  /** Registers a cleanup function for when the artifact is permanently disposed. */
+  onDispose(callback: ArtifactCleanup): void;
+  /** Starts a streaming process for a Singleton artifact. */
+  stream(callback: (ctx: ArtifactStreamContext<TState, TArtifact>) => ...): void;
 }
 
+/**
+ * Context for resolving dependencies within `use()` callback.
+ * @template TRegistry The full artifact registry type.
+ * @template TState The global state type.
+ */
 interface UseDependencyContext<TRegistry, TState> {
-  resolve<K extends keyof TRegistry>(key: K): Promise<ResolvedArtifact<TRegistry[K]>>; // Resolve an artifact (returns ResolvedArtifact)
-  require<K extends keyof TRegistry>(key: K): Promise<TRegistry[K]>; // Resolve an artifact (throws on error, returns instance directly)
-  select<S>(selector: (state: TState) => S): S; // Select state slice (reactive)
+  /** Resolves another artifact (returns `ResolvedArtifact`). */
+  resolve<K extends keyof TRegistry>(key: K): Promise<ResolvedArtifact<TRegistry[K]>>;
+  /** Resolves an artifact and throws on error (returns instance directly). */
+  require<K extends keyof TRegistry>(key: K): Promise<TRegistry[K]>;
+  /** Selects a slice of global state reactively. */
+  select<S>(selector: (state: TState) => S): S;
 }
 ```
 
 ### Resolving & Requiring Artifacts
 
-*   `container.resolve(key)`: Returns a `Promise<ResolvedArtifact<T>>`. `ResolvedArtifact` is a union type that can be `ReadyArtifact`, `ErrorArtifact`, or `PendingArtifact`. You should check the `ready` and `error` properties.
-*   `container.require(key)`: Returns a `Promise<T>` directly. If resolution fails or the artifact has an error, it will throw the error. Use this when you are certain the artifact will resolve successfully.
+- `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
-import { ArtifactError } from '@asaidimu/utils-artifacts';
-
-// Using resolve (recommended for robust error handling)
-const myArtifactResult = await container.resolve('myArtifact');
-if (myArtifactResult.ready) {
-  console.log('Artifact instance:', myArtifactResult.instance);
-} else if (myArtifactResult.error) {
-  console.error('Artifact failed to resolve:', myArtifactResult.error);
+// Using resolve for defensive programming
+const myServiceResult = await container.resolve("myService");
+if (myServiceResult.ready) {
+  console.log("Service instance:", myServiceResult.instance);
+} else if (myServiceResult.error) {
+  console.error("Service failed:", myServiceResult.error);
 } else {
-  console.log('Artifact is pending/idle.');
+  console.log("Service is pending or idle.");
 }
 
-// Using require (for simpler usage when errors are handled upstream or unexpected)
+// Using require for direct access when errors are handled upstream
 try {
-  const myArtifactInstance = await container.require('myArtifact');
-  console.log('Artifact instance:', myArtifactInstance);
+  const myServiceInstance = await container.require("myService");
+  console.log("Service instance:", myServiceInstance);
 } catch (error) {
-  if (error instanceof ArtifactError) {
-    console.error('Artifact system error:', error.message);
-  } else {
-    console.error('Artifact runtime error:', error);
-  }
+  console.error("Failed to get service:", error);
 }
 ```
 
 ### Watching Artifact Changes
 
-The `watch()` method provides an observer pattern to react to artifact changes without needing to repeatedly call `resolve()`. It's particularly useful for UI frameworks.
+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 myServiceWatcher = container.watch('myService');
+const loggerWatcher = container.watch("logger");
 
-const unsubscribe = myServiceWatcher.subscribe((resolvedArtifact) => {
+const unsubscribe = loggerWatcher.subscribe((resolvedArtifact) => {
   if (resolvedArtifact.ready) {
-    console.log('myService updated:', resolvedArtifact.instance);
+    console.log("Logger updated:", resolvedArtifact.instance);
   } else if (resolvedArtifact.error) {
-    console.error('myService error:', resolvedArtifact.error);
+    console.error("Logger error:", resolvedArtifact.error);
   }
-  // The `get()` method can also be used inside the callback or outside
-  // to get the current state of the artifact.
-  const current = myServiceWatcher.get();
-  console.log('Current state from get():', current.instance);
+  // `get()` retrieves the current resolved artifact state without subscribing.
+  const currentLogger = loggerWatcher.get();
+  console.log("Current logger:", currentLogger.instance);
 });
 
-// To stop receiving updates:
-unsubscribe();
+// To stop listening for updates:
+// unsubscribe();
 ```
 
 ### Reactive Dependencies (State Selection)
 
-Artifacts can react to changes in the global `DataStore` by using `ctx.select()`.
+Artifacts can automatically react to changes in your application's global state by using `ctx.select()` within the `use` callback.
 
 ```typescript
-interface UserSettings { userId: string; theme: string; };
-type AppRegistry = { userPreference: string };
+interface AppState {
+  user: { name: string; theme: "light" | "dark" };
+}
+interface AppRegistry {
+  userGreeting: string;
+}
 
-const userStore = new ReactiveDataStore<UserSettings>({ userId: 'guest', theme: 'light' });
-const userContainer = new ArtifactContainer<AppRegistry, UserSettings>(userStore);
+// Assume appStore is an instance of DataStore<AppState>
+const container = new ArtifactContainer<AppRegistry, AppState>(appStore);
 
-userContainer.register({
-  key: 'userPreference',
+container.register({
+  key: "userGreeting",
   factory: async ({ use }) => {
-    // This artifact will be rebuilt if state.theme changes
-    const theme = await use(({ select }) => select(state => state.theme));
-    return `Current theme is: ${theme}`;
+    // 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),
+    );
+    return `Hello, ${userName}! Your theme is ${theme}.`;
   },
 });
 
-async function runReactiveExample() {
-  let preference = await userContainer.resolve('userPreference');
-  console.log(preference.instance); // Output: Current theme is: light
-
-  // Update the store, which will trigger 'userPreference' to rebuild
-  await userStore.set({ theme: 'dark' });
-
-  // Resolve again to get the new instance
-  preference = await userContainer.resolve('userPreference');
-  console.log(preference.instance); // Output: Current theme is: dark
-}
-
-runReactiveExample();
+// Example of state change triggering rebuild
+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 run *before* a singleton artifact is rebuilt (due to invalidation) or before a transient artifact instance is discarded. Use this for instance-specific resource release (e.g., clearing timers, event listeners).
-*   `ctx.onDispose(fn)`: Registers a function to run *only when the artifact is permanently unregistered* from the container or the container itself is disposed. Use this for permanent resource release (e.g., closing database connections, unsubscribing from global events).
+- `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: 'myResource',
+  key: "resourceArtifact",
   scope: ArtifactScopes.Singleton,
-  factory: ({ onCleanup, onDispose }) => {
-    const resource = { id: Math.random(), intervalId: setInterval(() => {}, 1000) };
-    console.log(`Resource ${resource.id} created.`);
+  factory: ({ onCleanup, onDispose, use }) => {
+    const resourceId = Math.random();
+    console.log(`Resource ${resourceId} created.`);
+    const timerId = setInterval(
+      () => console.log(`Resource ${resourceId} heartbeat...`),
+      1000,
+    );
 
+    // Cleanup for the current instance (e.g., on rebuild or if transient)
     onCleanup(() => {
-      console.log(`Cleaning up instance ${resource.id}...`);
-      clearInterval(resource.intervalId);
+      console.log(`Cleaning up instance for resource ${resourceId}...`);
+      clearInterval(timerId);
     });
 
+    // Dispose for permanent removal from container
     onDispose(() => {
-      console.log(`Disposing artifact 'myResource'.`);
-      // Additional permanent resource release here
+      console.log(
+        `Disposing artifact 'resourceArtifact' (resource ${resourceId}).`,
+      );
+      // Final resource release
     });
 
-    return resource;
+    return { id: resourceId };
   },
 });
 
 async function lifecycleExample() {
-  await container.resolve('myResource');
-  // Simulate an invalidation (e.g., a dependency changed)
-  await container.invalidate('myResource'); // Triggers cleanup, then rebuilds
-  await container.resolve('myResource'); // A new instance is now resolved.
+  await container.resolve("resourceArtifact"); // Instance created and logs "heartbeat..."
+  console.log("Artifact resolved.");
 
-  // When unregistering, onDispose is called
-  await container.unregister('myResource'); // Triggers onCleanup (if active), then onDispose
+  // Simulate invalidation: will trigger onCleanup for the current instance, then rebuild.
+  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.");
 }
 lifecycleExample();
 ```
 
 ### Streaming Artifacts
 
-Singletons can continuously emit new values using `ctx.stream()`. This is powerful for reactive data sources.
+For artifacts that continuously emit values (e.g., real-time data, streams), use `ctx.stream()`. This is only supported for `Singleton` artifacts.
 
 ```typescript
 container.register({
-  key: 'counterStream',
+  key: "dataStream",
   scope: ArtifactScopes.Singleton,
-  factory: ({ stream, onCleanup }) => {
-    let count = 0;
-    let interval: ReturnType<typeof setInterval>;
+  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.");
 
-    stream(async ({ emit, signal }) => {
-      console.log('Counter stream started...');
-      interval = setInterval(() => {
+      intervalId = setInterval(() => {
         if (signal.aborted) {
-          console.log('Stream aborted, stopping interval.');
-          clearInterval(interval);
+          console.log("Stream signal aborted. Clearing interval.");
+          clearInterval(intervalId);
           return;
         }
-        count++;
-        emit(count); // Emit the new value
-        if (count >= 5) {
-          console.log('Count limit reached, stopping stream.');
-          clearInterval(interval);
-          return; // Stream producer can return to end the stream
+        counter++;
+        const newValue = `Data update #${counter}`;
+        console.log(`Emitting: ${newValue}`);
+        emit(newValue); // Emit the new value to the container
+        if (counter >= 5) {
+          console.log("Stream reached limit, stopping.");
+          clearInterval(intervalId);
+          // The factory function can return to stop the stream producer.
         }
       }, 500);
     });
 
     onCleanup(() => {
-      console.log('Cleaning up counter stream instance...');
-      // Ensure interval is cleared if stream is aborted/rebuilt
-      clearInterval(interval);
+      console.log("Cleaning up data stream instance...");
+      // Ensure interval is cleared if stream is aborted or rebuilt.
+      if (intervalId) clearInterval(intervalId);
     });
 
-    return 0; // Initial value before stream starts emitting
+    return "Initial stream value"; // Initial value before first emission
   },
 });
 
 async function streamExample() {
-  const watcher = container.watch('counterStream');
+  const watcher = container.watch("dataStream");
   const unsubscribe = watcher.subscribe((art) => {
-    if (art.ready) console.log('Counter value:', art.instance);
+    if (art.ready) console.log("Stream received:", art.instance);
   });
 
-  // Keep alive for a few seconds to see stream emissions
-  await new Promise(res => setTimeout(res, 3000));
+  // Keep alive for a few seconds to observe stream emissions
+  await new Promise((res) => setTimeout(res, 3000));
   unsubscribe();
-  console.log('Stream watcher unsubscribed.');
+  console.log("Stream watcher unsubscribed.");
 }
 streamExample();
 ```
 
 ### Invalidating Artifacts
 
-You can manually trigger an artifact to rebuild, which will also cascade invalidations to its dependents.
+Manually trigger an artifact to rebuild and cascade invalidations to its dependents.
 
 ```typescript
-// Invalidate a specific artifact
-await container.invalidate('myArtifact');
+// Invalidate an artifact; it will rebuild if it has dependents, is lazy and watched, or eagerly.
+await container.invalidate("myArtifact");
 
-// Force immediate rebuild, bypassing any debounce delay
-await container.invalidate('myArtifact', true);
+// Force immediate rebuild, bypassing any debounce delay.
+await container.invalidate("myArtifact", true);
 ```
 
 ### Debugging Artifacts
 
-The `debugInfo()` method provides a snapshot of the container's internal state, useful for understanding dependencies, status, and build counts.
+The `container.debugInfo()` method provides a snapshot of the container's internal state, which is invaluable for understanding dependencies, status, and build counts.
 
 ```typescript
 const debugNodes = container.debugInfo();
-debugNodes.forEach(node => {
-  console.log(`\nID: ${node.id}`);
+debugNodes.forEach((node) => {
+  console.log(`
+Artifact ID: ${node.id}`);
   console.log(`  Scope: ${node.scope}`);
-  console.log(`  Status: ${node.status}`); // 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(`  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(`  Build Count: ${node.buildCount}`);
 });
 ```
 
-### Retry Utility
+---
 
-The `Retry` class provides flexible retry logic for any async operation, supporting various strategies.
+## 🏗️ Project Architecture
 
-```typescript
-import { Retry, RetryExhaustedError, RetryPredicates } from '@asaidimu/utils-artifacts/retry';
+The `@asaidimu/utils-artifacts` library is architected around a central `ArtifactContainer` that orchestrates several specialized internal components:
 
-const unreliableOperation = async (attempt: number) => {
-  if (attempt < 3) {
-    console.log(`Unreliable operation failing on attempt ${attempt}`);
-    throw new Error('Transient network error');
-  }
-  console.log(`Unreliable operation succeeding on attempt ${attempt}`);
-  return 'Success!';
-};
-
-async function runRetryExample() {
-  try {
-    const result = await Retry.execute(
-      () => unreliableOperation(retryAttempt), // `retryAttempt` is for demonstration, actual attempt is internal.
-      {
-        retries: 4, // Total attempts: 1 (initial) + 4 (retries) = 5
-        strategy: 'exponential',
-        delay: 100, // Base delay 100ms
-        factor: 2,  // Multiplier 2x (100, 200, 400, 800)
-        maxDelay: 1000,
-        onRetry: (err, attempt, nextDelay) => {
-          console.warn(`Attempt ${attempt} failed: ${err}. Retrying in ${nextDelay}ms.`);
-          retryAttempt = attempt; // For demonstration only
-        },
-      }
-    );
-    console.log('Retry successful:', result);
-  } catch (e) {
-    if (e instanceof RetryExhaustedError) {
-      console.error(`Retry exhausted after ${e.attempts} attempts. Last error:`, e.lastError);
-    } else {
-      console.error('Unexpected error:', e);
-    }
-  }
+- **`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.
 
-  // Example with conditional retry based on error type
-  const fetchWithRetry = async (url: string) => {
-    return Retry.execute(
-      async () => {
-        const response = await fetch(url);
-        if (response.status >= 500) {
-          throw { status: response.status, message: 'Server error' }; // Simulate HTTP 5xx
-        }
-        return response.json();
-      },
-      {
-        retries: 5,
-        strategy: 'conditional',
-        shouldRetry: RetryPredicates.any(
-          RetryPredicates.networkErrors,
-          RetryPredicates.serverErrors,
-          RetryPredicates.httpStatus(429) // Also retry on Too Many Requests
-        ),
-        delay: (attempt) => Math.min(100 * Math.pow(2, attempt), 2000), // Custom delay function
-      }
-    );
-  };
+### Data Flow Example (Resolution & Reactivity)
 
-  // const data = await fetchWithRetry('https://api.example.com/data');
-}
-let retryAttempt = 0; // Used for demonstration purposes only
-runRetryExample();
-```
+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.
+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.
+
+### 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.
 
-### Concurrency Utilities (Once & Serializer)
+---
 
-`Once` ensures a function runs exactly one time, caching its result. `Serializer` ensures functions run sequentially. These are primarily used internally but are exposed for advanced use cases.
+## 📜 Considerations & Potential Pitfalls
 
-```typescript
-import { Once, Serializer } from '@asaidimu/utils-artifacts/sync';
-
-async function runOnceExample() {
-  const initialization = new Once<string>();
-  const expensiveInit = async () => {
-    console.log('Performing expensive initialization...');
-    await new Promise(res => setTimeout(res, 200));
-    return 'Initialized Resource';
-  };
+While `@asaidimu/utils-artifacts` offers powerful features, understanding its operational nuances and potential trade-offs is key to leveraging it effectively and avoiding common issues.
 
-  const [res1, res2, res3] = await Promise.all([
-    initialization.do(expensiveInit),
-    initialization.do(expensiveInit),
-    initialization.do(expensiveInit),
-  ]);
+### Debouncing Latency
 
-  console.log(res1.value, res2.value, res3.value); // All will be 'Initialized Resource'
-  // expensiveInit will be called only once.
-}
-runOnceExample();
+- **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.
 
-async function runSerializerExample() {
-  const queue = new Serializer<string>();
-  const order: string[] = [];
+### Wasted Build Effort from Late Staleness Detection
 
-  const task1 = async () => {
-    await new Promise(res => setTimeout(res, 100));
-    order.push('Task 1');
-    return 'Result 1';
-  };
-  const task2 = async () => {
-    order.push('Task 2');
-    return 'Result 2';
-  };
-  const task3 = async () => {
-    await new Promise(res => setTimeout(res, 50));
-    order.push('Task 3');
-    return 'Result 3';
-  };
+- **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.
 
-  await Promise.all([
-    queue.do(task1),
-    queue.do(task2),
-    queue.do(task3),
-  ]);
+### Efficiency of Global State Watching
 
-  console.log(order); // Expected: ['Task 1', 'Task 2', 'Task 3']
-}
-runSerializerExample();
-```
+- **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
 
-## 🏗️ Project Architecture
+- **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.
 
-The `ArtifactContainer` is designed with a modular architecture, delegating responsibilities to specialized internal components:
+### Sequential Cleanup/Dispose Execution
 
-*   **`ArtifactContainer`**: The public API entry point. It orchestrates interactions between the other internal components, providing a unified interface for artifact management.
-*   **`ArtifactRegistry`**: Stores the definitions (`ArtifactTemplate`s) of all registered artifacts, mapping unique keys to their factory functions and configuration options.
-*   **`ArtifactCache`**: Manages the storage and retrieval of resolved artifact instances, particularly for `Singleton` scoped artifacts. It handles caching, versioning, and state associated with active instances.
-*   **`ArtifactDependencyGraph`**: A bidirectional graph (`DependencyGraph`) that maps artifact-to-artifact dependencies and tracks which artifacts depend on state paths. This is crucial for circular dependency detection and efficient invalidation cascades.
-*   **`ArtifactManager`**: The core lifecycle manager. It handles the intricate process of building artifacts (executing factories), managing retries and timeouts, orchestrating `onCleanup`/`onDispose`, propagating stream emissions, and managing the reactive invalidation process based on artifact and state dependencies.
-*   **`ArtifactObserverManager`**: Manages the `container.watch()` API, maintaining subscriptions from external consumers and notifying them of artifact state changes. It handles reference counting and lazy initialization of watched artifacts.
-*   **`Retry`**: A standalone utility providing flexible retry mechanisms (fixed, exponential, jittered, conditional) for any asynchronous operation.
-*   **`Once` & `Serializer`**: Low-level concurrency primitives used internally (and exposed) to ensure that asynchronous operations (like artifact builds or stream emissions) execute safely and predictably, avoiding race conditions.
+- **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.
 
-### Data Flow
+### Dependency Graph Complexity
 
-1.  **Registration**: An `ArtifactTemplate` is registered with the `ArtifactRegistry`. A corresponding node is added to the `ArtifactDependencyGraph`.
-2.  **Resolution (`container.resolve`)**:
-    *   The `ArtifactContainer` forwards the request to the `ArtifactManager`.
-    *   The `Manager` consults the `ArtifactCache`. If a `Singleton` is already built and fresh, it's returned immediately.
-    *   Otherwise, the `Manager` retrieves the `ArtifactTemplate` from the `Registry`.
-    *   A factory is executed with an `ArtifactFactoryContext`.
-    *   Inside the factory:
-        *   `ctx.use(({ resolve }) => ...)`: Triggers recursive resolution of dependent artifacts. The `Manager` performs cycle detection via the `DependencyGraph` and updates artifact dependencies.
-        *   `ctx.use(({ select }) => ...)`: Registers state path dependencies with the `Manager`, which then subscribes to these paths via the `DataStore`.
-        *   `ctx.stream(...)`: For singletons, registers a stream producer that can `emit` new values.
-        *   `ctx.onCleanup`/`onDispose`: Registers lifecycle hooks.
-    *   The `Manager` handles retries for factory execution and commits the resulting instance (or error) to the `ArtifactCache`.
-    *   The `ArtifactCache` packages the result into a `ResolvedArtifact` for the consumer.
-3.  **Invalidation**:
-    *   **State Change**: A change in the `DataStore` (observed by `ArtifactManager` via `store.watch()`) triggers invalidation of dependent artifacts.
-    *   **Artifact Change**: A dependency being rebuilt or a stream emitting a new value, or manual `container.invalidate()` triggers invalidation.
-    *   The `ArtifactManager` runs the `onCleanup` hooks for the old instance, removes it from the `ArtifactCache`, and uses the `DependencyGraph` to identify and cascade invalidations to all affected dependents.
-    *   If configured (e.g., not lazy, has watchers), the `Manager` triggers a rebuild for the artifact.
-    *   Finally, `ArtifactObserverManager` notifies all active watchers.
-
-### Extension Points
-
-The primary extension point is the `ArtifactFactory` function itself, which receives the `ArtifactFactoryContext`. This context allows artifacts to:
-
-*   Declare and react to external dependencies (other artifacts, global state).
-*   Manage their internal lifecycle (cleanup, disposal).
-*   Create streaming data sources.
-*   Integrate with the underlying `DataStore` for dispatching actions.
+- **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.
 
 ---
 
@@ -650,8 +648,6 @@ The primary extension point is the `ArtifactFactory` function itself, which rece
 
 ### Development Setup
 
-To set up the project for local development:
-
 1.  **Clone the repository:**
     ```bash
     git clone https://github.com/asaidimu/erp-utils.git
@@ -663,44 +659,23 @@ To set up the project for local development:
     # or
     yarn install
     ```
-3.  **Build the project (if applicable, though typically handled by IDE/watch mode):**
-    ```bash
-    npm run build # Or `tsc` if not defined in package.json scripts
-    ```
 
 ### Scripts
 
-The `package.json` defines the following scripts:
-
-*   `npm test`: Runs all tests once.
-*   `npm test:watch`: Runs tests in watch mode, rerunning on file changes.
-*   `npm test:browser`: Runs tests in a browser environment (if configured), typically once.
+- `npm test`: Runs all tests once.
+- `npm test:watch`: Runs tests in watch mode, rerunning on file changes.
 
 ### Testing
 
-The project uses `vitest` for testing.
-
-*   To run all tests: `npm test`
-*   To run tests continuously during development: `npm test:watch`
-
-Tests utilize `fake-indexeddb` as seen in `vitest.setup.ts`, ensuring a consistent environment.
+The project uses `vitest` for testing. All new code should be accompanied by tests.
 
 ### Contributing Guidelines
 
-We welcome contributions! Please follow these guidelines:
-
-1.  **Fork the repository** and create your branch from `main`.
-2.  **Ensure code quality**: Write clean, readable TypeScript code. Adhere to existing coding style (ESLint and Prettier are typically configured in parent project).
-3.  **Tests**: All new features and bug fixes should be accompanied by appropriate unit or integration tests. Ensure existing tests pass.
-4.  **Commit Messages**: Use [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) for clear and consistent commit history. (e.g., `feat: add new artifact scope`, `fix: resolve circular dependency issue`).
-5.  **Pull Requests**:
-    *   Open a detailed Pull Request describing the changes, new features, or bug fixes.
-    *   Reference any related issues.
-    *   Ensure your branch is up-to-date with `main`.
-
-### Issue Reporting
-
-If you find a bug or have a feature request, please open an issue on the [GitHub Issues page](https://github.com/asaidimu/erp-utils/issues). Provide as much detail as possible, including steps to reproduce bugs and clear descriptions for feature requests.
+1.  **Fork and Branch**: Fork the repository and create a new branch from `main`.
+2.  **Code Quality**: Write clean, readable TypeScript code adhering to project conventions.
+3.  **Tests**: Add unit/integration tests for all new features and bug fixes.
+4.  **Commit Messages**: Use [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) (e.g., `feat: add streaming support`, `fix: correct debounce logic`).
+5.  **Pull Requests**: Submit PRs with clear descriptions and link to relevant issues.
 
 ---
 
@@ -708,33 +683,28 @@ If you find a bug or have a feature request, please open an issue on the [GitHub
 
 ### Troubleshooting
 
-*   **`ArtifactNotFoundError`**: This means you're trying to `resolve` or `watch` an artifact that hasn't been `register`ed. Double-check your artifact keys and ensure registration happens before resolution.
-*   **`CircularDependencyError`**: This occurs when your artifact graph forms a loop (e.g., A depends on B, B depends on A). The `debugInfo()` output and the error message's path can help you identify the cycle. Redesign your dependencies to break the cycle.
-*   **`TimeoutError`**: Your artifact factory took longer than the specified `timeout` during registration. This can indicate long-running sync operations, slow async dependencies, or an infinite loop. Increase the timeout or optimize your factory.
-*   **Unexpected Rebuilds/No Rebuilds**:
-    *   Use `container.debugInfo()` to inspect artifact statuses and `stateDependencies`/`dependencies`.
-    *   Ensure your `ctx.select()` selectors correctly identify the state slices you intend to react to.
-    *   Check `debounce` settings if an artifact seems to rebuild too frequently or too slowly.
-    *   Verify `onCleanup` and `onDispose` hooks are being called as expected to rule out resource leaks.
+- **`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
 
-*   **What's the difference between `Singleton` and `Transient` scopes?**
-    *   `Singleton`: Only one instance of the artifact is ever created. Subsequent `resolve` calls return the same instance. This is suitable for services, configurations, or shared resources. They support state dependencies, `onCleanup`/`onDispose`, and `stream`.
-    *   `Transient`: A new instance is created every time the artifact is resolved. Useful for ephemeral objects that should not be shared or cached. They do not support `stream` or persistent `onCleanup`/`onDispose` (though a single `cleanup` can be returned by `resolve`).
-*   **When should I use `resolve` versus `require`?**
-    *   Use `resolve` when you need to defensively handle potential errors or pending states of an artifact. It returns a `ResolvedArtifact` object that allows explicit checks (`.ready`, `.error`).
-    *   Use `require` when you are confident the artifact will resolve successfully and prefer to get the instance directly, allowing errors to propagate as exceptions. This simplifies code where error handling is done at a higher level.
-*   **How does `debounce` work for invalidation?**
-    `debounce` adds a delay (in milliseconds) before an artifact rebuilds after its dependencies change. If multiple dependency changes occur within this debounce period, the rebuild is aggregated into a single event, preventing excessive rapid rebuilds. `container.invalidate(key, true)` can bypass this debounce.
-*   **What is the purpose of `onCleanup` vs. `onDispose`?**
-    *   `onCleanup`: Tied to the *current instance's lifecycle*. It runs when a `Singleton` artifact's instance is replaced (e.g., due to an invalidation and rebuild), or when a `Transient` instance is returned and subsequently discarded. Use for resources specific to that particular instance.
-    *   `onDispose`: Tied to the *artifact's registration lifecycle*. It runs only when the artifact is permanently `unregister`ed from the container or when the container itself is `dispose`d. Use for resources that should persist across instance rebuilds but be released when the artifact itself is no longer managed.
+- **`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.
 
-### Changelog/Roadmap
-
-For detailed version history, please refer to the [CHANGELOG.md](https://github.com/asaidimu/erp-utils/blob/main/CHANGELOG.md) in the main repository.
-Future plans and roadmap items are tracked via GitHub issues and milestones.
+---
 
 ### License
 
@@ -742,4 +712,4 @@ This project is licensed under the [MIT License](https://github.com/asaidimu/erp
 
 ### Acknowledgments
 
-This library is part of the `@asaidimu/erp-utils` monorepository and integrates closely with `@core/store/types` (specifically, the `DataStore` interface) for reactive state management.
+This library is part of the `@asaidimu/erp-utils` monorepository and relies on a compatible `DataStore` implementation for reactive state management.