@k8ordo/state 0.1.0 → 1.0.0

package/dist/schema/object.mjs

@@ -40,6 +40,11 @@ const analyzeSchema = (schema, slot) => {
 		defaults
 	};
 };
+const pickKeys = (info, data) => {
+	const values = {};
+	for (const key of info.keys) values[key] = data[key];
+	return values;
+};
 /**
 * Whole-parse first; when that fails, the values are user-editable or stale
 * input, so one broken field falls back to its own default instead of taking
@@ -47,17 +52,11 @@ const analyzeSchema = (schema, slot) => {
 */
 const parseWithSalvage = (info, raw) => {
 	const whole = safeParse(info.schema, raw);
-	if (whole.success) {
-		const values = {};
-		for (const key of info.keys) values[key] = whole.data[key];
-		return values;
-	}
-	const salvaged = {};
-	for (const key of info.keys) if (key in raw) {
-		const field = safeParse(info.shape[key], raw[key]);
-		salvaged[key] = field.success ? field.data : info.defaults[key];
-	} else salvaged[key] = info.defaults[key];
-	return safeParse(info.schema, salvaged).success ? salvaged : { ...info.defaults };
+	if (whole.success) return pickKeys(info, whole.data);
+	const kept = {};
+	for (const key of info.keys) if (key in raw && safeParse(info.shape[key], raw[key]).success) kept[key] = raw[key];
+	const salvaged = safeParse(info.schema, kept);
+	return salvaged.success ? pickKeys(info, salvaged.data) : { ...info.defaults };
 };
 //#endregion
 export { analyzeSchema, isRecord, parseWithSalvage, sameValue };

package/dist/storage-state.d.mts

@@ -0,0 +1,37 @@
+import { StateSchema } from "./schema/object.mjs";
+import { RowCodec, Versioning } from "./row/codec.mjs";
+//#region src/storage-state.d.ts
+type StorageState<Kind extends 'local' | 'session', Schema extends StateSchema> = {
+  kind: Kind;
+  /** Identity of this state: the storage key and the store registry slot. */
+  key: string;
+  /** The schema as passed. */
+  schema: Schema;
+  /** The Web Storage 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, storage cannot be read, or (for a
+   * versioned local state) the row was written by another version. Neither
+   * the schema nor `migrate` runs there: treat the result as untrusted and
+   * read only the fields you need, each with its own fallback.
+   */
+  inlineRead: () => string;
+};
+/**
+ * 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.
+ */
+export type LocalState<Schema extends StateSchema = StateSchema> = StorageState<'local', Schema>;
+/**
+ * App-scope state that lives in sessionStorage: kept through reloads of the
+ * tab and gone when the tab closes, shared with no other tab — built the way
+ * local state is, over the other Web Storage area.
+ */
+export type SessionState<Schema extends StateSchema = StateSchema> = StorageState<'session', Schema>;
+export declare const storageCodecOf: (def: LocalState | SessionState) => RowCodec;
+export declare const defineLocalState: <Schema extends StateSchema>(key: string, schema: Schema, versioning?: Versioning<Schema>) => LocalState<Schema>;
+export declare const defineSessionState: <Schema extends StateSchema>(key: string, schema: Schema) => SessionState<Schema>;
+//#endregion

package/dist/storage-state.mjs

@@ -0,0 +1,37 @@
+import { createRowCodec } from "./row/codec.mjs";
+//#region src/storage-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 isObjectExpression = (value) => `${value}!==null&&typeof ${value}==="object"&&!Array.isArray(${value})`;
+const inlineReadOf = (area, storageKey, version) => {
+	const row = `JSON.parse(${area}.getItem(${literalOf(storageKey)}))`;
+	return version === void 0 ? `(()=>{try{const v=${row};return ${isObjectExpression("v")}?v:null}catch{return null}})()` : `(()=>{try{const r=${row};const v=Array.isArray(r)&&r.length===2&&r[0]===${String(version)}?r[1]:null;return ${isObjectExpression("v")}?v:null}catch{return null}})()`;
+};
+const codecs = /* @__PURE__ */ new WeakMap();
+const storageCodecOf = (def) => {
+	const codec = codecs.get(def);
+	if (codec === void 0) throw new TypeError(`"${def.key}" was not created by ${def.kind === "local" ? "defineLocalState" : "defineSessionState"} of this module instance`);
+	return codec;
+};
+const defineStorageState = (kind, area, key, schema, versioning) => {
+	const storageKey = `${STORAGE_KEY_PREFIX}${key}`;
+	const codec = createRowCodec(schema, kind, key, versioning);
+	const def = {
+		kind,
+		key,
+		schema,
+		storageKey,
+		inlineRead: () => inlineReadOf(area, storageKey, codec.version)
+	};
+	codecs.set(def, codec);
+	return def;
+};
+const defineLocalState = (key, schema, versioning) => defineStorageState("local", "localStorage", key, schema, versioning);
+const defineSessionState = (key, schema) => defineStorageState("session", "sessionStorage", key, schema, void 0);
+//#endregion
+export { defineLocalState, defineSessionState, storageCodecOf };

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

@@ -0,0 +1,12 @@
+import { StateValues } from "../schema/object.mjs";
+import { CookieState } from "../cookie-state.mjs";
+import { Store } from "./core.mjs";
+//#region src/store/cookie-store.d.ts
+export declare const cookieStoreOf: (def: CookieState) => Store;
+/**
+ * What SSR and the hydration render see: the values the server read from the
+ * request's cookies when the caller passed them down; the defaults otherwise.
+ * Pure on purpose: the server must never touch `document` or create a store.
+ */
+export declare const cookieInitialSnapshot: (def: CookieState, initialCookie: Readonly<StateValues> | undefined) => StateValues;
+//#endregion

package/dist/store/cookie-store.mjs

@@ -0,0 +1,129 @@
+import { cookieCodecOf, parseCookieText } from "../cookie-state.mjs";
+import { createHandle, createStoreCore, resolvePatch } from "./core.mjs";
+import { getOrCreateStore } from "./registry.mjs";
+//#region src/store/cookie-store.ts
+const MAX_AGE = 3456e4;
+const rawCookie = (name) => {
+	for (const part of document.cookie.split(";")) {
+		const at = part.indexOf("=");
+		if (at !== -1 && part.slice(0, at).trim() === name) return part.slice(at + 1).trim();
+	}
+};
+const decoded = (raw) => {
+	if (raw === void 0) return void 0;
+	try {
+		return decodeURIComponent(raw);
+	} catch {
+		return;
+	}
+};
+const createCookieStore = (def) => {
+	const codec = cookieCodecOf(def);
+	const { cookieName } = def;
+	const readRow = () => codec.read(parseCookieText(decoded(rawCookie(cookieName))));
+	const read = () => readRow().values;
+	let pending = null;
+	let handle = null;
+	let writing = 0;
+	let missed = false;
+	const sync = () => {
+		if (writing > 0) {
+			missed = true;
+			return;
+		}
+		missed = false;
+		const { values: fresh, stale } = readRow();
+		if (stale) writeBack();
+		core.applyNext(pending === null ? fresh : {
+			...fresh,
+			...pending
+		});
+	};
+	const onChange = (event) => {
+		if ([...event.changed, ...event.deleted].some((cookie) => cookie.name === cookieName)) sync();
+	};
+	cookieStore.addEventListener("change", onChange);
+	const write = async (patch, current) => {
+		try {
+			const target = codec.salvage({
+				...read(),
+				...patch
+			});
+			const init = {
+				name: cookieName,
+				value: encodeURIComponent(JSON.stringify(codec.row(target))),
+				path: "/",
+				sameSite: "lax",
+				maxAge: MAX_AGE
+			};
+			await cookieStore.set(init);
+		} catch (error) {
+			writing -= 1;
+			if (missed) sync();
+			current.fail(error);
+			return;
+		}
+		writing -= 1;
+		sync();
+		current.settle();
+	};
+	let writes = Promise.resolve();
+	const enqueue = (patch, current) => {
+		writing += 1;
+		writes = writes.then(() => write(patch, current));
+	};
+	const flush = () => {
+		const patch = pending;
+		const current = handle;
+		pending = null;
+		handle = null;
+		enqueue(patch, current);
+	};
+	function writeBack() {
+		enqueue({}, createHandle());
+	}
+	const first = readRow();
+	const core = createStoreCore(codec.keys, first.values);
+	if (first.stale) writeBack();
+	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: () => {
+			cookieStore.removeEventListener("change", onChange);
+			core.clear();
+		}
+	};
+};
+const cookieStoreOf = (def) => getOrCreateStore("cookie", def.key, () => createCookieStore(def));
+/**
+* What SSR and the hydration render see: the values the server read from the
+* request's cookies when the caller passed them down; the defaults otherwise.
+* Pure on purpose: the server must never touch `document` or create a store.
+*/
+const cookieInitialSnapshot = (def, initialCookie) => {
+	const codec = cookieCodecOf(def);
+	const base = { ...codec.defaults };
+	if (initialCookie !== void 0) {
+		for (const key of codec.keys) if (key in initialCookie) base[key] = initialCookie[key];
+	}
+	return base;
+};
+//#endregion
+export { cookieInitialSnapshot, cookieStoreOf };

package/dist/store/core.d.mts

@@ -4,17 +4,18 @@ import { StateValues } from "../schema/object.mjs";
  * Mirrors `navigation.navigate()`'s own return shape: an object holding the
  * promises rather than a promise, so fire-and-forget callers ignore it
  * without tripping no-floating-promises, and the 5% that await pick a stage.
- * Slots with no navigation behind them return both promises pre-settled —
- * the type stays uniform across every kind of state.
+ * Slots with no navigation behind them return the same pair, settled or
+ * rejected by the store itself — the type stays uniform across every kind of
+ * state.
  */
-type UpdateHandle = {
+export type UpdateHandle = {
   /** The write is in its home (history entry, storage, memory). */
   committed: Promise<void>;
   /** All downstream work (a router's intercept fetch/render) is done. */
   finished: Promise<void>;
 };
-type Patch = StateValues | ((current: StateValues) => StateValues);
-type Store = {
+export type Patch = StateValues | ((current: StateValues) => StateValues);
+export type Store = {
   subscribe: (keys: readonly string[] | null, notify: () => void) => () => void;
   getSnapshot: (sig: string, keys: readonly string[] | null) => StateValues;
   update: (patch: Patch, options?: {
@@ -22,7 +23,7 @@ type Store = {
   }) => UpdateHandle;
   dispose: () => void;
 };
-type Handle = {
+export type Handle = {
   external: UpdateHandle;
   settle: () => void;
   fail: (error: unknown) => void;
@@ -31,8 +32,8 @@ type Handle = {
     finished?: Promise<unknown> | undefined;
   }) => void;
 };
-declare const createHandle: () => Handle;
-type StoreCore = {
+export declare const createHandle: () => Handle;
+export type StoreCore = {
   snapshot: () => StateValues;
   applyNext: (next: StateValues) => void;
   subscribe: Store['subscribe'];
@@ -44,11 +45,10 @@ type StoreCore = {
  * exact per-key change detection, and notification only to the listeners
  * whose subscribed keys actually changed.
  */
-declare const createStoreCore: (keys: readonly string[], initial: StateValues) => StoreCore;
+export declare const createStoreCore: (keys: readonly string[], initial: StateValues) => StoreCore;
 /**
  * The unknown-field guard every store shares: the typed API already prevents
  * this, so reaching it means an untyped caller — fail loudly, not silently.
  */
-declare const resolvePatch: (patch: Patch, current: StateValues, keys: readonly string[], label: string) => StateValues;
-//#endregion
-export { Handle, Patch, Store, StoreCore, UpdateHandle, createHandle, createStoreCore, resolvePatch };
+export declare const resolvePatch: (patch: Patch, current: StateValues, keys: readonly string[], label: string) => StateValues;
+//#endregion

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

@@ -2,8 +2,7 @@ import { StateValues } from "../schema/object.mjs";
 import { MemoryState } from "../memory-state.mjs";
 import { Store } from "./core.mjs";
 //#region src/store/memory-store.d.ts
-declare const memoryStoreOf: (def: MemoryState) => Store;
+export declare const memoryStoreOf: (def: MemoryState) => Store;
 /** SSR renders the initial values — static, so no cross-request concern. */
-declare const memoryInitialSnapshot: (def: MemoryState) => StateValues;
-//#endregion
-export { memoryInitialSnapshot, memoryStoreOf };
+export declare const memoryInitialSnapshot: (def: MemoryState) => StateValues;
+//#endregion

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

@@ -2,20 +2,21 @@ import { StateValues } from "../schema/object.mjs";
 import { PageState } from "../page-state.mjs";
 import { Store } from "./core.mjs";
 //#region src/store/page-store.d.ts
-type UpdateOptions = {
+export type UpdateOptions = {
   /**
    * `replace` by default: an update is a refinement of the current entry.
-   * Opt into `push` for the updates the back button should undo.
+   * Opt into `push` for the updates the back button should undo. It applies
+   * only when a url value changes; an entry-only write rewrites the current
+   * entry in place.
    */
   history?: 'push' | 'replace';
 };
-declare const pageStoreOf: (def: PageState) => Store;
+export declare const pageStoreOf: (def: PageState) => Store;
 /**
  * What SSR and the hydration render see: the RSC-parsed url when the caller
  * passed one down; defaults for everything else — the entry slot never
  * reaches the server. Pure on purpose: the server must never touch
  * `navigation` or create a store.
  */
-declare const pageInitialSnapshot: (def: PageState, initialUrl: Readonly<StateValues> | undefined) => StateValues;
-//#endregion
-export { UpdateOptions, pageInitialSnapshot, pageStoreOf };
+export declare const pageInitialSnapshot: (def: PageState, initialUrl: Readonly<StateValues> | undefined) => StateValues;
+//#endregion

package/dist/store/page-store.mjs

@@ -51,37 +51,33 @@ const createPageStore = (def) => {
 		pending = null;
 		pendingPush = false;
 		handle = null;
-		const url = new URL(location.href);
-		const stored = storedEntryState();
-		const liveUrl = page.url === null ? {} : page.url.parse(url.searchParams);
-		const liveEntry = page.entry === null ? {} : page.entry.parse(isRecord(stored) ? stored[def.key] : void 0);
-		const target = canonical({
-			...liveUrl,
-			...liveEntry,
-			...patch
-		});
-		const urlChanged = page.url?.keys.some((key) => !sameValue(liveUrl[key], target[key])) ?? false;
-		const entryChanged = page.entry?.keys.some((key) => !sameValue(liveEntry[key], target[key])) ?? false;
-		if (!urlChanged && !entryChanged) {
-			core.applyNext(target);
-			current.settle();
-			return;
-		}
-		const state = carryState(stored, target);
-		if (!urlChanged) {
-			try {
+		try {
+			const url = new URL(location.href);
+			const stored = storedEntryState();
+			const liveUrl = page.url === null ? {} : page.url.parse(url.searchParams);
+			const liveEntry = page.entry === null ? {} : page.entry.parse(isRecord(stored) ? stored[def.key] : void 0);
+			const target = canonical({
+				...liveUrl,
+				...liveEntry,
+				...patch
+			});
+			const urlChanged = page.url?.keys.some((key) => !sameValue(liveUrl[key], target[key])) ?? false;
+			const entryChanged = page.entry?.keys.some((key) => !sameValue(liveEntry[key], target[key])) ?? false;
+			if (!urlChanged && !entryChanged) {
+				core.applyNext(target);
+				current.settle();
+				return;
+			}
+			const state = carryState(stored, target);
+			if (!urlChanged) {
 				navigation.updateCurrentEntry({ state });
 				current.settle();
-			} catch (error) {
-				current.fail(error);
+				return;
+			}
+			if (page.url !== null) {
+				for (const key of page.url.keys) url.searchParams.delete(key);
+				for (const [key, value] of new URLSearchParams(page.url.search(target))) url.searchParams.append(key, value);
 			}
-			return;
-		}
-		if (page.url !== null) {
-			for (const key of page.url.keys) url.searchParams.delete(key);
-			for (const [key, value] of new URLSearchParams(page.url.search(target))) url.searchParams.append(key, value);
-		}
-		try {
 			current.adopt(navigation.navigate(url.href, {
 				history: push ? "push" : "replace",
 				state
@@ -92,6 +88,11 @@ const createPageStore = (def) => {
 	};
 	const update = (patch, options) => {
 		const resolved = resolvePatch(patch, core.snapshot(), page.keys, def.key);
+		const echoed = canonical({
+			...core.snapshot(),
+			...pending,
+			...resolved
+		});
 		if (pending === null) {
 			pending = {};
 			handle = createHandle();
@@ -99,10 +100,6 @@ const createPageStore = (def) => {
 		}
 		Object.assign(pending, resolved);
 		if (options?.history === "push") pendingPush = true;
-		const echoed = canonical({
-			...core.snapshot(),
-			...pending
-		});
 		for (const key of Object.keys(pending)) pending[key] = echoed[key];
 		core.applyNext(echoed);
 		return handle.external;

package/dist/store/registry.d.mts

@@ -1,5 +1,5 @@
 //#region src/store/registry.d.ts
-declare const getOrCreateStore: <Store extends {
+export declare const getOrCreateStore: <Store extends {
   dispose?: () => void;
 }>(scope: string, key: string, create: () => Store) => Store;
 /**
@@ -7,6 +7,5 @@ declare const getOrCreateStore: <Store extends {
  * would carry state from one test into the next. Unmount components first —
  * mounted hooks keep their old store through closures.
  */
-declare const resetStateRegistry: () => void;
-//#endregion
-export { getOrCreateStore, resetStateRegistry };
+export declare const resetStateRegistry: () => void;
+//#endregion

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

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

package/dist/store/storage-store.mjs

@@ -0,0 +1,97 @@
+import { storageCodecOf } from "../storage-state.mjs";
+import { createHandle, createStoreCore, resolvePatch } from "./core.mjs";
+import { getOrCreateStore } from "./registry.mjs";
+//#region src/store/storage-store.ts
+const createStorageStore = (def, storage) => {
+	const codec = storageCodecOf(def);
+	const { storageKey } = def;
+	const write = (values) => {
+		storage.setItem(storageKey, JSON.stringify(codec.row(values)));
+	};
+	const readRow = () => {
+		const text = storage.getItem(storageKey);
+		let row;
+		try {
+			row = text === null ? void 0 : JSON.parse(text);
+		} catch {
+			row = void 0;
+		}
+		return codec.read(row);
+	};
+	const read = () => readRow().values;
+	const upgrade = () => {
+		queueMicrotask(() => {
+			const { values, stale } = readRow();
+			if (!stale) return;
+			try {
+				write(values);
+			} catch {}
+		});
+	};
+	const first = readRow();
+	const core = createStoreCore(codec.keys, first.values);
+	if (first.stale) upgrade();
+	let pending = null;
+	let handle = null;
+	const onStorage = (event) => {
+		if (event.storageArea !== storage) return;
+		if (event.key !== storageKey && event.key !== null) return;
+		const { values: fresh, stale } = readRow();
+		if (stale) upgrade();
+		core.applyNext(pending === null ? fresh : {
+			...fresh,
+			...pending
+		});
+	};
+	window.addEventListener("storage", onStorage);
+	const flush = () => {
+		const patch = pending;
+		const current = handle;
+		pending = null;
+		handle = null;
+		try {
+			const target = codec.salvage({
+				...read(),
+				...patch
+			});
+			const values = {};
+			for (const key of codec.keys) values[key] = target[key];
+			write(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, () => createStorageStore(def, localStorage));
+const sessionStoreOf = (def) => getOrCreateStore("session", def.key, () => createStorageStore(def, sessionStorage));
+/** SSR and hydration see the defaults — the server has no Web Storage. */
+const storageInitialSnapshot = (def) => ({ ...storageCodecOf(def).defaults });
+//#endregion
+export { localStoreOf, sessionStoreOf, storageInitialSnapshot };

package/dist/url/codec.d.mts

@@ -1,8 +1,8 @@
 import { StateSchema, StateValues } from "../schema/object.mjs";
 //#region src/url/codec.d.ts
 /** `URLSearchParams`, or the object shape frameworks hand to a page. */
-type UrlInput = URLSearchParams | Readonly<Record<string, string | readonly string[] | undefined>>;
-type UrlCodec = {
+export type UrlInput = URLSearchParams | Readonly<Record<string, string | readonly string[] | undefined>>;
+export type UrlCodec = {
   keys: readonly string[];
   defaults: Readonly<StateValues>;
   parse: (input: UrlInput) => StateValues;
@@ -10,6 +10,5 @@ type UrlCodec = {
   /** Runs already-typed values through the schema, salvage included. */
   salvage: (values: Readonly<StateValues>) => StateValues;
 };
-declare const createUrlCodec: (schema: StateSchema) => UrlCodec;
-//#endregion
-export { UrlCodec, UrlInput, createUrlCodec };
+export declare const createUrlCodec: (schema: StateSchema) => UrlCodec;
+//#endregion