@yakocloud/state-vocab 4.1.0 → 4.3.0

package/README.md

@@ -117,7 +117,7 @@ npm install @yakocloud/state-vocab react react-dom
 
 ## Quick Start
 
-Define your storage tree once (`setupStorage`/`defineState`), call `clientify` to attach React hooks. If you use react server components (RSC) wrap your app with `StateVocabProvider` at the root and call `serverify` to attach RSC-methods. Use state anywhere in the tree
+Define your storage tree once (`setupStorage`/`defineState`), call `clientify` to attach React hooks. If you use React Server Components (RSC), wrap the relevant subtree with `StateVocabProvider` and call `serverify` to attach server-side `.getState()` methods. Use state anywhere in the tree.
 
 Library SSR-requirements:
 - `Per-request store`: A Next.js server can handle multiple requests simultaneously. This means that the store should be created per request and should not be shared across requests.
@@ -366,28 +366,14 @@ export const storage = setupStorage({
 })
 ```
 
-**2. Create a client context, then create server and client storage handles:**
-
-Each storage tree needs its own React context so that multiple independent providers can coexist on the same page without their state bleeding into each other.
-
-```ts
-// storage.context.client.ts  ("use client")
-"use client"
-
-import { createContext } from 'react'
-
-export const StorageClientContext = createContext({})
-```
+**2. Create server and client storage handles:**
 
 ```ts
 // storage.server.ts
 import { storage } from '@/storage'
 import { serverify } from '@yakocloud/state-vocab/server'
-import { StorageClientContext } from '@/storage.context.client'
 
-export const serverStorage = serverify(storage, {
-  clientContext: StorageClientContext,
-})
+export const serverStorage = serverify(storage)
 ```
 
 ```ts
@@ -396,11 +382,8 @@ export const serverStorage = serverify(storage, {
 
 import { storage } from '@/storage'
 import { clientify } from '@yakocloud/state-vocab/client'
-import { StorageClientContext } from '@/storage.context.client'
 
-export const clientStorage = clientify(storage, {
-  clientContext: StorageClientContext,
-})
+export const clientStorage = clientify(storage)
 ```
 
 **3. Seed initial state in the server component and read it in Server and Client children:**
@@ -456,41 +439,67 @@ export default function UserInfoClient() {
 
 #### Multiple independent storage trees
 
-Because each `serverify`/`clientify` pair is bound to its own context, you can have multiple independent providers active at the same time — for example, a layout-level store and a page-level store — without them interfering with each other:
+Because each `serverify`/`clientify` pair is bound to its own React context, you can have multiple independent providers active at the same time — for example, a layout-level store and a page-level store — without them interfering with each other. Pass a `clientContext` to link the server and client sides of each tree:
 
 ```ts
-// layout.context.client.ts ("use client")
-export const LayoutClientContext = createContext({})
-
-// page.context.client.ts ("use client")
-export const PageClientContext = createContext({})
-
 // layout.storage.server.ts
-export const layoutServerStorage = serverify(layoutStorage, { 
-  clientContext: LayoutClientContext 
-})
+import { createContext } from 'react'
+export const LayoutClientContext = createContext({})
+export const layoutServerStorage = serverify(layoutStorage, { clientContext: LayoutClientContext })
 
 // layout.storage.client.ts ("use client")
-export const layoutClientStorage = clientify(layoutStorage, { 
-  clientContext: LayoutClientContext 
-})
+"use client"
+export const layoutClientStorage = clientify(layoutStorage, { clientContext: LayoutClientContext })
 
 // page.storage.server.ts
-export const pageServerStorage = serverify(pageStorage, { 
-  clientContext: PageClientContext 
-})
+import { createContext } from 'react'
+export const PageClientContext = createContext({})
+export const pageServerStorage = serverify(pageStorage, { clientContext: PageClientContext })
 
 // page.storage.client.ts ("use client")
-export const pageClientStorage = clientify(pageStorage, { 
-  clientContext: PageClientContext 
-})
+"use client"
+export const pageClientStorage = clientify(pageStorage, { clientContext: PageClientContext })
 ```
 
 Each `StateVocabProvider` wraps its own subtree; a component that calls `pageClientStorage.user.name.useState()` reads only from the nearest `pageServerStorage.StateVocabProvider`, not from the layout provider.
 
+#### Next.js App Router: layout and page are isolated contexts
+
+In Next.js App Router, **layouts do not re-render during client-side navigation between pages**. Layout and page run as independent React render passes — the layout renders once on entry and stays mounted; the page renders fresh on every navigation.
+
+Because `React.cache()` (which backs the per-request server store) is scoped to a single render pass, layout and page never share the same cache scope:
+
+- A page server component **cannot** call `layoutServerStorage.someField.getState()` — the layout's `StateVocabProvider` ran in a separate pass, so its vocab is not in the page's cache scope.
+- A layout server component **cannot** call `pageServerStorage.someField.getState()` for the same reason.
+- **Each storage tree must be both seeded and consumed within the same route segment.**
+
+```tsx
+// ✅ Correct — layout seeds and reads from its own storage
+// app/(dashboard)/layout.tsx
+const LayoutProvider = layoutServerStorage.StateVocabProvider
+export default async function Layout({ children }) {
+  return (
+    <LayoutProvider value={{ session: { id: 123 } }}>
+      <LayoutHeader />  {/* ← can call layoutServerStorage.session.getState() */}
+      {children}
+    </LayoutProvider>
+  )
+}
+
+// ❌ Wrong — page cannot reach layout's storage
+// app/(dashboard)/page.tsx
+export default async function Page() {
+  const session = layoutServerStorage.session.getState() // throws — not in layout's render pass
+}
+```
+
+If a page needs data that the layout already fetches (e.g., the current user session), fetch it independently in the page, pass it via URL params, or use a separate mechanism — do not attempt to share it through other state-vocab server storage across route segments.
+
+This constraint is **server-only**. On the client, there is no such limitation — client components can freely call `.useState()` from any storage (`layoutClientStorage`, `pageClientStorage`, or any other) regardless of which route segment they live in.
+
 #### `serverify(storage)`
 
-Converts a storage tree into its server-side counterpart. Each leaf gains a `.getState()` method that reads the value seeded into the nearest `StateVocabProvider`. Each namespace node (including the root) gains a `.seed()` method that returns the input wrapped under its full ancestor path. This method is optional for using. The result also exposes `StateVocabProvider` — a server-aware provider that accepts a plain object `value` prop to pre-seed the store.
+Converts a storage tree into its server-side counterpart. Each leaf gains a synchronous `.getState()` method that reads the value injected by the nearest `StateVocabProvider`. Each namespace node (including the root) gains a `.seed()` method that returns the input wrapped under its full ancestor path. The result also exposes `StateVocabProvider`.
 
 **`.seed()` syntax:**
 
@@ -508,7 +517,7 @@ serverStorage.person.address.seed({ city: 'NY' })
 // → { person: { address: { city: 'NY' } } }
 ```
 
-**`node.getState()`** reads the value for that leaf from the surrounding `StateVocabProvider`. Throws if called outside one.
+**`node.getState()`** synchronously reads the value for that leaf. Must be called within a React render context (i.e., inside a component that is a descendant of `StateVocabProvider`). Throws if called outside a provider scope or outside a React render context.
 
 #### `clientify(storage)`
 
@@ -745,28 +754,34 @@ import { StateVocabClientProvider } from '@yakocloud/state-vocab/client'
 </StateVocabClientProvider>
 ```
 
-### `serverify<T>(storage: T, options)`
+### `serverify<T>(storage: T, options?)`
 
 Converts a storage tree to its server-side counterpart. Available from `@yakocloud/state-vocab/server`.
 
 | Option | Type | Description |
 |---|---|---|
-| `clientContext` | `Context<object>` | **Required.** A React context created with `createContext({})` in a `"use client"` file. Must match the `clientContext` passed to `clientify` for the same storage tree. |
+| `clientContext` | `Context<object> \| undefined` | A React context created with `createContext({})`. Pass the same context to `clientify` when multiple independent storage trees coexist on the same page. Omit for single-tree setups. |
+
+The result exposes:
 
-Each leaf gains `.getState()` — reads the value from the nearest `StateVocabProvider`. Each namespace node gains `.seed()`, which returns the input wrapped under its full ancestor path. The result also includes `StateVocabProvider` — use it instead of importing from `@yakocloud/state-vocab/server`.
+- **`StateVocabProvider`** — server component that accepts a `value` prop and seeds the per-request store via `React.cache()`.
+- **`node.getState()`** — synchronously reads the value for that leaf. Must be called within a React render context (descendant of `StateVocabProvider`). Throws if called outside a provider scope or outside a render context.
+- **`node.seed(input)`** — wraps `input` under the node's ancestor path, returning a plain object ready to pass as the `value` prop.
 
 ```ts
 import { serverify } from '@yakocloud/state-vocab/server'
-import { MyClientContext } from '@/storage.context.client'
 
+const serverStorage = serverify(storage)
+// or, for multiple independent trees:
 const serverStorage = serverify(storage, { clientContext: MyClientContext })
 
-const { StateVocabProvider } = serverStorage        // server-aware provider
+const { StateVocabProvider } = serverStorage
 
-serverStorage.user.name.getState()                  // reads "user.name" from context
-serverStorage.user.seed({ name: 'Alice' })          // → { user: { name: 'Alice' } }
-serverStorage.person.address.seed({ city: 'NY' })   // → { person: { address: { city: 'NY' } } }
-serverStorage.seed({ user: { name: 'Alice' } })     // → { user: { name: 'Alice' } } (identity)
+// In a Server Component:
+serverStorage.user.name.getState()                     // reads "user.name" (sync)
+serverStorage.user.seed({ name: 'Alice' })             // → { user: { name: 'Alice' } }
+serverStorage.person.address.seed({ city: 'NY' })      // → { person: { address: { city: 'NY' } } }
+serverStorage.seed({ user: { name: 'Alice' } })        // → { user: { name: 'Alice' } } (identity)
 ```
 
 ### `clientify<T>(storage: T, options?)`
@@ -775,7 +790,7 @@ Converts a storage tree to its client-side counterpart. Available from `@yakoclo
 
 | Option | Type | Description |
 |---|---|---|
-| `clientContext` | `Context<object> \| undefined` | The React context created with `createContext({})` for this storage tree. Must match the `clientContext` passed to `serverify`. Required when using RSC; omit for SPA-only setups. |
+| `clientContext` | `Context<object> \| undefined` | The React context used to isolate this storage tree. Must match the `clientContext` passed to `serverify` for the same tree. Omit for single-tree setups. |
 
 Each leaf gains `.useState()` and `.useInitialState()`. The tree structure mirrors the original.
 

package/dist/client.cjs.js

@@ -1 +1 @@
-"use client";"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const f=require("react"),v=require("./constants-CbsduCZ7.js"),a=require("./utils-0CTNJ4ZE.js"),V=require("./provider-client-CAHe8VnM.js");function D(t,n,s=[]){return f.useMemo(()=>a.debounce(t,n),s)}const y=t=>{const{vocabStore:n,storage:s,statePath:o,value:e,deserialize:l,serialize:c}=t,d=s.getItem(o);d===null?a.isValueDefined(e)&&s.setItem(o,c(e)):n.set(o,l(d))},R=typeof window>"u",m=R?f.useEffect:f.useLayoutEffect,A=new V.VocabStore,P="Make sure your component is wrapped in StateVocabProvider (RSC) or disable ssr option in setupStorage for SPA (RCC only)";function I(t){const n=R?void 0:a.valueOrFactory(t.storage),s=a.valueOrFactory(t.defaultValue),o=t.bidirectional,e=this[v.STATE_PATH],l=this[v.STATE_VERBOSE],c=this[v.STATE_VERBOSE_PATH],d=this[v.STATE_SSR];let i=V.useStateVocabClientContext({clientContext:t.clientContext,verbose:l});if(!(i instanceof V.VocabStore)){if(d)throw new Error(P);i=A}const S=t.serialize??JSON.stringify,u=t.deserialize??JSON.parse,E=D(t.onSet??(()=>{}),t.delayedSet,[]),g=f.useRef(void 0),z=f.useRef(!1);if(!z.current){z.current=!0;let r=i.get(e);a.isValueDefined(r)||(r=s,a.isValueDefined(r)&&i.set(e,r)),!d&&n&&y({vocabStore:i,storage:n,statePath:e,value:r,serialize:S,deserialize:u})}const C=f.useSyncExternalStore(i.subscribe.bind(i),i.getClientSnapshot.bind(i),i.getServerSnapshot.bind(i));if(l)if(c){const r=a.get(C,c);r&&a.logStyled(r)}else a.logStyled(C);const h=a.get(C,e,s);g.current=h,m(()=>{!d||!n||y({vocabStore:i,storage:n,statePath:e,value:h,serialize:S,deserialize:u})},[]);const w=f.useEffectEvent(r=>{if(r.key!==e)return;const b=r.newValue,T=(b===null?null:u(b))??s;a.isValueDefined(T)&&(i.set(e,T),E(T,g.current))});f.useEffect(()=>{if(o)return window.addEventListener("storage",w),()=>window.removeEventListener("storage",w)},[o]);const x=f.useCallback(r=>{const b=a.isTransformer(r)?r(g.current):r;i.set(e,b),E(b,g.current),n&&n.setItem(e,S(b))},[i,e,E,n,S]),_=f.useCallback(()=>{const r=s;if(!a.isValueDefined(r)){n?.removeItem(e);return}i.set(e,r),E(r,g.current),n&&n.setItem(e,S(r))},[s,i,e,E,n,S]);return[h,x,_]}function p(t){const n=R?void 0:a.valueOrFactory(t.storage),s=a.valueOrFactory(t.defaultValue),o=this[v.STATE_PATH],e=this[v.STATE_VERBOSE],l=this[v.STATE_SSR];let c=V.useStateVocabClientContext({clientContext:t.clientContext,verbose:e});if(!(c instanceof V.VocabStore)){if(l)throw new Error(P);c=A}const d=t.serialize??JSON.stringify,i=t.deserialize??JSON.parse,S=f.useRef(!1);let u;S.current||(S.current=!0,u=c.get(o),a.isValueDefined(u)||(u=s,a.isValueDefined(u)&&c.set(o,u)),!l&&n&&y({vocabStore:c,storage:n,statePath:o,value:u,serialize:d,deserialize:i})),m(()=>{!l||!n||y({vocabStore:c,storage:n,statePath:o,value:u,serialize:d,deserialize:i})},[])}function k(t){return typeof t=="object"&&t!==null&&"clientSlot"in t}function O(t,n={}){const s={};for(const o in t){const e=t[o];k(e)?(s[o]=e.clientSlot({useState(l){return I.apply(this,[{clientContext:n.clientContext,...l}])},useInitialState(l){p.apply(this,[{clientContext:n.clientContext,...l}])}}),delete s[o].serverSlot,delete s[o].clientSlot):e!==null&&typeof e=="object"?s[o]=O(e,n):s[o]=e}return s}exports.StateVocabClientProvider=V.StateVocabClientProvider;exports.clientify=O;
+"use client";"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const f=require("react"),v=require("./constants-CbsduCZ7.js"),a=require("./utils-0CTNJ4ZE.js"),V=require("./provider-client-DA53zfcT.js");function D(t,n,s=[]){return f.useMemo(()=>a.debounce(t,n),s)}const y=t=>{const{vocabStore:n,storage:s,statePath:o,value:e,deserialize:l,serialize:c}=t,d=s.getItem(o);d===null?a.isValueDefined(e)&&s.setItem(o,c(e)):n.set(o,l(d))};function I(t){return typeof t=="object"&&t!==null&&"clientSlot"in t}const z=typeof window>"u",m=z?f.useEffect:f.useLayoutEffect,A=new V.VocabStore,P="Make sure your component is wrapped in StateVocabProvider (RSC) or disable ssr option in setupStorage for SPA (RCC only)";function p(t){const n=z?void 0:a.valueOrFactory(t.storage),s=a.valueOrFactory(t.defaultValue),o=t.bidirectional,e=this[v.STATE_PATH],l=this[v.STATE_VERBOSE],c=this[v.STATE_VERBOSE_PATH],d=this[v.STATE_SSR];let i=V.useStateVocabClientContext({clientContext:t.clientContext,verbose:l});if(!(i instanceof V.VocabStore)){if(d)throw new Error(P);i=A}const S=t.serialize??JSON.stringify,u=t.deserialize??JSON.parse,E=D(t.onSet??(()=>{}),t.delayedSet,[]),g=f.useRef(void 0),R=f.useRef(!1);if(!R.current){R.current=!0;let r=i.get(e);a.isValueDefined(r)||(r=s,a.isValueDefined(r)&&i.set(e,r)),!d&&n&&y({vocabStore:i,storage:n,statePath:e,value:r,serialize:S,deserialize:u})}const C=f.useSyncExternalStore(i.subscribe.bind(i),i.getClientSnapshot.bind(i),i.getServerSnapshot.bind(i));if(l)if(c){const r=a.get(C,c);r&&a.logStyled(r)}else a.logStyled(C);const h=a.get(C,e,s);g.current=h,m(()=>{!d||!n||y({vocabStore:i,storage:n,statePath:e,value:h,serialize:S,deserialize:u})},[]);const w=f.useEffectEvent(r=>{if(r.key!==e)return;const b=r.newValue,T=(b===null?null:u(b))??s;a.isValueDefined(T)&&(i.set(e,T),E(T,g.current))});f.useEffect(()=>{if(o)return window.addEventListener("storage",w),()=>window.removeEventListener("storage",w)},[o]);const x=f.useCallback(r=>{const b=a.isTransformer(r)?r(g.current):r;i.set(e,b),E(b,g.current),n&&n.setItem(e,S(b))},[i,e,E,n,S]),_=f.useCallback(()=>{const r=s;if(!a.isValueDefined(r)){n?.removeItem(e);return}i.set(e,r),E(r,g.current),n&&n.setItem(e,S(r))},[s,i,e,E,n,S]);return[h,x,_]}function k(t){const n=z?void 0:a.valueOrFactory(t.storage),s=a.valueOrFactory(t.defaultValue),o=this[v.STATE_PATH],e=this[v.STATE_VERBOSE],l=this[v.STATE_SSR];let c=V.useStateVocabClientContext({clientContext:t.clientContext,verbose:e});if(!(c instanceof V.VocabStore)){if(l)throw new Error(P);c=A}const d=t.serialize??JSON.stringify,i=t.deserialize??JSON.parse,S=f.useRef(!1);let u;S.current||(S.current=!0,u=c.get(o),a.isValueDefined(u)||(u=s,a.isValueDefined(u)&&c.set(o,u)),!l&&n&&y({vocabStore:c,storage:n,statePath:o,value:u,serialize:d,deserialize:i})),m(()=>{!l||!n||y({vocabStore:c,storage:n,statePath:o,value:u,serialize:d,deserialize:i})},[])}function O(t,n={}){const s={};for(const o in t){const e=t[o];I(e)?(s[o]=e.clientSlot({useState(l){return p.apply(this,[{clientContext:n.clientContext,...l}])},useInitialState(l){k.apply(this,[{clientContext:n.clientContext,...l}])}}),delete s[o].serverSlot,delete s[o].clientSlot):e!==null&&typeof e=="object"?s[o]=O(e,n):s[o]=e}return s}exports.StateVocabClientProvider=V.StateVocabClientProvider;exports.clientify=O;

package/dist/client.es.js

@@ -1,9 +1,9 @@
 "use client";
-import { useMemo as j, useRef as y, useSyncExternalStore as B, useEffectEvent as D, useEffect as P, useCallback as p, useLayoutEffect as H } from "react";
+import { useMemo as j, useRef as C, useSyncExternalStore as B, useEffectEvent as D, useEffect as P, useCallback as p, useLayoutEffect as H } from "react";
 import { S as A, a as I, b as O, c as F } from "./constants-BB1YAX6c.mjs";
 import { a as d, d as G, v as g, g as T, l as x, i as q } from "./utils-xV3x3fTc.mjs";
-import { V as C, u as _ } from "./provider-client-D0BmMWcY.mjs";
-import { S as ne } from "./provider-client-D0BmMWcY.mjs";
+import { V as y, u as _ } from "./provider-client-DLa3_Ms9.mjs";
+import { S as ne } from "./provider-client-DLa3_Ms9.mjs";
 function K(t, s, i = []) {
   return j(
     () => G(t, s),
@@ -21,14 +21,18 @@ const E = (t) => {
     serialize: l
   } = t, u = i.getItem(o);
   u === null ? d(e) && i.setItem(o, l(e)) : s.set(o, a(u));
-}, z = typeof window > "u", k = z ? P : H, J = new C(), L = "Make sure your component is wrapped in StateVocabProvider (RSC) or disable ssr option in setupStorage for SPA (RCC only)";
+};
 function Q(t) {
+  return typeof t == "object" && t !== null && "clientSlot" in t;
+}
+const z = typeof window > "u", k = z ? P : H, J = new y(), L = "Make sure your component is wrapped in StateVocabProvider (RSC) or disable ssr option in setupStorage for SPA (RCC only)";
+function U(t) {
   const s = z ? void 0 : g(t.storage), i = g(t.defaultValue), o = t.bidirectional, e = this[A], a = this[I], l = this[F], u = this[O];
   let r = _({
     clientContext: t.clientContext,
     verbose: a
   });
-  if (!(r instanceof C)) {
+  if (!(r instanceof y)) {
     if (u)
       throw new Error(L);
     r = J;
@@ -38,7 +42,7 @@ function Q(t) {
     }),
     t.delayedSet,
     []
-  ), b = y(void 0), w = y(!1);
+  ), b = C(void 0), w = C(!1);
   if (!w.current) {
     w.current = !0;
     let n = r.get(e);
@@ -100,18 +104,18 @@ function Q(t) {
     M
   ];
 }
-function U(t) {
+function W(t) {
   const s = z ? void 0 : g(t.storage), i = g(t.defaultValue), o = this[A], e = this[I], a = this[O];
   let l = _({
     clientContext: t.clientContext,
     verbose: e
   });
-  if (!(l instanceof C)) {
+  if (!(l instanceof y)) {
     if (a)
       throw new Error(L);
     l = J;
   }
-  const u = t.serialize ?? JSON.stringify, r = t.deserialize ?? JSON.parse, f = y(!1);
+  const u = t.serialize ?? JSON.stringify, r = t.deserialize ?? JSON.parse, f = C(!1);
   let c;
   f.current || (f.current = !0, c = l.get(o), d(c) || (c = i, d(c) && l.set(o, c)), !a && s && E({
     vocabStore: l,
@@ -131,22 +135,19 @@ function U(t) {
     });
   }, []);
 }
-function W(t) {
-  return typeof t == "object" && t !== null && "clientSlot" in t;
-}
 function X(t, s = {}) {
   const i = {};
   for (const o in t) {
     const e = t[o];
-    W(e) ? (i[o] = e.clientSlot({
+    Q(e) ? (i[o] = e.clientSlot({
       useState(a) {
-        return Q.apply(this, [{
+        return U.apply(this, [{
           clientContext: s.clientContext,
           ...a
         }]);
       },
       useInitialState(a) {
-        U.apply(this, [{
+        W.apply(this, [{
           clientContext: s.clientContext,
           ...a
         }]);

package/dist/provider-client-DA53zfcT.js

@@ -0,0 +1 @@
+"use client";"use strict";const h=require("react/jsx-runtime"),c=require("react"),r=require("./utils-0CTNJ4ZE.js"),a=c.createContext({});function S(e){const t=c.useContext(e.clientContext??a);return e.verbose&&console.log(`[Store uid]: ${t.uid}`),t}class u{uid;#t;#e;constructor(t){this.uid=Math.random().toString(36).slice(2),this.#t=t??{},this.#e=new Set}subscribe(t){return this.#e.add(t),()=>this.#e.delete(t)}getClientSnapshot(){return this.#t}getServerSnapshot(){return this.#t}get(t){return r.get(this.#t,t)}set(t,n){const s=r.get(this.#t,t),i=r.isTransformer(n)?n(s):n,o={...this.#t};r.set(o,t,i),this.#t=o,this.#e.forEach(l=>l())}}function b(e){const{clientContext:t,value:n,children:s}=e,[i]=c.useState(()=>new u(n)),o=t??a;return h.jsx(o.Provider,{value:i,children:s})}exports.StateVocabClientProvider=b;exports.VocabStore=u;exports.useStateVocabClientContext=S;

package/dist/{provider-client-D0BmMWcY.mjs → provider-client-DLa3_Ms9.mjs}

@@ -8,6 +8,7 @@ function m(e) {
   return e.verbose && console.log(`[Store uid]: ${t.uid}`), t;
 }
 class d {
+  uid;
   #t;
   #e;
   constructor(t) {

package/dist/server.cjs.js

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const s=require("react/jsx-runtime"),S=require("./constants-CbsduCZ7.js"),c=require("react"),d=require("./provider-client-CAHe8VnM.js"),y=require("./utils-0CTNJ4ZE.js"),i=e=>{if(c.useState)throw new Error(`${e} only intended for Server Components`)},a=c.cache(()=>new Map),x=({children:e})=>e,C=async e=>{i("StateVocabServerContext.Provider");const{serverContextKey:n,value:t,children:r}=e;return a().set(n,t),r},f=e=>(i("getStateVocab"),a().get(e)),b={Provider:c.useState?x:C},p=e=>{const{serverContextKey:n,value:t,children:r}=e;return s.jsx(b.Provider,{serverContextKey:n,value:t,children:r})};function P(e){const{children:n,serverContextKey:t,clientContext:r,value:o={}}=e;return s.jsx(p,{serverContextKey:t,value:o,children:s.jsx(d.StateVocabClientProvider,{clientContext:r,value:o,children:n})})}const h="Make sure your component is wrapped in StateVocabProvider";function w(e){const n=this[S.STATE_PATH],t=f(e.serverContextKey);if(!t)throw new Error(h);return y.get(t,n)}function g(e){return typeof e=="object"&&e!==null&&"serverSlot"in e}function l(e,n){const t={};for(const r in e){const o=e[r];if(g(o))t[r]=o.serverSlot({getState(){return w.apply(this,[{serverContextKey:n.serverContextKey}])}}),delete t[r].serverSlot,delete t[r].clientSlot;else if(o!==null&&typeof o=="object"){const u=v=>n.wrap({[r]:v});t[r]=l(o,{serverContextKey:n.serverContextKey,wrap:u})}else t[r]=o}return t.seed=r=>n.wrap(r),t}function K(e,n){const t=Symbol();return{...l(e,{serverContextKey:t,wrap:r=>r}),StateVocabProvider({children:r,value:o}){return s.jsx(P,{clientContext:n.clientContext,serverContextKey:t,value:o,children:r})}}}exports.serverify=K;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const l=require("react/jsx-runtime"),u=require("./constants-CbsduCZ7.js"),y=require("react"),S=require("./provider-client-DA53zfcT.js"),d=require("./utils-0CTNJ4ZE.js"),s=y.cache(()=>new Map),f=e=>s().get(e),v=(e,t)=>s().set(e,t);function b(e=""){const t=Symbol("test"),{size:n}=s();if(s().set(t,{}),s().size===n)throw new Error([e,"Start execution only within a React render context (per-request)."].join(" "));s().delete(t)}function x(e){return typeof e=="object"&&e!==null&&"serverSlot"in e}function p(e){const t=this[u.STATE_PATH],n=`Failed access to "${t}".`;b(n);const r=f(e.serverContextKey);if(!r)throw new Error(`${n} Reason: no data. Make sure your component is wrapped in StateVocabProvider.`);return d.get(r,t)}function i(e,t){const n={};for(const r in e){const o=e[r];if(x(o))n[r]=o.serverSlot({getState(){return p.apply(this,[{serverContextKey:t.serverContextKey}])}}),delete n[r].serverSlot,delete n[r].clientSlot;else if(o!==null&&typeof o=="object"){const c=a=>t.wrap({[r]:a});n[r]=i(o,{serverContextKey:t.serverContextKey,wrap:c})}else n[r]=o}return n.seed=r=>t.wrap(r),n}function w(e,t){t??={};const n=Object.keys(e).slice(0,3).join("-"),r=Symbol(n);return{...i(e,{serverContextKey:r,wrap:o=>o}),StateVocabProvider({children:o,value:c}){return c??={},v(r,c),l.jsx(S.StateVocabClientProvider,{clientContext:t.clientContext,value:c,children:o})}}}exports.serverify=w;

package/dist/server.es.js

@@ -1,104 +1,74 @@
-import { jsx as c } from "react/jsx-runtime";
-import { S as u } from "./constants-BB1YAX6c.mjs";
-import s, { cache as d } from "react";
-import { S as f } from "./provider-client-D0BmMWcY.mjs";
+import { jsx as l } from "react/jsx-runtime";
+import { S } from "./constants-BB1YAX6c.mjs";
+import { cache as f } from "react";
+import { S as u } from "./provider-client-DLa3_Ms9.mjs";
 import { g as y } from "./utils-xV3x3fTc.mjs";
-const a = (e) => {
-  if (s.useState)
-    throw new Error(`${e} only intended for Server Components`);
-}, i = d(() => /* @__PURE__ */ new Map()), p = ({ children: e }) => e, C = async (e) => {
-  a("StateVocabServerContext.Provider");
-  const { serverContextKey: o, value: t, children: r } = e;
-  return i().set(o, t), r;
-}, x = (e) => (a("getStateVocab"), i().get(e)), b = {
-  Provider: s.useState ? p : C
-}, m = (e) => {
-  const { serverContextKey: o, value: t, children: r } = e;
-  return /* @__PURE__ */ c(
-    b.Provider,
-    {
-      serverContextKey: o,
-      value: t,
-      children: r
-    }
-  );
-};
-function h(e) {
-  const {
-    children: o,
-    serverContextKey: t,
-    clientContext: r,
-    value: n = {}
-  } = e;
-  return /* @__PURE__ */ c(
-    m,
-    {
-      serverContextKey: t,
-      value: n,
-      children: /* @__PURE__ */ c(
-        f,
-        {
-          clientContext: r,
-          value: n,
-          children: o
-        }
-      )
-    }
-  );
-}
-const P = "Make sure your component is wrapped in StateVocabProvider";
-function w(e) {
-  const o = this[u], t = x(e.serverContextKey);
-  if (!t)
-    throw new Error(P);
-  return y(t, o);
+const s = f(() => /* @__PURE__ */ new Map()), p = (e) => s().get(e), x = (e, t) => s().set(e, t);
+function d(e = "") {
+  const t = /* @__PURE__ */ Symbol("test"), { size: o } = s();
+  if (s().set(t, {}), s().size === o)
+    throw new Error([
+      e,
+      "Start execution only within a React render context (per-request)."
+    ].join(" "));
+  s().delete(t);
 }
-function K(e) {
+function m(e) {
   return typeof e == "object" && e !== null && "serverSlot" in e;
 }
-function v(e, o) {
-  const t = {};
+function b(e) {
+  const t = this[S], o = `Failed access to "${t}".`;
+  d(o);
+  const r = p(e.serverContextKey);
+  if (!r)
+    throw new Error(
+      `${o} Reason: no data. Make sure your component is wrapped in StateVocabProvider.`
+    );
+  return y(r, t);
+}
+function i(e, t) {
+  const o = {};
   for (const r in e) {
     const n = e[r];
-    if (K(n))
-      t[r] = n.serverSlot({
+    if (m(n))
+      o[r] = n.serverSlot({
         getState() {
-          return w.apply(this, [{
-            serverContextKey: o.serverContextKey
+          return b.apply(this, [{
+            serverContextKey: t.serverContextKey
           }]);
         }
-      }), delete t[r].serverSlot, delete t[r].clientSlot;
+      }), delete o[r].serverSlot, delete o[r].clientSlot;
     else if (n !== null && typeof n == "object") {
-      const l = (S) => o.wrap({ [r]: S });
-      t[r] = v(n, {
-        serverContextKey: o.serverContextKey,
-        wrap: l
+      const c = (a) => t.wrap({ [r]: a });
+      o[r] = i(n, {
+        serverContextKey: t.serverContextKey,
+        wrap: c
       });
     } else
-      t[r] = n;
+      o[r] = n;
   }
-  return t.seed = (r) => o.wrap(r), t;
+  return o.seed = (r) => t.wrap(r), o;
 }
-function k(e, o) {
-  const t = /* @__PURE__ */ Symbol();
+function K(e, t) {
+  t ??= {};
+  const o = Object.keys(e).slice(0, 3).join("-"), r = Symbol(o);
   return {
-    ...v(e, {
-      serverContextKey: t,
-      wrap: (r) => r
+    ...i(e, {
+      serverContextKey: r,
+      wrap: (n) => n
     }),
-    StateVocabProvider({ children: r, value: n }) {
-      return /* @__PURE__ */ c(
-        h,
+    StateVocabProvider({ children: n, value: c }) {
+      return c ??= {}, x(r, c), /* @__PURE__ */ l(
+        u,
         {
-          clientContext: o.clientContext,
-          serverContextKey: t,
-          value: n,
-          children: r
+          clientContext: t.clientContext,
+          value: c,
+          children: n
         }
       );
     }
   };
 }
 export {
-  k as serverify
+  K as serverify
 };

package/dist/types/context.server.d.ts

@@ -1,12 +1,4 @@
-import React from "react";
-import type { PropsWithChildren, ReactNode } from "react";
 import type { Vocab } from "./state.types";
+export declare const getRequestStore: () => Map<symbol, Vocab>;
 export declare const getStateVocab: (serverContextKey: symbol) => Vocab | undefined;
-export declare const StateVocabServerContext: {
-    Provider: (({ children }: PropsWithChildren<{
-        value?: Vocab;
-    }>) => ReactNode) | ((props: PropsWithChildren<{
-        serverContextKey: symbol;
-        value: Vocab;
-    }>) => Promise<React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | Iterable<React.ReactNode> | (string | number | bigint | boolean | React.ReactPortal | React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | Iterable<React.ReactNode> | null | undefined)>);
-};
+export declare const setStateVocab: (serverContextKey: symbol, value: Vocab) => Map<symbol, Vocab>;

package/dist/types/setup.client.d.ts

@@ -1,21 +1,5 @@
 import { type Context } from "react";
-import type { ValueOrTransformer, VocabThis } from "./state.types";
-import VocabStore from "./store";
-import type { UseInitialStateOptions, UseStateOptions } from "./setup.types";
-declare function useState<V>(this: VocabThis, options: UseStateOptions<V> & {
-    clientContext: Context<VocabStore> | undefined;
-}): readonly [V, (nextValue: ValueOrTransformer<V>) => void, () => void];
-type Placeholder<V> = {
-    useState(options?: UseStateOptions<V>): ReturnType<typeof useState<V>>;
-    useInitialState(options?: UseInitialStateOptions<V>): void;
-};
-type Slot<V> = {
-    clientSlot(input: Placeholder<V>): Placeholder<V>;
-};
-type Clientified<R> = R extends Slot<infer TValue> ? Placeholder<TValue> : R extends object ? {
-    [K in keyof R]: Clientified<R[K]>;
-} : R;
+import type { ClientifyResult } from "./setup.client.types";
 export declare function clientify<R extends object>(tree: R, clientifyOptions?: {
     clientContext?: Context<object>;
-}): Clientified<R>;
-export {};
+}): ClientifyResult<R>;

package/dist/types/setup.client.types.d.ts

@@ -0,0 +1,29 @@
+import type { Deserialize, Serialize, ValueOrFactory, ValueOrTransformer } from "./state.types";
+export type UseStateOptions<V> = {
+    defaultValue?: ValueOrFactory<V>;
+    delayedSet?: number;
+    bidirectional?: true;
+    onSet?(nextValue: NoInfer<V>, prevValue: NoInfer<V>): void;
+    storage?: unknown;
+    serialize?: Serialize<V>;
+    deserialize?: Deserialize<V>;
+};
+type UseStateResult<V> = readonly [V, (nextValue: ValueOrTransformer<V>) => void, () => void];
+export type UseInitialStateOptions<V> = {
+    defaultValue?: ValueOrFactory<V>;
+    storage?: unknown;
+    serialize?: Serialize<V>;
+    deserialize?: Deserialize<V>;
+};
+type Placeholder<V> = {
+    useState(options?: UseStateOptions<V>): UseStateResult<V>;
+    useInitialState(options?: UseInitialStateOptions<V>): void;
+};
+export type ClientSlot<V> = {
+    clientSlot(input: Placeholder<V>): Placeholder<V>;
+};
+type Clientified<R> = R extends ClientSlot<infer V> ? Placeholder<V> : R extends object ? {
+    [K in keyof R]: Clientified<R[K]>;
+} : R;
+export type ClientifyResult<R> = Clientified<R>;
+export {};

package/dist/types/setup.client.utils.d.ts

@@ -1,6 +1,7 @@
+import type { ClientSlot } from "./setup.client.types";
+import type { Deserialize, Serialize } from "./state.types";
 import { type DependencyList } from "react";
 import VocabStore from "./store";
-import type { Deserialize, Serialize } from "./state.types";
 export declare function useDebounce<T extends (...args: never[]) => unknown>(effect: T, wait: number | undefined, deps?: DependencyList): (...args: Parameters<T>) => void;
 export declare const sync: <V>(options: {
     vocabStore: VocabStore;
@@ -10,3 +11,4 @@ export declare const sync: <V>(options: {
     deserialize: Deserialize<V>;
     value: V | undefined;
 }) => void;
+export declare function isClientSlot(value: unknown): value is ClientSlot<unknown>;

package/dist/types/setup.d.ts

@@ -1,14 +1,2 @@
-import { STATE_DEFINITION } from "./constants";
-type Path<T, Prefix extends string = ""> = {
-    [K in keyof T & string]: T[K] extends object ? T[K] extends {
-        [STATE_DEFINITION]: unknown;
-    } ? `${Prefix}${K}` : `${Prefix}${K}` | Path<T[K], `${Prefix}${K}.`> : `${Prefix}${K}`;
-}[keyof T & string];
-type InjectPathsOptions<T extends object> = {
-    path: string;
-    verbose: boolean;
-    verbosePath: Path<T>;
-    ssr: boolean;
-};
+import type { InjectPathsOptions } from "./setup.types";
 export declare function setupStorage<T extends object>(tree: T, options?: Partial<Omit<InjectPathsOptions<T>, "path">>): T;
-export {};

package/dist/types/setup.server.d.ts

@@ -1,28 +1,5 @@
-import type { Context, PropsWithChildren, ReactNode } from "react";
-import type { Vocab } from "./state.types";
-type Placeholder<V> = {
-    getState(): V;
-};
-type Slot<V> = {
-    serverSlot(input: Placeholder<V>): Placeholder<V>;
-};
-type ServerifiedValue<R> = {
-    [K in keyof R]?: R[K] extends Slot<infer V> ? V : R[K] extends object ? ServerifiedValue<R[K]> : R[K];
-};
-type Serverified<R> = R extends Slot<infer TValue> ? Placeholder<TValue> : R extends object ? {
-    seed(input: ServerifiedValue<R>): Vocab;
-} & {
-    [K in keyof R]: Serverified<R[K]>;
-} : R;
-type ServerifyResult<R extends object> = {
-    seed(input: ServerifiedValue<R>): Vocab;
-    StateVocabProvider(props: PropsWithChildren<{
-        value?: ServerifiedValue<R>;
-    }>): Promise<ReactNode>;
-} & {
-    [K in keyof R]: Serverified<R[K]>;
-};
-export declare function serverify<R extends object>(tree: R, serverifyOptions: {
-    clientContext: Context<object>;
+import type { Context } from "react";
+import type { ServerifyResult } from "./setup.server.types";
+export declare function serverify<R extends object>(tree: R, serverifyOptions?: {
+    clientContext?: Context<object>;
 }): ServerifyResult<R>;
-export {};

package/dist/types/setup.server.types.d.ts

@@ -0,0 +1,25 @@
+import type { PropsWithChildren, ReactNode } from "react";
+import type { Vocab } from "./state.types";
+type Placeholder<V> = {
+    getState(): V;
+};
+export type ServerSlot<V> = {
+    serverSlot(input: Placeholder<V>): Placeholder<V>;
+};
+type ServerifiedValue<R> = {
+    [K in keyof R]?: R[K] extends ServerSlot<infer V> ? V : R[K] extends object ? ServerifiedValue<R[K]> : R[K];
+};
+type Serverified<R> = R extends ServerSlot<infer V> ? Placeholder<V> : R extends object ? {
+    seed(input: ServerifiedValue<R>): Vocab;
+} & {
+    [K in keyof R]: Serverified<R[K]>;
+} : R;
+export type ServerifyResult<R extends object> = {
+    seed(input: ServerifiedValue<R>): Vocab;
+    StateVocabProvider(props: PropsWithChildren<{
+        value?: ServerifiedValue<R>;
+    }>): ReactNode;
+} & {
+    [K in keyof R]: Serverified<R[K]>;
+};
+export {};

package/dist/types/setup.server.utils.d.ts

@@ -0,0 +1,3 @@
+import type { ServerSlot } from "./setup.server.types";
+export declare function healtcheck(prefix?: string): void;
+export declare function isServerSlot(value: unknown): value is ServerSlot<unknown>;

package/dist/types/setup.types.d.ts

@@ -1,16 +1,13 @@
-import type { Deserialize, Serialize, ValueOrFactory } from "./state.types";
-export type UseStateOptions<V> = {
-    defaultValue?: ValueOrFactory<V>;
-    delayedSet?: number;
-    bidirectional?: true;
-    onSet?(nextValue: NoInfer<V>, prevValue: NoInfer<V>): void;
-    storage?: unknown;
-    serialize?: Serialize<V>;
-    deserialize?: Deserialize<V>;
-};
-export type UseInitialStateOptions<V> = {
-    defaultValue?: ValueOrFactory<V>;
-    storage?: unknown;
-    serialize?: Serialize<V>;
-    deserialize?: Deserialize<V>;
+import { STATE_DEFINITION } from "./constants";
+type Path<T, Prefix extends string = ""> = {
+    [K in keyof T & string]: T[K] extends object ? T[K] extends {
+        [STATE_DEFINITION]: unknown;
+    } ? `${Prefix}${K}` : `${Prefix}${K}` | Path<T[K], `${Prefix}${K}.`> : `${Prefix}${K}`;
+}[keyof T & string];
+export type InjectPathsOptions<T extends object> = {
+    path: string;
+    verbose: boolean;
+    verbosePath: Path<T>;
+    ssr: boolean;
 };
+export {};

package/dist/types/state.d.ts

@@ -1,5 +1,5 @@
-import { STATE_DEFINITION, STATE_PATH, STATE_SSR, STATE_VERBOSE, STATE_VERBOSE_PATH } from "./constants";
 import type { Deserialize, Serialize, ValueOrFactory, ValueOrTransformer, VocabThis } from "./state.types";
+import { STATE_DEFINITION, STATE_PATH, STATE_SSR, STATE_VERBOSE, STATE_VERBOSE_PATH } from "./constants";
 export declare function defineState<V>(superOptions?: {
     defaultValue?: ValueOrFactory<V>;
     bidirectional?: true;

package/dist/types/utils.d.ts

@@ -7,3 +7,4 @@ export declare function logStyled(obj: unknown): void;
 export declare const isTransformer: <V>(v: ValueOrTransformer<V>) => v is Transformer<V>;
 export declare const isValueDefined: <V>(v: V | undefined) => v is V;
 export declare const valueOrFactory: <V>(input: ValueOrFactory<V>) => V;
+export declare function withTimeout<T>(promise: Promise<T>, ms: number, message: string): Promise<T>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yakocloud/state-vocab",
-  "version": "4.1.0",
+  "version": "4.3.0",
   "main": "dist/index.cjs.js",
   "module": "dist/index.es.js",
   "types": "dist/types/index.d.ts",

package/dist/provider-client-CAHe8VnM.js

@@ -1 +0,0 @@
-"use client";"use strict";const h=require("react/jsx-runtime"),c=require("react"),r=require("./utils-0CTNJ4ZE.js"),a=c.createContext({});function S(e){const t=c.useContext(e.clientContext??a);return e.verbose&&console.log(`[Store uid]: ${t.uid}`),t}class u{#t;#e;constructor(t){this.uid=Math.random().toString(36).slice(2),this.#t=t??{},this.#e=new Set}subscribe(t){return this.#e.add(t),()=>this.#e.delete(t)}getClientSnapshot(){return this.#t}getServerSnapshot(){return this.#t}get(t){return r.get(this.#t,t)}set(t,n){const s=r.get(this.#t,t),i=r.isTransformer(n)?n(s):n,o={...this.#t};r.set(o,t,i),this.#t=o,this.#e.forEach(l=>l())}}function b(e){const{clientContext:t,value:n,children:s}=e,[i]=c.useState(()=>new u(n)),o=t??a;return h.jsx(o.Provider,{value:i,children:s})}exports.StateVocabClientProvider=b;exports.VocabStore=u;exports.useStateVocabClientContext=S;

package/dist/types/provider.d.ts

@@ -1,8 +0,0 @@
-import type { Context, PropsWithChildren } from "react";
-import type { Vocab } from "./state.types";
-import VocabStore from "./store";
-export declare function StateVocabProvider(props: PropsWithChildren<{
-    value?: Vocab;
-    serverContextKey: symbol;
-    clientContext: Context<VocabStore>;
-}>): import("react/jsx-runtime").JSX.Element;

package/dist/types/provider.server.d.ts

@@ -1,6 +0,0 @@
-import type { Vocab } from "./state.types";
-import type { PropsWithChildren } from "react";
-export declare const StateVocabServerProvider: React.FC<PropsWithChildren<{
-    value: Vocab;
-    serverContextKey: symbol;
-}>>;