@asaidimu/utils-artifacts 1.0.0

package/README.md

@@ -0,0 +1,799 @@
+# @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.
+
+[![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/utils/ci.yml?branch=main&style=flat-square)](https://github.com/asaidimu/utils/actions?query=workflow%3ACI)
+
+## 🚀 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)
+    *   [Yielding Intermediate Values](#yielding-intermediate-values)
+    *   [Hierarchical Containers](#hierarchical-containers)
+    *   [Debugging Information](#debugging-information)
+*   [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
+
+`@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.
+
+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 artifacts when their declared dependencies (other artifacts or global state slices) change.
+*   **Singleton & Transient Scopes**: Control whether an artifact is instantiated once and reused (`Singleton`) or created fresh on every request (`Transient`).
+*   **Hierarchical Containers**: Create child containers that can inherit and resolve artifacts from their parents, enabling scoped dependency trees.
+*   **State-Driven Invalidation with Debouncing**: Integrates with a `DataStore` to track state dependencies, triggering artifact rebuilds only when relevant state paths change, with configurable debouncing.
+*   **Fine-grained Dependency Tracking**: Explicitly declare dependencies on other artifacts using `ctx.resolve()` and on state slices using `ctx.select()`.
+*   **Robust Error Handling**: Built-in detection and specific error types for circular dependencies, missing artifacts, and illegal operations, distinguishing between `system` (structural) and `external` (runtime) errors.
+*   **Lifecycle Hooks**: Register `onCleanup` callbacks for instance-specific resource release and `onDispose` for final resource teardown.
+*   **Asynchronous Artifact Resolution**: Supports `async`/`await` in artifact factories, with configurable retries for external failures and timeouts.
+*   **`ArtifactWatcher` for Reactive Observation**: Observe changes to an artifact's resolved value over time, subscribing to updates without repeatedly resolving.
+*   **Live Updates via `yield()`**: Singleton artifacts can proactively update their value from within their factory, immediately notifying dependents and watchers.
+*   **Comprehensive Debugging Info**: `getDebugInfo()` provides a snapshot of the container's state, including artifact statuses, dependencies, and dependents.
+
+---
+
+## 📦 Installation & Setup
+
+### Prerequisites
+
+*   Node.js (v18 or higher recommended)
+*   A package manager like Bun, npm, or Yarn.
+*   An implementation of the `DataStore` interface for reactive state management. We highly recommend using [`@asaidimu/utils-store`](https://www.npmjs.com/package/@asaidimu/utils-store).
+
+### Installation Steps
+
+Install the package using your preferred package manager:
+
+```bash
+# With Bun
+bun add @asaidimu/utils-artifacts
+
+# With npm
+npm install @asaidimu/utils-artifacts
+
+# With Yarn
+yarn add @asaidimu/utils-artifacts
+```
+
+### Configuration
+
+To use the `ArtifactContainer`, you need to initialize it with an object that provides `get` and `watch` methods conforming to the `DataStore` interface. This allows the container to read the current application state and subscribe to state changes for reactive invalidation.
+
+If you're using `@asaidimu/utils-store` as your `DataStore`:
+
+```typescript
+import { ArtifactContainer, ArtifactScope } from '@asaidimu/utils-artifacts';
+import { ReactiveDataStore } from '@asaidimu/utils-store'; // Assuming this provides DataStore interface
+
+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]
+};
+
+const store = new ReactiveDataStore<AppState>(initialAppState);
+
+// Initialize the ArtifactContainer
+const container = new ArtifactContainer<Record<string, any>, AppState>(store);
+
+// Now you can start registering artifacts
+```
+
+### Verification
+
+You can verify the installation by trying to import and instantiate the `ArtifactContainer`:
+
+```typescript
+import { ArtifactContainer } from '@asaidimu/utils-artifacts';
+// Assuming a mock or real DataStore is available
+const mockStore = {
+  get: () => ({}),
+  watch: () => () => {},
+};
+const container = new ArtifactContainer(mockStore);
+console.log('ArtifactContainer initialized successfully!');
+// If no errors, the installation is successful.
+```
+
+---
+
+## 💡 Usage Documentation
+
+### Basic Artifacts (Singleton & Transient)
+
+Artifacts can be registered with different scopes, controlling their lifecycle.
+
+#### Singleton Scope
+
+A singleton artifact is created only once. Subsequent `resolve` calls return the same instance.
+
+```typescript
+import { ArtifactContainer, ArtifactScope } from '@asaidimu/utils-artifacts';
+import { ReactiveDataStore } from '@asaidimu/utils-store';
+
+const store = new ReactiveDataStore({});
+const container = new ArtifactContainer(store);
+
+let buildCount = 0;
+
+container.register({
+  key: 'mySingletonService',
+  factory: () => {
+    buildCount++;
+    console.log('Building mySingletonService...');
+    return {
+      name: 'SingletonService',
+      version: '1.0.0'
+    };
+  },
+  scope: ArtifactScope.Singleton,
+  lazy: false, // Build immediately on registration
+});
+
+async function runSingletonExample() {
+  const service1 = await container.resolve('mySingletonService');
+  const service2 = await container.resolve('mySingletonService');
+
+  console.log('Service 1:', service1.instance);
+  console.log('Service 2:', service2.instance);
+
+  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');
+
+  // Output:
+  // Building mySingletonService...
+  // Service 1: { name: 'SingletonService', version: '1.0.0' }
+  // Service 2: { name: 'SingletonService', version: '1.0.0' }
+}
+
+runSingletonExample();
+```
+
+#### Transient Scope
+
+A transient artifact creates a new instance every time it is resolved.
+
+```typescript
+import { ArtifactContainer, ArtifactScope } from '@asaidimu/utils-artifacts';
+import { ReactiveDataStore } from '@asaidimu/utils-store';
+
+const store = new ReactiveDataStore({});
+const container = new ArtifactContainer(store);
+
+container.register({
+  key: 'myTransientFactory',
+  factory: () => {
+    console.log('Building myTransientFactory...');
+    return {
+      id: Math.random().toString(36).substring(7),
+      timestamp: Date.now()
+    };
+  },
+  scope: ArtifactScope.Transient,
+});
+
+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');
+
+  // Output:
+  // Building myTransientFactory...
+  // Building myTransientFactory...
+  // Instance 1: { id: '...', timestamp: ... }
+  // Instance 2: { id: '...', timestamp: ... }
+}
+
+runTransientExample();
+```
+
+### Reactive State Dependencies
+
+Artifacts can react to changes in your global `DataStore` state by using `ctx.select()` within their factory's `use` block.
+
+```typescript
+import { ArtifactContainer, ArtifactScope } from '@asaidimu/utils-artifacts';
+import { ReactiveDataStore } from '@asaidimu/utils-store';
+
+interface AppState {
+  theme: 'dark' | 'light';
+  notificationsEnabled: boolean;
+}
+
+const store = new ReactiveDataStore<AppState>({
+  theme: 'dark',
+  notificationsEnabled: true,
+});
+const container = new ArtifactContainer<any, AppState>(store);
+
+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));
+
+    console.log(`UI Config Build ${uiComponentBuilds}: Theme=${theme}, Notifications=${notifications}`);
+    return { theme, notifications };
+  },
+  scope: ArtifactScope.Singleton,
+});
+
+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?.notificationsEnabled === 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
+}
+
+runReactiveStateExample();
+```
+
+### Artifact-to-Artifact Dependencies
+
+Artifacts can depend on other artifacts using `ctx.resolve()` within their factory's `use` block. Changes to a dependency will invalidate the dependent artifact.
+
+```typescript
+import { ArtifactContainer, ArtifactScope } from '@asaidimu/utils-artifacts';
+import { ReactiveDataStore } from '@asaidimu/utils-store';
+
+const store = new ReactiveDataStore({});
+const container = new ArtifactContainer(store);
+
+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: ArtifactScope.Singleton,
+});
+
+let userRepositoryBuilds = 0;
+container.register({
+  key: 'userRepository',
+  factory: async ({ use }) => {
+    userRepositoryBuilds++;
+    console.log(`Building UserRepository (${userRepositoryBuilds})...`);
+    const db = await use((ctx) => ctx.resolve('dbConnection'));
+    return {
+      dbClient: db.instance?.client,
+      findUser: (id: string) => `User ${id} from ${db.instance?.client}`
+    };
+  },
+  scope: ArtifactScope.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
+}
+
+runArtifactDependencyExample();
+```
+
+### Lifecycle Hooks: `onCleanup` & `onDispose`
+
+Artifacts can register cleanup functions to manage resources.
+
+*   `onCleanup`: Executed *before* a new instance of a `Singleton` artifact is built (due to invalidation) or when the artifact is explicitly unregistered. Ideal for releasing resources tied to a specific instance.
+*   `onDispose`: Executed *only* when the artifact is unregistered or the container itself is disposed. Ideal for final, permanent resource release.
+
+```typescript
+import { ArtifactContainer, ArtifactScope } 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',
+  factory: ({ onCleanup, onDispose }) => {
+    console.log('Ticker artifact created.');
+    let count = 0;
+    currentInterval = setInterval(() => {
+      count++;
+      console.log(`Tick: ${count}`);
+    }, 1000);
+
+    onCleanup(() => {
+      console.log('Cleaning up old Ticker instance (stopping interval)...');
+      clearInterval(currentInterval);
+    });
+
+    onDispose(() => {
+      console.log('Disposing Ticker artifact (final cleanup)...');
+      // Additional final cleanup could go here
+    });
+
+    return { start: Date.now() };
+  },
+  scope: ArtifactScope.Singleton,
+  lazy: false, // Eagerly build
+});
+
+async function runLifecycleHooksExample() {
+  await container.resolve('ticker');
+  console.log('Ticker running for 3 seconds...');
+  await new Promise(res => setTimeout(res, 3000));
+
+  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.');
+
+  // Output will show 'Cleaning up old Ticker instance' on invalidation,
+  // and 'Disposing Ticker artifact' on unregister.
+}
+
+runLifecycleHooksExample();
+```
+
+### Watching Artifacts for Changes
+
+The `watch()` 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.
+
+```typescript
+import { ArtifactContainer, ArtifactScope } from '@asaidimu/utils-artifacts';
+import { ReactiveDataStore } from '@asaidimu/utils-store';
+
+interface AppState {
+  counter: number;
+}
+
+const store = new ReactiveDataStore<AppState>({ counter: 0 });
+const container = new ArtifactContainer<any, AppState>(store);
+
+container.register({
+  key: 'reactiveCounter',
+  factory: async ({ use }) => {
+    const count = await use((ctx) => ctx.select((state) => state.counter));
+    return `Current count: ${count}`;
+  },
+  scope: ArtifactScope.Singleton,
+});
+
+async function runWatcherExample() {
+  console.log('Setting up watcher...');
+  const watcher = container.watch('reactiveCounter');
+
+  let unsubscribe = watcher.subscribe(() => {
+    const resolved = watcher.get();
+    if (resolved.ready) {
+      console.log('Watcher received update:', resolved.instance);
+    } else if (resolved.error) {
+      console.error('Watcher received error:', resolved.error);
+    } else {
+      console.log('Watcher received pending update (artifact not ready yet).');
+    }
+  });
+
+  // Initial state should trigger a notification (pending, then ready)
+  await new Promise(res => setTimeout(res, 10)); // Give watcher time to resolve
+
+  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--- Disposing watcher ---');
+  unsubscribe(); // Unsubscribe first
+  await watcher.dispose(); // Then dispose the watcher itself
+
+  // Output:
+  // Setting up watcher...
+  // Watcher received pending update (artifact not ready yet).
+  // Watcher received update: Current count: 0
+  //
+  // --- Incrementing counter ---
+  // Watcher received update: Current count: 1
+  //
+  // --- Incrementing counter again ---
+  // Watcher received update: Current count: 2
+  //
+  // --- Disposing watcher ---
+}
+
+runWatcherExample();
+```
+
+### Yielding Intermediate Values
+
+For long-running or multi-stage artifact factories, `ctx.yield()` allows a Singleton artifact to publish intermediate values. This updates the artifact's current instance and notifies dependents/watchers without fully completing the factory execution.
+
+```typescript
+import { ArtifactContainer, ArtifactScope } from '@asaidimu/utils-artifacts';
+import { ReactiveDataStore } from '@asaidimu/utils-store';
+
+const store = new ReactiveDataStore({});
+const container = new ArtifactContainer(store);
+
+container.register({
+  key: 'longProcessArtifact',
+    factory: async ({ yield: publish }) => {
+        async function process() {
+            console.log('Starting long process...');
+
+            publish('Step 1: Initializing...');
+            await new Promise(res => setTimeout(res, 100));
+
+            publish('Step 2: Loading data...');
+            await new Promise(res => setTimeout(res, 100));
+
+            publish('Step 3: Processing data...');
+            await new Promise(res => setTimeout(res, 100));
+
+            console.log('Long process complete.');
+        }
+
+        process()
+        return 'Created factory...';
+  },
+  scope: ArtifactScope.Singleton,
+});
+
+async function runYieldExample() {
+  const watcher = container.watch('longProcessArtifact');
+  const unsubscribe = watcher.subscribe(() => {
+    const resolved = watcher.get();
+    if (resolved.instance) {
+      console.log('Watcher observed yield:', resolved.instance);
+    }
+  });
+
+  await container.resolve('longProcessArtifact'); // Trigger the factory
+  console.log('Factory finished.');
+
+  unsubscribe();
+  await watcher.dispose();
+
+  // Output will show intermediate values from `yield` as they occur,
+  // then the final result once the factory completes.
+}
+
+runYieldExample();
+```
+
+### Hierarchical Containers
+
+Create child containers to manage dependencies in a nested, scoped manner. Child containers can resolve artifacts registered in their parent.
+
+```typescript
+import { ArtifactContainer, ArtifactScope } from '@asaidimu/utils-artifacts';
+import { ReactiveDataStore } from '@asaidimu/utils-store';
+
+const store = new ReactiveDataStore({});
+const parentContainer = new ArtifactContainer(store);
+
+parentContainer.register({
+  key: 'globalConfig',
+  factory: () => ({ logLevel: 'info', serverUrl: 'api.example.com' }),
+  scope: ArtifactScope.Singleton,
+});
+
+const childContainer = parentContainer.createChild();
+
+childContainer.register({
+  key: 'featureService',
+  factory: async ({ use }) => {
+    const config = await use((ctx) => ctx.resolve('globalConfig')); // Resolves from parent
+    return {
+      name: 'FeatureService',
+      apiUrl: `${config.instance?.serverUrl}/feature`
+    };
+  },
+  scope: ArtifactScope.Singleton,
+});
+
+async function runHierarchicalExample() {
+  const globalConfig = await parentContainer.resolve('globalConfig');
+  const featureService = await childContainer.resolve('featureService');
+
+  console.log('Global Config from parent:', globalConfig.instance);
+  console.log('Feature Service from child:', featureService.instance);
+
+  console.assert(globalConfig.instance?.logLevel === 'info', 'Parent artifact resolved');
+  console.assert(featureService.instance?.apiUrl === 'api.example.com/feature', 'Child resolved parent artifact');
+
+  // Output:
+  // Global Config from parent: { logLevel: 'info', serverUrl: 'api.example.com' }
+  // Feature Service from child: { name: 'FeatureService', apiUrl: 'api.example.com/feature' }
+}
+
+runHierarchicalExample();
+```
+
+### Debugging Information
+
+Use `getDebugInfo()` to inspect the current state of artifacts within a container, including their status, dependencies, and dependents.
+
+```typescript
+import { ArtifactContainer, ArtifactScope } from '@asaidimu/utils-artifacts';
+import { ReactiveDataStore } from '@asaidimu/utils-store';
+
+const store = new ReactiveDataStore({});
+const container = new ArtifactContainer(store);
+
+container.register({
+  key: 'serviceA',
+  factory: () => 'Service A Instance',
+  scope: ArtifactScope.Singleton,
+});
+
+container.register({
+  key: 'serviceB',
+  factory: async ({ use }) => {
+    await use((ctx) => ctx.resolve('serviceA'));
+    return 'Service B Instance';
+  },
+  scope: ArtifactScope.Singleton,
+});
+
+async function runDebugInfoExample() {
+  await container.resolve('serviceB'); // Resolve to build dependencies
+
+  const debugInfo = container.getDebugInfo();
+  console.log('--- Artifact Debug Information ---');
+  debugInfo.forEach(node => {
+    console.log(`ID: ${node.id}`);
+    console.log(`  Scope: ${node.scope}`);
+    console.log(`  Status: ${node.status}`);
+    console.log(`  Dependencies: ${node.dependencies.join(', ') || 'None'}`);
+    console.log(`  Dependents: ${node.dependents.join(', ') || 'None'}`);
+    console.log(`  Render Count: ${node.renderCount}`);
+    console.log('---');
+  });
+
+  // Example output for 'serviceB':
+  // ID: serviceB
+  //   Scope: singleton
+  //   Status: active
+  //   Dependencies: serviceA
+  //   Dependents: None
+  //   Render Count: 1
+}
+
+runDebugInfoExample();
+```
+
+---
+
+## 🏛️ 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).
+
+### Core Components
+
+*   **`ArtifactContainer`**: The heart of the system. It manages the registration, resolution, lifecycle (Singleton/Transient), and reactive updates of all artifacts. It can also create child containers to form a hierarchy.
+*   **`ArtifactDefinition`**: An internal representation of a registered artifact, holding its configuration (scope, lazy loading, retries, etc.) and runtime state (current instance, error, cleanup functions, dependency graph links).
+*   **`ArtifactFactory`**: A function that defines how an artifact instance is created. It receives an `ArtifactFactoryContext` which is crucial for declaring dependencies and managing its lifecycle.
+*   **`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) and `get` (for reading current state). The `buildPaths` function is used internally to derive specific state paths for granular dependency tracking.
+*   **`ArtifactWatcher`**: An observable interface for tracking the resolved state of an artifact over time, providing `get` for current value and `subscribe` for updates.
+
+### Data Flow
+
+1.  **Registration (`container.register`)**: An `ArtifactFactory` is associated with a `key` and `ArtifactOptions` (scope, lazy, retries, etc.).
+2.  **Resolution (`container.resolve`)**:
+    *   If the artifact is a `Singleton` and already built, the cached instance is returned.
+    *   If not built, the `ArtifactFactory` is invoked within a specialized context.
+    *   **Dependency Declaration (`ctx.use`)**: Inside the factory, `ctx.use` provides:
+        *   `ctx.resolve(key)`: Declares a dependency on another artifact. This call recursively triggers resolution of the dependency.
+        *   `ctx.select(selector)`: Declares a dependency on a slice of the global `DataStore` state. Internally, `buildPaths` extracts specific state paths from the selector.
+3.  **Dependency Graph Construction**: As dependencies are declared, the `ArtifactContainer` builds a precise, bidirectional dependency graph, linking artifacts to their dependents and subscribed state paths.
+4.  **Reactive Invalidation**:
+    *   **State Changes**: When a `DataStore` value changes, its `watch` callback is invoked. If the changed path matches an `ArtifactDefinition`'s `stateDependencies`, `container.invalidate()` is called for that artifact.
+    *   **Artifact Changes**: When an artifact is rebuilt or `yield()`s a new value, its `dependents` are identified and `container.invalidate()` is called for each.
+5.  **Rebuild Process**: `container.invalidate()` triggers:
+    *   **Debouncing**: If configured, rebuilds are debounced to consolidate multiple rapid invalidations into a single rebuild.
+    *   **Cleanup**: `onCleanup` hooks for the old instance are run.
+    *   **New Instance**: The `ArtifactFactory` is re-executed, creating a new instance.
+    *   **Graph Update**: The dependency graph is updated based on the new factory execution.
+    *   **Notification**: `ArtifactWatcher` subscribers are notified of the new instance.
+6.  **Disposal (`container.dispose` / `container.unregister`)**: All resources (`onDispose` hooks, state subscriptions, instance cache) are released.
+
+### Extension Points
+
+The primary extension point is the **`ArtifactFactory` function**. By implementing custom factories, you can:
+*   Integrate with any third-party library or framework.
+*   Define complex business logic.
+*   Manage external resources like database connections, API clients, or message queues.
+*   Provide custom logging, monitoring, or telemetry by injecting those services as dependencies.
+
+The `ArtifactContainer` itself is designed to be highly configurable via `ArtifactOptions`, allowing fine-tuning of scope, lazy loading, error handling, and reactive behavior.
+
+---
+
+## 👨‍💻 Development & Contributing
+
+We welcome contributions! Please read the guidelines below.
+
+### Development Setup
+
+1.  **Clone the repository**:
+    ```bash
+    git clone https://github.com/asaidimu/utils.git
+    cd utils/src/artifacts
+    ```
+2.  **Install dependencies**:
+    ```bash
+    bun install
+    # or npm install
+    # or yarn install
+    ```
+3.  **Build (if necessary for changes outside `src`)**:
+    ```bash
+    bun run build
+    ```
+
+### Scripts
+
+*   `bun install`: Installs project dependencies.
+*   `bun run test`: Runs the test suite using Vitest.
+*   `bun run build`: Compiles the TypeScript source code into JavaScript.
+
+### Testing
+
+This project uses [Vitest](https://vitest.dev/) for testing.
+
+*   To run all tests:
+    ```bash
+    bun run test
+    ```
+*   To run tests in watch mode:
+    ```bash
+    bun run test --watch
+    ```
+*   Ensure all new features or bug fixes are accompanied by appropriate unit and/or integration tests.
+
+### 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/utils/blob/main/CONTRIBUTING.md) for detailed guidelines on:
+
+*   Reporting issues
+*   Submitting pull requests
+*   Coding standards
+*   Commit message conventions (we follow Conventional Commits)
+
+### Issue Reporting
+
+Found a bug or have a feature request? Please open an issue on our [GitHub Issues page](https://github.com/asaidimu/utils/issues).
+Provide as much detail as possible, including steps to reproduce, expected behavior, and your environment.
+
+---
+
+## ➕ Additional Information
+
+### Troubleshooting
+
+*   **`ArtifactNotFoundError`**: This typically means you're trying to `resolve` an artifact that hasn't been `register`ed in the current container or any of its parent containers. 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 don't cache or react to invalidations).
+    *   Verify you are using `ctx.use()` and `ctx.select()` (for state) or `ctx.resolve()` (for other artifacts) inside your factory to declare dependencies.
+    *   Check that your `DataStore` implementation is correctly triggering its `watch` callbacks.
+*   **`IllegalScopeError`**: You might be trying to `yield` a value from a `Transient` artifact. `yield` is only meaningful for `Singleton` artifacts, which maintain a persistent instance.
+*   **Timeout Errors**: Your artifact factory took longer than `timeoutMs` to complete. Consider increasing the `timeoutMs` or optimizing your factory's logic.
+
+### 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.
+    *   **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 outputs.
+*   **How does `debounce` work?**
+    `debounce` prevents an 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. This is crucial for performance with rapid state changes.
+
+### Changelog / Roadmap
+
+*   **Changelog**: For a detailed list of changes, please refer to the [CHANGELOG.md](https://github.com/asaidimu/utils/blob/main/CHANGELOG.md) file in the main repository.
+*   **Roadmap**: Future plans and upcoming features are typically outlined in the main repository's [issue tracker](https://github.com/asaidimu/utils/issues) or project boards.
+
+### License
+
+This project is licensed under the MIT License. See the [LICENSE](https://github.com/asaidimu/utils/blob/main/LICENSE) file for details.
+
+### Acknowledgments
+
+*   Developed as part of the `@asaidimu` utilities collection.
+*   Uses [Semantic Release](https://semantic-release.gitbook.io/semantic-release/) for automated versioning and publishing.
+*   Leverages [Vitest](https://vitest.dev/) for fast and reliable testing.
+