react-state-custom 1.0.30 → 1.0.32

package/README.md

@@ -19,10 +19,9 @@ npm install react-state-custom
 If you already know how to write a component with `useState`, you're moments away from sharing that state everywhere.
 
 1. **Write a plain hook** – encapuslate data fetching, derived values, and actions inside a normal React hook.
-2. **Create a root context** – `createRootCtx('feature', useFeatureState)` publishes the hook output into a context namespace.
-3. **Let AutoRoot manage lifecycles** – `createAutoCtx(rootCtx, 150)` registers the store with `<AutoRootCtx />` and (optionally) keeps it alive for a short grace period after the last subscriber unmounts.
-4. **Mount `<AutoRootCtx />` once** – drop it near the top of your tree (wrap it with your own `ErrorBoundary` if desired).
-5. **Consume anywhere** – call the generated `useCtxState` hook and destructure data via `useQuickSubscribe` or any `useDataSubscribe*` helper.
+2. **Create a store** – `createStore('feature', useFeatureState)` creates a shared store and returns a `useStore` hook.
+3. **Mount `<AutoRootCtx />` once** – drop it near the top of your tree (wrap it with your own `ErrorBoundary` if desired).
+4. **Consume anywhere** – call the generated `useStore` hook to access data and actions.
 
 ```tsx
 const useFeatureState = ({ featureId }: { featureId: string }) => {
@@ -31,8 +30,7 @@ const useFeatureState = ({ featureId }: { featureId: string }) => {
   return { value, double, increment: () => setValue(v => v + 1) }
 }
 
-const featureRoot = createRootCtx('feature', useFeatureState)
-export const { useCtxState: useFeatureCtx } = createAutoCtx(featureRoot, 250)
+export const { useStore: useFeatureStore } = createStore('feature', useFeatureState)
 
 function AppShell() {
   return (
@@ -44,8 +42,7 @@ function AppShell() {
 }
 
 function FeatureMeter({ featureId }: { featureId: string }) {
-  const ctx = useFeatureCtx({ featureId })
-  const { value, double, increment } = useQuickSubscribe(ctx)
+  const { value, double, increment } = useFeatureStore({ featureId })
   return (
     <section>
       <strong>{value}</strong>
@@ -111,8 +108,10 @@ Every consumer re-renders whenever anything in `value` changes, you have to reme
 
 ### With React State Custom (hook-first store)
 
+### With React State Custom (hook-first store)
+
 ```typescript
-import { createRootCtx, createAutoCtx, useQuickSubscribe, AutoRootCtx } from 'react-state-custom';
+import { createStore, AutoRootCtx } from 'react-state-custom';
 
 // 1. Write your state logic using familiar React hooks
 function useCounterState() {
@@ -123,8 +122,8 @@ function useCounterState() {
   return { count, increment, decrement };
 }
 
-// 2. Create shared context (one line!)
-const { useCtxState } = createAutoCtx(createRootCtx('counter', useCounterState));
+// 2. Create shared store (one line!)
+const { useStore } = createStore('counter', useCounterState);
 
 // 3. Add AutoRootCtx to your app root (mount it once near the top of your tree)
 function App() {
@@ -138,8 +137,7 @@ function App() {
 
 // 4. Use anywhere in your app
 function Counter() {
-  const ctx = useCtxState();
-  const { count, increment, decrement } = useQuickSubscribe(ctx);
+  const { count, increment, decrement } = useStore({});
   
   return (
     <div>
@@ -153,7 +151,7 @@ function Counter() {
 
 > ℹ️ `AutoRootCtx` accepts optional `Wrapper` and `debugging` props. Pass an ErrorBoundary-like component through `Wrapper` to isolate failures, or set `debugging` to `true` to render raw state snapshots in the DOM (handy alongside React DevTools when tracking updates).
 
-`useQuickSubscribe` keeps `Counter` focused on `count`, so even if this context grows with more fields later, the component only re-renders when `count` changes.
+`useStore` keeps `Counter` focused on `count`, so even if this context grows with more fields later, the component only re-renders when `count` changes.
 
 **That's it!** No reducers, no actions, no providers to wrap—just hooks.
 
@@ -162,7 +160,8 @@ function Counter() {
 - **Contexts on demand** – `Context` extends `EventTarget`, so every state update is just an event dispatch. `getContext` memoizes instances per name and `useDataContext` automatically bumps a counter so unused contexts self-evict shortly after the last consumer unmounts.
 - **Publishers** – `useDataSource` and `useDataSourceMultiple` publish inside effects to keep renders pure. A registry guards against duplicate publishers fighting over the same key so you get actionable errors instead of stale data.
 - **Subscribers** – `useDataSubscribe*` hooks cover single, multiple, debounced, and transformed reads. `useQuickSubscribe` proxies the backing data object so each component subscribes only to the properties it touches.
-- **Root factories** – `createRootCtx` runs your headless hook exactly once per parameter set, publishes every returned key, and throws if two roots try to mount with the same resolved name. Parameters are serialized via `paramsToId`, so stick to primitive props (string/number/boolean/bigint/null/undefined) to keep IDs deterministic.
+- **Root factories** – `createRootCtx` runs your headless hook exactly once per parameter set, publishes every returned key, and throws if two roots try to mount with the same resolved name. Your hook receives `(props, preState)` so it can rehydrate from the last published values when a root remounts. Parameters are serialized via `paramsToId`, so stick to primitive props (string/number/boolean/bigint/null/undefined) to keep IDs deterministic.
+- **Composable Stores** – Because stores are just hooks, you can subscribe to one store *inside* the logic of another. This enables powerful reactive chains where a derived store automatically updates whenever its upstream dependencies change.
 - **Auto orchestration** – Mount `<AutoRootCtx />` once and wire each root through `createAutoCtx`. The auto root listens for subscription requests, mounts/destroys the corresponding root on demand, and optionally keeps them alive for a configurable `timeToClean` window to smooth thrashing.
 - **Dev tooling** – `DevToolContainer` watches the memoized context cache, flashes updates in place, and lets you plug in custom renderers so you can diff state right beside your UI.
 
@@ -196,6 +195,16 @@ const { Root, useCtxState } = createRootCtx('my-state', useMyState);
 const { useCtxState } = createAutoCtx(rootContext);
 ```
 
+### 6. Store factory – all in one
+```typescript
+const { useStore } = createStore('my-state', useMyState);
+```
+
+### 6. Store factory – all in one
+```typescript
+const { useStore } = createStore('my-state', useMyState);
+```
+
 ## 🎯 Key Features
 
 ### 1. **Just React Hooks**
@@ -299,9 +308,7 @@ function useAuthState() {
   return { user, loading, login, logout };
 }
 
-export const { useCtxState: useAuthState } = createAutoCtx(
-  createRootCtx('auth', useAuthState)
-);
+export const { useStore: useAuthStore } = createStore('auth', useAuthState);
 
 // App.tsx
 function App() {
@@ -318,8 +325,7 @@ function App() {
 
 // Header.tsx - Only re-renders when user changes
 function Header() {
-  const ctx = useAuthState();
-  const { user, logout } = useQuickSubscribe(ctx);
+  const { user, logout } = useAuthStore({});
   
   return (
     <header>
@@ -337,7 +343,7 @@ function Header() {
 
 // ProtectedRoute.tsx - Only re-renders when loading or user changes
 function ProtectedRoute({ children }) {
-  const ctx = useAuthState();
+  const ctx = useAuthStore.useCtxState({});
   const { user, loading } = useDataSubscribeMultiple(ctx, 'user', 'loading');
   
   if (loading) return <Spinner />;
@@ -400,21 +406,18 @@ function useUserState({ userId }: { userId: string }) {
   // State logic here
 }
 
-const { useCtxState: useUserCtxState } = createAutoCtx(
-  createRootCtx('user', useUserState)
-);
+const { useStore: useUserStore } = createStore('user', useUserState);
 
 // Different instances for different users
 function UserProfile({ userId }) {
-  const ctx = useUserCtxState({ userId }); // Automatic instance per userId
-  const { user } = useQuickSubscribe(ctx);
+  const { user } = useUserStore({ userId }); // Automatic instance per userId
   return <div>{user?.name}</div>;
 }
 ```
 
-> Need to avoid rapid mount/unmount churn? Pass a second argument to `createAutoCtx` (for example `createAutoCtx(rootCtx, 200)`) to keep instances alive for a few extra milliseconds before disposal.
+> Need to avoid rapid mount/unmount churn? Pass a second argument to `createStore` (for example `createStore('user', useUserState, 200)`) to keep instances alive for a few extra milliseconds before disposal.
 
-> ⚠️ The props you pass to `createRootCtx`/`useCtxState` must be composed of primitive values (string, number, boolean, bigint, null, or undefined). Objects are rejected so context names stay deterministic—pass IDs instead of raw objects.
+> ⚠️ The props you pass to `createStore`/`useStore` must be composed of primitive values (string, number, boolean, bigint, null, or undefined). Objects are rejected so context names stay deterministic—pass IDs instead of raw objects.
 
 ### Debounced Subscriptions
 Optimize performance for frequently changing values:
@@ -438,6 +441,32 @@ const userStats = useDataSubscribeWithTransform(
 );
 ```
 
+### Composing Stores (Derived State)
+Since stores are just hooks, you can subscribe to one store *inside* another. This allows you to build reactive dependency chains where a downstream store automatically updates when an upstream store changes.
+
+```typescript
+// 1. Upstream Store
+const { useStore: useUserStore } = createStore('user', () => {
+  const [role, setRole] = useState('guest');
+  return { role, setRole };
+});
+
+// 2. Downstream Store (depends on User)
+const useDashboardStore = () => {
+  // Subscribe to the upstream store
+  const { role } = useUserStore({});
+
+  // Derive state based on the upstream value
+  const permissions = useMemo(() => {
+    return role === 'admin' ? ['read', 'write', 'delete'] : ['read'];
+  }, [role]);
+
+  return { permissions };
+};
+
+const { useStore: useDashboardStore } = createStore('dashboard', useDashboardStore);
+```
+
 ## 🎮 Live Examples
 
 Explore interactive examples in the **[Live Demo](https://vothanhdat.github.io/react-state-custom/)**:

package/dist/index.d.ts

@@ -1,7 +1,8 @@
 export { Context, getContext, useDataContext, useDataSource, useDataSourceMultiple, useDataSubscribe, useDataSubscribeMultiple, useDataSubscribeMultipleWithDebounce, useDataSubscribeWithTransform } from './state-utils/ctx';
 export { createRootCtx } from './state-utils/createRootCtx';
-export { AutoRootCtx, createAutoCtx } from './state-utils/createAutoCtx';
+export { AutoRootCtx, createAutoCtx, createStore } from './state-utils/createAutoCtx';
 export { useArrayChangeId } from './state-utils/useArrayChangeId';
+export { paramsToId, type ParamsToIdRecord, type ParamsToIdInput } from './state-utils/paramsToId';
 export { useQuickSubscribe } from './state-utils/useQuickSubscribe';
 export { DevToolContainer } from './dev-tool/DevTool';
 export type { DataViewComponent } from './dev-tool/DataViewComponent';