@asaidimu/utils-store 5.0.0 → 6.0.0

package/README.md

@@ -22,7 +22,6 @@ A comprehensive, type-safe, and reactive state management library for TypeScript
   - [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)
@@ -49,7 +48,6 @@ This library offers robust tools to handle your state with confidence, enabling
 *   📦 **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, 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.
@@ -82,7 +80,6 @@ yarn add @asaidimu/utils-store
 
 *   **Node.js**: (LTS version recommended) for development and compilation.
 *   **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
 
@@ -698,7 +695,7 @@ 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 }
-const removed = store.use({ name: 'TemporaryLogger', action: (s, u) => console.log('Temporary logger saw:', u) })(); // Remove the temporary logger
+const removed = temporaryLoggerId(); // Remove the temporary logger
 console.log('Middleware removed:', removed);
 await store.set({ counter: 1 }); // TemporaryLogger will not be called now
 ```
@@ -872,10 +869,8 @@ try {
 
 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';
+import { ReactiveDataStore, ArtifactContainer, ArtifactScope } from '@asaidimu/utils-store';
 
 interface AppState {
     user: { id: string; name: string; };
@@ -883,12 +878,10 @@ interface AppState {
 }
 
 // Mock DataStore interface for standalone ArtifactContainer usage
-let currentState: AppState = {
+const store = new ReactiveDataStore<AppState>({
     user: { id: 'user-1', name: 'Alice' },
     config: { apiUrl: '/api/v1', logLevel: 'info' }
-};
-
-const store = new ReactiveDataStore<AppState>(currentState);
+});
 
 const container = new ArtifactContainer(store);
 
@@ -911,16 +904,17 @@ const apiClientCleanup = () => console.log('API Client connection closed.');
 container.register({
     key: 'apiClient',
     scope: ArtifactScope.Singleton,
-    factory: async ({ use, current }) => {
+    factory: async ({ use, onCleanup, 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 [{
+        onCleanup(apiClientCleanup); // Register cleanup for this instance
+        return {
             fetchUser: (id: string) => `Fetching ${id} from ${apiUrl}`,
             sendData: (data: any) => `Sending ${JSON.stringify(data)} to ${apiUrl}`
-        }, apiClientCleanup];
+        };
     }
 });
 
@@ -929,17 +923,18 @@ const userServiceCleanup = () => console.log('User Service resources released.')
 container.register({
     key: 'userService',
     scope: ArtifactScope.Singleton,
-    factory: async ({ use, current }) => {
+    factory: async ({ use, onCleanup, 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),
+        onCleanup(userServiceCleanup); // Register cleanup for this instance
+        return {
+            getUserProfile: () => apiClient.instance!.fetchUser(store.get().user.id),
             updateUserName: (newName: string) => `Updating user name to ${newName} via API. Current: ${userName}`
-        }, userServiceCleanup];
+        };
     }
 });
 
@@ -948,48 +943,47 @@ container.register({
 async function runDemo() {
     console.log('\n--- Initial Artifact Resolution ---');
     const logger1 = await container.resolve('logger');
-    logger1.log('Application started.');
+    logger1.instance!.log('Application started.');
 
     const apiClient1 = await container.resolve('apiClient');
-    console.log(apiClient1.fetchUser('123'));
+    console.log(apiClient1.instance!.fetchUser('123'));
 
     const userService1 = await container.resolve('userService');
-    console.log(userService1.getUserProfile());
+    console.log(userService1.instance!.getUserProfile());
 
     // Transient artifact resolves a new instance
     const logger2 = await container.resolve('logger');
-    expect(logger1).not.toBe(logger2); // Will be different instances
+    console.log('Logger instances are different:', logger1.instance !== logger2.instance);
 
-    // Singleton artifacts resolve the same instance
+    // Singleton artifacts resolve the same instance initially
     const apiClient2 = await container.resolve('apiClient');
-    expect(apiClient1).toBe(apiClient2);
+    console.log('API Client instances are same:', apiClient1.instance === apiClient2.instance);
 
     console.log('\n--- Simulate State Change (config.apiUrl) ---');
-    store.set({ config:{ apiUrl: '/api/v2'}})
+    await store.set({ config:{ apiUrl: '/api/v2'}})
+    // This state change invalidates 'apiClient' which depends on 'config.apiUrl'
+    // and then invalidates 'userService' which depends on 'apiClient'.
 
     // 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
+    console.log(apiClient3.instance!.fetchUser('123'));
+    console.log('API Client instances are different:', apiClient3.instance !== apiClient1.instance); // 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(userService2.instance!.getUserProfile());
+    console.log('User Service instances are different:', userService2.instance !== userService1.instance); // Should be a new instance
 
     console.log('\n--- Simulate State Change (user.name) ---');
-    simulateStateUpdate(
-        { ...currentState, user: { ...currentState.user, name: 'Bob' } },
-        ['user.name']
-    );
+    await store.set({ user: { name: 'Bob' } });
 
     // 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
+    console.log('API Client instances are same:', apiClient4.instance === apiClient3.instance); // 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(userService3.instance!.getUserProfile());
+    console.log('User Service instances are different:', userService3.instance !== userService2.instance); // New user service instance
 
     console.log('\n--- Unregistering Artifacts ---');
     await container.unregister('userService');
@@ -1000,220 +994,13 @@ async function runDemo() {
     try {
         await container.resolve('userService');
     } catch (e: any) {
-        console.error('Expected error:', e.message);
+        console.error('Expected error:', e.message); // Artifact not found
     }
 }
 
 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.
@@ -1509,29 +1296,6 @@ console.log('Final value:', store.get().value, 'Final status:', store.get().stat
 
 The `@asaidimu/utils-store` library is built with a modular, component-based architecture to promote maintainability, testability, and extensibility. Each core concern is encapsulated within its own class, with `ReactiveDataStore` acting as the central coordinator.
 
-```
-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                # `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
-├── 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>`**: 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`.