@asaidimu/utils-store 2.3.2 → 4.0.0

package/README.md

@@ -1,8 +1,8 @@
 # `@asaidimu/utils-store`
 
-**A Reactive Data Store for TypeScript Applications**
+**A Type-Safe Reactive Data Store for TypeScript Applications**
 
-A comprehensive, type-safe, and reactive state management library for TypeScript applications, featuring robust middleware, transactional updates, deep observability, and an optional persistence layer. It simplifies complex state interactions by promoting immutability, explicit updates, and a modular design.
+A comprehensive, type-safe, and reactive state management library for TypeScript applications, featuring robust middleware, atomic transactions, dependency injection for services (artifacts), deep observability, and an optional persistence layer. It simplifies complex state interactions by promoting immutability, explicit updates, and a modular design.
 
 [![npm version](https://img.shields.io/npm/v/@asaidimu/utils-store?style=flat-square)](https://www.npmjs.com/package/@asaidimu/utils-store)
 [![License](https://img.shields.io/npm/l/@asaidimu/utils-store?style=flat-square)](https://github.com/asaidimu/erp-utils/blob/main/LICENSE)
@@ -16,9 +16,13 @@ A comprehensive, type-safe, and reactive state management library for TypeScript
 - [Installation & Setup](#installation--setup)
 - [Usage Documentation](#usage-documentation)
   - [Basic Usage](#basic-usage)
+  - [Actions & Dispatch](#actions--dispatch)
+  - [Reactive Selectors](#reactive-selectors)
   - [Persistence Integration](#persistence-integration)
   - [Middleware System](#middleware-system)
   - [Transaction Support](#transaction-support)
+  - [Artifacts (Dependency Injection)](#artifacts-dependency-injection)
+  - [React Integration](#react-integration)
   - [Store Observer (Debugging & Observability)](#store-observer-debugging--observability)
   - [Event System](#event-system)
 - [Project Architecture](#project-architecture)
@@ -31,25 +35,30 @@ A comprehensive, type-safe, and reactive state management library for TypeScript
 
 `@asaidimu/utils-store` is a powerful and flexible state management solution designed for modern TypeScript applications. It provides a highly performant and observable way to manage your application's data, ensuring type safety and predictability across complex state interactions. Built on principles of immutability and explicit updates, it makes state changes easy to track, debug, and extend.
 
-This library offers robust tools to handle your state with confidence, enabling features like atomic transactions, a pluggable middleware pipeline, and deep runtime introspection for unparalleled debugging capabilities. It emphasizes a component-based design internally, allowing for clear separation of concerns for core state management, middleware processing, persistence, and observability.
+This library offers robust tools to handle your state with confidence, enabling features like atomic transactions, a pluggable middleware pipeline, a powerful dependency injection system for services (artifacts), and deep runtime introspection for unparalleled debugging capabilities. It emphasizes a component-based design internally, allowing for clear separation of concerns for core state management, middleware processing, persistence, and observability.
 
 ### Key Features
 
 *   📊 **Type-safe State Management**: Full TypeScript support for defining and interacting with your application state, leveraging `DeepPartial<T>` for precise, structural updates while maintaining strong type inference.
 *   🔄 **Reactive Updates & Granular Subscriptions**: Subscribe to granular changes at specific paths within your state or listen for any change, ensuring efficient re-renders or side effects. The internal `diff` algorithm optimizes notifications by identifying only truly changed paths.
+*   🚀 **Action System**: Dispatch named actions to encapsulate state updates, improving code organization and enabling detailed logging and observability for each logical operation, including debouncing capabilities.
+*   🔍 **Reactive Selectors with Memoization**: Efficiently derive computed state from your store using reactive selectors that re-evaluate and notify subscribers only when their accessed paths actually change, preventing unnecessary renders.
 *   🧠 **Composable Middleware System**:
     *   **Transform Middleware**: Intercept, modify, normalize, or enrich state updates before they are applied. These can return a `DeepPartial<T>` to apply further changes or `void` for side effects.
     *   **Blocking Middleware**: Implement custom validation, authorization, or other conditional logic to prevent invalid state changes from occurring. If a blocking middleware returns `false` or throws an error, the update is immediately halted and rolled back.
 *   📦 **Atomic Transaction Support**: Group multiple state updates into a single, atomic operation. If any update within the transaction fails or an error is thrown, the entire transaction is rolled back to the state before the transaction began, guaranteeing data integrity. Supports both synchronous and asynchronous operations.
-*   💾 **Optional Persistence Layer**: Seamlessly integrate with any `SimplePersistence<T>` implementation (e.g., for local storage, IndexedDB, or backend synchronization) to load an initial state and save subsequent changes. The store emits a `persistence:ready` event and listens for external updates.
-*   🔍 **Deep Observer & Debugging (`StoreObserver`)**: An optional but highly recommended class for unparalleled runtime introspection and debugging:
-    *   **Comprehensive Event History**: Captures a detailed log of all internal store events (`update:start`, `middleware:complete`, `transaction:error`, `persistence:ready`, `middleware:executed`, etc.).
+*   💾 **Optional Persistence Layer**: Seamlessly integrate with any `SimplePersistence<T>` implementation (e.g., for local storage, IndexedDB, or backend synchronization) to load an initial state and save subsequent changes. The store emits a `persistence:ready` event and listens for external updates, handling persistence queueing and retries.
+*   🧩 **Artifacts (Dependency Injection)**: A flexible dependency injection system to manage services, utilities, or complex objects that your actions and other artifacts depend on. Supports `Singleton` (re-evaluated on dependencies change) and `Transient` (new instance every time) scopes, and reactive resolution using `use(({select, resolve}) => ...)` context. Handles dependency graphs and circular dependency detection.
+*   ⚛️ **React Integration**: Provides a `createStore` factory function that returns a custom React hook (`useStore`). This hook offers `select` (memoized selector hook), `actions` (bound action dispatchers), and `resolve` (reactive artifact resolver) for seamless integration with React components. It leverages React's `useSyncExternalStore` for optimal performance.
+*   👀 **Deep Observer & Debugging (`StoreObserver`)**: An optional but highly recommended class for unparalleled runtime introspection and debugging:
+    *   **Comprehensive Event History**: Captures a detailed log of all internal store events (`update:start`, `middleware:complete`, `transaction:error`, `persistence:ready`, `middleware:executed`, `action:start`, `selector:accessed`, etc.).
     *   **State Snapshots**: Maintains a configurable history of your application's state over time, allowing for easy inspection of changes between updates and post-mortem analysis.
     *   **Time-Travel Debugging**: Leverage the recorded state history to `undo` and `redo` state changes, providing powerful capabilities for debugging complex asynchronous flows and state transitions.
     *   **Performance Metrics**: Track real-time performance indicators like total update count, listener executions, average update times, largest update size, and slow operation warnings to identify bottlenecks.
     *   **Configurable Console Logging**: Provides human-readable, color-coded logging of store events directly to the browser console for immediate feedback during development.
     *   **Pre-built Debugging Middlewares**: Includes helper methods to easily create a generic logging middleware and a validation middleware for immediate use.
-*   🗑️ **Property Deletion**: Supports explicit property deletion within partial updates using the global `Symbol.for("delete")`or a custom marker.
+    *   **Session Management**: Save and load observer sessions for offline analysis or sharing bug reproductions.
+*   🗑️ **Property Deletion**: Supports explicit property deletion within partial updates using the global `Symbol.for("delete")` or a custom marker.
 *   ⚡ **Concurrency Handling**: Automatically queues and processes `set` updates to prevent race conditions during concurrent calls, ensuring updates are applied in a predictable, sequential order.
 
 ---
@@ -72,7 +81,8 @@ yarn add @asaidimu/utils-store
 ### Prerequisites
 
 *   **Node.js**: (LTS version recommended) for development and compilation.
-*   **TypeScript**: (v4.0+ recommended) for full type-safety during development.
+*   **TypeScript**: (v4.0+ recommended) for full type-safety during development. Modern TS features (ES2017+ for `async/await`, ES2020+ for `Symbol.for()` and `structuredClone()`) are utilized. `moduleResolution`: `Node16` or `Bundler` is recommended in `tsconfig.json`.
+*   **React**: (v16.8+ for hooks) if using the `@asaidimu/utils-store/react` integration.
 
 ### Verification
 
@@ -90,12 +100,12 @@ interface MyState {
 const store = new ReactiveDataStore<MyState>({ count: 0, message: "Hello" });
 
 // Subscribing to "count" will only log when 'count' path changes
-store.subscribe("count", (state) => {
+store.watch("count", (state) => {
   console.log(`Count changed to: ${state.count}`);
 });
 
 // Subscribing to "" (empty string) will log for any store update
-store.subscribe("", (state) => {
+store.watch("", (state) => {
     console.log(`Store updated to: ${JSON.stringify(state)}`);
 });
 
@@ -133,14 +143,14 @@ This section provides practical examples and detailed explanations of how to use
 Learn how to create a store, read state, and update state with partial objects or functions.
 
 ```typescript
-import { ReactiveDataStore, type DeepPartial } from '@asaidimu/utils-store';
+import { ReactiveDataStore, DELETE_SYMBOL, type DeepPartial } from '@asaidimu/utils-store';
 
 // 1. Define your state interface for type safety
 interface AppState {
   user: {
     id: string;
     name: string;
-    email: string;
+    email?: string; // email is optional as we'll delete it
     isActive: boolean;
   };
   products: Array<{ id: string; name: string; price: number }>;
@@ -223,21 +233,21 @@ console.log('State after functional update, products count:', store.get().produc
 
 // 6. Subscribing to state changes
 // You can subscribe to the entire state (path: '') or specific paths (e.g., 'user.name', 'settings.notificationsEnabled').
-const unsubscribeUser = store.subscribe('user', (state) => {
+const unsubscribeUser = store.watch('user', (state) => {
   console.log('User data changed:', state.user);
 });
 
-const unsubscribeNotifications = store.subscribe('settings.notificationsEnabled', (state) => {
+const unsubscribeNotifications = store.watch('settings.notificationsEnabled', (state) => {
   console.log('Notifications setting changed:', state.settings.notificationsEnabled);
 });
 
 // Subscribe to multiple paths at once
-const unsubscribeMulti = store.subscribe(['user.name', 'products'], (state) => {
+const unsubscribeMulti = store.watch(['user.name', 'products'], (state) => {
   console.log('User name or products changed:', state.user.name, state.products.length);
 });
 
 // Subscribe to any change in the store (root listener)
-const unsubscribeAll = store.subscribe('', (state) => {
+const unsubscribeAll = store.watch('', (state) => {
   console.log('Store updated (any path changed). Current products count:', state.products.length);
 });
 
@@ -264,31 +274,238 @@ await store.set({ user: { isActive: true } });
 // No console output from the above listeners after unsubscribing.
 
 // 8. Deleting properties
-// Use `Symbol.for("delete")` to explicitly remove a property from the state.
-// Note: You might need a type cast (e.g., `as DeepPartial<string>`) for TypeScript if strict type checking is enabled.
-const DELETE_ME = Symbol.for("delete");
+// Use `DELETE_SYMBOL` (exported from the library) to explicitly remove a property from the state.
 await store.set({
   user: {
-    email: DELETE_ME as DeepPartial<string> // Cast is needed for type inference
+    email: DELETE_SYMBOL as DeepPartial<string> // Type cast is needed for strict TypeScript environments
   }
 });
 console.log('User email after deletion:', store.get().user.email);
 // Output: User email after deletion: undefined
 ```
 
+### Actions & Dispatch
+
+The `dispatch` method allows you to encapsulate state updates into named actions. This improves code organization, provides clear semantic meaning to updates, and enables detailed logging and observability through `StoreObserver` and the event system. Actions can also be debounced to prevent excessive updates.
+
+```typescript
+import { ReactiveDataStore } from '@asaidimu/utils-store';
+
+interface CounterState {
+  value: number;
+  history: string[];
+}
+
+const store = new ReactiveDataStore<CounterState>({ value: 0, history: [] });
+
+// 1. Register an action
+store.register({
+  name: 'incrementCounter',
+  fn: (state, amount: number) => ({ // Action function receives state and dispatched parameters
+    value: state.value + amount,
+    history: [...state.history, `Incremented by ${amount} at ${new Date().toLocaleTimeString()}`],
+  }),
+});
+
+// 2. Register an action with debounce
+store.register({
+  name: 'incrementCounterDebounced',
+  fn: (state, amount: number) => ({
+    value: state.value + amount,
+    history: [...state.history, `Debounced Increment by ${amount} at ${new Date().toLocaleTimeString()}`],
+  }),
+  debounce: {
+    delay: 100, // Debounce for 100ms
+    // Optional: condition to decide whether to debounce.
+    // Here, we always debounce if `amount` is different from previous.
+    condition: (previousArgs, currentArgs) => previousArgs?.[0] !== currentArgs[0],
+  }
+});
+
+// 3. Register an async action
+store.register({
+  name: 'loadInitialValue',
+  fn: async (state, userId: string) => {
+    console.log(`Simulating loading initial value for user: ${userId}`);
+    await new Promise(resolve => setTimeout(resolve, 200)); // Simulate API call
+    return {
+      value: 100, // Fetched value
+      history: [...state.history, `Loaded initial value for ${userId}`],
+    };
+  },
+});
+
+// 4. Dispatch actions
+console.log('Initial value:', store.get().value); // 0
+
+await store.dispatch('incrementCounter', 5);
+console.log('Value after incrementCounter(5):', store.get().value); // 5
+
+await store.dispatch('incrementCounter', 10);
+console.log('Value after incrementCounter(10):', store.get().value); // 15
+
+// Dispatch debounced actions multiple times quickly
+store.dispatch('incrementCounterDebounced', 1);
+store.dispatch('incrementCounterDebounced', 2);
+store.dispatch('incrementCounterDebounced', 3);
+console.log('Value after immediate debounced dispatches (still 15, waiting for debounce):', store.get().value);
+
+// Wait for the debounce to complete
+await new Promise(resolve => setTimeout(150, resolve));
+console.log('Value after debounced dispatches settled (only last one applied):', store.get().value); // 15 + 3 = 18
+
+// Dispatch an async action
+await store.dispatch('loadInitialValue', 'user-abc');
+console.log('Value after loadInitialValue:', store.get().value); // 100 (overwritten by fetched value)
+console.log('History:', store.get().history);
+
+// 5. Deregister an action
+const deregisterRisky = store.register({
+  name: 'riskyAction',
+  fn: () => { throw new Error('Risky action!'); }
+});
+
+deregisterRisky(); // Action is now removed
+
+try {
+  await store.dispatch('riskyAction');
+} catch (error: any) {
+  console.error('Expected error when dispatching deregistered action:', error.message);
+}
+```
+
+### Reactive Selectors
+
+Reactive selectors provide an efficient way to derive computed data from your store. They automatically track their dependencies and will only re-evaluate and notify subscribers if the underlying data they access changes. This prevents unnecessary re-renders in UI frameworks.
+
+```typescript
+import { ReactiveDataStore } from '@asaidimu/utils-store';
+
+interface UserProfile {
+  firstName: string;
+  lastName: string;
+  email: string;
+  address: {
+    city: string;
+    zipCode: string;
+  };
+  isActive: boolean;
+  friends: string[];
+}
+
+const store = new ReactiveDataStore<UserProfile>({
+  firstName: 'John',
+  lastName: 'Doe',
+  email: 'john.doe@example.com',
+  address: {
+    city: 'New York',
+    zipCode: '10001',
+  },
+  isActive: true,
+  friends: ['Alice', 'Bob'],
+});
+
+// Create a reactive selector for the full name
+const selectFullName = store.select((state) => `${state.firstName} ${state.lastName}`);
+
+// Create a reactive selector for user's location
+const selectLocation = store.select((state) => `${state.address.city}, ${state.address.zipCode}`);
+
+// Create a reactive selector for user's active status
+const selectIsActive = store.select((state) => state.isActive);
+
+// Create a reactive selector for the number of friends
+const selectFriendCount = store.select((state) => state.friends.length);
+
+let lastFullName = '';
+let lastLocation = '';
+let lastIsActive = false;
+let lastFriendCount = 0;
+
+// Subscribe to the full name selector
+const unsubscribeFullName = selectFullName.subscribe((fullName) => {
+  lastFullName = fullName;
+  console.log('Full Name Changed:', lastFullName);
+});
+
+// Subscribe to the location selector
+const unsubscribeLocation = selectLocation.subscribe((location) => {
+  lastLocation = location;
+  console.log('Location Changed:', lastLocation);
+});
+
+// Subscribe to the active status selector
+const unsubscribeIsActive = selectIsActive.subscribe((isActive) => {
+  lastIsActive = isActive;
+  console.log('Is Active Changed:', lastIsActive);
+});
+
+// Subscribe to the friend count selector
+const unsubscribeFriendCount = selectFriendCount.subscribe((count) => {
+  lastFriendCount = count;
+  console.log('Friend Count Changed:', lastFriendCount);
+});
+
+
+// Get initial values
+lastFullName = selectFullName.get();
+lastLocation = selectLocation.get();
+lastIsActive = selectIsActive.get();
+lastFriendCount = selectFriendCount.get();
+console.log('Initial Full Name:', lastFullName);
+console.log('Initial Location:', lastLocation);
+console.log('Initial Is Active:', lastIsActive);
+console.log('Initial Friend Count:', lastFriendCount);
+
+
+console.log('\n--- Performing Updates ---');
+
+// Update first name (should trigger selectFullName)
+await store.set({ firstName: 'Jane' });
+// Output: Full Name Changed: Jane Doe
+
+await store.set({ lastName: 'Smith' }); // Should trigger selectFullName
+// Output: Full Name Changed: Jane Smith
+
+await store.set({ address: { city: 'Los Angeles' } }); // Should trigger selectLocation
+// Output: Location Changed: Los Angeles, 10001
+
+await store.set({ isActive: false }); // Should trigger selectIsActive
+// Output: Is Active Changed: false
+
+await store.set({ email: 'jane.smith@example.com' }); // Should NOT trigger any of the above selectors directly
+// No output from subscribed selectors
+
+await store.set((state) => ({ friends: [...state.friends, 'Charlie'] })); // Should trigger selectFriendCount
+// Output: Friend Count Changed: 3
+
+console.log('\n--- Current Values ---');
+console.log('Current Full Name:', selectFullName.get());
+console.log('Current Location:', selectLocation.get());
+console.log('Current Is Active:', selectIsActive.get());
+console.log('Current Friend Count:', selectFriendCount.get());
+
+// Cleanup
+unsubscribeFullName();
+unsubscribeLocation();
+unsubscribeIsActive();
+unsubscribeFriendCount();
+```
+
 ### Persistence Integration
 
-The `ReactiveDataStore` can integrate with any persistence layer that implements the `SimplePersistence<T>` interface. This allows you to load an initial state and automatically save subsequent changes. The store emits a `persistence:ready` event once the persistence layer has loaded any initial state.
+The `ReactiveDataStore` can integrate with any persistence layer that implements the `SimplePersistence<T>` interface. This allows you to load an initial state and automatically save subsequent changes. The store emits a `persistence:ready` event once the persistence layer has loaded any initial state. You can use `@asaidimu/utils-persistence` for concrete implementations or provide your own.
 
 ```typescript
 import { ReactiveDataStore, type StoreEvent } from '@asaidimu/utils-store';
+import { v4 as uuidv4 } from 'uuid'; // For generating unique instance IDs
 
 // Define the SimplePersistence interface (from `@asaidimu/utils-persistence` or your own)
 interface SimplePersistence<T extends object> {
-  get(): Promise<T | null>;
-  set(instanceId: string, state: T): Promise<boolean>;
-  subscribe(instanceId: string, listener: (state: T) => void): () => void;
-  // An unsubscribe method for the persistence layer is recommended but not enforced by this interface
+  get(): T | null | Promise<T | null>; // Can be synchronous or asynchronous
+  set(instanceId: string, state: T): boolean | Promise<boolean>; // Can be synchronous or asynchronous
+  subscribe?(instanceId: string, listener: (state: T) => void): () => void; // Optional: for external change detection
+  clear?(): boolean | Promise<boolean>; // Optional: for clearing persisted data
 }
 
 // Example: A simple in-memory persistence for demonstration
@@ -297,56 +514,63 @@ class InMemoryPersistence<T extends object> implements SimplePersistence<T> {
   private data: T | null = null;
   // Using a map to simulate different instances subscribing to common data
   private subscribers: Map<string, (state: T) => void> = new Map();
+  private uniqueStoreId: string; // Acts as the storageKey/store identifier
 
-  constructor(initialData: T | null = null) {
+  constructor(uniqueStoreId: string, initialData: T | null = null) {
+      this.uniqueStoreId = uniqueStoreId;
       this.data = initialData;
   }
 
-  async get(): Promise<T | null> {
-    console.log('Persistence: Loading state...');
+  get(): T | null { // Synchronous get for simplicity
+    console.log(`Persistence [${this.uniqueStoreId}]: Loading state...`);
     return this.data ? structuredClone(this.data) : null;
   }
 
   async set(instanceId: string, state: T): Promise<boolean> {
-    console.log(`Persistence: Saving state for instance ${instanceId}...`);
+    console.log(`Persistence [${this.uniqueStoreId}]: Saving state for instance ${instanceId}...`);
     this.data = structuredClone(state); // Store a clone
     // Simulate external change notification for *other* instances
     this.subscribers.forEach((callback, subId) => {
       // Only notify other instances, not the one that just saved
       if (subId !== instanceId) {
-        callback(structuredClone(this.data!)); // Pass a clone to prevent mutation
+        // Ensure to queue the microtask for async notification to prevent synchronous re-entry issues
+        queueMicrotask(() => callback(structuredClone(this.data!))); // Pass a clone to prevent mutation
       }
     });
     return true;
   }
 
   subscribe(instanceId: string, callback: (state: T) => void): () => void {
-    console.log(`Persistence: Subscribing to external changes for instance ${instanceId}`);
+    console.log(`Persistence [${this.uniqueStoreId}]: Subscribing to external changes for instance ${instanceId}`);
     this.subscribers.set(instanceId, callback);
     return () => {
-      console.log(`Persistence: Unsubscribing for instance ${instanceId}`);
+      console.log(`Persistence [${this.uniqueStoreId}]: Unsubscribing for instance ${instanceId}`);
       this.subscribers.delete(instanceId);
     };
   }
 }
 
 interface UserConfig {
-  theme: 'light' | 'dark';
+  theme: 'light' | 'dark' | 'system';
   fontSize: number;
 }
 
 // Create a persistence instance, possibly with some pre-existing data
-const userConfigPersistence = new InMemoryPersistence<UserConfig>({ theme: 'dark', fontSize: 18 });
+// The 'my-user-config' string acts as the unique identifier for this particular data set in persistence
+const userConfigPersistence = new InMemoryPersistence<UserConfig>('my-user-config', { theme: 'dark', fontSize: 18 });
 
 // Initialize the store with persistence
 const store = new ReactiveDataStore<UserConfig>(
   { theme: 'light', fontSize: 16 }, // Initial state if no persisted data found (or if persistence is not used)
-  userConfigPersistence // Pass your persistence implementation here
+  userConfigPersistence, // Pass your persistence implementation here
+  // You can also pass persistence options like retries and delay
+  undefined, // Use default DELETE_SYMBOL
+  { persistenceMaxRetries: 5, persistenceRetryDelay: 2000 }
 );
 
 // Optionally, listen for persistence readiness (important for UIs that depend on loaded state)
 const storeReadyPromise = new Promise<void>(resolve => {
-  store.onStoreEvent('persistence:ready', (data) => {
+  store.on('persistence:ready', (data) => {
     console.log(`Store is ready and persistence is initialized! Timestamp: ${new Date(data.timestamp).toLocaleTimeString()}`);
     resolve();
   });
@@ -370,7 +594,7 @@ console.log('Current theme:', store.get().theme);
 // Simulate an external change (e.g., another tab or process updating the state)
 // Note: The `instanceId` here should be different from the store's `store.id()`
 // to simulate an external change and trigger the store's internal persistence subscription.
-await userConfigPersistence.set('another-instance-id-123', { theme: 'system', fontSize: 20 });
+await userConfigPersistence.set(uuidv4(), { theme: 'system', fontSize: 20 });
 // The store will automatically update its state and notify its listeners due to the internal subscription.
 console.log('Current theme after external update:', store.get().theme);
 // Output: Current theme after external update: system
@@ -442,8 +666,8 @@ store.use({
     if (typeof update.counter === 'number') {
       return { counter: state.counter + update.counter };
     }
-    // Return the original update or void if no transformation is needed for other paths
-    return update;
+    // Return the original update or undefined if no transformation is needed for other paths
+    return undefined;
   },
 });
 
@@ -453,7 +677,7 @@ Middleware: Incoming update: { counter: 5 }
 */
 console.log('State after counter set:', store.get());
 /* Output will show:
-  counter: 5 (initial) + 5 (update) = 10,
+  counter: 0 (initial) + 5 (update) = 5 (due to CounterIncrementMiddleware)
   lastAction updated by TimestampActionMiddleware,
   logs updated by TimestampActionMiddleware,
   version: 1 (incremented by VersionIncrementMiddleware)
@@ -474,7 +698,8 @@ console.log('State after manual action:', store.get());
 const temporaryLoggerId = store.use({ name: 'TemporaryLogger', action: (s, u) => console.log('Temporary logger saw:', u) });
 await store.set({ counter: 1 });
 // Output: Temporary logger saw: { counter: 1 }
-store.unuse(temporaryLoggerId); // Remove the temporary logger
+const removed = store.use({ name: 'TemporaryLogger', action: (s, u) => console.log('Temporary logger saw:', u) })(); // Remove the temporary logger
+console.log('Middleware removed:', removed);
 await store.set({ counter: 1 }); // TemporaryLogger will not be called now
 ```
 
@@ -643,6 +868,352 @@ try {
 }
 ```
 
+### Artifacts (Dependency Injection)
+
+The Artifact system provides a powerful way to manage external dependencies, services, or complex objects that your actions or other artifacts might need. It supports `Singleton` (created once, reactive to dependencies) and `Transient` (new instance every time) scopes, and allows artifacts to depend on state changes and other artifacts.
+
+This example uses the `ArtifactContainer` directly for clarity, but in React applications, you'd typically use the `createStore` factory, which automatically integrates with `ArtifactContainer` and exposes resolution via `useStore().resolve()`.
+
+```typescript
+import { ArtifactContainer, ArtifactScope } from '@asaidimu/utils-store/artifacts';
+
+interface AppState {
+    user: { id: string; name: string; };
+    config: { apiUrl: string; logLevel: string; };
+}
+
+// Mock DataStore interface for standalone ArtifactContainer usage
+let currentState: AppState = {
+    user: { id: 'user-1', name: 'Alice' },
+    config: { apiUrl: '/api/v1', logLevel: 'info' }
+};
+
+const store = new ReactiveDataStore<AppState>(currentState);
+
+const container = new ArtifactContainer(store);
+
+// --- Artifact Definitions ---
+
+// Artifact 1: Simple Logger (Transient) - new instance every time
+container.register({
+    key: 'logger',
+    scope: ArtifactScope.Transient,
+    factory: () => {
+        console.log('Logger artifact created (Transient)');
+        return {
+            log: (message: string) => console.log(`[LOG] ${message}`)
+        };
+    }
+});
+
+// Artifact 2: API Client (Singleton) - depends on state.config.apiUrl
+const apiClientCleanup = () => console.log('API Client connection closed.');
+container.register({
+    key: 'apiClient',
+    scope: ArtifactScope.Singleton,
+    factory: async ({ use, current }) => {
+        const apiUrl = await use(({ select }) => select((state: AppState) => state.config.apiUrl));
+        console.log(`API Client created/re-created for URL: ${apiUrl}`);
+        if (current) {
+            console.log('Re-creating API client. Old instance:', current);
+        }
+        return [{
+            fetchUser: (id: string) => `Fetching ${id} from ${apiUrl}`,
+            sendData: (data: any) => `Sending ${JSON.stringify(data)} to ${apiUrl}`
+        }, apiClientCleanup];
+    }
+});
+
+// Artifact 3: User Service (Singleton) - depends on 'apiClient' and state.user.name
+const userServiceCleanup = () => console.log('User Service resources released.');
+container.register({
+    key: 'userService',
+    scope: ArtifactScope.Singleton,
+    factory: async ({ use, current }) => {
+        const apiClient = await use(({ resolve }) => resolve('apiClient'));
+        const userName = await use(({ select }) => select((state: AppState) => state.user.name));
+        console.log(`User Service created/re-created for user: ${userName}`);
+        if (current) {
+            console.log('Re-creating User Service. Old instance:', current);
+        }
+        return [{
+            getUserProfile: () => apiClient.fetchUser(mockGet().user.id),
+            updateUserName: (newName: string) => `Updating user name to ${newName} via API. Current: ${userName}`
+        }, userServiceCleanup];
+    }
+});
+
+// --- Usage ---
+
+async function runDemo() {
+    console.log('\n--- Initial Artifact Resolution ---');
+    const logger1 = await container.resolve('logger');
+    logger1.log('Application started.');
+
+    const apiClient1 = await container.resolve('apiClient');
+    console.log(apiClient1.fetchUser('123'));
+
+    const userService1 = await container.resolve('userService');
+    console.log(userService1.getUserProfile());
+
+    // Transient artifact resolves a new instance
+    const logger2 = await container.resolve('logger');
+    expect(logger1).not.toBe(logger2); // Will be different instances
+
+    // Singleton artifacts resolve the same instance
+    const apiClient2 = await container.resolve('apiClient');
+    expect(apiClient1).toBe(apiClient2);
+
+    console.log('\n--- Simulate State Change (config.apiUrl) ---');
+    store.set({ config:{ apiUrl: '/api/v2'}})
+
+    // After config.apiUrl changes, apiClient (and userService) should be re-created
+    const apiClient3 = await container.resolve('apiClient'); // This will trigger re-creation
+    console.log(apiClient3.fetchUser('123'));
+    expect(apiClient3).not.toBe(apiClient1); // Should be a new instance
+
+    // userService should also be re-created because apiClient, its dependency, was re-created
+    const userService2 = await container.resolve('userService');
+    console.log(userService2.getUserProfile());
+    expect(userService2).not.toBe(userService1); // Should be a new instance
+
+    console.log('\n--- Simulate State Change (user.name) ---');
+    simulateStateUpdate(
+        { ...currentState, user: { ...currentState.user, name: 'Bob' } },
+        ['user.name']
+    );
+
+    // Only userService (which depends on user.name) should be re-created this time, not apiClient
+    const apiClient4 = await container.resolve('apiClient');
+    expect(apiClient4).toBe(apiClient3); // Still the same API client instance
+
+    const userService3 = await container.resolve('userService');
+    console.log(userService3.getUserProfile());
+    expect(userService3).not.toBe(userService2); // New user service instance
+
+    console.log('\n--- Unregistering Artifacts ---');
+    await container.unregister('userService');
+    // Output: User Service resources released. (cleanup called)
+    await container.unregister('apiClient');
+    // Output: API Client connection closed. (cleanup called)
+
+    try {
+        await container.resolve('userService');
+    } catch (e: any) {
+        console.error('Expected error:', e.message);
+    }
+}
+
+runDemo();
+```
+
+### React Integration
+
+The `@asaidimu/utils-store/react-store` module provides a `createStore` factory function that integrates the core `ReactiveDataStore` with React's context and `useSyncExternalStore` hook. This makes it easy to consume state, dispatch actions, and resolve artifacts in your React components.
+
+```typescript
+// store.ts (example for an E-commerce dashboard)
+import { ArtifactScope, createStore, ActionMap, ArtifactsMap } from '@asaidimu/utils-store';
+
+export interface Product {
+    id: number; name: string; price: number; stock: number; image: string;
+}
+export interface CartItem extends Product { quantity: number; }
+export interface Order { id: string; items: CartItem[]; total: number; date: Date; }
+
+export interface ECommerceState extends Record<string, any> {
+    products: Product[];
+    cart: CartItem[];
+    orders: Order[];
+    topSellers: { id: number; name: string; sales: number }[];
+    activeUsers: number;
+}
+
+const initialState: ECommerceState = {
+    products: [
+        { id: 1, name: 'Wireless Mouse', price: 25.99, stock: 150, image: 'https://placehold.co/600x400/white/black?text=Mouse' },
+        { id: 2, name: 'Mechanical Keyboard', price: 79.99, stock: 100, image: 'https://placehold.co/600x400/white/black?text=Keyboard' },
+    ],
+    cart: [], orders: [], topSellers: [], activeUsers: 1428,
+};
+
+// 1. Define Artifacts
+export const artifacts = {
+    logger: {
+        scope: ArtifactScope.Singleton,
+        factory: () => ((...args:any[]) => console.log('Artifact Logger:', ...args))
+    },
+    analytics: {
+        scope: ArtifactScope.Transient,
+        factory: () => ({
+            trackEvent: (name: string, data: object) => console.log(`[Analytics] ${name}`, data)
+        })
+    }
+} as const satisfies ArtifactsMap<ECommerceState>
+
+// 2. Define Actions
+export const actions = {
+    addToCart: async ({ state, resolve }, product: Product) => {
+        const log = await resolve("logger");
+        const analytics = await resolve("analytics");
+        analytics.trackEvent('add_to_cart', { product: product.name });
+
+        const existingItem = state.cart.find((item) => item.id === product.id);
+        if (existingItem) {
+            return {
+                cart: state.cart.map((item) =>
+                    item.id === product.id ? { ...item, quantity: item.quantity + 1 } : item
+                ),
+            };
+        }
+        const result = { cart: [...state.cart, { ...product, quantity: 1 }] };
+        log("Item added:", product.name);
+        return result
+    },
+    removeFromCart: ({ state }, productId: number) => ({
+        cart: state.cart.filter((item) => item.id !== productId),
+    }),
+    checkout: ({ state }) => {
+        const total = state.cart.reduce((sum, item) => sum + item.price * item.quantity, 0);
+        const newOrder: Order = {
+            id: crypto.randomUUID(), items: state.cart, total, date: new Date(),
+        };
+        return {
+            cart: [], orders: [newOrder, ...state.orders],
+        };
+    },
+    // Simulated real-time updates for the dashboard example
+    updateStock: ({ state }) => ({
+        products: state.products.map(p => ({
+            ...p,
+            stock: Math.max(0, p.stock + Math.floor(Math.random() * 10) - 5)
+        }))
+    }),
+    updateActiveUsers: ({ state }) => ({
+        activeUsers: state.activeUsers + Math.floor(Math.random() * 20) - 10,
+    }),
+    addRandomOrder: ({ state }) => {
+        const randomProduct = state.products[Math.floor(Math.random() * state.products.length)];
+        const quantity = Math.floor(Math.random() * 3) + 1;
+        const newOrder: Order = {
+            id: crypto.randomUUID(),
+            items: [{ ...randomProduct, quantity }],
+            total: randomProduct.price * quantity,
+            date: new Date(),
+        };
+        return {
+            orders: [newOrder, ...state.orders],
+        };
+    },
+} as const satisfies ActionMap<ECommerceState, typeof artifacts>
+
+// 3. Create the React Store Hook
+export const useStore = createStore(
+    {
+        state: initialState,
+        artifacts,
+        actions,
+    },
+    { enableMetrics: true, enableConsoleLogging: true }
+);
+
+// App.tsx (React Component)
+import { useEffect, useMemo } from 'react';
+import { useStore } from './store'; // Import the custom hook
+
+function ProductCatalog() {
+    const { select, actions } = useStore();
+    const products = select((state) => state.products); // Reactive selector for products
+
+    return (
+        <div>
+            <h2>Products</h2>
+            {products.map((product) => (
+                <div key={product.id}>
+                    {product.name} - ${product.price} ({product.stock} in stock)
+                    <button onClick={() => actions.addToCart(product)}>Add to Cart</button>
+                </div>
+            ))}
+        </div>
+    );
+}
+
+function ShoppingCart() {
+    const { select, actions } = useStore();
+    const cart = select((state) => state.cart); // Reactive selector for cart
+    const total = useMemo(() => cart.reduce((sum, item) => sum + item.price * item.quantity, 0), [cart]);
+
+    return (
+        <div>
+            <h2>Shopping Cart</h2>
+            {cart.length === 0 ? (
+                <p>Your cart is empty.</p>
+            ) : (
+                <ul>
+                    {cart.map((item) => (
+                        <li key={item.id}>
+                            {item.name} x {item.quantity} - ${item.price * item.quantity}
+                            <button onClick={() => actions.removeFromCart(item.id)}>Remove</button>
+                        </li>
+                    ))}
+                </ul>
+            )}
+            <p>Total: ${total.toFixed(2)}</p>
+            {cart.length > 0 && <button onClick={() => actions.checkout()}>Checkout</button>}
+        </div>
+    );
+}
+
+function DebugPanel() {
+    const { resolve, watch, state } = useStore();
+    const [logger, loggerReady] = resolve('logger'); // Reactive artifact resolution
+    const [analytics, analyticsReady] = resolve('analytics');
+
+    const isLoadingAddToCart = watch('addToCart'); // Watch specific action loading state
+
+    return (
+        <div>
+            <h3>Debug Panel</h3>
+            <p>Add to Cart Loading: {isLoadingAddToCart ? 'Yes' : 'No'}</p>
+            <p>Store is ready: {useStore().isReady ? 'Yes' : 'No'}</p>
+            <button onClick={() => loggerReady && logger('Debug message from UI')}>Log via Artifact</button>
+            <button onClick={() => analyticsReady && analytics.trackEvent('ui_event', { component: 'DebugPanel' })}>Track UI Event</button>
+            <pre>Full State: {JSON.stringify(state(), null, 2)}</pre>
+        </div>
+    );
+}
+
+function App() {
+    const { actions } = useStore();
+
+    // Simulate real-time updates
+    useEffect(() => {
+        const stockInterval = setInterval(() => actions.updateStock(), 2000);
+        const usersInterval = setInterval(() => actions.updateActiveUsers(), 3000);
+        const ordersInterval = setInterval(() => actions.addRandomOrder(), 5000);
+
+        return () => {
+            clearInterval(stockInterval);
+            clearInterval(usersInterval);
+            clearInterval(ordersInterval);
+        };
+    }, [actions]);
+
+    return (
+        <div>
+            <h1>E-Commerce App</h1>
+            <ProductCatalog />
+            <hr />
+            <ShoppingCart />
+            <hr />
+            <DebugPanel />
+        </div>
+    );
+}
+
+export default App;
+```
+
 ### Store Observer (Debugging & Observability)
 
 The `StoreObserver` class provides advanced debugging and monitoring capabilities for any `ReactiveDataStore` instance. It allows you to inspect event history, state changes, and even time-travel through your application's state. It's an invaluable tool for understanding complex state flows.
@@ -674,6 +1245,8 @@ const observer = new StoreObserver(store, {
     updates: true,           // Log all update lifecycle events (start/complete)
     middleware: true,        // Log middleware start/complete/error/blocked/executed events
     transactions: true,      // Log transaction start/complete/error events
+    actions: true,           // Log action start/complete/error events
+    selectors: true,         // Log selector accessed/changed events
   },
   performanceThresholds: {
     updateTime: 50,          // Warn in console if an update takes > 50ms
@@ -693,8 +1266,8 @@ await store.set({ messages: ['Hello World!'] });
 await store.set({ settings: { debugMode: false } });
 
 // Simulate a slow update to trigger performance warning
-await new Promise(resolve => setTimeout(resolve, 60)); // Artificially delay
-await store.set({ messages: ['Another message', 'And another'] });
+// await new Promise(resolve => setTimeout(resolve, 60)); // Artificially delay
+// await store.set({ messages: ['Another message', 'And another'] });
 // This last set will cause a console warning for "Slow update detected" if enableConsoleLogging is true.
 
 // 1. Get Event History
@@ -706,7 +1279,7 @@ events.slice(0, 5).forEach(event => console.log(`Type: ${event.type}, Data: ${JS
 // 2. Get State History
 console.log('\n--- State History (Most Recent First) ---');
 const stateSnapshots = observer.getStateHistory();
-stateSnapshots.forEach((snapshot, index) => console.log(`State #${index}: Messages: ${snapshot.messages.join(', ')}, User Status: ${snapshot.user.status}`));
+stateSnapshots.forEach((snapshot, index) => console.log(`State #${index}: Messages: ${snapshot.state.messages.join(', ')}, User Status: ${snapshot.state.user.status}`));
 
 // 3. Get Recent Changes (Diffs)
 console.log('\n--- Recent State Changes (Diffs) ---');
@@ -745,7 +1318,7 @@ if (timeTravel.canRedo()) {
   console.log('After redo 1:', store.get().messages); // Output: ['First message']
 }
 
-console.log('Time-Travel history length:', timeTravel.getHistoryLength()); // Reflects `maxStateHistory` + initial state
+console.log('Time-Travel history length:', timeTravel.length()); // Reflects `maxStateHistory` + initial state
 
 // 5. Custom Debugging Middleware (provided by StoreObserver for convenience)
 // Example: A logging middleware that logs every update
@@ -769,7 +1342,7 @@ const validationMiddlewareId = store.use({ name: 'DebugValidation', block: true,
 
 try {
     await store.set({ messages: ['m1','m2','m3','m4','m5','m6'] }); // This will be blocked
-} catch (e) {
+} catch (e: any) {
     console.warn(`Caught expected error from validation middleware: ${e.message}`);
 }
 console.log('Current messages after failed validation:', store.get().messages); // Should be the state before this set.
@@ -788,7 +1361,7 @@ await store.set({ messages: ['Final message after disconnect'] });
 
 ### Event System
 
-The store emits various events during its lifecycle, allowing for advanced monitoring, logging, and integration with external systems. You can subscribe to these events using `store.onStoreEvent(eventName, listener)`. The `StoreObserver` leverages this event system internally to provide its rich debugging capabilities.
+The store emits various events during its lifecycle, allowing for advanced monitoring, logging, and integration with external systems. You can subscribe to these events using `store.on(eventName, listener)`. The `StoreObserver` leverages this event system internally to provide its rich debugging capabilities.
 
 ```typescript
 import { ReactiveDataStore, type StoreEvent } from '@asaidimu/utils-store';
@@ -801,58 +1374,93 @@ interface MyState {
 const store = new ReactiveDataStore<MyState>({ value: 0, status: 'idle' });
 
 // Subscribe to 'update:start' event - triggered before an update begins processing.
-store.onStoreEvent('update:start', (data) => {
-  console.log(`[${new Date(data.timestamp).toLocaleTimeString()}] ⚡ Update started.`);
+store.on('update:start', (data) => {
+  console.log(`[${new Date(data.timestamp).toLocaleTimeString()}] ⚡ Update started. Action ID: ${data.actionId || 'N/A'}`);
 });
 
 // Subscribe to 'update:complete' event - triggered after an update is fully applied or blocked.
-store.onStoreEvent('update:complete', (data) => {
+store.on('update:complete', (data) => {
   if (data.blocked) {
     console.warn(`[${new Date(data.timestamp).toLocaleTimeString()}] ✋ Update blocked. Error:`, data.error?.message);
   } else {
-    console.log(`[${new Date(data.timestamp).toLocaleTimeString()}] ✅ Update complete. Changed paths: ${data.changedPaths?.join(', ')} (took ${data.duration?.toFixed(2)}ms)`);
+    console.log(`[${new Date(data.timestamp).toLocaleTimeString()}] ✅ Update complete. Changed paths: ${data.deltas?.map((d:any) => d.path).join(', ')} (took ${data.duration?.toFixed(2)}ms)`);
   }
 });
 
 // Subscribe to middleware lifecycle events
-store.onStoreEvent('middleware:start', (data) => {
-  console.log(`[${new Date(data.timestamp).toLocaleTimeString()}] ▶ Middleware "${data.name}" (${data.type}) started.`);
+store.on('middleware:start', (data) => {
+  console.log(`[${new Date(data.timestamp).toLocaleTimeString()}] ▶ Middleware "${data.name}" (${data.type || 'transform'}) started.`);
 });
 
-store.onStoreEvent('middleware:complete', (data) => {
-  console.log(`[${new Date(data.timestamp).toLocaleTimeString()}] ◀ Middleware "${data.name}" (${data.type}) completed in ${data.duration?.toFixed(2)}ms.`);
+store.on('middleware:complete', (data) => {
+  console.log(`[${new Date(data.timestamp).toLocaleTimeString()}] ◀ Middleware "${data.name}" (${data.type || 'transform'}) completed in ${data.duration?.toFixed(2)}ms.`);
 });
 
-store.onStoreEvent('middleware:error', (data) => {
+store.on('middleware:error', (data) => {
   console.error(`[${new Date(data.timestamp).toLocaleTimeString()}] ❌ Middleware "${data.name}" failed:`, data.error);
 });
 
-store.onStoreEvent('middleware:blocked', (data) => {
+store.on('middleware:blocked', (data) => {
   console.warn(`[${new Date(data.timestamp).toLocaleTimeString()}] 🛑 Middleware "${data.name}" blocked an update.`);
 });
 
-store.onStoreEvent('middleware:executed', (data) => {
+store.on('middleware:executed', (data) => {
   // This event captures detailed execution info for all middlewares, useful for aggregate metrics.
   console.debug(`[${new Date(data.timestamp).toLocaleTimeString()}] 📊 Middleware executed: "${data.name}" - Duration: ${data.duration?.toFixed(2)}ms, Blocked: ${data.blocked}`);
 });
 
 // Subscribe to transaction lifecycle events
-store.onStoreEvent('transaction:start', (data) => {
+store.on('transaction:start', (data) => {
   console.log(`[${new Date(data.timestamp).toLocaleTimeString()}] 📦 Transaction started.`);
 });
 
-store.onStoreEvent('transaction:complete', (data) => {
+store.on('transaction:complete', (data) => {
   console.log(`[${new Date(data.timestamp).toLocaleTimeString()}] 📦 Transaction complete.`);
 });
 
-store.onStoreEvent('transaction:error', (data) => {
+store.on('transaction:error', (data) => {
   console.error(`[${new Date(data.timestamp).toLocaleTimeString()}] 📦 Transaction failed:`, data.error);
 });
 
 // Subscribe to persistence events
-store.onStoreEvent('persistence:ready', (data) => {
+store.on('persistence:ready', (data) => {
   console.log(`[${new Date(data.timestamp).toLocaleTimeString()}] 💾 Persistence layer is ready.`);
 });
+store.on('persistence:queued', (data) => {
+    console.log(`[${new Date(data.timestamp).toLocaleTimeString()}] ⏳ Persistence task queued: ${data.taskId}, queue size: ${data.queueSize}`);
+});
+store.on('persistence:success', (data) => {
+    console.log(`[${new Date(data.timestamp).toLocaleTimeString()}] ✅ Persistence success for task: ${data.taskId}, took ${data.duration?.toFixed(2)}ms`);
+});
+store.on('persistence:retry', (data) => {
+    console.warn(`[${new Date(data.timestamp).toLocaleTimeString()}] 🔄 Persistence retry for task: ${data.taskId}, attempt ${data.attempt}/${data.maxRetries}`);
+});
+store.on('persistence:failed', (data) => {
+    console.error(`[${new Date(data.timestamp).toLocaleTimeString()}] ❌ Persistence failed permanently for task: ${data.taskId}`, data.error);
+});
+
+
+// Subscribe to action events
+store.on('action:start', (data) => {
+  console.log(`[${new Date(data.timestamp).toLocaleTimeString()}] 🚀 Action "${data.name}" (ID: ${data.actionId}) started with params:`, data.params);
+});
+
+store.on('action:complete', (data) => {
+  console.log(`[${new Date(data.timestamp).toLocaleTimeString()}] ✔️ Action "${data.name}" (ID: ${data.actionId}) completed in ${data.duration?.toFixed(2)}ms.`);
+});
+
+store.on('action:error', (data) => {
+  console.error(`[${new Date(data.timestamp).toLocaleTimeString()}] 🔥 Action "${data.name}" (ID: ${data.actionId}) failed:`, data.error);
+});
+
+// Subscribe to selector events
+store.on('selector:accessed', (data) => {
+    console.debug(`[${new Date(data.timestamp).toLocaleTimeString()}] 👀 Selector (ID: ${data.selectorId}) accessed paths: ${data.accessedPaths.join(', ')}`);
+});
+
+store.on('selector:changed', (data) => {
+    console.log(`[${new Date(data.timestamp).toLocaleTimeString()}] 📢 Selector (ID: ${data.selectorId}) changed. New result:`, data.newResult);
+});
 
 
 // Add a transform middleware to demonstrate `middleware:start/complete/executed`
@@ -906,58 +1514,73 @@ src/store/
 ├── index.ts                # Main entry point (exports all public APIs)
 ├── types.ts                # TypeScript interfaces and types for the store
 ├── store.ts                # `ReactiveDataStore` - The main orchestrator
-├── state.ts                # `CoreStateManager` - Manages the immutable state and diffing
+├── state.ts                # `StateManager` - Manages the immutable state and diffing
 ├── merge.ts                # `createMerge` - Deep merging utility with deletion support
 ├── diff.ts                 # `createDiff`, `createDerivePaths` - Change detection utilities
 ├── middleware.ts           # `MiddlewareEngine` - Manages and executes middleware pipeline
 ├── transactions.ts         # `TransactionManager` - Handles atomic state transactions
 ├── persistence.ts          # `PersistenceHandler` - Integrates with `SimplePersistence` layer
 ├── metrics.ts              # `MetricsCollector` - Gathers runtime performance metrics
-├── observability.ts        # `StoreObserver` - Debugging and introspection utilities
-└── ...                     # (Other test files like *.test.ts, internal helpers)
+├── selector.ts             # `SelectorManager` - Manages reactive selectors for derived state
+├── observer.ts             # `StoreObserver` - Debugging and introspection utilities
+├── artifacts.ts            # `ArtifactContainer` - Dependency Injection system for services
+├── actions.ts              # `ActionManager` - Manages registration and dispatch of named actions
+└── react-store/            # React integration module (hooks, context)
+    ├── index.ts
+    ├── types.ts
+    ├── store.ts            # `createStore` - Factory for React hooks
+    └── execution.ts        # `ActionTracker` - Tracks action execution history for React integration
 ```
 
 ### Core Components
 
-*   **`ReactiveDataStore<T>` (`store.ts`)**: The public API and primary entry point. It orchestrates interactions between all other internal components. It manages the update queue, ensures sequential processing of `set` calls, and exposes public methods like `get`, `set`, `subscribe`, `transaction`, `use`, `unuse`, and `onStoreEvent`.
-*   **`CoreStateManager<T>` (`state.ts`)**: Responsible for the direct management of the immutable state (`cache`). It applies incoming state changes, performs efficient object `diff`ing to identify modified paths, and notifies internal listeners (via an `updateBus`) about granular state changes.
-*   **`MiddlewareEngine<T>` (`middleware.ts`)**: Manages the registration and execution of both `blocking` and `transform` middleware functions. It ensures middleware execution order, handles potential errors, and emits detailed lifecycle events for observability.
-*   **`PersistenceHandler<T>` (`persistence.ts`)**: Handles integration with an external persistence layer via the `SimplePersistence` interface. It loads initial state, saves subsequent changes, and listens for external updates from the persistence layer to keep the in-memory state synchronized across multiple instances (e.g., browser tabs).
-*   **`TransactionManager<T>` (`transactions.ts`)**: Provides atomic state operations. It creates a snapshot of the state before an `operation` begins and, if the operation fails, ensures the state is reverted to this snapshot, guaranteeing data integrity. It integrates closely with the store's event system for tracking transaction status.
-*   **`MetricsCollector` (`metrics.ts`)**: Observes the internal `eventBus` to gather and expose real-time performance metrics of the store, such as update counts, listener executions, average update times, and the largest update size.
-*   **`StoreObserver<T>` (`observability.ts`)**: An optional, yet highly valuable, debugging companion. It taps into the `ReactiveDataStore`'s extensive event stream and state changes to build a comprehensive history of events and state snapshots, enabling powerful features like time-travel debugging, detailed console logging, and performance monitoring.
-*   **`createMerge` (`merge.ts`)**: A factory function that returns a configurable deep merging utility (`MergeFunction`). This utility is crucial for immutably applying partial updates and specifically handles `Symbol.for("delete")` for explicit property removal.
-*   **`createDiff` / `createDerivePaths` (`diff.ts`)**: Factory functions returning utilities for efficient comparison between two objects (`diff`) to identify changed paths, and for deriving all parent paths from a set of changes (`derivePaths`). These are fundamental for optimizing listener notifications and internal change detection.
+*   **`ReactiveDataStore<T>`**: The public API and primary entry point. It orchestrates interactions between all other internal components. It manages the update queue, ensures sequential processing of `set` calls, and exposes public methods like `get`, `dispatch`, `select`, `set`, `watch`, `transaction`, `use`, and `on`.
+*   **`StateManager<T>`**: Responsible for the direct management of the immutable state (`cache`). It applies incoming state changes, performs efficient object `diff`ing to identify modified paths, and notifies internal listeners (via an `updateBus`) about granular state changes.
+*   **`MiddlewareEngine<T>`**: Manages the registration and execution of both `blocking` and `transform` middleware functions. It ensures middleware execution order, handles potential errors, and emits detailed lifecycle events for observability.
+*   **`PersistenceHandler<T>`**: Handles integration with an external persistence layer via the `SimplePersistence` interface. It loads initial state, saves subsequent changes, and listens for external updates from the persistence layer to keep the in-memory state synchronized across multiple instances (e.g., browser tabs). It also manages a background queue for persistence tasks with retries and exponential backoff.
+*   **`TransactionManager<T>`**: Provides atomic state operations. It creates a snapshot of the state before an `operation` begins and, if the operation fails, ensures the state is reverted to this snapshot, guaranteeing data integrity. It integrates closely with the store's event system for tracking transaction status.
+*   **`MetricsCollector`**: Observes the internal `eventBus` to gather and expose real-time performance metrics of the store, such as update counts, listener executions, average update times, largest update size, total events fired, and transaction/middleware execution counts.
+*   **`SelectorManager<T>`**: Manages the creation, memoization, and reactivity of selectors. It tracks the paths accessed by each selector and re-evaluates them efficiently only when relevant parts of the state change, notifying their subscribers.
+*   **`StoreObserver<T>`**: An optional, yet highly valuable, debugging companion. It taps into the `ReactiveDataStore`'s extensive event stream and state changes to build a comprehensive history of events and state snapshots, enabling powerful features like time-travel debugging, detailed console logging, and performance monitoring. It also supports saving/loading and exporting observer sessions.
+*   **`ArtifactContainer<T>`**: Implements a dependency injection system for managing services (artifacts) with different lifecycles (Singleton, Transient) and complex dependencies on state paths and other artifacts. It handles lazy initialization, reactive re-evaluation, and resource cleanup.
+*   **`ActionManager<T>`**: Manages the registration of named actions and their dispatch. It handles action lifecycle events, debouncing logic, and ensures actions interact correctly with the core `set` method.
+*   **`createMerge`**: A factory function that returns a configurable deep merging utility (`MergeFunction`). This utility is crucial for immutably applying partial updates and specifically handles `Symbol.for("delete")` for explicit property removal.
+*   **`createDiff` / `createDerivePaths`**: Factory functions returning utilities for efficient comparison between two objects (`createDiff`) to identify changed paths, and for deriving all parent paths from a set of changes (`createDerivePaths`). These are fundamental for optimizing listener notifications and internal change detection.
 
 ### Data Flow
 
 The `ReactiveDataStore` handles state updates in a robust, queued, and event-driven manner:
 
-1.  **`store.set(update)` call**:
-    *   If another update is already in progress (`isUpdating`), the new `update` is queued in `pendingUpdates`. This ensures sequential processing and prevents race conditions, and the `store.state().pendingChanges` reflects the queue.
+1.  **`store.set(update)` or `store.dispatch(actionName, actionFn, ...)` call**:
+    *   If `dispatch` is used, an `action:start` event is emitted. The `actionFn` (which can be `async`) is executed to produce a `DeepPartial` update which is then passed to `store.set`. Actions can be debounced, delaying their `set` call and potentially cancelling previous in-flight actions.
+    *   All `set` calls are automatically queued to prevent race conditions during concurrent updates, ensuring sequential processing. The `store.state().pendingChanges` reflects the queue.
     *   An `update:start` event is immediately emitted.
 2.  **Middleware Execution**:
-    *   The `MiddlewareEngine` first executes all `blocking` middlewares (registered via `store.use({ block: true, ... })`). If any blocking middleware returns `false` or throws an error, the update is immediately halted. An `update:complete` event with `blocked: true` is emitted, and the process stops, with the state remaining unchanged.
+    *   The `MiddlewareEngine` first executes all `blocking` middlewares (registered via `store.use({ block: true, ... })`). If any blocking middleware returns `false` or throws an error, the update is immediately halted. An `update:complete` event with `blocked: true` and an `error` property is emitted, and the process stops, with the state remaining unchanged.
     *   If not blocked, `transform` middlewares (registered via `store.use({ action: ... })`) are executed sequentially. Each transform middleware receives the current state and the incoming partial update, and can return a new `DeepPartial<T>` that is then merged into the effective update payload.
     *   Detailed lifecycle events (`middleware:start`, `middleware:complete`, `middleware:error`, `middleware:blocked`, `middleware:executed`) are emitted during this phase, providing granular insight into middleware behavior.
 3.  **State Application**:
-    *   The `CoreStateManager` receives the (potentially transformed) final `DeepPartial` update.
+    *   The `StateManager` receives the (potentially transformed) final `DeepPartial` update.
     *   It internally uses the `createMerge` utility to immutably construct the new full state object.
-    *   It then performs a `createDiff` comparison between the *previous* state and the *new* state to precisely identify all `changedPaths` (an array of strings).
-    *   If changes are detected, the `CoreStateManager` updates its internal immutable `cache` to the `newState` and then emits an internal `update` event for each granular `changedPath` on its `updateBus`.
+    *   It then performs a `createDiff` comparison between the *previous* state and the *new* state to precisely identify all `changedPaths` (an array of `StateDelta` objects).
+    *   If changes are detected, the `StateManager` updates its internal immutable `cache` to the `newState` and then emits an internal `update` event for each granular `changedPath` on its `updateBus`.
 4.  **Listener Notification**:
-    *   Any external subscribers (registered with `store.subscribe()`) whose registered paths match or are parent paths of the `changedPaths` are efficiently notified with the latest state. The `MetricsCollector` tracks `listenerExecutions` during this phase.
+    *   Any external subscribers (registered with `store.watch()` or `store.subscribe()`) whose registered paths match or are parent paths of the `changedPaths` are efficiently notified with the latest state. The `MetricsCollector` tracks `listenerExecutions` during this phase.
+    *   The `SelectorManager` re-evaluates reactive selectors whose `accessedPaths` are affected by the `changedPaths`. If a selector's result changes, it notifies its own subscribers and emits a `selector:changed` event.
+    *   `ArtifactContainer` also receives change notifications for state paths its artifacts depend on, triggering re-evaluation for `Singleton` scoped artifacts.
 5.  **Persistence Handling**:
-    *   The `PersistenceHandler` receives the `changedPaths` and the new state. If a `SimplePersistence` implementation was configured during store initialization, it attempts to save the new state using `persistence.set()`.
+    *   The `PersistenceHandler` receives the `changedPaths` and the new state. If a `SimplePersistence` implementation was configured during store initialization, it attempts to save the new state using `persistence.set()`. This is done in the background via a queue, emitting `persistence:queued`, `persistence:success`, `persistence:retry`, and `persistence:failed` events.
     *   The `PersistenceHandler` also manages loading initial state and reacting to external state changes (e.g., from other browser tabs or processes) through `persistence.subscribe()`.
 6.  **Completion & Queue Processing**:
-    *   An `update:complete` event is emitted, containing crucial information about the update's duration, the `changedPaths`, and any blocking errors.
-    *   The `isUpdating` flag is reset. If there are any `pendingUpdates` in the queue, the next update is immediately pulled and processed, ensuring all queued updates are eventually applied in order.
+    *   An `update:complete` event is emitted, containing crucial information about the update's duration, the `StateDelta[]`, and any blocking errors.
+    *   If the update originated from a `dispatch` call, an `action:complete` or `action:error` event is emitted, correlating with the `action:start` event via a shared `actionId`.
+    *   The update queue automatically processes the next pending update.
 
 ### Extension Points
 
 *   **Custom Middleware**: Developers can inject their own `Middleware` (for transformation) and `BlockingMiddleware` (for validation/prevention) functions using `store.use()`. This allows for highly customizable update logic, centralized logging, complex validation, authorization, or triggering specific side effects.
 *   **Custom Persistence**: The `SimplePersistence<T>` interface provides a clear contract for developers to integrate the store with any storage solution, whether it's local storage, IndexedDB, a backend API, or a WebSocket connection. This offers complete control over data durability and synchronization.
+*   **Custom Artifacts**: The `ArtifactContainer` (directly or via React integration) allows defining and managing any custom services, utilities, or dependencies with defined scopes and lifecycle management.
 
 ---
 
@@ -995,9 +1618,8 @@ From the `src/store` directory, the following `pnpm` scripts are available:
 
 *   `pnpm test`: Runs all unit tests using [Vitest](https://vitest.dev/).
 *   `pnpm test:watch`: Runs tests in watch mode for continuous development.
+*   `pnpm dev`: Starts the Vite development server for the UI example.
 *   `pnpm lint`: Lints the codebase using [ESLint](https://eslint.org/).
-*   `pnpm format`: Formats the code using [Prettier](https://prettier.io/).
-*   `pnpm build`: Compiles TypeScript to JavaScript (CommonJS and ES Modules) and generates declaration files (`.d.ts`).
 
 ### Testing
 
@@ -1040,9 +1662,14 @@ If you find a bug or have a feature request, please open an issue on the [GitHub
 ### Troubleshooting
 
 *   **"Update not triggering listeners"**:
-    *   Ensure you are subscribing to the correct path. `store.subscribe('user.name', ...)` will not trigger if you update `user.email` (unless you also subscribe to `user` or the root `''` path).
+    *   Ensure you are subscribing to the correct path. `store.watch('user.name', ...)` will not trigger if you update `user.email` (unless you also subscribe to `user` or the root `''` path).
     *   If the new value is strictly equal (`===`) to the old value, no change will be detected by the internal `diff` function, and listeners will not be notified.
     *   Verify your `DeepPartial` update correctly targets the intended part of the state.
+*   **"Reactive Selector not re-evaluating"**:
+    *   Ensure the state path(s) accessed by the selector are actually changing. The selector re-evaluates only when its dependencies change.
+    *   If using `select(() => state.someArray.length)`, it might not re-evaluate if array elements change but `length` remains the same.
+    *   Check for strict equality issues: if the new computed value is strictly equal to the old one, no re-evaluation notification will occur.
+    *   Avoid complex operations (array methods, conditionals, arithmetic) within selectors as they might bypass the static path analysis and lead to unexpected behavior or errors.
 *   **"State not rolling back after transaction error"**:
     *   Ensure the error is thrown *within* the `transaction` callback function. Errors caught and handled inside the callback, or thrown outside of it, will not trigger the rollback mechanism.
     *   Promises within the transaction *must* be `await`ed so the `TransactionManager` can capture potential rejections and manage the atomic operation correctly.
@@ -1052,29 +1679,35 @@ If you find a bug or have a feature request, please open an issue on the [GitHub
     *   Ensure your `transform` middleware returns a `DeepPartial<T>` or `void`/`Promise<void>`, and `blocking` middleware returns `boolean`/`Promise<boolean>`.
 *   **"Performance warnings in console"**:
     *   If `StoreObserver` is enabled with `enableConsoleLogging: true`, it will warn about updates or middlewares exceeding defined `performanceThresholds`. This is an informational warning, not an error, indicating a potentially slow operation that could be optimized in your application.
+*   **"Artifact not resolving or re-evaluating"**:
+    *   Check for `Circular dependency` errors in the console during `resolve`.
+    *   For `Singleton` artifacts, ensure its `state` or `artifact` dependencies are actually changing to trigger re-evaluation. If a dependency changes, the artifact (and its downstream dependents) will be invalidated and re-created on next `resolve`.
+    *   For `Transient` artifacts, a new instance is created on every `resolve`.
 
 ### FAQ
 
 **Q: How are arrays handled during updates?**
 A: Arrays are treated as primitive values. When you provide an array in a `DeepPartial` update (e.g., `set({ items: [new Array] })`), the entire array at that path is replaced with the new array, not merged element-by-element. This ensures predictable behavior and avoids complex, potentially ambiguous partial array merging logic.
 
-**Q: What is `Symbol.for("delete")`?**
-A: `Symbol.for("delete")` is a special global symbol used to explicitly remove a property from the state during a `set` operation. If you pass `Symbol.for("delete")` as the value for a key in your `DeepPartial` update, that key will be removed from the resulting state object. This provides a clear semantic for deletion.
+**Q: What is `DELETE_SYMBOL`?**
+A: `DELETE_SYMBOL` (exported from `@asaidimu/utils-store`) is a special global symbol (`Symbol.for("delete")`) used to explicitly remove a property from the state during a `set` operation. If you pass `DELETE_SYMBOL` as the value for a key in your `DeepPartial` update, that key will be removed from the resulting state object. This provides a clear semantic for deletion.
 
 **Q: How do I debug my store's state changes?**
 A: The `StoreObserver` class is your primary tool. Instantiate it with your `ReactiveDataStore` instance. It provides methods to get event history, state snapshots, and even time-travel debugging capabilities. Enabling `enableConsoleLogging: true` in `StoreObserver` options provides immediate, formatted console output during development, showing update lifecycles, middleware execution, and transaction events.
 
 **Q: What is `SimplePersistence<T>`?**
-A: It's a minimal interface that defines the contract for any persistence layer you wish to integrate. It requires `get()`, `set(instanceId, state)`, and `subscribe(instanceId, listener)` methods. You need to provide an implementation of this interface to enable state saving and loading. An example `InMemoryPersistence` implementation is provided in the [Persistence Integration](#persistence-integration) section.
+A: It's a minimal interface that defines the contract for any persistence layer you wish to integrate. It requires `get()`, `set(instanceId, state)`, and an optional `subscribe(instanceId, listener)` methods. You need to provide an implementation of this interface to enable state saving and loading. You can use concrete implementations from `@asaidimu/utils-persistence` or create your own.
+
+**Q: How does the Artifact system work?**
+A: The Artifact system is a dependency injection container. You register `ArtifactFactory` functions with a `key` and a `scope` (`Singleton` or `Transient`). Factories receive a `context` with `state()` (current state snapshot) and `use()` (to declare dependencies on other artifacts or specific state paths). The `use()` method is crucial for building the dependency graph, allowing the system to automatically re-evaluate `Singleton` artifacts when their dependencies change. In React, you use `useStore().resolve()` to access artifacts reactively.
 
-**Q: Can I use this with React/Vue/Angular or other UI frameworks?**
-A: Yes, absolutely. This is a framework-agnostic state management library. You would typically use the `subscribe` method within your framework's lifecycle hooks (e.g., `useEffect` in React, `onMounted` in Vue) to react to state changes and update your UI components. The library's reactivity model is independent of any specific framework.
+**Q: What's the difference between `set` and `dispatch`?**
+A: `set` is the foundational method for updating the state, handling the core logic of applying changes, running middleware, and notifying subscribers. `dispatch` builds upon `set` by adding an "action" concept. It wraps `set` calls, providing a semantic name, optional parameters, and lifecycle callbacks (`action:start`, `action:complete`, `action:error`). This makes `dispatch` ideal for orchestrating complex, named operations and provides better observability, which can be correlated across the update lifecycle via a shared `actionId`. Use `set` for simple, direct updates; use `dispatch` for logical operations that should be tracked as distinct "actions."
 
 ### Changelog / Roadmap
 
 *   **Changelog**: For detailed version history, including new features, bug fixes, and breaking changes, please refer to the project's [CHANGELOG.md](https://github.com/asaidimu/erp-utils/blob/main/src/store/CHANGELOG.md) file.
 *   **Roadmap**: Future plans for `@asaidimu/utils-store` may include:
-    *   Official framework-specific integrations (e.g., React hooks library for easier consumption).
     *   More advanced query/selector capabilities with built-in memoization for derived state.
     *   Built-in serialization/deserialization options for persistence, perhaps with schema validation.
     *   Higher-order middlewares for common patterns (e.g., async data fetching, debouncing updates).
@@ -1089,3 +1722,5 @@ This project is licensed under the [MIT License](https://github.com/asaidimu/erp
 *   Inspired by modern state management patterns such as Redux, Zustand, and Vuex, emphasizing immutability and explicit state changes.
 *   Leverages the `@asaidimu/events` package for robust internal event bus capabilities.
 *   Utilizes the `uuid` library for generating unique instance IDs.
+
+---