@asaidimu/react-store 1.0.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Saidimu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,170 @@
+# @asaidimu/react-store
+
+A robust, production-ready state management solution for React applications, designed for performance, scalability, and ease of use.
+
+## Installation
+
+Install the package using npm or yarn:
+
+```bash
+npm install @asaidimu/react-store
+```
+
+## Key Features
+
+- **Performance Metrics**: Built-in metrics collection for debugging and performance monitoring.
+- **Selector Caching**: Efficient selector caching system to optimize state access.
+- **Middleware Support**: Execute middleware functions during state updates.
+- **Persistence**: Persist state across page reloads with customizable storage options.
+- **Error Handling**: Comprehensive error handling with recovery strategies.
+
+## Usage
+
+### Basic Example
+
+```typescript
+// store.ts
+import { createNodeStore } from "@asaidimu/react-store";
+
+interface State {
+  count: number;
+}
+
+const definition = {
+  state: { count: 0 },
+  actions: {
+    increment: (state) => ({ count: state.count + 1 }),
+    decrement: (state) => ({ count: state.count - 1 }),
+  },
+};
+
+const useStore = createNodeStore(definition);
+
+export default useStore;
+```
+
+```typescript
+// component.tsx
+import useStore from "./store";
+
+function Counter() {
+  const { select, actions } = useStore();
+
+  const count = select((state) => state.count);
+
+  return (
+    <div>
+      <p>Count: {count}</p>
+      <button onClick={() => actions.increment()}>Increment</button>
+      <button onClick={() => actions.decrement()}>Decrement</button>
+    </div>
+  );
+}
+
+export default Counter;
+```
+
+### Advanced Example with Middleware and Persistence
+
+```typescript
+// store.ts
+import { createNodeStore } from "@asaidimu/react-store";
+
+interface State {
+  count: number;
+}
+
+const definition = {
+  state: { count: 0 },
+  actions: {
+    increment: (state) => ({ count: state.count + 1 }),
+    decrement: (state) => ({ count: state.count - 1 }),
+  },
+  middleware: [(state) => {
+    console.log("State updated:", state);
+    return state;
+  }],
+};
+
+const useStore = createNodeStore(definition);
+
+export default useStore;
+```
+
+### Using Selectors
+
+Selectors can be used to memoize frequently accessed state properties:
+
+```typescript
+const { select } = useStore();
+
+// Memoized selector for total items
+const totalItems = select((state) => state.items.length);
+
+// Usage in component
+function Component() {
+  const itemsCount = totalItems();
+
+  return <div>Items: {itemsCount}</div>;
+}
+```
+
+## Configuration Options
+
+The `createNodeStore` function accepts a configuration object with the following options:
+
+| Option              | Description                                                                 | Default Value |
+|----------------------|-----------------------------------------------------------------------------|--------------|
+| `enableMetrics`      | Enable performance metrics collection                                         | `false`      |
+| `middleware`         | Array of middleware functions to execute during state updates                | `[]`         |
+| `error`              | Error handling and recovery configuration                                     | `null`       |
+
+### Error Handling Configuration
+
+The `error` option accepts an object with the following properties:
+
+| Property           | Description                                                                 |
+|--------------------|-----------------------------------------------------------------------------|
+| `onError`         | Function to call when an error occurs                                         |
+| `recovery`        | Recovery configuration                                                     |
+
+The `recovery` object can have the following properties:
+
+| Property           | Description                                                                 |
+|--------------------|-----------------------------------------------------------------------------|
+| `strategy`       | Recovery strategy (`"rollback"`, `"retry"`, `"reset"`)                        |
+| `maxAttempts`    | Maximum number of retry attempts                                              |
+| `backoffMs`      | Backoff time in milliseconds between retry attempts                            |
+
+
+## Middleware
+
+Middleware functions can be used to execute logic before or after state updates. They receive the current state and must return a new state object.
+
+```typescript
+const middleware = (state) => {
+  console.log("State before update:", state);
+  return state;
+};
+```
+
+## Performance Metrics
+
+The library provides built-in performance metrics collection. You can access these metrics using the `getMetrics` function.
+
+```typescript
+const metrics = useStore.getMetrics();
+console.log("Updates:", metrics.updates);
+console.log("Last update duration:", metrics.lastUpdateDuration);
+```
+
+## Debugging
+
+The library provides several debugging features:
+
+- **Metrics Collection**: Track state updates and subscription triggers.
+- **Error Logging**: Detailed error logging with stack traces.
+
+## License
+
+This library is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

package/index.cjs

@@ -0,0 +1 @@
+"use strict";var p=Object.defineProperty;var S=Object.getOwnPropertyDescriptor;var b=Object.getOwnPropertyNames;var T=Object.prototype.hasOwnProperty;var v=(a,e)=>{for(var t in e)p(a,t,{get:e[t],enumerable:!0})},w=(a,e,t,i)=>{if(e&&typeof e=="object"||typeof e=="function")for(let r of b(e))!T.call(a,r)&&r!==t&&p(a,r,{get:()=>e[r],enumerable:!(i=S(e,r))||i.enumerable});return a};var M=a=>w(p({},"__esModule",{value:!0}),a);var $={};v($,{StateManager:()=>l,createStore:()=>x});module.exports=M($);var h=require("react");var y=require("@asaidimu/node"),k="root",g=class{cache=new Map;maxSize;maxAge;constructor(e=100,t=5e3){this.maxSize=e,this.maxAge=t}get(e){let t=this.cache.get(e);if(t){if(Date.now()-t.timestamp>this.maxAge){this.cache.delete(e);return}return t.value}}set(e,t){if(this.cache.size>=this.maxSize){let i=this.cache.keys().next().value;this.cache.delete(i)}this.cache.set(e,{value:t,timestamp:Date.now()})}},l=class{manager;subscribers=new Set;middleware;options;definition;middlewareCache;constructor(e,t={}){this.definition=e,this.options=t,this.middleware=t.middleware||[],this.middlewareCache=new g,this.manager=this.initializeManager()}initializeManager(){let e=(0,y.createNodeManager)();e.add("root",null,{key:"root"});let t=(i="root",r=this.definition.state)=>{for(let[s,n]of Object.entries(r))typeof n=="object"&&!Array.isArray(n)?(e.add(`${i}/${s}`,null,{key:s}),t(`${i}/${s}`,n)):e.add(`${i}/${s}`,n,{key:s})};if(t(),this.definition.sync){let i=this.getState.bind(this),r=this.definition.sync;e.subscribe("node",()=>{r(i())})}return e}getState(){return this.manager.store().map("key").root}getTree(){return this.manager.store().serialize()}setState(e,t){let i=this.getState();if(!i)return;let r=(s,n)=>{if(typeof n=="object"&&!Array.isArray(n))for(let[o,u]of Object.entries(n)){let d=`${s}/${o}`;r(d,u)}else this.manager.update(s,n)};try{for(let[s,n]of Object.entries(e)){let o=t?`${t}/${s}`:`root/${s}`;if(i[s]===n)continue;if(!this.validateState({[s]:n},o))throw new Error(`Validation failed for ${o}`);let u=this.applyMiddleware({[s]:n},o);r(o,u[s])}this.notifySubscribers()}catch(s){this.handleError(s,{action:"setState",state:e})}}validateState(e,t){if(!this.options.validation)return!0;let i=t.split("/").pop(),r=this.options.validation[i];return r?r.every(s=>{try{return s.validate(e[i])}catch(n){return console.error(`Validation error at ${t}:`,n),!1}}):!0}applyMiddleware(e,t){let i=`${t}-${JSON.stringify(e)}`,r=this.middlewareCache.get(i);if(r)return r;let s=this.middleware.reduce((n,o)=>o(n),e);return this.middlewareCache.set(i,s),s}handleError(e,t){this.options.error?.onError&&this.options.error.onError(e,t),this.options.error?.recovery}subscribe(e){return this.subscribers.add(e),()=>{this.subscribers.delete(e)}}notifySubscribers(){this.subscribers.forEach(e=>e())}select(e,t){let i=[],r=this.manager;function s(n){let o={get:(u,d)=>{let c=`${n}/${d}`;return r.exists(c)&&i.push(c),s(c)}};return new Proxy({},o)}return e(s(k)),r.subscribe({event:"node",path:i},t)}};var f=class{metrics={updates:0,subscriptionTriggers:0,middlewareExecutions:0,batchSize:0,lastUpdateDuration:0};enableMetrics;constructor(e=!1){this.enableMetrics=e}track(e,t){if(!this.enableMetrics)return t();let i=performance.now();try{let r=t();return this.recordMetric(e,performance.now()-i),r}catch(r){throw this.recordError(e,r),r}}recordMetric(e,t){switch(e){case"update":this.metrics.updates++,this.metrics.lastUpdateDuration=t;break;case"subscription":this.metrics.subscriptionTriggers++;break;case"middleware":this.metrics.middlewareExecutions++;break}}recordError(e,t){console.error(`Error in ${e}:`,t)}getMetrics(){return{...this.metrics}}reset(){this.metrics={updates:0,subscriptionTriggers:0,middlewareExecutions:0,batchSize:0,lastUpdateDuration:0}}},m=class{selectorCache=new WeakMap;create(e){return t=>{let i=this.selectorCache.get(e);i||(i=new WeakMap,this.selectorCache.set(e,i));let r=i.get(t);if(r)return r.result;let s=e(t);return i.set(t,{result:s,deps:[]}),s}}};function x(a,e={}){let t=new l(a,e),i=new m,r=new f(e.enableMetrics),s=Object.entries(a.actions).reduce((n,[o,u])=>(n[o]=async(...d)=>{try{return await r.track("update",async()=>{let c=await u(t.getState(),...d);return t.setState(c),c})}catch(c){throw console.error(`Error in action ${o}:`,c),c}},n),{});return function(){return{select:(0,h.useCallback)(u=>{let d=i.create(u);return(0,h.useSyncExternalStore)(c=>r.track("subscription",()=>t.select(d,c)),()=>d(t.getState()),()=>d(t.getState()))},[]),actions:s,getState:()=>t.getState(),getTree:()=>t.getTree(),getMetrics:()=>r.getMetrics(),resetMetrics:()=>r.reset()}}}0&&(module.exports={StateManager,createStore});

package/index.d.cts

@@ -0,0 +1,91 @@
+import * as _asaidimu_node from '@asaidimu/node';
+
+type Middleware<T> = (state: T) => T;
+type Actions<T> = {
+    [K: string]: (state: T, ...args: any[]) => Partial<T> | Promise<Partial<T>>;
+};
+interface StoreDefinition<T, R extends Actions<T>> {
+    state: T;
+    actions: R;
+    sync?: (args: T) => void;
+}
+type Schema<T> = {
+    [K in keyof T]?: {
+        validate: (value: T[K]) => boolean;
+        message: string;
+    }[];
+};
+interface Migration<T> {
+    version: number;
+    migrate: (state: T) => T;
+}
+interface ErrorConfig {
+    onError?: (error: Error, errorInfo: {
+        action?: string;
+        state?: any;
+        [key: string]: unknown;
+    }) => void;
+    recovery?: {
+        strategy: "rollback" | "retry" | "reset";
+        maxAttempts: number;
+        backoffMs: number;
+    };
+}
+interface StoreOptions<T> {
+    name?: string;
+    trace?: boolean;
+    maxTraceHistory?: number;
+    traceRetentionPeriod?: number;
+    middleware?: Middleware<T>[];
+    migrations?: Migration<T>[];
+    validation?: Schema<T>;
+    error?: ErrorConfig;
+}
+interface StateManagerMetrics {
+    updates: number;
+    subscriptionTriggers: number;
+    middlewareExecutions: number;
+    batchSize: number;
+    lastUpdateDuration: number;
+}
+
+/**
+ * Production-ready store creator without unnecessary memoization
+ */
+declare function createStore<T extends Record<string, unknown>, R extends Actions<T>>(definition: StoreDefinition<T, R>, options?: StoreOptions<T> & {
+    enableMetrics?: boolean;
+    devTools?: boolean;
+}): () => {
+    select: <S>(selector: (state: T) => S) => S;
+    actions: { [K in keyof R]: (...args: Parameters<R[K]> extends [T, ...infer P] ? P : never) => void; };
+    getState: () => T;
+    getTree: () => _asaidimu_node.Node<any, {
+        key: string;
+    }>[];
+    getMetrics: () => StateManagerMetrics;
+    resetMetrics: () => void;
+};
+
+declare class StateManager<T extends Record<string, unknown>, R extends Actions<T>> {
+    private manager;
+    private subscribers;
+    private middleware;
+    private options;
+    private definition;
+    private middlewareCache;
+    constructor(definition: StoreDefinition<T, R>, options?: StoreOptions<T>);
+    private initializeManager;
+    getState(): T;
+    getTree(): _asaidimu_node.Node<any, {
+        key: string;
+    }>[];
+    setState(nextState: Partial<T>, path?: string): void;
+    private validateState;
+    private applyMiddleware;
+    private handleError;
+    subscribe(callback: () => void): () => void;
+    private notifySubscribers;
+    select<S>(selector: (state: T) => S, callback: (state: any) => void): () => void;
+}
+
+export { StateManager, createStore };

package/index.d.ts

@@ -0,0 +1,91 @@
+import * as _asaidimu_node from '@asaidimu/node';
+
+type Middleware<T> = (state: T) => T;
+type Actions<T> = {
+    [K: string]: (state: T, ...args: any[]) => Partial<T> | Promise<Partial<T>>;
+};
+interface StoreDefinition<T, R extends Actions<T>> {
+    state: T;
+    actions: R;
+    sync?: (args: T) => void;
+}
+type Schema<T> = {
+    [K in keyof T]?: {
+        validate: (value: T[K]) => boolean;
+        message: string;
+    }[];
+};
+interface Migration<T> {
+    version: number;
+    migrate: (state: T) => T;
+}
+interface ErrorConfig {
+    onError?: (error: Error, errorInfo: {
+        action?: string;
+        state?: any;
+        [key: string]: unknown;
+    }) => void;
+    recovery?: {
+        strategy: "rollback" | "retry" | "reset";
+        maxAttempts: number;
+        backoffMs: number;
+    };
+}
+interface StoreOptions<T> {
+    name?: string;
+    trace?: boolean;
+    maxTraceHistory?: number;
+    traceRetentionPeriod?: number;
+    middleware?: Middleware<T>[];
+    migrations?: Migration<T>[];
+    validation?: Schema<T>;
+    error?: ErrorConfig;
+}
+interface StateManagerMetrics {
+    updates: number;
+    subscriptionTriggers: number;
+    middlewareExecutions: number;
+    batchSize: number;
+    lastUpdateDuration: number;
+}
+
+/**
+ * Production-ready store creator without unnecessary memoization
+ */
+declare function createStore<T extends Record<string, unknown>, R extends Actions<T>>(definition: StoreDefinition<T, R>, options?: StoreOptions<T> & {
+    enableMetrics?: boolean;
+    devTools?: boolean;
+}): () => {
+    select: <S>(selector: (state: T) => S) => S;
+    actions: { [K in keyof R]: (...args: Parameters<R[K]> extends [T, ...infer P] ? P : never) => void; };
+    getState: () => T;
+    getTree: () => _asaidimu_node.Node<any, {
+        key: string;
+    }>[];
+    getMetrics: () => StateManagerMetrics;
+    resetMetrics: () => void;
+};
+
+declare class StateManager<T extends Record<string, unknown>, R extends Actions<T>> {
+    private manager;
+    private subscribers;
+    private middleware;
+    private options;
+    private definition;
+    private middlewareCache;
+    constructor(definition: StoreDefinition<T, R>, options?: StoreOptions<T>);
+    private initializeManager;
+    getState(): T;
+    getTree(): _asaidimu_node.Node<any, {
+        key: string;
+    }>[];
+    setState(nextState: Partial<T>, path?: string): void;
+    private validateState;
+    private applyMiddleware;
+    private handleError;
+    subscribe(callback: () => void): () => void;
+    private notifySubscribers;
+    select<S>(selector: (state: T) => S, callback: (state: any) => void): () => void;
+}
+
+export { StateManager, createStore };

package/index.js

@@ -0,0 +1 @@
+import{useCallback as y,useSyncExternalStore as S}from"react";import{createNodeManager as f}from"@asaidimu/node";var m="root",h=class{cache=new Map;maxSize;maxAge;constructor(e=100,t=5e3){this.maxSize=e,this.maxAge=t}get(e){let t=this.cache.get(e);if(t){if(Date.now()-t.timestamp>this.maxAge){this.cache.delete(e);return}return t.value}}set(e,t){if(this.cache.size>=this.maxSize){let i=this.cache.keys().next().value;this.cache.delete(i)}this.cache.set(e,{value:t,timestamp:Date.now()})}},l=class{manager;subscribers=new Set;middleware;options;definition;middlewareCache;constructor(e,t={}){this.definition=e,this.options=t,this.middleware=t.middleware||[],this.middlewareCache=new h,this.manager=this.initializeManager()}initializeManager(){let e=f();e.add("root",null,{key:"root"});let t=(i="root",s=this.definition.state)=>{for(let[r,n]of Object.entries(s))typeof n=="object"&&!Array.isArray(n)?(e.add(`${i}/${r}`,null,{key:r}),t(`${i}/${r}`,n)):e.add(`${i}/${r}`,n,{key:r})};if(t(),this.definition.sync){let i=this.getState.bind(this),s=this.definition.sync;e.subscribe("node",()=>{s(i())})}return e}getState(){return this.manager.store().map("key").root}getTree(){return this.manager.store().serialize()}setState(e,t){let i=this.getState();if(!i)return;let s=(r,n)=>{if(typeof n=="object"&&!Array.isArray(n))for(let[a,d]of Object.entries(n)){let c=`${r}/${a}`;s(c,d)}else this.manager.update(r,n)};try{for(let[r,n]of Object.entries(e)){let a=t?`${t}/${r}`:`root/${r}`;if(i[r]===n)continue;if(!this.validateState({[r]:n},a))throw new Error(`Validation failed for ${a}`);let d=this.applyMiddleware({[r]:n},a);s(a,d[r])}this.notifySubscribers()}catch(r){this.handleError(r,{action:"setState",state:e})}}validateState(e,t){if(!this.options.validation)return!0;let i=t.split("/").pop(),s=this.options.validation[i];return s?s.every(r=>{try{return r.validate(e[i])}catch(n){return console.error(`Validation error at ${t}:`,n),!1}}):!0}applyMiddleware(e,t){let i=`${t}-${JSON.stringify(e)}`,s=this.middlewareCache.get(i);if(s)return s;let r=this.middleware.reduce((n,a)=>a(n),e);return this.middlewareCache.set(i,r),r}handleError(e,t){this.options.error?.onError&&this.options.error.onError(e,t),this.options.error?.recovery}subscribe(e){return this.subscribers.add(e),()=>{this.subscribers.delete(e)}}notifySubscribers(){this.subscribers.forEach(e=>e())}select(e,t){let i=[],s=this.manager;function r(n){let a={get:(d,c)=>{let o=`${n}/${c}`;return s.exists(o)&&i.push(o),r(o)}};return new Proxy({},a)}return e(r(m)),s.subscribe({event:"node",path:i},t)}};var p=class{metrics={updates:0,subscriptionTriggers:0,middlewareExecutions:0,batchSize:0,lastUpdateDuration:0};enableMetrics;constructor(e=!1){this.enableMetrics=e}track(e,t){if(!this.enableMetrics)return t();let i=performance.now();try{let s=t();return this.recordMetric(e,performance.now()-i),s}catch(s){throw this.recordError(e,s),s}}recordMetric(e,t){switch(e){case"update":this.metrics.updates++,this.metrics.lastUpdateDuration=t;break;case"subscription":this.metrics.subscriptionTriggers++;break;case"middleware":this.metrics.middlewareExecutions++;break}}recordError(e,t){console.error(`Error in ${e}:`,t)}getMetrics(){return{...this.metrics}}reset(){this.metrics={updates:0,subscriptionTriggers:0,middlewareExecutions:0,batchSize:0,lastUpdateDuration:0}}},g=class{selectorCache=new WeakMap;create(e){return t=>{let i=this.selectorCache.get(e);i||(i=new WeakMap,this.selectorCache.set(e,i));let s=i.get(t);if(s)return s.result;let r=e(t);return i.set(t,{result:r,deps:[]}),r}}};function M(u,e={}){let t=new l(u,e),i=new g,s=new p(e.enableMetrics),r=Object.entries(u.actions).reduce((n,[a,d])=>(n[a]=async(...c)=>{try{return await s.track("update",async()=>{let o=await d(t.getState(),...c);return t.setState(o),o})}catch(o){throw console.error(`Error in action ${a}:`,o),o}},n),{});return function(){return{select:y(d=>{let c=i.create(d);return S(o=>s.track("subscription",()=>t.select(c,o)),()=>c(t.getState()),()=>c(t.getState()))},[]),actions:r,getState:()=>t.getState(),getTree:()=>t.getTree(),getMetrics:()=>s.getMetrics(),resetMetrics:()=>s.reset()}}}export{l as StateManager,M as createStore};

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@asaidimu/react-store",
+  "version": "1.0.0",
+  "description": "Efficient react state manager.",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "files": [
+    "./*"
+  ],
+  "keywords": [
+    "typescript"
+  ],
+  "author": "Saidimu <47994458+asaidimu@users.noreply.github.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/asaidimu/node-react.git"
+  },
+  "bugs": {
+    "url": "https://github.com/asaidimu/node-react/issues"
+  },
+  "homepage": "https://github.com/asaidimu/node-react#readme",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "tag": "latest",
+    "access": "public"
+  },
+  "dependencies": {
+    "@asaidimu/events": "^1.0.0",
+    "@asaidimu/node": "^1.0.4",
+    "react": "^19.0.0"
+  }
+}