@asaidimu/react-store 2.0.0 → 2.1.0

package/README.md

@@ -21,9 +21,9 @@ This package is currently in **beta**. The API is subject to rapid changes and s
     *   [Persistence](#persistence)
     *   [Middleware](#middleware)
     *   [Observability](#observability)
-    *   [Remote Observability](#remote-observability)
     *   [Transaction Support](#transaction-support)
     *   [Event System](#event-system)
+    *   [Watching Action Loading States](#watching-action-loading-states)
     *   [Advanced Hook Properties](#advanced-hook-properties)
 *   [Project Architecture](#project-architecture)
 *   [Development & Contributing](#development--contributing)
@@ -51,8 +51,8 @@ Designed with modern React in mind, it leverages `useSyncExternalStore` for opti
 *   📦 **Transaction Support**: Group multiple state updates into a single atomic operation, with automatic rollback if any part of the transaction fails.
 *   💾 **Built-in Persistence**: Seamlessly integrate with web storage mechanisms like `IndexedDB` and `WebStorage` (localStorage/sessionStorage), including cross-tab synchronization.
 *   🔍 **Deep Observability**: Gain profound insights into your application's state with built-in metrics, detailed event logging, state history, and time-travel debugging capabilities.
-*   📈 **Remote Observability**: Extend monitoring by sending collected metrics and traces to external systems like OpenTelemetry, Prometheus, or Grafana Cloud.
-*   ⚡ **Performance Optimized**: Features intelligent selector caching and debounced actions to prevent rapid successive calls and ensure smooth application performance.
+*   ⚡ **Performance Optimized**: Features intelligent selector caching (now using `WeakMap` for enhanced efficiency) and debounced actions with configurable immediate execution to prevent rapid successive calls and ensure smooth application performance.
+*   🚀 **Action Loading States**: Track the real-time loading status of individual actions, providing immediate feedback on asynchronous operations.
 *   ⚛️ **React 18+ Ready**: Fully compatible with the latest React versions, leveraging modern APIs for enhanced performance and development ergonomics.
 *   🗑️ **Explicit Deletions**: Use `Symbol.for("delete")` to explicitly remove properties from nested state objects.
 
@@ -94,7 +94,6 @@ const myStore = createStore({
   },
 });
 
-console.log(myStore().select(s => s.value)); // Should output 'hello'
 ```
 
 If no errors are thrown, the package is correctly installed.
@@ -135,7 +134,7 @@ const myStore = createStore({
     }),
   },
 }, {
-  debounceTime: 100, // Debounce actions by 100ms
+  debounceTime: 0, // Actions execute immediately by default
   enableConsoleLogging: true, // Enable console logs for store events
   logEvents: { updates: true, transactions: true, middleware: true },
   performanceThresholds: { updateTime: 20, middlewareTime: 5 }, // Warn for slow operations
@@ -431,7 +430,7 @@ const useObservedStore = createStore(
     },
     maxEvents: 500, // Max number of events to keep in history
     maxStateHistory: 50, // Max number of state snapshots for time travel
-    debounceTime: 300, // Debounce actions by 300ms to prevent rapid calls
+    debounceTime: 0, // Actions execute immediately by default
   },
 );
 
@@ -737,6 +736,63 @@ function EventMonitor() {
 }
 ```
 
+### Watching Action Loading States
+
+The `watch` function returned by the `useStore` hook allows you to subscribe to the loading status of individual actions. This is particularly useful for displaying loading indicators for asynchronous operations.
+
+```tsx
+import React from 'react';
+import { createStore } from '@asaidimu/react-store';
+
+interface DataState {
+  items: string[];
+}
+
+const useDataStore = createStore({
+  state: { items: [] },
+  actions: {
+    fetchItems: async (state) => {
+      // Simulate an API call
+      await new Promise(resolve => setTimeout(resolve, 2000));
+      return { items: ['Item A', 'Item B', 'Item C'] };
+    },
+    addItem: async (state, item: string) => {
+      // Simulate a quick add operation
+      await new Promise(resolve => setTimeout(resolve, 500));
+      return { items: [...state.items, item] };
+    },
+  },
+});
+
+function DataLoader() {
+  const { actions, select, watch } = useDataStore();
+  const items = select(s => s.items);
+
+  // Watch the loading state of specific actions
+  const isFetchingItems = watch('fetchItems');
+  const isAddingItem = watch('addItem');
+
+  return (
+    <div>
+      <h2>Data Loader</h2>
+      <button onClick={() => actions.fetchItems()} disabled={isFetchingItems}>
+        {isFetchingItems ? 'Fetching...' : 'Fetch Items'}
+      </button>
+      <button onClick={() => actions.addItem(`New Item ${items.length + 1}`)} disabled={isAddingItem}>
+        {isAddingItem ? 'Adding...' : 'Add Item'}
+      </button>
+      
+      <h3>Items:</h3>
+      <ul>
+        {items.map((item, index) => (
+          <li key={index}>{item}</li>
+        ))}
+      </ul>
+    </div>
+  );
+}
+```
+
 ### Advanced Hook Properties
 
 The hook returned by `createStore` provides several properties for advanced usage and debugging, beyond the commonly used `select`, `actions`, and `isReady`:
@@ -751,6 +807,7 @@ function MyAdvancedComponent() {
     observer,      // StoreObservability instance (if `enableMetrics` was true)
     actionTracker, // Instance of ActionTracker for monitoring action executions
     state,         // A hook `() => T` to get the entire reactive state object
+    watch,         // Function to watch the loading status of actions
   } = useMyStore(); // Assuming useMyStore is defined from createStore
 
   // Example: Accessing the full state (use with caution for performance, `select` is preferred)
@@ -766,6 +823,10 @@ function MyAdvancedComponent() {
   // Example: Accessing action history
   console.log("Action executions:", actionTracker.getExecutions());
 
+  // Example: Watching a specific action's loading state
+  const isLoadingSomeAction = watch('someActionName');
+  console.log("Is 'someActionName' loading?", isLoadingSomeAction);
+
   return (
     <div>
       {/* ... your component content ... */}
@@ -778,57 +839,53 @@ function MyAdvancedComponent() {
 
 `@asaidimu/react-store` is structured to provide a modular yet integrated state management solution.
 
+### Internal Structure
+
+The core logic of this package resides directly within the `src/` directory:
+
 ```
 .
 ├── src/
-│   ├── hooks/
-│   │   └── observability.ts        # React hook for remote observability
-│   ├── persistence/
-│   │   ├── indexedb.ts             # IndexedDB persistence adapter
-│   │   ├── local-storage.ts        # WebStorage (localStorage/sessionStorage) persistence adapter
-│   │   └── types.ts                # Interface for persistence adapters
-│   ├── state/
-│   │   ├── diff.ts                 # Utility for deep diffing state objects
-│   │   ├── merge.ts                # Utility for immutable deep merging state objects
-│   │   ├── observability.ts        # Core observability logic for ReactiveDataStore
-│   │   └── store.ts                # Core ReactiveDataStore implementation (the state machine)
-│   ├── store/
-│   │   ├── compare.ts              # Utilities for fast comparison (e.g., array hashing)
-│   │   ├── execution.ts            # Action tracking interface and class
-│   │   ├── hash.ts                 # Utilities for hashing objects (e.g., for selectors)
-│   │   ├── index.ts                # Main `createStore` React hook
-│   │   ├── paths.ts                # Utility for building selector paths
-│   │   └── selector.ts             # Selector memoization manager
-│   ├── types.ts                    # Core TypeScript types for the library
-│   └── utils/
-│       ├── destinations.ts         # Concrete remote observability destinations (OTel, Prometheus, Grafana)
-│       └── remote-observability.ts # Remote observability extension for StoreObservability
-├── index.ts                        # Main entry point for the library
+│   ├── execution.ts            # Action tracking interface and class
+│   ├── hash.ts                 # Utilities for hashing objects (e.g., for selectors)
+│   ├── paths.ts                # Utility for building selector paths
+│   ├── selector.ts             # Selector memoization manager
+│   ├── store.ts                # Main `createStore` React hook implementation
+│   └── types.ts                # Core TypeScript types for the library
+├── index.ts                    # Main entry point for the library (re-exports `createStore` and other public APIs)
 ├── package.json
 └── tsconfig.json
 ```
 
+### Key External Dependencies
+
+This library leverages the following `@asaidimu` packages for its core functionalities:
+
+*   **`@asaidimu/utils-store`**: Provides the foundational `ReactiveDataStore` for state management, including immutable updates, transactions, and core event emission. It also includes `StoreObservability` for deep insights into state changes.
+*   **`@asaidimu/utils-persistence`**: Offers persistence adapters like `WebStoragePersistence` and `IndexedDBPersistence` for saving and loading state.
+
 ### Core Components
 
-*   **`ReactiveDataStore` (`src/state/store.ts`)**: The heart of the library. It manages the immutable state, processes updates (including debouncing), handles middleware, transactions, and interacts with persistence adapters. It also emits detailed internal events for observability.
-*   **`StoreObservability` (`src/state/observability.ts`)**: An extension built on top of `ReactiveDataStore`'s event system. It provides debugging features like event history, state snapshots for time-travel, performance metrics, and utilities to create logging/validation middleware.
-*   **`createStore` Hook (`src/store/index.ts`)**: The primary React-facing API. It instantiates `ReactiveDataStore` and `StoreObservability`, wraps actions with debouncing and tracking, and provides the `select` hook powered by `useSyncExternalStore` for efficient component updates.
-*   **Persistence Adapters (`src/persistence/`)**: Implement the `DataStorePersistence` interface. `WebStoragePersistence` (for localStorage/sessionStorage) and `IndexedDBPersistence` provide concrete storage solutions with cross-tab synchronization.
-*   **`RemoteObservability` (`src/utils/remote-observability.ts`)**: Extends `StoreObservability` to enable sending metrics, logs, and traces to external monitoring systems. It defines a pluggable `RemoteDestination` interface and provides out-of-the-box implementations.
+*   **`ReactiveDataStore` (from `@asaidimu/utils-store`)**: The foundational state management layer. This external library manages the immutable state, processes updates, handles middleware, transactions, and interacts with persistence adapters. It also emits detailed internal events for observability.
+*   **`StoreObservability` (from `@asaidimu/utils-store`)**: An extension built on top of the external `ReactiveDataStore`'s event system. It provides debugging features like event history, state snapshots for time-travel, performance metrics, and utilities to create logging/validation middleware.
+*   **`createStore` Hook (`src/store.ts`)**: The primary React-facing API. It instantiates the external `ReactiveDataStore` and `StoreObservability`, wraps actions with debouncing and tracking, and provides the `select` hook powered by `useSyncExternalStore` for efficient component updates, and the `watch` function for action loading states.
+*   **Persistence Adapters (from `@asaidimu/utils-persistence`)**: Implement the `DataStorePersistence` interface. `WebStoragePersistence` and `IndexedDBPersistence` provide concrete storage solutions with cross-tab synchronization.
 
 ### Data Flow
 
 1.  **Action Dispatch**: A React component calls an action (e.g., `actions.increment(1)`). Actions are debounced by default.
-2.  **Action Execution Tracking**: The `ActionTracker` records the action's details (name, params, start time).
-3.  **State Update Request**: The action, after potential debouncing, initiates a `store.set()` call with a partial state update or a function.
-4.  **Transaction Context**: If within a `store.transaction()`, the state is snapshotted for potential rollback.
-5.  **Blocking Middleware**: Updates first pass through `blockingMiddleware`. If any middleware returns `false` or throws, the update is halted, and the state is not modified.
-6.  **Transform Middleware**: If not blocked, updates then pass through transforming `middleware`. These functions can modify the partial update.
-7.  **State Merging**: The final transformed update is immutably merged into the current state using the `merge` utility. `Symbol.for("delete")` is handled here for property removal.
-8.  **Change Detection**: The `diff` utility identifies which paths in the state have truly changed.
-9.  **Persistence**: If changes occurred, the new state is saved via the configured `DataStorePersistence` adapter (e.g., `localStorage`, `IndexedDB`). External changes from persistence are also subscribed to and applied.
-10. **Listener Notification**: Only `React.useSyncExternalStore` subscribers whose selected paths have changed are notified, triggering re-renders of relevant components.
-11. **Observability Events**: Throughout this flow, the `ReactiveDataStore` emits fine-grained events (`update:start`, `middleware:complete`, `transaction:error`, etc.) that `StoreObservability` captures for debugging, metrics, and remote reporting.
+2.  **Action Loading State Update**: The store immediately updates the loading state for the dispatched action to `true`.
+3.  **Action Execution Tracking**: The `ActionTracker` records the action's details (name, params, start time).
+4.  **State Update Request**: The action, after potential debouncing, initiates a `store.set()` call with a partial state update or a function returning a partial object.
+5.  **Transaction Context**: If within a `store.transaction()`, the state is snapshotted for potential rollback.
+6.  **Blocking Middleware**: Updates first pass through `blockingMiddleware`. If any middleware returns `false` or throws, the update is halted, and the state is not modified.
+7.  **Transform Middleware**: If not blocked, updates then pass through transforming `middleware`. These functions can modify the partial update.
+8.  **State Merging**: The final transformed update is immutably merged into the current state using `ReactiveDataStore`'s internal merge utility.
+9.  **Change Detection**: `ReactiveDataStore`'s internal diffing mechanism identifies which paths in the state have truly changed.
+10. **Persistence**: If changes occurred, the new state is saved via the configured `DataStorePersistence` adapter (e.g., `localStorage`, `IndexedDB`). External changes from persistence are also subscribed to and applied.
+11. **Listener Notification**: Only `React.useSyncExternalStore` subscribers whose selected paths have changed are notified, triggering re-renders of relevant components.
+12. **Action Loading State Reset**: Once the action completes (success or error), the loading state for that action is reset to `false`.
+13. **Observability Events**: Throughout this flow, the `ReactiveDataStore` emits fine-grained events (`update:start`, `middleware:complete`, `transaction:error`, etc.) that `StoreObservability` captures for debugging, metrics, and remote reporting.
 
 ### Extension Points
 
@@ -861,7 +918,7 @@ We welcome contributions! Please follow the guidelines below.
 *   `bun clean`: Removes the `dist` directory.
 *   `bun prebuild`: Cleans `dist` and runs a sync script (internal).
 *   `bun build`: Compiles the TypeScript source into `dist/` for CJS and ESM formats, generates type definitions, and minifies.
-*   `bun dev`: Starts a development server (likely for a UI example).
+*   `bun dev`: Starts the e-commerce dashboard demonstration.
 *   `bun postbuild`: Copies `README.md`, `LICENSE.md`, and `dist.package.json` into the `dist` folder.
 
 ### Testing
@@ -929,7 +986,7 @@ interface StoreOptions<T> {
     middlewareTime?: number; // default: 20ms
   };
   persistence?: DataStorePersistence<T>; // Optional persistence adapter instance
-  debounceTime?: number; // Time in milliseconds to debounce actions (default: 250ms)
+  debounceTime?: number; // Time in milliseconds to debounce actions (default: 0ms)
 }
 
 const useStore = createStore(definition, options);
@@ -943,13 +1000,14 @@ const useStore = createStore(definition, options);
 *   `actionTracker`: An instance of `ActionTracker` for monitoring the execution history of your actions.
 *   `state`: A hook `() => T` that returns the entire current state object. Use sparingly as it will cause re-renders on *any* state change.
 *   `isReady`: A boolean indicating whether the store's persistence layer (if configured) has finished loading its initial state.
+*   `watch`: A function to watch the loading status of actions.
 
 #### `ReactiveDataStore` (accessed via `useStore().store`)
 
 *   `get(clone?: boolean): T`: Retrieves the current state. Pass `true` to get a deep clone (recommended for mutations outside of actions).
 *   `set(update: StateUpdater<T>): Promise<void>`: Updates the state with a partial object or a function returning a partial object.
 *   `subscribe(path: string | string[], listener: (state: T) => void): () => void`: Subscribes a listener to changes at a specific path or array of paths. Returns an unsubscribe function.
-*   `transaction<R>(operation: () => R | Promise<R>): Promise<R>`: Executes a function as an atomic transaction. Rolls back all changes if an error occurs.
+*   `transaction<R>(operation: () => R | Promise<R>): Promise<R}`: Executes a function as an atomic transaction. Rolls back all changes if an error occurs.
 *   `use(middleware: Middleware<T>, name?: string): string`: Adds a transforming middleware. Returns its ID.
 *   `useBlockingMiddleware(middleware: BlockingMiddleware<T>, name?: string): string`: Adds a blocking middleware. Returns its ID.
 *   `removeMiddleware(id: string): boolean`: Removes a middleware by its ID.
@@ -968,20 +1026,6 @@ const useStore = createStore(definition, options);
 *   `clearHistory(): void`: Clears the event and state history.
 *   `disconnect(): void`: Cleans up all listeners and resources.
 
-#### `RemoteObservability` (accessed via `useRemoteObservability` hook)
-
-Extends `StoreObservability` with methods for sending metrics and traces externally.
-
-*   `addDestination(destination: RemoteDestination): boolean`: Adds a remote destination for metrics.
-*   `removeDestination(id: string): boolean`: Removes a remote destination by ID.
-*   `getDestinations(): Array<{ id: string; name: string }> `: Gets a list of configured destinations.
-*   `testAllConnections(): Promise<Record<string, boolean>>`: Tests connectivity to all destinations.
-*   `beginTrace(name: string): string`: Starts a new performance trace, returning its ID.
-*   `beginSpan(traceId: string, name: string, labels?: Record<string, string>): string`: Starts a new span within a trace, returning its ID.
-*   `endSpan(traceId: string, spanName: string): void`: Ends a specific span within a trace.
-*   `endTrace(traceId: string): void`: Ends a performance trace and sends it to remote destinations.
-*   `trackMetric(metric: RemoteMetricsPayload['metrics'][0]): void`: Manually add a metric to the batch for reporting.
-
 #### Persistence Adapters
 
 All adapters implement `DataStorePersistence<T>`:
@@ -1006,7 +1050,7 @@ All adapters implement `DataStorePersistence<T>`:
 
 ### Comparison with Other State Management Solutions
 
-`@asaidimu/react-store` aims to provide a comprehensive, all-in-one solution for React state management. Here's a comparison to popular alternatives:
+`@asaidimu/react-store` aims to be a comprehensive, all-in-one solution for React state management. Here's a comparison to popular alternatives:
 
 | **Feature**            | **@asaidimu/react-store** | **Redux**          | **Zustand**        | **MobX**           | **Recoil**         |
 | :--------------------- | :------------------------ | :----------------- | :----------------- | :----------------- | :----------------- |

package/index.cjs

@@ -1 +1 @@
-"use strict";var e=require("react"),t=require("@asaidimu/utils-store");var r=class{selectorCache=new WeakMap;create(e){return t=>{let r=this.selectorCache.get(e);r||(r=new WeakMap,this.selectorCache.set(e,r));const n=r.get(t);if(n)return n.result;const s=e(t);return r.set(t,{result:s,deps:[]}),s}}},n=class{executions=[];maxHistory=100;listeners=new Set;track(e){this.executions.unshift(e),this.executions.length>this.maxHistory&&this.executions.pop(),this.notify()}getExecutions(){return[...this.executions]}subscribe(e){return this.listeners.add(e),()=>this.listeners.delete(e)}notify(){this.listeners.forEach((e=>e()))}};exports.createStore=function(s,{enableMetrics:c,debounceTime:i=250,...o}={}){const a=new t.ReactiveDataStore(s.state,o.persistence),u=c?new t.StoreObserver(a,o):void 0,l=new r;s.middleware&&Object.entries(s.middleware).forEach((([e,t])=>a.use({name:e,action:t}))),s.blockingMiddleware&&Object.entries(s.blockingMiddleware).forEach((([e,t])=>a.use({block:!0,name:e,action:t})));const h=new n,d=new Map,w=Object.entries(s.actions).reduce(((e,[t,r])=>(e[t]=function(e,t){let r=null,n=null;return function(...s){return r&&(clearTimeout(r),n&&n(new Error("Debounced by a newer call"))),new Promise(((c,i)=>{const o=this;n=i,r=setTimeout((()=>{r=null,n=null,e.apply(o,s).then(c).catch(i)}),t)}))}}((async(...e)=>{const n=`${t}-${JSON.stringify(e)}`;if(d.get(n))return;d.set(n,!0);const s=crypto.randomUUID(),c=performance.now(),i={id:s,name:t,params:e,startTime:c};try{return await a.set((async t=>{const n=await r(t,...e);return i.result=n,n})),i.status="success",a.get()}catch(e){throw i.status="error",i.error=e instanceof Error?e:new Error(String(e)),console.error(`Error in action ${t}:`,e),e}finally{i.endTime=performance.now(),i.duration=i.endTime-c,h.track(i),d.delete(n)}}),i),e)),{});function y(e,t){const r=function(e,t="."){const r=[],n={get:(e,t)=>{const s=[];return r.length>0&&s.push(...r[r.length-1]),s.push(t),r.push(s),new Proxy({},n)}};return e(new Proxy({},n)),r.map((e=>e.join(t)))}(e);return a.subscribe(r,t)}const b=()=>a.get(),m=e=>(a.isReady()&&e(),a.onStoreEvent("persistence:ready",e)),f=()=>a.isReady();return function(){const t=e.useCallback((t=>{const r=l.create(t);return e.useSyncExternalStore((e=>y(r,e)),(()=>r(a.get())),(()=>r(a.get())))}),[]),r=e.useCallback((()=>e.useSyncExternalStore((e=>a.subscribe("",e)),b,b)),[]),n=e.useSyncExternalStore(m,f,f);return{store:a,observer:u,select:t,actions:w,isReady:n,actionTracker:h,get state(){return r}}}};
+"use strict";var e=require("react"),t=require("@asaidimu/utils-store");var r=class{selectorCache=new WeakMap;create(e){return t=>{let r=this.selectorCache.get(e);if(r&&r.lastState===t)return r.lastResult;const n=e(t);return this.selectorCache.set(e,{lastState:t,lastResult:n}),n}}},n=class{executions=[];maxHistory=100;listeners=new Set;track(e){this.executions.unshift(e),this.executions.length>this.maxHistory&&this.executions.pop(),this.notify()}getExecutions(){return[...this.executions]}subscribe(e){return this.listeners.add(e),()=>this.listeners.delete(e)}notify(){this.listeners.forEach((e=>e()))}};function s(e,t=new WeakMap){return void 0===e?"undefined":"function"==typeof e||"symbol"==typeof e?"":"string"==typeof e?`"${e}"`:"number"==typeof e||"boolean"==typeof e||null===e?String(e):Array.isArray(e)?`[${e.map((e=>s(e,t))).join(",")}]`:"object"==typeof e?t.has(e)?'"__circular__"':(t.set(e,!0),`{${Object.keys(e).sort().map((r=>`"${r}":${s(e[r],t)}`)).join(",")}}`):""}function o(e){let t=3421674724,r=2216829733;const n=s(e);for(let e=0;e<n.length;e++){r^=n.charCodeAt(e);const s=Math.imul(r,435),o=Math.imul(r,435)+Math.imul(t,435);r=s>>>0,t=o>>>0}return(t>>>0).toString(16)+(r>>>0).toString(16)}exports.createStore=function(s,{enableMetrics:i,debounceTime:a=0,...c}={}){const u=new t.ReactiveDataStore(s.state,c.persistence),l=new t.ReactiveDataStore(Object.fromEntries(Object.keys(s.actions).map((e=>[e,!1])))),h=i?new t.StoreObserver(u,c):void 0,d=new r,f=i?new n:void 0,y=i?new Map:void 0;s.middleware&&Object.entries(s.middleware).forEach((([e,t])=>u.use({name:e,action:t}))),s.blockingMiddleware&&Object.entries(s.blockingMiddleware).forEach((([e,t])=>u.use({block:!0,name:e,action:t})));const m=Object.entries(s.actions).reduce(((e,[t,r])=>(e[t]=function(e,t){if(0===t)return e;let r=null;return function(...n){return new Promise(((s,o)=>{r&&clearTimeout(r);const i=this;r=setTimeout((()=>{r=null,e.apply(i,n).then(s).catch(o)}),t)}))}}((async(...e)=>{const n=`${t}-${o(e)}`;if(y?.get(n))return;y?.set(n,!0);const s=f?crypto.randomUUID():void 0,i=f?performance.now():void 0,a=f?{id:s,name:t,params:e,startTime:i}:{};try{return l.set((e=>({...e,[t]:!0}))),await u.set((async t=>{const n=await r(t,...e);return f&&(a.result=n),n})),f&&(a.status="success"),u.get()}catch(e){throw f&&(a.status="error",a.error=e instanceof Error?e:new Error(String(e))),console.error(`Error in action ${t}:`,e),e}finally{l.set((e=>({...e,[t]:!1}))),f&&(a.endTime=performance.now(),a.duration=a.endTime-i,f.track(a)),y?.delete(n)}}),a),e)),{});function p(e,t){const r=function(e,t="."){const r=[],n={get:(e,t)=>{const s=[];return r.length>0&&s.push(...r[r.length-1]),s.push(t),r.push(s),new Proxy({},n)}};return e(new Proxy({},n)),r.map((e=>e.join(t)))}(e);return u.subscribe(r,t)}const b=()=>u.get(),w=e=>(u.isReady()&&e(),u.onStoreEvent("persistence:ready",e)),g=()=>u.isReady(),S=new Map;return function(){const t=e.useCallback((t=>{S.has(t)||S.set(t,d.create(t));const r=S.get(t);return e.useSyncExternalStore((e=>p(r,e)),(()=>r(u.get())),(()=>r(u.get())))}),[]),r=e.useCallback((()=>e.useSyncExternalStore((e=>u.subscribe("",e)),b,b)),[]),n=e.useSyncExternalStore(w,g,g);return{store:u,observer:h,select:t,actions:m,isReady:n,actionTracker:f,watch:t=>e.useSyncExternalStore((e=>l.subscribe(t,e)),(()=>l.get()[t]),(()=>l.get()[t])),get state(){return r}}}};

package/index.d.cts

@@ -6,6 +6,7 @@ type StoreOptions<T> = ObservabilityOptions & {
     persistence?: SimplePersistence<T>;
 };
 type Action<T> = (state: T, ...args: any[]) => DeepPartial<T>;
+type LoadingState<T extends string> = Record<T, boolean>;
 type StoreSelector<T, S> = (state: T) => S;
 type Actions<T> = {
     [K: string]: (state: T, ...args: any[]) => DeepPartial<T> | Promise<DeepPartial<T>>;
@@ -13,10 +14,21 @@ type Actions<T> = {
 interface StoreDefinition<T, R extends Actions<T>> {
     state: T;
     actions: R;
+    loading?: LoadingState<keyof R & string>;
     sync?: (args: T) => void;
     blockingMiddleware?: Record<string, BlockingMiddleware<T>>;
     middleware?: Record<string, Middleware<T>>;
 }
+type StoreHook<T, R extends Actions<T>> = () => {
+    store: any;
+    observer: any;
+    select: <S>(selector: (state: T) => S) => S;
+    actions: R;
+    isReady: boolean;
+    actionTracker: any;
+    watch: (action: keyof R & string) => boolean;
+    state: () => T;
+};
 
 interface ActionExecution {
     id: string;
@@ -60,9 +72,11 @@ declare function createStore<T extends Record<string, unknown>, R extends Action
     readonly actions: { [K in keyof R]: (...args: Parameters<R[K]> extends [T, ...infer P] ? P : never) => Promise<T>; };
     readonly isReady: boolean;
     /** track actions */
-    readonly actionTracker: ActionTracker;
+    readonly actionTracker: ActionTracker | undefined;
+    /** watch loading state */
+    readonly watch: (action: keyof R & string) => LoadingState<keyof R & string>[keyof R & string];
     /** Complete store state */
     readonly state: () => T;
 };
 
-export { type Action, type Actions, type StoreDefinition, type StoreOptions, type StoreSelector, createStore };
+export { type Action, type Actions, type LoadingState, type StoreDefinition, type StoreHook, type StoreOptions, type StoreSelector, createStore };

package/index.d.ts

@@ -6,6 +6,7 @@ type StoreOptions<T> = ObservabilityOptions & {
     persistence?: SimplePersistence<T>;
 };
 type Action<T> = (state: T, ...args: any[]) => DeepPartial<T>;
+type LoadingState<T extends string> = Record<T, boolean>;
 type StoreSelector<T, S> = (state: T) => S;
 type Actions<T> = {
     [K: string]: (state: T, ...args: any[]) => DeepPartial<T> | Promise<DeepPartial<T>>;
@@ -13,10 +14,21 @@ type Actions<T> = {
 interface StoreDefinition<T, R extends Actions<T>> {
     state: T;
     actions: R;
+    loading?: LoadingState<keyof R & string>;
     sync?: (args: T) => void;
     blockingMiddleware?: Record<string, BlockingMiddleware<T>>;
     middleware?: Record<string, Middleware<T>>;
 }
+type StoreHook<T, R extends Actions<T>> = () => {
+    store: any;
+    observer: any;
+    select: <S>(selector: (state: T) => S) => S;
+    actions: R;
+    isReady: boolean;
+    actionTracker: any;
+    watch: (action: keyof R & string) => boolean;
+    state: () => T;
+};
 
 interface ActionExecution {
     id: string;
@@ -60,9 +72,11 @@ declare function createStore<T extends Record<string, unknown>, R extends Action
     readonly actions: { [K in keyof R]: (...args: Parameters<R[K]> extends [T, ...infer P] ? P : never) => Promise<T>; };
     readonly isReady: boolean;
     /** track actions */
-    readonly actionTracker: ActionTracker;
+    readonly actionTracker: ActionTracker | undefined;
+    /** watch loading state */
+    readonly watch: (action: keyof R & string) => LoadingState<keyof R & string>[keyof R & string];
     /** Complete store state */
     readonly state: () => T;
 };
 
-export { type Action, type Actions, type StoreDefinition, type StoreOptions, type StoreSelector, createStore };
+export { type Action, type Actions, type LoadingState, type StoreDefinition, type StoreHook, type StoreOptions, type StoreSelector, createStore };

package/index.js

@@ -1 +1 @@
-import{useCallback as e,useSyncExternalStore as t}from"react";import{ReactiveDataStore as r,StoreObserver as n}from"@asaidimu/utils-store";var s=class{selectorCache=new WeakMap;create(e){return t=>{let r=this.selectorCache.get(e);r||(r=new WeakMap,this.selectorCache.set(e,r));const n=r.get(t);if(n)return n.result;const s=e(t);return r.set(t,{result:s,deps:[]}),s}}},i=class{executions=[];maxHistory=100;listeners=new Set;track(e){this.executions.unshift(e),this.executions.length>this.maxHistory&&this.executions.pop(),this.notify()}getExecutions(){return[...this.executions]}subscribe(e){return this.listeners.add(e),()=>this.listeners.delete(e)}notify(){this.listeners.forEach((e=>e()))}};function o(o,{enableMetrics:c,debounceTime:a=250,...u}={}){const l=new r(o.state,u.persistence),h=c?new n(l,u):void 0,d=new s;o.middleware&&Object.entries(o.middleware).forEach((([e,t])=>l.use({name:e,action:t}))),o.blockingMiddleware&&Object.entries(o.blockingMiddleware).forEach((([e,t])=>l.use({block:!0,name:e,action:t})));const m=new i,w=new Map,f=Object.entries(o.actions).reduce(((e,[t,r])=>(e[t]=function(e,t){let r=null,n=null;return function(...s){return r&&(clearTimeout(r),n&&n(new Error("Debounced by a newer call"))),new Promise(((i,o)=>{const c=this;n=o,r=setTimeout((()=>{r=null,n=null,e.apply(c,s).then(i).catch(o)}),t)}))}}((async(...e)=>{const n=`${t}-${JSON.stringify(e)}`;if(w.get(n))return;w.set(n,!0);const s=crypto.randomUUID(),i=performance.now(),o={id:s,name:t,params:e,startTime:i};try{return await l.set((async t=>{const n=await r(t,...e);return o.result=n,n})),o.status="success",l.get()}catch(e){throw o.status="error",o.error=e instanceof Error?e:new Error(String(e)),console.error(`Error in action ${t}:`,e),e}finally{o.endTime=performance.now(),o.duration=o.endTime-i,m.track(o),w.delete(n)}}),a),e)),{});function p(e,t){const r=function(e,t="."){const r=[],n={get:(e,t)=>{const s=[];return r.length>0&&s.push(...r[r.length-1]),s.push(t),r.push(s),new Proxy({},n)}};return e(new Proxy({},n)),r.map((e=>e.join(t)))}(e);return l.subscribe(r,t)}const y=()=>l.get(),b=e=>(l.isReady()&&e(),l.onStoreEvent("persistence:ready",e)),g=()=>l.isReady();return function(){const r=e((e=>{const r=d.create(e);return t((e=>p(r,e)),(()=>r(l.get())),(()=>r(l.get())))}),[]),n=e((()=>t((e=>l.subscribe("",e)),y,y)),[]),s=t(b,g,g);return{store:l,observer:h,select:r,actions:f,isReady:s,actionTracker:m,get state(){return n}}}}export{o as createStore};
+import{useCallback as e,useSyncExternalStore as t}from"react";import{ReactiveDataStore as n,StoreObserver as r}from"@asaidimu/utils-store";var s=class{selectorCache=new WeakMap;create(e){return t=>{let n=this.selectorCache.get(e);if(n&&n.lastState===t)return n.lastResult;const r=e(t);return this.selectorCache.set(e,{lastState:t,lastResult:r}),r}}},o=class{executions=[];maxHistory=100;listeners=new Set;track(e){this.executions.unshift(e),this.executions.length>this.maxHistory&&this.executions.pop(),this.notify()}getExecutions(){return[...this.executions]}subscribe(e){return this.listeners.add(e),()=>this.listeners.delete(e)}notify(){this.listeners.forEach((e=>e()))}};function i(e,t=new WeakMap){return void 0===e?"undefined":"function"==typeof e||"symbol"==typeof e?"":"string"==typeof e?`"${e}"`:"number"==typeof e||"boolean"==typeof e||null===e?String(e):Array.isArray(e)?`[${e.map((e=>i(e,t))).join(",")}]`:"object"==typeof e?t.has(e)?'"__circular__"':(t.set(e,!0),`{${Object.keys(e).sort().map((n=>`"${n}":${i(e[n],t)}`)).join(",")}}`):""}function c(e){let t=3421674724,n=2216829733;const r=i(e);for(let e=0;e<r.length;e++){n^=r.charCodeAt(e);const s=Math.imul(n,435),o=Math.imul(n,435)+Math.imul(t,435);n=s>>>0,t=o>>>0}return(t>>>0).toString(16)+(n>>>0).toString(16)}function a(i,{enableMetrics:a,debounceTime:u=0,...l}={}){const h=new n(i.state,l.persistence),d=new n(Object.fromEntries(Object.keys(i.actions).map((e=>[e,!1])))),f=a?new r(h,l):void 0,m=new s,p=a?new o:void 0,y=a?new Map:void 0;i.middleware&&Object.entries(i.middleware).forEach((([e,t])=>h.use({name:e,action:t}))),i.blockingMiddleware&&Object.entries(i.blockingMiddleware).forEach((([e,t])=>h.use({block:!0,name:e,action:t})));const b=Object.entries(i.actions).reduce(((e,[t,n])=>(e[t]=function(e,t){if(0===t)return e;let n=null;return function(...r){return new Promise(((s,o)=>{n&&clearTimeout(n);const i=this;n=setTimeout((()=>{n=null,e.apply(i,r).then(s).catch(o)}),t)}))}}((async(...e)=>{const r=`${t}-${c(e)}`;if(y?.get(r))return;y?.set(r,!0);const s=p?crypto.randomUUID():void 0,o=p?performance.now():void 0,i=p?{id:s,name:t,params:e,startTime:o}:{};try{return d.set((e=>({...e,[t]:!0}))),await h.set((async t=>{const r=await n(t,...e);return p&&(i.result=r),r})),p&&(i.status="success"),h.get()}catch(e){throw p&&(i.status="error",i.error=e instanceof Error?e:new Error(String(e))),console.error(`Error in action ${t}:`,e),e}finally{d.set((e=>({...e,[t]:!1}))),p&&(i.endTime=performance.now(),i.duration=i.endTime-o,p.track(i)),y?.delete(r)}}),u),e)),{});function w(e,t){const n=function(e,t="."){const n=[],r={get:(e,t)=>{const s=[];return n.length>0&&s.push(...n[n.length-1]),s.push(t),n.push(s),new Proxy({},r)}};return e(new Proxy({},r)),n.map((e=>e.join(t)))}(e);return h.subscribe(n,t)}const g=()=>h.get(),x=e=>(h.isReady()&&e(),h.onStoreEvent("persistence:ready",e)),j=()=>h.isReady(),k=new Map;return function(){const n=e((e=>{k.has(e)||k.set(e,m.create(e));const n=k.get(e);return t((e=>w(n,e)),(()=>n(h.get())),(()=>n(h.get())))}),[]),r=e((()=>t((e=>h.subscribe("",e)),g,g)),[]),s=t(x,j,j);return{store:h,observer:f,select:n,actions:b,isReady:s,actionTracker:p,watch:e=>t((t=>d.subscribe(e,t)),(()=>d.get()[e]),(()=>d.get()[e])),get state(){return r}}}}export{a as createStore};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@asaidimu/react-store",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "Efficient react state manager.",
   "main": "index.js",
   "types": "index.d.ts",
@@ -26,12 +26,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@asaidimu/events": "^1.1.1",
-    "@asaidimu/indexed": "^1.1.3",
-    "@asaidimu/node": "^1.0.6",
-    "@asaidimu/query": "^1.1.2",
-    "@asaidimu/utils-persistence": "^2.0.1",
-    "@asaidimu/utils-store": "^2.1.0",
+    "@asaidimu/utils-persistence": "^2.1.0",
+    "@asaidimu/utils-store": "^2.2.0",
     "hash-wasm": "^4.12.0",
     "react": "^19.0.0",
     "uuid": "^11.1.0"