@asaidimu/utils-artifacts 8.2.4 → 8.2.6

package/README.md

@@ -1,715 +1,347 @@
 # @asaidimu/utils-artifacts
 
-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)
+Reactive dependency injection and lifecycle management for TypeScript applications.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Table of Contents
+
+1. [Overview](#overview)
+2. [Core Concepts](#core-concepts)
+3. [Quick Start](#quick-start)
+4. [Usage](#usage)
+   - [Registering Artifacts](#registering-artifacts)
+   - [Resolving Dependencies](# resolves-dependencies)
+   - [Streaming Artifacts](#streaming-artifacts)
+   - [Parameterized Artifacts](#parameterized-artifacts)
+   - [Lifecycle Management](#lifecycle-management)
+   - [Observing Artifacts](#observing-artifacts)
+5. [Architecture](#architecture)
+6. [Development](#development)
+7. [Testing](#testing)
+8. [API Reference](#api-reference)
 
 ---
 
-## 🚀 Quick Links
-
-- [Overview & Features](#-overview--features)
-- [Why Use This Library? (Power & Use Cases)](#-why-use-this-library-power--use-cases)
-- [Installation & Setup](#-installation--setup)
-- [Usage Documentation](#-usage-documentation)
-  - [Basic Usage](#basic-usage)
-  - [Registering Artifacts](#registering-artifacts)
-  - [Resolving & Requiring Artifacts](#resolving--requiring-artifacts)
-  - [Watching Artifact Changes](#watching-artifact-changes)
-  - [Reactive Dependencies (State Selection)](#reactive-dependencies-state-selection)
-  - [Artifact Lifecycle (Cleanup & Dispose)](#artifact-lifecycle-cleanup--dispose)
-  - [Streaming Artifacts](#streaming-artifacts)
-  - [Invalidating Artifacts](#invalidating-artifacts)
-  - [Debugging Artifacts](#debugging-artifacts)
-- [Project Architecture](#-project-architecture)
-- [Considerations & Potential Pitfalls](#-considerations--potential-pitfalls)
-- [Development & Contributing](#-development--contributing)
-- [Additional Information](#-additional-information)
-
----
-
-## ✨ Overview & Features
-
-`@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.
-
-### Key Features
-
-- **Declarative Dependency Injection (DI)**: Define artifact dependencies implicitly through factory context methods (`ctx.use`, `ctx.resolve`, `ctx.require`).
-- **Reactive State Management**: Automatically re-evaluate artifacts when slices of a global `DataStore` change via `ctx.select`, enabling highly reactive applications.
-- **Flexible Scoping**: Supports `Singleton` (single, cached instance) and `Transient` (new instance per resolution) artifact scopes.
-- **Advanced Lifecycle Management**: `onCleanup` for instance-specific resource release and `onDispose` for permanent artifact teardown.
-- **Streaming Artifacts**: Use `ctx.stream` to build long-lived artifacts that continuously emit new values, ideal for real-time data, web sockets, or periodic tasks.
-- **Robust Error Handling & Retries**: Integrated retry logic for resilient operations and a comprehensive `ArtifactError` hierarchy for clear diagnostics.
-- **Concurrency Primitives**: Internal utilities for managing race conditions and sequential execution of async operations.
-- **Debuggability**: `container.debugInfo()` provides a snapshot of the artifact graph, statuses, and dependencies for easy troubleshooting.
-- **Watcher API**: `container.watch()` allows external consumers to subscribe to artifact changes without directly resolving them.
-- **Circular Dependency Detection**: Prevents infinite loops during resolution by detecting and reporting cycles in the dependency graph.
-
----
-
-## 🚀 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.
+## 1. Overview
 
----
+`@asaidimu/utils-artifacts` is a high-performance TypeScript library for managing the lifecycle, dependencies, and reactivity of application components, referred to as **artifacts**.
 
-## 📦 Installation & Setup
+Unlike traditional Dependency Injection (DI) containers, this system implements a **Lazy-Resolution, Lazy-Invalidation** model. This ensures that components are created only when requested and are rebuilt only when their specific dependencies change, minimizing unnecessary re-computations and avoiding the manual orchestration of event listeners in the UI layer.
 
-### Prerequisites
+## 2. Core Concepts
 
-- 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).
+To use the library effectively, it is essential to understand the mental model of an artifact's lifecycle:
 
-### Installation Steps
+### The Artifact Lifecycle
 
-To install the library, use your preferred package manager:
+An artifact transitions through the following states:
 
-```bash
-npm install @asaidimu/utils-artifacts
-# or
-yarn add @asaidimu/utils-artifacts
-```
+- **Idle**: The artifact is registered but has not yet been resolved. No resources are consumed.
+- **Pending**: The factory function is currently executing (asynchronous resolution).
+- **Ready**: The artifact instance is available and cached.
+- **Invalidated**: A dependency change has occurred. The cached instance is marked as stale, but the artifact is not rebuilt immediately. It returns to the **Idle** state for the next `resolve()` call.
 
-### Configuration
+### Singleton vs. Transient
 
-`@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`.
+- **Singleton**: A single instance is shared across the entire container. Ideal for services, API clients, and shared state managers.
+- **Transient**: A fresh instance is created on every `resolve()` call. Ideal for lightweight utility functions or state transformations.
 
-### Verification
-
-You can verify the installation by attempting to import and register a basic artifact:
+## 3. Quick Start
 
 ```typescript
+import { ReactiveDataStore } from "@asaidimu/utils-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 };
 
-const store = new ReactiveDataStore<AppState>({ count: 0 });
-const container = new ArtifactContainer<AppRegistry, AppState>(store);
-
-container.register({
-  key: "myService",
-  factory: async ({ use }) => {
-    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");
-  console.log(service.instance); // Expected: Service is running with count: 0
+interface State {
+  count: number;
 }
 
-runExample();
-```
-
----
-
-## 📖 Usage Documentation
-
-### Basic Usage
-
-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'; // Assuming this is your state 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 Registry {
+  counterLabel: string;
 }
 
-interface AppRegistry {
-  logger: LoggerService;
-  apiClient: ApiClient;
-  themeService: 'light' | 'dark';
-  appInfo: string;
-}
-
-// Example DataStore (from @asaidimu/utils-store or similar)
-const appStore = new ReactiveDataStore<AppState>({
-  appName: 'My App',
-  version: '1.0.0',
-  config: {
-    theme: 'light',
-    apiUrl: 'https://api.example.com',
-  },
-});
-
-// 2. Instantiate the ArtifactContainer
-const container = new ArtifactContainer<AppRegistry, AppState>(appStore);
-
-// Mock services for demonstration
-class LoggerService {
-  constructor(private prefix: string) {}
-  log(message: string) {
-    console.log(`[${this.prefix}] ${message}`);
-  }
-}
-
-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
-  factory: () => new LoggerService('APP'),
-});
+const store = new ReactiveDataStore<State>({ count: 0 });
+const container = new ArtifactContainer<Registry, State>(store);
 
+// Register a reactive artifact
 container.register({
-  key: 'apiClient',
-  scope: ArtifactScopes.Singleton,
+  key: "counterLabel",
   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 {
-      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}` };
-      }
-    };
+    const count = await use((ctx) => ctx.select((s) => s.count));
+    return `The current count is ${count}`;
   },
 });
 
-container.register({
-  key: 'themeService',
-  scope: ArtifactScopes.Singleton,
-  factory: async ({ use }) => {
-    // Theme service depends directly on state
-    return await use(({ select }) => select(state => state.config.theme));
-  },
-});
+// Resolve the artifact
+const result = await container.resolve("counterLabel");
+console.log(result.instance); // "The current count is 0"
 
-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}`;
-  },
+// watch the artifact
+const observer = container.watch("counterLabel");
+observer.subscribe((result) => {
+  console.log(`Observed: ${result.instance}`); // "The current count is 0"
 });
 
-// 4. Resolve artifacts to use them
-async function main() {
-  const logger = await container.resolve('logger');
-  logger.instance?.log('Application started.');
-
-  const appInfo = await container.resolve('appInfo');
-  console.log(appInfo.instance); // Logs the app information after API call
-
-  // Example of reacting to state changes
-  console.log('
---- Changing theme ---');
-  await appStore.set(s => ({ ...s, config: { ...s.config, theme: 'dark' } }));
+// simulate state changes
+while (true) {
+  const { count } = store.get();
+  if (count === 10) {
+    break;
+  }
 
-  // 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
+  await new Promise((r) => setTimeout(r, 300));
+  store.set(({ count }) => ({ count: count + 1 }));
 }
 
-main();
+// TODO
+// add example operations for invalidate and calling cleanup
+// add more examples for complex artifact interactions
 ```
 
+## 4. Usage
+
 ### Registering Artifacts
 
-Use `container.register()` to define an artifact. Each artifact requires a unique `key` and a `factory` function.
+Artifacts are registered via an `ArtifactTemplate`. By default, artifacts are singletons and lazily instantiated.
 
 ```typescript
-import { ArtifactScopes, ArtifactTemplate } from "@asaidimu/utils-artifacts";
-
-// Define your app's state and registry types for better type safety
-interface MyAppState {
-  /* ... */
-}
-interface MyAppRegistry {
-  myService: string;
-}
-
-// 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, // 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.
+container.register({
+  key: "apiClient",
+  factory: () => new ApiClient(),
+  scope: "singleton",
+  lazy: true,
 });
 ```
 
-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> {
-  /** 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>;
-  /** 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> {
-  /** 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>>`. This union type represents the artifact's state: `ReadyArtifact`, `ErrorArtifact`, or `PendingArtifact`. Check `.ready` and `.error` properties for robust handling.
-- `container.require(key)`: Returns a `Promise<T>` directly. It throws an error if resolution fails. Use this when you expect success and prefer exception-based error handling.
-
-```typescript
-// Using resolve for defensive programming
-const myServiceResult = await container.resolve("myService");
-if (myServiceResult.ready) {
-  console.log("Service instance:", myServiceResult.instance);
-} else if (myServiceResult.error) {
-  console.error("Service failed:", myServiceResult.error);
-} else {
-  console.log("Service is pending or idle.");
-}
-
-// Using require for direct access when errors are handled upstream
-try {
-  const myServiceInstance = await container.require("myService");
-  console.log("Service instance:", myServiceInstance);
-} catch (error) {
-  console.error("Failed to get service:", error);
-}
-```
-
-### Watching Artifact Changes
+### Resolving Dependencies
 
-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.
+Use the `ctx.use` callback to declare dependencies on other artifacts or state slices. This is the mandatory method for the container to track the dependency graph and trigger invalidations.
 
 ```typescript
-const loggerWatcher = container.watch("logger");
+container.register({
+  key: "userService",
+  factory: async ({ use }) => {
+    // Dependency on another artifact
+    const client = await use((ctx) => ctx.require("apiClient"));
+    // Dependency on a slice of the global state
+    const config = await use((ctx) => ctx.select((s) => s.authConfig));
 
-const unsubscribe = loggerWatcher.subscribe((resolvedArtifact) => {
-  if (resolvedArtifact.ready) {
-    console.log("Logger updated:", resolvedArtifact.instance);
-  } else if (resolvedArtifact.error) {
-    console.error("Logger error:", resolvedArtifact.error);
-  }
-  // `get()` retrieves the current resolved artifact state without subscribing.
-  const currentLogger = loggerWatcher.get();
-  console.log("Current logger:", currentLogger.instance);
+    return new UserService(client, config);
+  },
 });
-
-// To stop listening for updates:
-// unsubscribe();
 ```
 
-### Reactive Dependencies (State Selection)
+### Streaming Artifacts
 
-Artifacts can automatically react to changes in your application's global state by using `ctx.select()` within the `use` callback.
+Singletons can emit multiple values over time. The container automatically notifies all dependents and observers upon every emission, triggering a cascading invalidation.
 
 ```typescript
-interface AppState {
-  user: { name: string; theme: "light" | "dark" };
-}
-interface AppRegistry {
-  userGreeting: string;
-}
-
-// Assume appStore is an instance of DataStore<AppState>
-const container = new ArtifactContainer<AppRegistry, AppState>(appStore);
-
 container.register({
-  key: "userGreeting",
-  factory: async ({ use }) => {
-    // This artifact will rebuild if appStore.user.theme changes.
-    const theme = await use(({ select }) =>
-      select((state) => state.user.theme),
-    );
-    const userName = await use(({ select }) =>
-      select((state) => state.user.name),
-    );
-    return `Hello, ${userName}! Your theme is ${theme}.`;
+  key: "socketData",
+  factory: ({ stream }) => {
+    stream(({ emit, signal }) => {
+      const socket = new WebSocket("...");
+      socket.onmessage = (e) => emit(e.data);
+
+      // IMPORTANT: Always use the signal to stop the stream
+      // when the artifact is invalidated or unregistered.
+      signal.addEventListener("abort", () => {
+        socket.close();
+      });
+
+      // If the stream is a loop, check signal.aborted in every iteration
+      // while (!signal.aborted) {
+      //   await someAsyncWork();
+      //   emit(result);
+      // }
+    });
+    return null; // Initial value
   },
 });
-
-// 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)
+### Parameterized Artifacts
 
-- `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).
+Define a `paramKey` to create distinct instances based on resolution parameters.
 
-```typescript
-container.register({
-  key: "resourceArtifact",
-  scope: ArtifactScopes.Singleton,
-  factory: ({ onCleanup, onDispose, use }) => {
-    const resourceId = Math.random();
-    console.log(`Resource ${resourceId} created.`);
-    const timerId = setInterval(
-      () => console.log(`Resource ${resourceId} heartbeat...`),
-      1000,
-    );
-
-    // Cleanup for the current instance (e.g., on rebuild or if transient)
-    onCleanup(() => {
-      console.log(`Cleaning up instance for resource ${resourceId}...`);
-      clearInterval(timerId);
-    });
+> **Critical Resource Management**
+> Parameterized singletons are cached indefinitely by default to ensure reactive consistency. In high-cardinality scenarios (e.g., resolving thousands of unique user IDs), this can lead to memory exhaustion over long application runtimes.
+>
+> **Best Practices for Resource Management**:
+>
+> 1. **Prefer `transient` scope**: If the artifact does not need to be shared across multiple consumers, use `scope: 'transient'` to avoid cache accumulation.
+> 2. **Manual Cleanup**: For `singleton` parameterized artifacts, invoke `container.unregister(key, params)` when the artifact is no longer needed (e.g., when a user logs out or a view is destroyed).
+> 3. **Monitor Cache**: If resolving dynamic, high-volume data, track the number of active parameter keys to ensure the container remains within memory constraints.
 
-    // Dispose for permanent removal from container
-    onDispose(() => {
-      console.log(
-        `Disposing artifact 'resourceArtifact' (resource ${resourceId}).`,
-      );
-      // Final resource release
-    });
+**Critical Note**: The `paramKey` function must be **deterministic**. The string returned by this function is the actual primary key used for caching and invalidation. If the function is non-deterministic or produces collisions, you will either lose caching benefits or accidentally invalidate unrelated instances of the same parameterized artifact.
 
-    return { id: resourceId };
+```typescript
+container.register({
+  key: "userProfile",
+  paramKey: (params) => `user:${params.id}`,
+  factory: async (ctx) => {
+    const { id } = ctx.params;
+    return fetchUser(id);
   },
 });
 
-async function lifecycleExample() {
-  await container.resolve("resourceArtifact"); // Instance created and logs "heartbeat..."
-  console.log("Artifact resolved.");
-
-  // Simulate invalidation: will trigger onCleanup for the current instance, then rebuild.
-  await container.invalidate("resourceArtifact");
-  console.log("Artifact invalidated and rebuilt.");
-
-  // Manually dispose the artifact and container
-  await container.unregister("resourceArtifact"); // Triggers onDispose
-  console.log("Artifact unregistered.");
-}
-lifecycleExample();
+// Resolves the cached singleton for user:123
+const user = await container.resolve("userProfile", { id: "123" });
 ```
 
-### Streaming Artifacts
+### Lifecycle Management
 
-For artifacts that continuously emit values (e.g., real-time data, streams), use `ctx.stream()`. This is only supported for `Singleton` artifacts.
+Explicitly manage the lifecycle of an artifact by using `onCleanup` and `onDispose` within the factory.
 
 ```typescript
 container.register({
-  key: "dataStream",
-  scope: ArtifactScopes.Singleton,
-  factory: ({ stream, onCleanup, use }) => {
-    let counter = 0;
-    let intervalId: ReturnType<typeof setInterval> | undefined;
-
-    stream(async ({ emit, signal, value }) => {
-      console.log("Data stream started...");
-      const logger = await use(({ require }) => require("logger")); // Example dependency
-      logger.log("Stream active. Emitting values.");
-
-      intervalId = setInterval(() => {
-        if (signal.aborted) {
-          console.log("Stream signal aborted. Clearing interval.");
-          clearInterval(intervalId);
-          return;
-        }
-        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);
-    });
+  key: "connection",
+  factory: async ({ onCleanup, onDispose }) => {
+    const conn = new Connection();
+    await conn.connect();
 
-    onCleanup(() => {
-      console.log("Cleaning up data stream instance...");
-      // Ensure interval is cleared if stream is aborted or rebuilt.
-      if (intervalId) clearInterval(intervalId);
-    });
+    onCleanup(() => conn.disconnect());
+    onDispose(() => conn.destroy());
 
-    return "Initial stream value"; // Initial value before first emission
+    return conn;
   },
 });
-
-async function streamExample() {
-  const watcher = container.watch("dataStream");
-  const unsubscribe = watcher.subscribe((art) => {
-    if (art.ready) console.log("Stream received:", art.instance);
-  });
-
-  // Keep alive for a few seconds to observe stream emissions
-  await new Promise((res) => setTimeout(res, 3000));
-  unsubscribe();
-  console.log("Stream watcher unsubscribed.");
-}
-streamExample();
 ```
 
-### Invalidating Artifacts
+### Observing Artifacts
 
-Manually trigger an artifact to rebuild and cascade invalidations to its dependents.
+Use `ArtifactObserver` (via `container.watch`) to bind the artifact's state to UI components or external monitors.
 
 ```typescript
-// 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);
-```
-
-### Debugging Artifacts
-
-The `container.debugInfo()` method provides a snapshot of the container's internal state, which is invaluable for understanding dependencies, status, and build counts.
+const observer = container.watch("userProfile", { id: "123" });
 
-```typescript
-const debugNodes = container.debugInfo();
-debugNodes.forEach((node) => {
-  console.log(`
-Artifact ID: ${node.id}`);
-  console.log(`  Scope: ${node.scope}`);
-  console.log(`  Status: ${node.status}`); // e.g., 'active', 'error', 'idle', 'building', 'pending', 'debouncing'
-  console.log(
-    `  Dependencies (Artifacts): ${node.dependencies.join(", ") || "None"}`,
-  );
-  console.log(
-    `  Dependencies (State Paths): ${node.stateDependencies.join(", ") || "None"}`,
-  );
-  console.log(`  Dependents: ${node.dependents.join(", ") || "None"}`);
-  console.log(`  Build Count: ${node.buildCount}`);
+observer.subscribe((resolved) => {
+  console.log("Artifact state changed:", resolved.ready);
+  if (resolved.ready) {
+    console.log("Instance available:", resolved.instance);
+  }
 });
 ```
 
----
-
-## 🏗️ Project Architecture
-
-The `@asaidimu/utils-artifacts` library is architected around a central `ArtifactContainer` that orchestrates several specialized internal components:
-
-- **`ArtifactContainer`**: The main public API. It aggregates and coordinates the other components, providing methods for registering, resolving, watching, invalidating, and disposing artifacts.
-- **`ArtifactRegistry`**: Stores the definitions (`ArtifactTemplate`s) for all artifacts. It maps artifact keys to their factories and configuration options.
-- **`ArtifactCache`**: Manages the lifecycle and instances of resolved artifacts. It stores singleton instances, tracks artifact versions, and caches results.
-- **`ArtifactDependencyGraph`**: Maintains the relationships between artifacts and their dependencies on global state paths. This graph is critical for detecting circular dependencies and for efficiently cascading invalidations.
-- **`ArtifactManager`**: The core engine responsible for artifact lifecycle management. It handles artifact building (executing factories), managing retries, timeouts, stream propagation, and the reactive invalidation process. It utilizes the other components for dependency resolution and state observation.
-- **`ArtifactObserverManager`**: Implements the `container.watch()` API. It manages subscriptions from external consumers, notifies them of artifact state changes, and tracks active watchers to manage lazy loading and resource cleanup.
-
-### Data Flow Example (Resolution & Reactivity)
-
-1.  **Registration**: An artifact (`key`, `factory`, `scope`, etc.) is registered with the `ArtifactRegistry`. The `ArtifactDependencyGraph` registers a node for this artifact.
-2.  **Resolution (`container.resolve`)**:
-    - The `ArtifactContainer` delegates to `ArtifactManager`.
-    - The `Manager` checks the `ArtifactCache`. If a `Singleton` is already built and valid, its instance is returned.
-    - If not cached or if an invalidation occurred, the `Manager` retrieves the artifact's `ArtifactTemplate` from the `Registry`.
-    - The `Manager` prepares the `ArtifactFactoryContext` and executes the artifact's `factory` function.
-    - **Dependency Declaration**:
-      - Inside the factory, `ctx.use(({ resolve/require }) => ...)` calls recursively trigger artifact resolution, updating the `ArtifactDependencyGraph`.
-      - `ctx.use(({ select }) => ...)` registers state path dependencies. The `Manager` sets up listeners on the `DataStore` for these paths.
-    - **Build Execution**: The `Manager` handles potential retries, timeouts, and cleanup logic.
-    - **Cache Update**: Upon successful build, the instance is stored in the `ArtifactCache`. The `ArtifactDependencyGraph` is updated with the artifact's declared dependencies.
-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.
+## 5. Architecture
 
----
-
-## 📜 Considerations & Potential Pitfalls
+`@asaidimu/utils-artifacts` implements a **Directed Acyclic Graph (DAG)** for dependency management using a **Pull-based Invalidation** model.
 
-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.
+### Troubleshooting Circular Dependencies
 
-### Debouncing Latency
+Circular dependencies occur when artifact A depends on B, and B depends on A, creating a cycle in the DAG. The container will detect this at runtime and throw a `SystemError`.
 
-- **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.
+**Common Remediation Strategies**:
 
-### Wasted Build Effort from Late Staleness Detection
+1. **Extract Shared Logic**: Identify the common dependency shared by both artifacts and move it into a third, independent base artifact.
+2. **Use Provider Pattern**: Refactor the shared behavior into a 'provider' artifact that both A and B can depend on without forming a loop.
+3. **Decompose Artifacts**: Break the circular logic into smaller, discrete units where one unit coordinates the interaction between the others.
 
-- **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.
+### Push vs. Pull Reactivity
 
-### Efficiency of Global State Watching
+In traditional reactive systems (Push model), a change in a source value immediately triggers a chain reaction of re-computations across all dependents. This often leads to "update storms" where a single state change causes dozens of immediate, synchronous re-renders or calculations, regardless of whether the result is actually needed at that moment.
 
-- **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.
+In contrast, this library uses a **Pull model**. When a state slice or source artifact emits a change, the container simply marks all downstream dependent artifacts as **Invalidated** (setting a stale flag). It does not execute any factories. No work is performed until a consumer actually calls `resolve()` or an observer is notified.
 
-### Startup Cost of Eager Loading
+This approach ensures that if a state value changes ten times in a single event loop, the dependent artifacts are only rebuilt **once**—the next time they are requested. This collapses multiple invalidations into a single, deferred rebuild, maximizing computational efficiency and reducing main-thread blocking.
 
-- **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.
+## 6. Development
 
-### Sequential Cleanup/Dispose Execution
-
-- **Observation**: Cleanup and dispose functions are executed sequentially. If an artifact has many dependencies with complex or time-consuming teardown routines, this sequential execution can slow down the overall teardown process for an artifact or the entire container.
-- **Recommendation**: For artifacts with numerous or computationally intensive cleanup tasks, evaluate if these tasks can be safely executed concurrently (e.g., using `Promise.all` within the cleanup/dispose logic) to improve teardown performance.
+```bash
+# Install dependencies
+bun install
 
-### Dependency Graph Complexity
+# Run unit tests
+bun test
 
-- **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.
+# Run tests in watch mode
+bun run test:watch
+```
 
----
+## 7. Testing
 
-## 🛠️ Development & Contributing
+The library is verified against a comprehensive suite including:
 
-### Development Setup
+- Resolution race condition prevention.
+- Circular dependency detection.
+- Circular dependency detection.
+- Stream lifecycle and AbortSignal compliance.
+- Parameterized invalidation cascades.
 
-1.  **Clone the repository:**
-    ```bash
-    git clone https://github.com/asaidimu/erp-utils.git
-    cd erp-utils/src/artifacts
-    ```
-2.  **Install dependencies:**
-    ```bash
-    npm install
-    # or
-    yarn install
-    ```
+## 8. API Reference
 
-### Scripts
+### ArtifactContainer
 
-- `npm test`: Runs all tests once.
-- `npm test:watch`: Runs tests in watch mode, rerunning on file changes.
+| Method                     | Description                                                                                                                                                          |
+| :------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `register(template)`       | Registers a new artifact template.                                                                                                                                   |
+| `resolve(key, params?)`    | Resolves the artifact. Returns a `ResolvedArtifact` object containing the `instance` and `ready` status.                                                             |
+| `require(key, params?)`    | Same as `resolve`, but returns the instance directly or throws if resolution if resolution fails.                                                                    |
+| `invalidate(key, params?)` | Manually trigger a rebuild of the artifact and its dependents.                                                                                                       |
+| `unregister(key, params?)` | Removes the artifact from the registry. If `params` is omitted, the entire template is removed; if provided, only the specific virtual artifact instance is removed. |
 
-### Testing
+### ArtifactObserver
 
-The project uses `vitest` for testing. All new code should be accompanied by tests.
+| Method                        | Description                                                                                                 |
+| :---------------------------- | :---------------------------------------------------------------------------------------------------------- |
+| `get()`                       | Returns the current cached snapshot of the artifact.                                                        |
+| `subscribe(callback, eager?)` | Subscribes to changes. The callback is invoked whenever the artifact state changes (Ready, Error, Pending). |
+| `resolve()`                   | Manually triggers the resolution of the artifact if it is currently idle.                                   |
 
-### Contributing Guidelines
+### ArtifactFactoryContext
 
-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.
+| Method                | Description                                                                                                                        |
+| :-------------------- | :--------------------------------------------------------------------------------------------------------------------------------- |
+| `use(callback)`       | The primary method for declaring dependencies. Any `resolve` or `select` calls inside the callback are registered as dependencies. |
+| `onCleanup(cleanup)`  | Registers a function to be executed before the artifact is rebuilt or disposed.                                                    |
+| `onDispose(callback)` | Registers a function to be executed be executed before the artifact is permanently removed.                                        |
+| `stream(callback)`    | Initializes a streaming process for a Singleton artifact.                                                                          |
+| `state()`             | Returns a non-reactive read of the current global state.                                                                           |
 
----
+### ArtifactTemplate
 
-## ℹ️ Additional Information
+| Method     | Description                                                             |
+| :--------- | :---------------------------------------------------------------------- |
+| `key`      | Unique identifier for the artifact.                                     |
+| `factory`  | The factory function that creates the artifact instance.                |
+| `scope`    | `singleton` (default) or `transient`.                                   |
+| `lazy`     | If `true` (default), the artifact is built only when requested.         |
+| `timeout`  | Maximum time allowed for the factory to complete.                       |
+| `retries`  | Number of times to retry the factory on failure.                        |
+| `debounce` | Base debounce time in milliseconds for invalidation events to collapse. |
+| `paramKey` | Function to generate a unique key for parameterized artifacts.          |
 
-### Troubleshooting
+### ResolvedArtifact
 
-- **`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.
+| Property   | Description                                                                          |
+| :--------- | :----------------------------------------------------------------------------------- |
+| `instance` | The resolved artifact instance. Available only when `ready` is true.                 |
+| `ready`    | Boolean indicating if the artifact is resolved and available for use.                |
+| `error`    | The error caught during the factory execution. Available only when `ready` is false. |
 
-### FAQ
+#### Error Handling & Recovery
 
-- **`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.
+Since `ResolvedArtifact` is a discriminated union, you can safely narrow the type of the instance or the error by checking the `ready` flag:
 
----
+```typescript
+const artifact = await container.resolve("userProfile");
 
-### License
+if (artifact.ready) {
+  // Type is narrowed to ReadyArtifact: instance is available
+  console.log(artifact.instance);
+} else {
+  // Type is narrowed to ErrorArtifact: error is available
+  console.error("Failed to resolve artifact:", artifact.error);
 
-This project is licensed under the [MIT License](https://github.com/asaidimu/erp-utils/blob/main/LICENSE).
+  // Optionally trigger a manual rebuild to recover from transient failures
+  // await container.invalidate("userProfile");
+}
+```
 
-### Acknowledgments
+### ArtifactStreamContext
 
-This library is part of the `@asaidimu/erp-utils` monorepository and relies on a compatible `DataStore` implementation for reactive state management.
+| Method | Description |
+| { "type": "text", "text": "| `emit(value)` | Emits a new value, triggering invalidation of dependents. |
+| `set(update)` | Dispatches a state update to the global store. |
+| `signal` | AbortSignal to stop the stream. |