@k8ordo/state 0.2.0 → 1.0.0

package/docs/llms.txt

@@ -3,11 +3,18 @@
 > Declare state by where it lives: `definePageState` (typed URL search params
 > plus hidden history-entry state — the two faces of one entry, updated
 > atomically over the Navigation API), `defineLocalState` (localStorage,
-> cross-tab), `defineMemoryState` (a typed shared box, resets on reload).
-> One zod schema per place derives the server read, canonical links, salvage
-> of stale data, and a client subscription with exact per-key change
-> detection. Works through links and GET forms before JavaScript loads;
-> imperative url updates ride a Navigation-API-intercepting router.
+> cross-tab), `defineSessionState` (sessionStorage — the same store over the
+> per-tab area: survives a reload, gone with the tab), `defineCookieState` (a
+> cookie the browser writes with the Cookie Store API and the server reads
+> from the request, so preferences render without a flash of the default —
+> never a secret, it cannot be `HttpOnly`), `defineMemoryState` (a typed
+> shared box with no schema, resets on reload). One zod schema per boundary
+> place (url, entry, local, session, cookie) derives the server read,
+> canonical links, salvage of stale data, and a client subscription with
+> exact per-key change detection. Links and GET forms write the URL before
+> JavaScript loads under any router (the server renders what they wrote
+> wherever it reads the search); imperative url updates ride a
+> Navigation-API-intercepting router.
 >
 > Like every k8ordo package it assumes React 19 and Server Components, uses
 > only what has reached Baseline newly available, and ships no polyfills or
@@ -17,36 +24,70 @@ When installed via npm, these docs live under `node_modules/@k8ordo/state/docs/`
 
 ## Guide
 
-- [Design Guide](GUIDE.md): the four places and when each fits, the shared
-  definition module, reading on the server, updating on the client, batching
-  and update handles, subscription granularity, router requirements, typed
-  routes via `Register`, reading local state before hydration, and pairing
-  with `@k8ordo/form` for GET forms.
+- [Design Guide](GUIDE.md): the places and when each fits, the shared
+  definition module, versions and migrations of stored rows, reading on the
+  server, cookie state the server renders (and how it relates to cookies the
+  server writes), updating on the client,
+  batching and update handles, subscription granularity, router
+  requirements, typed routes via `Register`, reading local state before
+  hydration, and pairing with `@k8ordo/form` for GET forms.
 
 ## Entry point
 
 - `@k8ordo/state` — `definePageState(key, { url?, entry? })` returns a pure
   definition usable from server and client: `parseUrl(searchParams)` reads
-  the url slot typed with defaults applied and per-field salvage (wherever the
-  router hands a page its search — under `@k8ordo/static` / `@k8ordo/server` a
-  page receives `params` and `pathname` only, and the url slot is read in the
-  browser);
-  `href(base, values?)` builds a canonical link keeping the path literal in
-  the type; `search(values?)` returns the query string alone.
-  `defineLocalState(key, schema)` and `defineMemoryState(key, initial)`
-  declare app-scope state; a local definition also exposes `storageKey` (the
-  localStorage key, `k8ordo-state:<key>`) and `inlineRead()`, a JavaScript
-  expression for an inline `<script>` that evaluates to the stored object or
-  `null` before hydration — unvalidated, so read only what you need with a
-  fallback. `useAppState(definition, keys?, { initialUrl? })`
-  (client) works on any kind and returns `[state, update]` — state is the
-  flat merge of a page definition's slots; `update(patch)` applies
-  synchronously, batches per handler into one write (url+entry atomically via
-  `navigation.navigate()`, entry-only via `updateCurrentEntry()`, local via
-  one `setItem`), and returns `{ committed, finished }` promise handles
-  (settled for non-navigating kinds; `{ history: 'push' }` exists only on
-  page state). `resetStateRegistry()` clears stores between tests. Augment
+  the url slot typed with defaults applied and invalid values salvaged
+  (wherever the router hands a page its search — in `@k8ordo/framework`'s
+  server mode a page that exports `search = listState.url` receives the slot parsed as
+  `search` and is loaded again when the search moves; any other framework
+  page never sees the search, and the url slot is read in the browser);
+  `urlReader(schema)` is that reading for a url schema alone, the codec
+  built once (what the framework's generated table calls);
+  `href(path, values?)` builds a canonical link keeping the path literal in
+  the type — the path written from the app's root, the link carrying Vite's
+  `base` (`import.meta.env.BASE_URL`) in front; `search(values?)` returns the
+  query string alone.
+  `defineLocalState(key, schema, versioning?)`,
+  `defineSessionState(key, schema)`,
+  `defineCookieState(key, schema, versioning?)` and
+  `defineMemoryState(key, initial)` declare app-scope state;
+  `versioning` is `{ version, migrate(old, fromVersion) }` (type
+  `Versioning`): rows are then stored as `[version, values]`, a row with no
+  version reads as version 0, an older row goes through `migrate` and then
+  the schema's field-by-field salvage and is written back in the current
+  version by the browser store (`parseCookies` migrates but never writes), a
+  newer row is salvaged and left alone, and a throwing `migrate` reads as
+  nothing stored without touching the row; a local or session definition also exposes
+  `storageKey` (the key in its storage area, `k8ordo-state:<key>`) and
+  `inlineRead()`, a JavaScript expression for an inline `<script>` that
+  evaluates to the object stored in that area or `null` before hydration
+  (also `null` for a row of another version, when versioned) —
+  unvalidated, so read only what you need with a fallback. A
+  cookie definition exposes `cookieName` (`k8ordo-state.<key>`),
+  `parseCookies(cookies)` — reads the values out of a request's
+  percent-decoded cookies (`request.cookies` in `@k8ordo/framework`'s server mode), salvaged
+  like any read — and `cookieValue(values?)`, the unencoded JSON a server
+  hands its cookie API (`cookies().set`, which percent-encodes it) when it
+  sets the same cookie (`Path=/`, `SameSite=Lax`, `Max-Age=34560000`, never
+  `HttpOnly`). `useAppState(definition, keys?, { initialUrl? } |
+  { initialCookie? })` (client) works on any kind and returns
+  `[state, update]` — state is the flat merge of a page definition's slots;
+  `initialUrl` / `initialCookie` seed the server and hydration renders with
+  what the server read; `update(patch)` applies synchronously, batches the
+  calls a handler makes with no `await` between them into one write
+  (url+entry changes atomically via `navigation.navigate()`, entry-only
+  changes via `updateCurrentEntry()`, local and session via one `setItem`,
+  cookie via one
+  `cookieStore.set()`; memory applies per call), and returns
+  `{ committed, finished }` promise handles (for non-navigating kinds they
+  settle once the write lands, and a write that fails — the browser refuses
+  it (a full Web Storage area, a cookie over 4 KB) or the schema throws on
+  it — rejects them with its error;
+  `{ history: 'push' }` exists only on page state and takes effect only when
+  a url value changes).
+  `resetStateRegistry()` clears stores between tests. Augment
   `interface Register { routes: typeof routes }` — the same line as for
-  `@k8ordo/router` — to constrain `href` paths to the route table's linkable
-  paths; a router without a table registers its own path union as
+  `@k8ordo/router` — to check each `href` path against the route table's
+  linkable patterns segment by segment (`NavigablePath`, so a `/:locale`
+  table no longer takes every path); a router without a table registers its own path union as
   `interface Register { path }` instead.

package/package.json

@@ -1,13 +1,15 @@
 {
   "name": "@k8ordo/state",
-  "version": "0.2.0",
-  "description": "Declare state by where it lives — URL search params, history-entry state, localStorage, or memory. One zod schema per place, over the Navigation API.",
+  "version": "1.0.0",
+  "description": "Declare state by where it lives — URL search params, history-entry state, localStorage, sessionStorage, a cookie, or memory. One zod schema per boundary place and a typed box for memory, over the Navigation API.",
   "keywords": [
+    "cookie",
     "localstorage",
     "navigation-api",
     "react",
     "search-params",
     "server-components",
+    "sessionstorage",
     "state",
     "url-state",
     "zod"
@@ -41,26 +43,29 @@
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "0.18.5",
-    "@types/react": "19.2.18",
-    "@vitejs/plugin-react": "6.0.5",
-    "@vitest/browser-playwright": "4.1.10",
-    "publint": "0.3.23",
-    "react": "19.2.8",
-    "react-dom": "19.2.8",
+    "@k8ordo/router": "^1.0.0",
+    "@types/react": "19.3.0",
+    "@types/react-dom": "19.3.0",
+    "@vitejs/plugin-basic-ssl": "2.3.0",
+    "@vitejs/plugin-react": "6.1.2",
+    "@vitest/browser-playwright": "5.0.3",
+    "playwright": "1.63.0",
+    "publint": "0.3.25",
+    "react": "19.3.0",
+    "react-dom": "19.3.0",
     "typescript": "7.0.2",
-    "vite": "8.2.1",
-    "vite-plus": "0.2.9",
-    "vitest": "4.1.10",
-    "vitest-browser-react": "2.2.0",
-    "zod": "4.4.3",
-    "@k8ordo/router": "^0.1.0"
+    "vite": "npm:@voidzero-dev/vite-plus-core@1.1.0",
+    "vite-plus": "1.1.0",
+    "vitest": "5.0.3",
+    "vitest-browser-react": "2.3.0",
+    "zod": "4.6.5"
   },
   "peerDependencies": {
-    "@types/react": ">=19.2.18",
-    "react": ">=19.2.6",
-    "typescript": ">=7.0.2",
-    "zod": "^4.4.3",
-    "@k8ordo/router": "^0.1.0"
+    "@k8ordo/router": "^1.0.0",
+    "@types/react": ">=19.3.0",
+    "react": ">=19.3.0",
+    "typescript": ">=7.0.0",
+    "zod": "^4.4.3"
   },
   "peerDependenciesMeta": {
     "@k8ordo/router": {

package/dist/local-state.d.mts

@@ -1,29 +0,0 @@
-import { StateSchema } from "./schema/object.mjs";
-import { StoredCodec } from "./entry/codec.mjs";
-//#region src/local-state.d.ts
-/**
- * App-scope state that lives in localStorage: device-persistent, shared
- * across tabs, never page-bound — which is why it is its own definition kind
- * instead of a slot on a page state.
- */
-type LocalState<Schema extends StateSchema = StateSchema> = {
-  kind: 'local';
-  /** Identity of this state: the storage key and the store registry slot. */
-  key: string;
-  /** The schema as passed. */
-  schema: Schema;
-  /** The localStorage key the values are written under: `k8ordo-state:<key>`. */
-  storageKey: string;
-  /**
-   * A JavaScript expression, for an inline `<script>`, that evaluates in the
-   * browser to the stored object — or `null` when nothing is stored, the JSON
-   * is corrupt, the value is not an object, or storage cannot be read. The
-   * schema does not run there: treat the result as untrusted and read only
-   * the fields you need, each with its own fallback.
-   */
-  inlineRead: () => string;
-};
-declare const localCodecOf: (def: LocalState) => StoredCodec;
-declare const defineLocalState: <Schema extends StateSchema>(key: string, schema: Schema) => LocalState<Schema>;
-//#endregion
-export { LocalState, defineLocalState, localCodecOf };

package/dist/local-state.mjs

@@ -1,30 +0,0 @@
-import { createStoredCodec } from "./entry/codec.mjs";
-//#region src/local-state.ts
-const STORAGE_KEY_PREFIX = "k8ordo-state:";
-/**
-* The key as a JavaScript string literal. `JSON.stringify` escapes it for
-* JavaScript; `<` is escaped on top so the literal can never close the inline
-* `<script>` it is written into, whatever the key contains.
-*/
-const literalOf = (text) => JSON.stringify(text).replaceAll("<", String.raw`\u003c`);
-const inlineReadOf = (storageKey) => `(()=>{try{const v=JSON.parse(localStorage.getItem(${literalOf(storageKey)}));return v!==null&&typeof v==="object"&&!Array.isArray(v)?v:null}catch{return null}})()`;
-const codecs = /* @__PURE__ */ new WeakMap();
-const localCodecOf = (def) => {
-	const codec = codecs.get(def);
-	if (codec === void 0) throw new TypeError(`"${def.key}" was not created by defineLocalState of this module instance`);
-	return codec;
-};
-const defineLocalState = (key, schema) => {
-	const storageKey = `${STORAGE_KEY_PREFIX}${key}`;
-	const def = {
-		kind: "local",
-		key,
-		schema,
-		storageKey,
-		inlineRead: () => inlineReadOf(storageKey)
-	};
-	codecs.set(def, createStoredCodec(schema, "local"));
-	return def;
-};
-//#endregion
-export { defineLocalState, localCodecOf };

package/dist/store/local-store.d.mts

@@ -1,9 +0,0 @@
-import { StateValues } from "../schema/object.mjs";
-import { LocalState } from "../local-state.mjs";
-import { Store } from "./core.mjs";
-//#region src/store/local-store.d.ts
-declare const localStoreOf: (def: LocalState) => Store;
-/** SSR and hydration see the defaults — the server has no localStorage. */
-declare const localInitialSnapshot: (def: LocalState) => StateValues;
-//#endregion
-export { localInitialSnapshot, localStoreOf };

package/dist/store/local-store.mjs

@@ -1,79 +0,0 @@
-import { localCodecOf } from "../local-state.mjs";
-import { createHandle, createStoreCore, resolvePatch } from "./core.mjs";
-import { getOrCreateStore } from "./registry.mjs";
-//#region src/store/local-store.ts
-const createLocalStore = (def) => {
-	const codec = localCodecOf(def);
-	const { storageKey } = def;
-	const read = () => {
-		const text = localStorage.getItem(storageKey);
-		if (text === null) return codec.parse(void 0);
-		try {
-			return codec.parse(JSON.parse(text));
-		} catch {
-			return codec.parse(void 0);
-		}
-	};
-	const core = createStoreCore(codec.keys, read());
-	let pending = null;
-	let handle = null;
-	const onStorage = (event) => {
-		if (event.storageArea !== localStorage) return;
-		if (event.key !== storageKey && event.key !== null) return;
-		const fresh = read();
-		core.applyNext(pending === null ? fresh : {
-			...fresh,
-			...pending
-		});
-	};
-	window.addEventListener("storage", onStorage);
-	const flush = () => {
-		const patch = pending;
-		const current = handle;
-		pending = null;
-		handle = null;
-		const target = codec.salvage({
-			...read(),
-			...patch
-		});
-		const values = {};
-		for (const key of codec.keys) values[key] = target[key];
-		try {
-			localStorage.setItem(storageKey, JSON.stringify(values));
-			core.applyNext(target);
-			current.settle();
-		} catch (error) {
-			current.fail(error);
-		}
-	};
-	const update = (patch) => {
-		const resolved = resolvePatch(patch, core.snapshot(), codec.keys, def.key);
-		if (pending === null) {
-			pending = {};
-			handle = createHandle();
-			queueMicrotask(flush);
-		}
-		Object.assign(pending, resolved);
-		const echoed = codec.salvage({
-			...core.snapshot(),
-			...pending
-		});
-		for (const key of Object.keys(pending)) pending[key] = echoed[key];
-		core.applyNext(echoed);
-		return handle.external;
-	};
-	return {
-		subscribe: core.subscribe,
-		getSnapshot: core.getSnapshot,
-		update,
-		dispose: () => {
-			window.removeEventListener("storage", onStorage);
-			core.clear();
-		}
-	};
-};
-const localStoreOf = (def) => getOrCreateStore("local", def.key, () => createLocalStore(def));
-/** SSR and hydration see the defaults — the server has no localStorage. */
-const localInitialSnapshot = (def) => ({ ...localCodecOf(def).defaults });
-//#endregion
-export { localInitialSnapshot, localStoreOf };