@asaidimu/utils-artifacts 4.1.1 → 5.0.1

package/README.md

@@ -1,52 +1,51 @@
-# `@asaidimu/utils-artifacts`
+# @asaidimu/utils-artifacts
 
-A powerful, reactive dependency injection container for managing application artifacts and their lifecycles. It provides a robust framework for building modular, maintainable, and highly responsive applications by decoupling components and managing their state-driven dependencies.
+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.
 
 [![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://github.com/asaidimu/erp-utils/blob/main/LICENSE)
-[![Build Status](https://img.shields.io/github/actions/workflow/status/asaidimu/erp-utils/ci.yml?branch=main&label=Build&style=flat-square)](https://github.com/asaidimu/erp-utils/actions?query=workflow%3ACI)
+[![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)
 
 ---
 
-### 🚀 Quick Links
-
-*   [Overview & Features](#-overview--features)
-*   [Installation & Setup](#-installation--setup)
-*   [Usage Documentation](#-usage-documentation)
-    *   [Basic Artifacts (Singleton & Transient)](#basic-artifacts-singleton--transient)
-    *   [Reactive State Dependencies](#reactive-state-dependencies)
-    *   [Artifact-to-Artifact Dependencies](#artifact-to-artifact-dependencies)
-    *   [Lifecycle Hooks: `onCleanup` & `onDispose`](#lifecycle-hooks-oncleanup--ondispose)
-    *   [Watching Artifacts for Changes](#watching-artifacts-for-changes)
-    *   [Streaming Artifacts with `ctx.stream()`](#streaming-artifacts-with-ctxstream)
-    *   [Debugging Information](#debugging-information)
-*   [Project Architecture](#-project-architecture)
-*   [Development & Contributing](#-development--contributing)
-*   [Additional Information](#-additional-information)
+## 🚀 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)
 
 ---
 
-⚠️ **Beta Warning**
-This package is currently in **beta**. The API is subject to rapid changes and should not be considered stable. Breaking changes may occur frequently without notice as we iterate and improve. We’ll update this warning once the package reaches a stable release. Use at your own risk and share feedback or report issues to help us improve!
+## ✨ Overview & Features
 
-## 📚 Overview & Features
+`@asaidimu/utils-artifacts` is a reactive dependency injection container designed to bring order and efficiency to complex application architectures. It allows you to define application components (called "artifacts") as factories that declare their dependencies on other artifacts and global application state. The container automatically manages the lifecycle, instantiation, and invalidation of these artifacts, ensuring that components are always up-to-date with their dependencies.
 
-`@asaidimu/utils-artifacts` is a sophisticated dependency injection (DI) container designed for modern TypeScript applications. It allows you to register "artifacts" – which can be any JavaScript object, function, or value – and manage their creation, lifecycle, and dependencies. What sets it apart is its reactive nature: artifacts can declare dependencies on both other artifacts and specific slices of a global application state (managed by an external `DataStore` like `@asaidimu/utils-store`). When these declared dependencies change, the container automatically invalidates and rebuilds the affected artifacts, propagating updates through the dependency graph efficiently, with support for debouncing to prevent excessive rebuilds.
+### Key Features
 
-This package is ideal for building complex, event-driven systems, front-end applications, or backend services where state changes need to trigger logical recalculations or UI updates in a structured and testable manner. It promotes modularity, testability, and maintainability by centralizing dependency management and automating reactive updates.
-
-### ✨ Key Features
-
-*   **Reactive Dependency Injection**: Automatically invalidates and rebuilds `Singleton` artifacts when their declared dependencies (other artifacts or global state slices) change, ensuring reactive updates throughout your application.
-*   **Singleton & Transient Scopes**: Control whether an artifact is instantiated once and reused (`Singleton`) or created fresh on every request (`Transient`).
-*   **State-Driven Invalidation with Debouncing**: Integrates with a `DataStore` (e.g., `@asaidimu/utils-store`) to track state dependencies, triggering artifact rebuilds only when relevant state paths change, with configurable debouncing to prevent excessive rebuilds.
-*   **Fine-grained Dependency Tracking**: Explicitly declare dependencies on other artifacts using `ctx.use(({ resolve }) => resolve('someKey'))` and on state slices using `ctx.use(({ select }) => select(state => state.somePath))`.
-*   **Robust Error Handling**: Built-in detection and specific error types for circular dependencies (`CircularDependencyError`), missing artifacts (`ArtifactNotFoundError`), illegal operations (`IllegalScopeError`), and timeouts (`TimeoutError`), distinguishing between `system` (structural) and `external` (runtime) errors.
-*   **Lifecycle Hooks**: Register `onCleanup` callbacks for instance-specific resource release (executed before a `Singleton` instance is rebuilt) and `onDispose` for final resource teardown (executed when the artifact is unregistered).
-*   **Asynchronous Artifact Resolution**: Supports `async`/`await` in artifact factories, with configurable `retries` for external failures and `timeout` settings for long-running operations.
-*   **`ArtifactObserver` for Reactive Observation**: Use `container.watch(key)` to get an observer that allows subscribing to an artifact's resolved value over time, providing reactive updates to UI components or other systems.
-*   **Live Streaming with `ctx.stream()`**: `Singleton` artifacts can emit multiple values over their lifetime from within their factory using `ctx.stream()`, immediately notifying dependents and watchers of new data. This is ideal for continuous data sources like WebSockets or background processes.
-*   **Comprehensive Debugging Info**: `container.debugInfo()` provides a runtime snapshot of the container's state, including artifact statuses, dependencies (artifact-to-artifact and state-to-artifact), and dependents.
+*   **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.
 
 ---
 
@@ -54,761 +53,688 @@ This package is ideal for building complex, event-driven systems, front-end appl
 
 ### Prerequisites
 
-*   **Node.js**: (v18 or higher recommended)
-*   **Package Manager**: `Bun`, `npm`, or `Yarn`.
-*   **DataStore Implementation**: An external implementation of a `DataStore` interface with `get` and `watch` methods. We highly recommend using [`@asaidimu/utils-store`](https://www.npmjs.com/package/@asaidimu/utils-store) as it is designed for seamless integration.
+*   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`).
 
 ### Installation Steps
 
-Install the package using your preferred package manager:
+To install the library, use your preferred package manager:
 
 ```bash
-# With Bun
-bun add @asaidimu/utils-artifacts
-
-# With npm
 npm install @asaidimu/utils-artifacts
-
-# With Yarn
+# or
 yarn add @asaidimu/utils-artifacts
 ```
 
 ### Configuration
 
-To use the `ArtifactContainer`, you need to initialize it with an object that provides `watch` (for reactive subscriptions to state changes), `get` (for reading the current state), and `set` (for allowing artifacts to update state, e.g., via `ctx.stream` or `ctx.set`).
+`@asaidimu/utils-artifacts` is a library and does not require global configuration files. Its primary setup involves initializing the `ArtifactContainer` with an instance of a `DataStore`.
 
-If you're using `@asaidimu/utils-store` as your `DataStore`:
+### Verification
+
+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'; // Recommended DataStore
+import { ReactiveDataStore } from '@asaidimu/utils-store'; // Assuming you have this store
 
-interface AppState {
-  config: { theme: string; debugMode: boolean };
-  user: { id: string; name: string };
-  data: number[];
-}
-
-const initialAppState: AppState = {
-  config: { theme: 'dark', debugMode: true },
-  user: { id: 'user-123', name: 'Augustine' },
-  data: [1, 2, 3]
-};
+// Define your application's global state and artifact registry types
+type AppState = { count: number; };
+type AppRegistry = { myService: string; };
 
-const store = new ReactiveDataStore<AppState>(initialAppState);
-
-// Initialize the ArtifactContainer
-// The generic arguments <TRegistry, TState> are inferred or can be explicitly provided.
-const container = new ArtifactContainer<Record<string, any>, AppState>(store);
-
-// Now you can start registering artifacts
-```
+const store = new ReactiveDataStore<AppState>({ count: 0 });
+const container = new ArtifactContainer<AppRegistry, AppState>(store);
 
-### Verification
+container.register({
+  key: 'myService',
+  factory: async ({ use }) => {
+    const currentCount = await use(({ select }) => select(s => s.count));
+    return `Service is running with count: ${currentCount}`;
+  },
+});
 
-You can verify the installation by trying to import and instantiate the `ArtifactContainer`:
+async function runExample() {
+  const service = await container.resolve('myService');
+  console.log(service.instance); // Expected: Service is running with count: 0
+}
 
-```typescript
-import { ArtifactContainer } from '@asaidimu/utils-artifacts';
-// Assuming a mock or real DataStore is available
-const mockStore = {
-  get: () => ({}), // Returns an empty object for state
-  watch: () => () => {}, // Returns a no-op unsubscribe function
-  set: async () => ({}), // Returns a no-op set function
-};
-const container = new ArtifactContainer(mockStore);
-console.log('ArtifactContainer initialized successfully!');
-// If no errors, the installation is successful.
+runExample();
 ```
 
 ---
 
-## 💡 Usage Documentation
+## 📖 Usage Documentation
 
-### Basic Artifacts (Singleton & Transient)
+### Basic Usage
 
-Artifacts can be registered with different scopes, controlling their lifecycle and instantiation behavior.
-
-#### Singleton Scope
-
-A `Singleton` artifact is created only once. Subsequent `resolve` calls or reactive updates will return or use the same instance, unless its dependencies change, which triggers a rebuild. This is the default scope.
+The core of the library is the `ArtifactContainer`. You initialize it with a `DataStore` that manages your application's global state.
 
 ```typescript
 import { ArtifactContainer, ArtifactScopes } from '@asaidimu/utils-artifacts';
 import { ReactiveDataStore } from '@asaidimu/utils-store';
 
-const store = new ReactiveDataStore({});
-const container = new ArtifactContainer(store);
+// 1. Define your application's global state and artifact registry types
+interface AppState {
+  appName: string;
+  version: string;
+  config: {
+    theme: 'light' | 'dark';
+    apiUrl: string;
+  };
+}
+
+interface AppRegistry {
+  logger: LoggerService;
+  apiClient: ApiClient;
+  themeService: 'light' | 'dark';
+  appInfo: string;
+}
+
+// Example DataStore (from @asaidimu/utils-store)
+const appStore = new ReactiveDataStore<AppState>({
+  appName: 'My App',
+  version: '1.0.0',
+  config: {
+    theme: 'light',
+    apiUrl: 'https://api.example.com',
+  },
+});
 
-let buildCount = 0;
+// 2. Instantiate the ArtifactContainer
+const container = new ArtifactContainer<AppRegistry, AppState>(appStore);
+
+// 3. Define and register your artifact factories
+class LoggerService {
+  constructor(private prefix: string) {}
+  log(message: string) {
+    console.log(`[${this.prefix}] ${message}`);
+  }
+}
+
+container.register({
+  key: 'logger',
+  scope: ArtifactScopes.Singleton, // Ensure only one instance of the logger
+  factory: () => new LoggerService('APP'),
+});
 
 container.register({
-  key: 'mySingletonService',
-  factory: () => {
-    buildCount++;
-    console.log('Building mySingletonService...');
+  key: 'apiClient',
+  scope: ArtifactScopes.Singleton,
+  factory: async ({ use }) => {
+    // ApiClient depends on the logger and state.config.apiUrl
+    const logger = await use(({ require }) => require('logger'));
+    const apiUrl = await use(({ select }) => select(state => state.config.apiUrl));
+
+    logger.log(`Initializing API client for ${apiUrl}`);
     return {
-      name: 'SingletonService',
-      version: '1.0.0'
+      fetchData: async (path: string) => {
+        logger.log(`Fetching from ${apiUrl}${path}`);
+        // Simulate API call
+        await new Promise(res => setTimeout(res, 100));
+        return { message: `Data from ${apiUrl}${path}` };
+      }
     };
   },
+});
+
+container.register({
+  key: 'themeService',
   scope: ArtifactScopes.Singleton,
-  lazy: false, // Build immediately on registration if it's a Singleton
+  factory: async ({ use }) => {
+    // Theme service depends directly on state
+    return await use(({ select }) => select(state => state.config.theme));
+  },
 });
 
-async function runSingletonExample() {
-  const service1 = await container.resolve('mySingletonService');
-  const service2 = await container.resolve('mySingletonService');
+container.register({
+  key: 'appInfo',
+  scope: ArtifactScopes.Singleton,
+  factory: async ({ use }) => {
+    // App info depends on other artifacts and state
+    const logger = await use(({ require }) => require('logger'));
+    const apiClient = await use(({ require }) => require('apiClient'));
+    const appName = await use(({ select }) => select(s => s.appName));
+
+    const data = await apiClient.fetchData('/info');
+    logger.log(`App Info: ${appName}, Data: ${data.message}`);
+    return `App: ${appName}, API Data: ${data.message}`;
+  },
+});
+
+// 4. Resolve artifacts to use them
+async function main() {
+  const logger = await container.resolve('logger');
+  logger.instance?.log('Application started.');
 
-  console.log('Service 1:', service1.instance);
-  console.log('Service 2:', service2.instance);
+  const appInfo = await container.resolve('appInfo');
+  console.log(appInfo.instance); // Logs the app information after API call
 
-  console.assert(buildCount === 1, 'Singleton factory should be called once');
-  console.assert(service1.instance === service2.instance, 'Both resolutions should return the same instance');
-  console.assert(service1.ready, 'Singleton should be ready');
+  // Example of reacting to state changes
+  console.log('\n--- Changing theme ---');
+  await appStore.set(s => ({ ...s, config: { ...s.config, theme: 'dark' } }));
 
-  // Output:
-  // Building mySingletonService...
-  // Service 1: { name: 'SingletonService', version: '1.0.0' }
-  // Service 2: { name: 'SingletonService', version: '1.0.0' }
+  // 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
 }
 
-runSingletonExample();
+main();
 ```
 
-#### Transient Scope
+### Registering Artifacts
 
-A `Transient` artifact creates a new instance every time it is resolved. These artifacts do not participate in caching, reactive invalidation, or lifecycle hooks like `onCleanup` and `onDispose`.
+Use `container.register()` to define an artifact. Each artifact requires a unique `key` and a `factory` function.
 
 ```typescript
-import { ArtifactContainer, ArtifactScopes } from '@asaidimu/utils-artifacts';
-import { ReactiveDataStore } from '@asaidimu/utils-store';
-
-const store = new ReactiveDataStore({});
-const container = new ArtifactContainer(store);
+import { ArtifactScopes } from '@asaidimu/utils-artifacts';
 
 container.register({
-  key: 'myTransientFactory',
-  factory: () => {
-    console.log('Building myTransientFactory...');
-    return {
-      id: Math.random().toString(36).substring(7),
-      timestamp: Date.now()
-    };
-  },
-  scope: ArtifactScopes.Transient,
+  key: 'myArtifact',
+  factory: () => 'Hello, Artifact!',
+  // 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
 });
+```
 
-async function runTransientExample() {
-  const instance1 = await container.resolve('myTransientFactory');
-  const instance2 = await container.resolve('myTransientFactory');
-
-  console.log('Instance 1:', instance1.instance);
-  console.log('Instance 2:', instance2.instance);
-
-  console.assert(instance1.instance !== instance2.instance, 'Transient should return different instances');
-  console.assert(instance1.ready && instance2.ready, 'Transient instances should be ready immediately');
+The `factory` function receives an `ArtifactFactoryContext` object:
 
-  // Output:
-  // Building myTransientFactory...
-  // Building myTransientFactory...
-  // Instance 1: { id: '...', timestamp: ... }
-  // Instance 2: { id: '...', timestamp: ... }
+```typescript
+interface ArtifactFactoryContext<TRegistry, TState, TArtifact> {
+  state(): TState; // Get current global state (non-reactive)
+  previous?: TArtifact; // Previous instance (for singletons on rebuild)
+  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)
 }
 
-runTransientExample();
+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)
+}
 ```
 
-### Reactive State Dependencies
+### Resolving & Requiring Artifacts
 
-Artifacts can react to changes in your global `DataStore` state by using `ctx.use(({ select }) => ...)` within their factory. When the selected state slice changes, the `Singleton` artifact is automatically invalidated and rebuilt.
+*   `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.
 
 ```typescript
-import { ArtifactContainer, ArtifactScopes } from '@asaidimu/utils-artifacts';
-import { ReactiveDataStore } from '@asaidimu/utils-store';
+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);
+} else {
+  console.log('Artifact is pending/idle.');
+}
 
-interface AppState {
-  theme: 'dark' | 'light';
-  notificationsEnabled: boolean;
+// Using require (for simpler usage when errors are handled upstream or unexpected)
+try {
+  const myArtifactInstance = await container.require('myArtifact');
+  console.log('Artifact instance:', myArtifactInstance);
+} catch (error) {
+  if (error instanceof ArtifactError) {
+    console.error('Artifact system error:', error.message);
+  } else {
+    console.error('Artifact runtime error:', error);
+  }
 }
+```
 
-const store = new ReactiveDataStore<AppState>({
-  theme: 'dark',
-  notificationsEnabled: true,
-});
-const container = new ArtifactContainer<any, AppState>(store);
+### Watching Artifact Changes
 
-let uiComponentBuilds = 0;
-container.register({
-  key: 'uiConfiguration',
-  factory: async ({ use }) => {
-    uiComponentBuilds++;
-    const theme = await use((ctx) => ctx.select((state) => state.theme));
-    const notifications = await use((ctx) => ctx.select((state) => state.notificationsEnabled));
+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.
 
-    console.log(`UI Config Build ${uiComponentBuilds}: Theme=${theme}, Notifications=${notifications}`);
-    return { theme, notifications };
-  },
-  scope: ArtifactScopes.Singleton,
-});
+```typescript
+const myServiceWatcher = container.watch('myService');
 
-async function runReactiveStateExample() {
-  // Initial resolution
-  let uiConfig = await container.resolve('uiConfiguration');
-  console.assert(uiConfig.instance?.theme === 'dark', 'Initial theme should be dark');
-  console.assert(uiComponentBuilds === 1, 'Initial build count should be 1');
-
-  // Simulate state change
-  console.log('\n--- Changing theme to light ---');
-  await store.set({ theme: 'light' });
-
-  // Resolve again - artifact should have been invalidated and rebuilt
-  uiConfig = await container.resolve('uiConfiguration');
-  console.assert(uiConfig.instance?.theme === 'light', 'Updated theme should be light');
-  console.assert(uiComponentBuilds === 2, 'Build count should increment after state change');
-
-  // Simulate another state change (different property)
-  console.log('\n--- Disabling notifications ---');
-  await store.set({ notificationsEnabled: false });
-
-  // Resolve again
-  uiConfig = await container.resolve('uiConfiguration');
-  console.assert(uiConfig.instance?.notifications === false, 'Notifications should be false');
-  console.assert(uiComponentBuilds === 3, 'Build count should increment after another state change');
-
-  // Output:
-  // UI Config Build 1: Theme=dark, Notifications=true
-  //
-  // --- Changing theme to light ---
-  // UI Config Build 2: Theme=light, Notifications=true
-  //
-  // --- Disabling notifications ---
-  // UI Config Build 3: Theme=light, Notifications=false
-}
+const unsubscribe = myServiceWatcher.subscribe((resolvedArtifact) => {
+  if (resolvedArtifact.ready) {
+    console.log('myService updated:', resolvedArtifact.instance);
+  } else if (resolvedArtifact.error) {
+    console.error('myService 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);
+});
 
-runReactiveStateExample();
+// To stop receiving updates:
+unsubscribe();
 ```
 
-### Artifact-to-Artifact Dependencies
+### Reactive Dependencies (State Selection)
 
-Artifacts can depend on other artifacts using `ctx.use(({ resolve }) => resolve('otherArtifactKey'))` or `ctx.use(({ require }) => require('otherArtifactKey'))` within their factory. Changes (invalidations) to a dependency will automatically invalidate the dependent artifact.
+Artifacts can react to changes in the global `DataStore` by using `ctx.select()`.
 
 ```typescript
-import { ArtifactContainer, ArtifactScopes } from '@asaidimu/utils-artifacts';
-import { ReactiveDataStore } from '@asaidimu/utils-store';
-
-const store = new ReactiveDataStore({});
-const container = new ArtifactContainer(store);
+interface UserSettings { userId: string; theme: string; };
+type AppRegistry = { userPreference: string };
 
-let dbConnectionBuilds = 0;
-container.register({
-  key: 'dbConnection',
-  factory: async () => {
-    dbConnectionBuilds++;
-    console.log(`Establishing DB Connection (${dbConnectionBuilds})...`);
-    await new Promise(res => setTimeout(res, 50)); // Simulate async work
-    return { client: 'PostgreSQL', status: 'connected' };
-  },
-  scope: ArtifactScopes.Singleton,
-});
+const userStore = new ReactiveDataStore<UserSettings>({ userId: 'guest', theme: 'light' });
+const userContainer = new ArtifactContainer<AppRegistry, UserSettings>(userStore);
 
-let userRepositoryBuilds = 0;
-container.register({
-  key: 'userRepository',
+userContainer.register({
+  key: 'userPreference',
   factory: async ({ use }) => {
-    userRepositoryBuilds++;
-    console.log(`Building UserRepository (${userRepositoryBuilds})...`);
-    const db = await use((ctx) => ctx.require('dbConnection')); // Using 'require' for direct instance
-    return {
-      dbClient: db.client,
-      findUser: (id: string) => `User ${id} from ${db.client}`
-    };
+    // This artifact will be rebuilt if state.theme changes
+    const theme = await use(({ select }) => select(state => state.theme));
+    return `Current theme is: ${theme}`;
   },
-  scope: ArtifactScopes.Singleton,
 });
 
-async function runArtifactDependencyExample() {
-  // Initial resolution of UserRepository, which will resolve dbConnection first
-  let userRepo = await container.resolve('userRepository');
-  console.assert(dbConnectionBuilds === 1, 'DB Connection built once');
-  console.assert(userRepositoryBuilds === 1, 'User Repository built once');
-  console.log('User Repo initialized:', userRepo.instance?.findUser('1'));
-
-  // Manually invalidate the dbConnection. This will trigger a rebuild of both.
-  console.log('\n--- Invalidating DB Connection ---');
-  const dbConnection = await container.resolve('dbConnection');
-  await dbConnection.invalidate(true); // `true` forces immediate rebuild
-
-  // Resolve UserRepository again - it should have been rebuilt
-  userRepo = await container.resolve('userRepository');
-  console.assert(dbConnectionBuilds === 2, 'DB Connection rebuilt');
-  console.assert(userRepositoryBuilds === 2, 'User Repository rebuilt due to DB change');
-  console.log('User Repo after invalidation:', userRepo.instance?.findUser('2'));
-
-  // Output:
-  // Establishing DB Connection (1)...
-  // Building UserRepository (1)...
-  // User Repo initialized: User 1 from PostgreSQL
-  //
-  // --- Invalidating DB Connection ---
-  // Establishing DB Connection (2)...
-  // Building UserRepository (2)...
-  // User Repo after invalidation: User 2 from PostgreSQL
+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
 }
 
-runArtifactDependencyExample();
+runReactiveExample();
 ```
 
-### Lifecycle Hooks: `onCleanup` & `onDispose`
-
-Artifacts can register cleanup functions to manage resources, ensuring proper release when instances are no longer needed.
+### Artifact Lifecycle (Cleanup & Dispose)
 
-*   `onCleanup(callback)`: Registered callbacks are executed *before* a `Singleton` artifact's instance is replaced (due to invalidation/rebuild). Ideal for releasing resources tied to that specific *instance* (e.g., stopping timers, closing old connections).
-*   `onDispose(callback)`: Registered callbacks are executed *only* when the artifact is explicitly `unregister()`ed from the container or the container itself is `dispose()`d. Ideal for final, permanent resource release associated with the *artifact definition itself*.
+*   `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).
 
 ```typescript
-import { ArtifactContainer, ArtifactScopes } from '@asaidimu/utils-artifacts';
-import { ReactiveDataStore } from '@asaidimu/utils-store';
-
-const store = new ReactiveDataStore({});
-const container = new ArtifactContainer(store);
-
-let currentInterval: any;
-
 container.register({
-  key: 'ticker',
+  key: 'myResource',
+  scope: ArtifactScopes.Singleton,
   factory: ({ onCleanup, onDispose }) => {
-    console.log('Ticker artifact created.');
-    let count = 0;
-    currentInterval = setInterval(() => {
-      count++;
-      // console.log(`Tick: ${count}`); // Uncomment to see live ticks
-    }, 1000);
+    const resource = { id: Math.random(), intervalId: setInterval(() => {}, 1000) };
+    console.log(`Resource ${resource.id} created.`);
 
     onCleanup(() => {
-      console.log('Cleaning up old Ticker instance (stopping interval)...');
-      clearInterval(currentInterval);
+      console.log(`Cleaning up instance ${resource.id}...`);
+      clearInterval(resource.intervalId);
     });
 
     onDispose(() => {
-      console.log('Disposing Ticker artifact (final cleanup)...');
-      // Additional final cleanup could go here, e.g., closing file handles
+      console.log(`Disposing artifact 'myResource'.`);
+      // Additional permanent resource release here
     });
 
-    return { start: Date.now() };
+    return resource;
   },
-  scope: ArtifactScopes.Singleton,
-  lazy: false, // Eagerly build
 });
 
-async function runLifecycleHooksExample() {
-  await container.resolve('ticker');
-  console.log('Ticker running for 2 seconds...');
-  await new Promise(res => setTimeout(res, 2000));
-
-  console.log('\n--- Invalidating Ticker (will trigger onCleanup and rebuild) ---');
-  const ticker = await container.resolve('ticker'); // Get current to invalidate
-  await ticker.invalidate(true); // Force rebuild
-  console.log('Ticker rebuilt. Running for 2 more seconds...');
-  await new Promise(res => setTimeout(res, 2000));
-
-  console.log('\n--- Unregistering Ticker (will trigger onDispose) ---');
-  await container.unregister('ticker');
-  console.log('Ticker unregistered.');
+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.
 
-  // Output will show 'Cleaning up old Ticker instance' on invalidation,
-  // and 'Disposing Ticker artifact' on unregister.
+  // When unregistering, onDispose is called
+  await container.unregister('myResource'); // Triggers onCleanup (if active), then onDispose
 }
-
-runLifecycleHooksExample();
+lifecycleExample();
 ```
 
-### Watching Artifacts for Changes
+### Streaming Artifacts
 
-The `container.watch(key)` method provides a reactive way to observe an artifact's value without repeatedly calling `resolve()`. This is particularly useful for UI frameworks or reactive data flows where you want to be notified of changes as they occur.
+Singletons can continuously emit new values using `ctx.stream()`. This is powerful for reactive data sources.
 
 ```typescript
-import { ArtifactContainer, ArtifactScopes, WatcherDisposedError } from '@asaidimu/utils-artifacts';
-import { ReactiveDataStore } from '@asaidimu/utils-store';
+container.register({
+  key: 'counterStream',
+  scope: ArtifactScopes.Singleton,
+  factory: ({ stream, onCleanup }) => {
+    let count = 0;
+    let interval: ReturnType<typeof setInterval>;
 
-interface AppState {
-  counter: number;
-}
+    stream(async ({ emit, signal }) => {
+      console.log('Counter stream started...');
+      interval = setInterval(() => {
+        if (signal.aborted) {
+          console.log('Stream aborted, stopping interval.');
+          clearInterval(interval);
+          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
+        }
+      }, 500);
+    });
 
-const store = new ReactiveDataStore<AppState>({ counter: 0 });
-const container = new ArtifactContainer<any, AppState>(store);
+    onCleanup(() => {
+      console.log('Cleaning up counter stream instance...');
+      // Ensure interval is cleared if stream is aborted/rebuilt
+      clearInterval(interval);
+    });
 
-let reactiveCounterBuilds = 0;
-container.register({
-  key: 'reactiveCounter',
-  factory: async ({ use }) => {
-    reactiveCounterBuilds++;
-    const count = await use((ctx) => ctx.select((state) => state.counter));
-    return `Current count: ${count} (Build: ${reactiveCounterBuilds})`;
+    return 0; // Initial value before stream starts emitting
   },
-  scope: ArtifactScopes.Singleton,
 });
 
-async function runWatcherExample() {
-  console.log('Setting up watcher...');
-  const watcher = container.watch('reactiveCounter');
-
-  let unsubscribe = watcher.subscribe((resolved) => {
-    if (resolved.ready) {
-      console.log('Watcher received update:', resolved.instance);
-    } else if (resolved.error) {
-      console.error('Watcher received error:', resolved.error.message);
-    } else {
-      console.log('Watcher received pending update (artifact not yet ready).');
-    }
+async function streamExample() {
+  const watcher = container.watch('counterStream');
+  const unsubscribe = watcher.subscribe((art) => {
+    if (art.ready) console.log('Counter value:', art.instance);
   });
 
-  // Give watcher time to resolve the artifact initially
-  await new Promise(res => setTimeout(res, 10)); 
-
-  console.log('\n--- Incrementing counter ---');
-  await store.set({ counter: 1 });
-  await new Promise(res => setTimeout(res, 10));
-
-  console.log('\n--- Incrementing counter again ---');
-  await store.set({ counter: 2 });
-  await new Promise(res => setTimeout(res, 10));
-
-  console.log('\n--- Unsubscribing & Disposing watcher ---');
-  unsubscribe(); // Unsubscribe from updates
-  
-  // After all subscribers are gone, the underlying artifact instance for watching transients is cleaned up.
-  // The watcher itself can then be disposed, making it unusable.
-  await new Promise(res => setTimeout(res, 10)); // Give cleanup a moment
-  // For singletons, watcher.dispose() is effectively a no-op as the underlying artifact remains
-  // For transients, it would clean up the internal singleton clone.
-  
-  try {
-    watcher.get(); // Attempt to access after dispose
-  } catch (e) {
-    if (e instanceof WatcherDisposedError) {
-      console.error('Caught expected error after watcher dispose:', e.message);
-    } else {
-      throw e;
-    }
-  }
-
-  // Output:
-  // Setting up watcher...
-  // Watcher received pending update (artifact not yet ready).
-  // Watcher received update: Current count: 0 (Build: 1)
-  //
-  // --- Incrementing counter ---
-  // Watcher received update: Current count: 1 (Build: 2)
-  //
-  // --- Incrementing counter again ---
-  // Watcher received update: Current count: 2 (Build: 3)
-  //
-  // --- Unsubscribing & Disposing watcher ---
-  // Caught expected error after watcher dispose: [ArtifactContainer] Artifact with key:reactiveCounter has already been disposed
+  // Keep alive for a few seconds to see stream emissions
+  await new Promise(res => setTimeout(res, 3000));
+  unsubscribe();
+  console.log('Stream watcher unsubscribed.');
 }
-
-runWatcherExample();
+streamExample();
 ```
 
-### Streaming Artifacts with `ctx.stream()`
+### Invalidating Artifacts
 
-`Singleton` artifacts can leverage `ctx.stream(callback)` to become continuous sources of data. The `callback` receives an `ArtifactStreamContext` which allows emitting new values over time via `ctx.emit(value)`. Each emission updates the artifact's instance, notifying all dependents and watchers immediately. This is ideal for scenarios like WebSocket clients, background workers, or long-running computations that produce intermediate results.
+You can manually trigger an artifact to rebuild, which will also cascade invalidations to its dependents.
 
 ```typescript
-import { ArtifactContainer, ArtifactScopes } from "@asaidimu/utils-artifacts";
-import { ReactiveDataStore } from "@asaidimu/utils-store";
-
-const store = new ReactiveDataStore({});
-const container = new ArtifactContainer<{ producer: number; consumer: string }, {}>(store);
+// Invalidate a specific artifact
+await container.invalidate('myArtifact');
 
-const PRODUCER_TIMEOUT = 50; // ms
-const PRODUCER_LIMIT = 3;
+// Force immediate rebuild, bypassing any debounce delay
+await container.invalidate('myArtifact', true);
+```
 
-container.register({
-  key: "producer",
-  factory: ({ stream }) => {
-    let value = 0;
+### Debugging Artifacts
 
-    // The stream callback is executed in the background
-    stream(async ({ emit, signal }) => {
-      console.log("Producer: Stream started.");
-      while (!signal.aborted) {
-        await new Promise((res) => setTimeout(res, PRODUCER_TIMEOUT)); // Simulate async work
-        value++;
-        console.log(`Producer: Emitting value: ${value}`);
-        await emit(value); // Emit new value, notifying dependents and watchers
-        if (value >= PRODUCER_LIMIT) {
-          console.log("Producer: Reached limit, stopping stream.");
-          break;
-        }
-      }
-    });
+The `debugInfo()` method provides a snapshot of the container's internal state, useful for understanding dependencies, status, and build counts.
 
-    return value; // Initial value returned by the factory
-  },
-  scope: ArtifactScopes.Singleton,
+```typescript
+const debugNodes = container.debugInfo();
+debugNodes.forEach(node => {
+  console.log(`\nID: ${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(`  Build Count: ${node.buildCount}`);
 });
+```
 
-container.register({
-  key: "consumer",
-  factory: async ({ use }) => {
-    // This artifact depends on the 'producer'
-    const producerValue = await use(({ require }) => require("producer"));
-    return `Consumed: ${producerValue}`;
-  },
-  scope: ArtifactScopes.Singleton,
-});
+### Retry Utility
 
-async function runStreamExample() {
-  const watcher = container.watch("consumer");
-  const receivedValues: string[] = [];
+The `Retry` class provides flexible retry logic for any async operation, supporting various strategies.
 
-  const unsubscribe = watcher.subscribe((resolved) => {
-    if (resolved.instance && !receivedValues.includes(resolved.instance)) {
-      receivedValues.push(resolved.instance);
-      console.log(`Watcher: Received "${resolved.instance}"`);
-    }
-  });
+```typescript
+import { Retry, RetryExhaustedError, RetryPredicates } from '@asaidimu/utils-artifacts/retry';
 
-  // Initial resolve to kick-start the producer factory and stream
-  await container.resolve("consumer");
+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!';
+};
 
-  // Give enough time for the stream to run and emit all values
-  // (PRODUCER_LIMIT * PRODUCER_TIMEOUT) + some buffer for processing
-  await new Promise((res) => setTimeout(res, (PRODUCER_LIMIT * PRODUCER_TIMEOUT) + 100));
+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);
+    }
+  }
 
-  console.log('\n--- Stream Complete ---');
-  console.log('All received values:', receivedValues);
-  // Expected: ["Consumed: 0", "Consumed: 1", "Consumed: 2", "Consumed: 3"]
+  // 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
+      }
+    );
+  };
 
-  unsubscribe(); // Clean up the watcher
+  // const data = await fetchWithRetry('https://api.example.com/data');
 }
-
-runStreamExample();
+let retryAttempt = 0; // Used for demonstration purposes only
+runRetryExample();
 ```
 
-### Debugging Information
+### Concurrency Utilities (Once & Serializer)
 
-Use `container.debugInfo()` to inspect the current state of all registered artifacts within a container, including their status, direct dependencies (artifact-to-artifact and state), and dependents. This is an invaluable tool for understanding your application's dependency graph at runtime.
+`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.
 
 ```typescript
-import { ArtifactContainer, ArtifactScopes } from '@asaidimu/utils-artifacts';
-import { ReactiveDataStore } from '@asaidimu/utils-store';
-
-interface AppState {
-  configVersion: number;
+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';
+  };
+
+  const [res1, res2, res3] = await Promise.all([
+    initialization.do(expensiveInit),
+    initialization.do(expensiveInit),
+    initialization.do(expensiveInit),
+  ]);
+
+  console.log(res1.value, res2.value, res3.value); // All will be 'Initialized Resource'
+  // expensiveInit will be called only once.
 }
-
-const store = new ReactiveDataStore<AppState>({ configVersion: 1 });
-const container = new ArtifactContainer<any, AppState>(store);
-
-container.register({
-  key: 'configService',
-  factory: async ({ use }) => {
-    const version = await use((ctx) => ctx.select((state) => state.configVersion));
-    return `Config v${version}`;
-  },
-  scope: ArtifactScopes.Singleton,
-});
-
-container.register({
-  key: 'dataProcessor',
-  factory: async ({ use }) => {
-    const config = await use((ctx) => ctx.resolve('configService'));
-    return `Processing with ${config.instance}`;
-  },
-  scope: ArtifactScopes.Singleton,
-});
-
-container.register({
-  key: 'ephemeralTool',
-  factory: () => 'A transient tool',
-  scope: ArtifactScopes.Transient,
-});
-
-async function runDebugInfoExample() {
-  await container.resolve('dataProcessor'); // Resolve to build dependencies
-  await container.resolve('ephemeralTool'); // Resolve a transient (doesn't cache, but will show up if just resolved)
-
-  const debugInfo = container.debugInfo();
-  console.log('--- Artifact Debug Information ---');
-  debugInfo.forEach(node => {
-    console.log(`\nID: ${node.id}`);
-    console.log(`  Scope: ${node.scope}`);
-    console.log(`  Status: ${node.status}`);
-    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(`  Render Count: ${node.renderCount}`);
-    console.log('---');
-  });
-
-  // Example output for 'dataProcessor':
-  // ID: dataProcessor
-  //   Scope: singleton
-  //   Status: active
-  //   Dependencies (Artifacts): configService
-  //   Dependencies (State Paths): None
-  //   Dependents: None
-  //   Render Count: 1
+runOnceExample();
+
+async function runSerializerExample() {
+  const queue = new Serializer<string>();
+  const order: string[] = [];
+
+  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';
+  };
+
+  await Promise.all([
+    queue.do(task1),
+    queue.do(task2),
+    queue.do(task3),
+  ]);
+
+  console.log(order); // Expected: ['Task 1', 'Task 2', 'Task 3']
 }
-
-runDebugInfoExample();
+runSerializerExample();
 ```
 
 ---
 
-## 🏛️ Project Architecture
-
-The `@asaidimu/utils-artifacts` package is built around the central `ArtifactContainer` class, which orchestrates the lifecycle and dependencies of various "artifacts" (any component or value you register). It is designed to be modular and extensible, promoting maintainability and testability.
+## 🏗️ Project Architecture
 
-### Core Components
+The `ArtifactContainer` is designed with a modular architecture, delegating responsibilities to specialized internal components:
 
-*   **`ArtifactContainer`**: The public-facing entry point of the system. It orchestrates the registration, resolution, lifecycle management (`Singleton`/`Transient`), and reactive updates of all artifacts. It provides methods like `register`, `resolve`, `watch`, `invalidate`, and `debugInfo`.
-*   **`ArtifactRegistry`**: Manages the definitions of all registered artifacts, storing their factory functions and configuration options (scope, lazy loading, retries, debounce, timeout). It ensures unique keys and provides basic CRUD for artifact templates.
-*   **`ArtifactCache`**: Stores the runtime state of resolved `Singleton` artifacts, including their instances, errors, cleanup functions, state dependencies, and internal synchronization primitives (`Once`, `Serializer`). It's responsible for packaging cached data into the public `ResolvedArtifact` format, maintaining reference stability.
-*   **`ArtifactDependencyGraph`**: A specialized wrapper around a generic `DependencyGraph` that tracks artifact-to-artifact dependencies and state path dependencies. It's crucial for detecting circular dependencies, managing the dependency graph, and determining the cascade order during invalidation.
-*   **`ArtifactManager`**: The core engine responsible for the actual building, invalidation, and disposal of artifact instances. It interacts heavily with the `Registry`, `Cache`, `DependencyGraph`, and `DataStore`. It implements retry logic, timeouts, and manages lifecycle hooks (`onCleanup`, `onDispose`) and `ctx.stream` functionality.
-*   **`ArtifactObserverManager`**: Handles the creation and management of `ArtifactObserver` instances, allowing external code to subscribe to artifact changes. It also manages reference counting for watchers and notifies them of updates, including special handling for `Transient` artifacts to ensure they are watched via a temporary `Singleton` clone.
-*   **`DataStore` (External Dependency)**: The container relies on an external data store (e.g., `@asaidimu/utils-store`) to manage global application state. The container interacts with it via `watch` (for reactive subscriptions to state changes), `get` (for reading the current state), and `set` (allowing artifacts to dispatch state updates).
-*   **Synchronization Primitives (`Mutex`, `Once`, `Serializer`)**: These internal utilities (`src/artifacts/sync.ts`) provide robust mechanisms for managing concurrency, ensuring single execution of tasks, and processing operations sequentially. They are fundamental building blocks for the `ArtifactManager` and `ArtifactCache`.
-*   **Error Handling (`ArtifactError` hierarchy)**: A dedicated set of custom error classes (`src/artifacts/errors.ts`) provides clear, categorized error messages for system-level issues (e.g., circular dependencies, missing artifacts, illegal operations), simplifying debugging and error handling.
+*   **`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.
 
 ### Data Flow
 
-1.  **Registration (`container.register`)**: An `ArtifactTemplate` (containing an `ArtifactFactory` and its `options`) is stored in the `ArtifactRegistry`. A corresponding node is added to the `ArtifactDependencyGraph`.
-2.  **Resolution (`container.resolve` or `container.require`)**:
-    *   If the artifact is a `Singleton` and already built, its cached instance from `ArtifactCache` is returned.
-    *   If not built (or `Transient`), the `ArtifactManager` invokes the `ArtifactFactory` within a specialized `ArtifactFactoryContext`.
-    *   **Dependency Declaration (`ctx.use`)**: Inside the factory, `ctx.use` provides methods to declare dependencies:
-        *   `ctx.resolve(key)`/`ctx.require(key)`: Recursively triggers resolution of another artifact. The relationship is added to the `ArtifactDependencyGraph`.
-        *   `ctx.select(selector)`: Extracts specific state paths from the global `DataStore`. These paths are registered as state dependencies for the artifact.
-3.  **Dependency Graph Construction**: As dependencies are declared (via `ctx.resolve`/`ctx.require` or `ctx.select`), the `ArtifactDependencyGraph` constructs a precise, bidirectional graph, linking artifacts and their state dependencies.
-4.  **Reactive Invalidation**:
-    *   **State Changes**: When a `DataStore` value changes, `ArtifactManager` identifies affected `Singleton` artifacts (those subscribed to the changed state paths) and calls `container.invalidate()` for them.
-    *   **Artifact Changes**: When a `Singleton` artifact is rebuilt, explicitly `invalidate()`d, or proactively `stream()`s a new value, its direct and transitive `dependents` are identified by the `ArtifactDependencyGraph`, and `container.invalidate()` is called for each, cascading updates.
-5.  **Rebuild Process**: `container.invalidate()` triggers:
-    *   **Debouncing**: If configured (`debounce` option), rebuilds are debounced (`activeDebounceMs`) to consolidate multiple rapid invalidations, preventing excessive factory executions.
-    *   **Cleanup**: `onCleanup` hooks for the *old* instance are executed.
-    *   **New Instance**: The `ArtifactFactory` is re-executed by the `ArtifactManager`, creating a new instance.
-    *   **Graph Update**: The dependency graph is updated based on any *new* dependencies declared by the re-executed factory.
-    *   **Notification**: `ArtifactObserver` subscribers are notified of the new instance via `ArtifactObserverManager`.
-6.  **Streaming Updates (`ctx.stream`)**: If a `Singleton` artifact uses `ctx.stream`, subsequent `ctx.emit(value)` calls from within its factory:
-    *   Update the artifact's cached instance in `ArtifactCache`.
-    *   Increment the artifact's internal version.
-    *   Trigger `invalidate()` on all its dependents and `notifyObservers()`, effectively propagating the streamed value reactively.
-7.  **Disposal (`container.dispose` / `container.unregister`)**: All resources associated with an artifact (`onDispose` hooks, state subscriptions, cache entry, graph links) are released. Full container disposal clears everything.
+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**. By implementing custom factories, you can:
-*   Integrate with any third-party library or framework (e.g., database clients, API wrappers, authentication services).
-*   Define complex business logic that reacts to state or other services.
-*   Manage external resources like database connections, API clients, or message queues, ensuring they are properly initialized and cleaned up using `onCleanup` and `onDispose`.
-*   Provide custom logging, monitoring, or telemetry by injecting those services as dependencies.
+The primary extension point is the `ArtifactFactory` function itself, which receives the `ArtifactFactoryContext`. This context allows artifacts to:
 
-The `ArtifactContainer` itself is designed to be highly configurable via `ArtifactTemplate` options, allowing fine-tuning of scope, lazy loading, error handling, and reactive behavior.
+*   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.
 
 ---
 
-## 👨‍💻 Development & Contributing
-
-We welcome contributions! Please read the guidelines below.
+## 🛠️ Development & Contributing
 
 ### Development Setup
 
-1.  **Clone the repository**:
+To set up the project for local development:
+
+1.  **Clone the repository:**
     ```bash
     git clone https://github.com/asaidimu/erp-utils.git
-    cd erp-utils/src/artifacts # Navigate to this package's directory
+    cd erp-utils/src/artifacts
     ```
-2.  **Install dependencies**:
+2.  **Install dependencies:**
     ```bash
-    bun install
-    # or npm install
-    # or yarn install
+    npm install
+    # or
+    yarn install
     ```
-3.  **Build (if necessary for changes outside `src`)**:
+3.  **Build the project (if applicable, though typically handled by IDE/watch mode):**
     ```bash
-    bun run build
+    npm run build # Or `tsc` if not defined in package.json scripts
     ```
 
 ### Scripts
 
-The `package.json` for this package includes the following scripts:
+The `package.json` defines the following scripts:
 
-*   `bun install`: Installs project dependencies.
-*   `bun run test`: Runs the test suite using Vitest.
-*   `bun run test:watch`: Runs tests in watch mode for continuous feedback.
-*   `bun run test:browser`: Runs tests in a browser environment using Playwright.
-*   `bun run build`: Compiles the TypeScript source code into JavaScript.
+*   `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.
 
 ### Testing
 
-This project uses [Vitest](https://vitest.dev/) for testing, with support for browser-based tests via Playwright.
+The project uses `vitest` for testing.
 
-*   To run all tests:
-    ```bash
-    bun run test
-    ```
-*   To run tests in watch mode:
-    ```bash
-    bun run test --watch
-    ```
-*   To run tests in a browser environment:
-    ```bash
-    bun run test:browser
-    ```
-*   Ensure all new features or bug fixes are accompanied by appropriate unit and/or integration tests.
+*   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.
 
 ### Contributing Guidelines
 
-We appreciate your interest in contributing to `@asaidimu/utils-artifacts`!
-Please refer to the main repository's [CONTRIBUTING.md](https://github.com/asaidimu/erp-utils/blob/main/CONTRIBUTING.md) for detailed guidelines on:
+We welcome contributions! Please follow these guidelines:
 
-*   Reporting issues
-*   Submitting pull requests
-*   Coding standards
-*   Commit message conventions (we follow [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/))
+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
 
-Found a bug or have a feature request? Please open an issue on our [GitHub Issues page](https://github.com/asaidimu/erp-utils/issues).
-Provide as much detail as possible, including steps to reproduce, expected behavior, and your environment.
+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.
 
 ---
 
-## ➕ Additional Information
+## ℹ️ Additional Information
 
 ### Troubleshooting
 
-*   **`ArtifactNotFoundError`**: This typically means you're trying to `resolve` or `watch` an artifact that hasn't been `register`ed in the current container. Double-check your `key`s and registration calls.
-*   **`CircularDependencyError`**: Occurs when artifact A depends on B, and B depends back on A (directly or indirectly). This indicates a structural problem in your dependency graph. Redesign your artifacts to break the cycle. The error message will show the path of the cycle.
-*   **Artifact Not Updating Reactively**:
-    *   Ensure your artifact is a `Singleton` (Transient artifacts do not cache, react to invalidations, or support streaming).
-    *   Verify you are using `ctx.use()` and `ctx.select()` (for state dependencies) or `ctx.use(({ resolve }) => resolve('otherKey'))` (for artifact dependencies) inside your factory to properly declare dependencies.
-    *   Check that your `DataStore` implementation is correctly triggering its `watch` callbacks when state changes.
-*   **`IllegalScopeError`**: You might be trying to `stream` a value from a `Transient` artifact. The `stream` method is only meaningful for `Singleton` artifacts, which maintain a persistent, updateable instance.
-*   **`TimeoutError`**: Your artifact factory took longer than its configured `timeout` to complete, or an internal `Mutex` lock operation exceeded its timeout. Consider increasing the `timeout` in the artifact's `ArtifactTemplate` or optimizing your factory's logic.
-*   **`WatcherDisposedError`**: You are attempting to access a watcher's state (`watcher.get()`) after `watcher.dispose()` has been called. Ensure you unsubscribe from all callbacks (`unsubscribe()`) and dispose of watchers when no longer needed (`watcher.dispose()`), and avoid using them afterward.
+*   **`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.
 
 ### FAQ
 
-*   **What is an "artifact" in this context?**
-    An artifact is simply any JavaScript/TypeScript value, object, or function that you want the `ArtifactContainer` to manage. This could be a service, a repository, a configuration object, a computed value, or even a simple primitive.
-*   **Why use this over a simpler DI library?**
-    `@asaidimu/utils-artifacts` goes beyond basic DI by adding a powerful reactive layer. It automatically handles the propagation of changes from global state or other artifacts, making it easier to build self-updating components and reactive systems without manual subscription management.
-*   **When should I use `Singleton` vs. `Transient`?**
-    *   **Singleton**: For services, database connections, configuration objects, or any resource that should be shared and consistently available throughout your application. They are efficient as they are built once and reused, and they react to dependency changes.
-    *   **Transient**: For objects that need a fresh instance every time they are requested, such as temporary calculators, request-scoped contexts, or factory functions that produce unique, short-lived outputs. They do not react to dependencies or retain state.
-*   **How does `debounce` work?**
-    The `debounce` option (part of `ArtifactTemplate`) prevents a `Singleton` artifact from rebuilding too frequently. If multiple invalidations occur within the specified `debounce` time, they are consolidated, and the artifact's factory is only run once after the activity ceases (or after the last invalidation within the debounce window). This is crucial for performance with rapid state changes, especially when many state changes might trigger the same artifact rebuild.
+*   **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.
 
-### Changelog / Roadmap
+### Changelog/Roadmap
 
-*   **Changelog**: For a detailed list of changes, please refer to the [CHANGELOG.md](https://github.com/asaidimu/erp-utils/blob/main/CHANGELOG.md) file in the main repository.
-*   **Roadmap**: Future plans and upcoming features for `@asaidimu/utils-artifacts` are typically outlined in the main repository's [issue tracker](https://github.com/asaidimu/erp-utils/issues) or project boards.
+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
 
@@ -816,7 +742,4 @@ This project is licensed under the [MIT License](https://github.com/asaidimu/erp
 
 ### Acknowledgments
 
-*   Developed as part of the `@asaidimu` utilities collection.
-*   Leverages foundational packages like [`@asaidimu/utils-store`](https://www.npmjs.com/package/@asaidimu/utils-store) and `@asaidimu/events` within the `erp-utils` monorepo.
-*   Uses [Semantic Release](https://semantic-release.gitbook.io/semantic-release/) for automated versioning and publishing.
-*   Utilizes [Vitest](https://vitest.dev/) for fast and reliable testing.
+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.