@k8ordo/state 0.1.0 → 1.0.0

package/dist/url/codec.mjs

@@ -1,4 +1,5 @@
 import { analyzeSchema, parseWithSalvage, sameValue } from "../schema/object.mjs";
+import { safeEncode } from "zod/v4/core";
 //#region src/url/codec.ts
 const defOf = (schema) => schema._zod.def;
 /**
@@ -17,21 +18,45 @@ const readAll = (input, key) => {
 	if (value === void 0) return [];
 	return typeof value === "string" ? [value] : value;
 };
-const serializeValue = (key, value) => {
+/**
+* 真偽値は、フィールド（配列なら要素）のスキーマ自身が encode した綴りで書く。`String(true)` の
+* `"true"` は `z.stringbool({ truthy: ['yes'] })` が読み返せず、既定値に落ちる。
+*/
+const spellBoolean = (schema, value) => {
+	try {
+		const encoded = safeEncode(schema, value);
+		if (encoded.success && typeof encoded.data === "string") return encoded.data;
+	} catch {}
+	return String(value);
+};
+const serializeValue = (schema, key, value) => {
 	if (typeof value === "string") return value;
-	if (typeof value === "number" || typeof value === "bigint" || typeof value === "boolean") return String(value);
-	throw new TypeError(`url field "${key}" holds a ${typeof value}, which has no URL serialization`);
+	if (typeof value === "boolean") return spellBoolean(schema, value);
+	if (typeof value === "number" || typeof value === "bigint") return String(value);
+	throw new TypeError(`url field "${key}" holds a value of type ${typeof value}, which has no URL serialization`);
+};
+const refuseBoolean = (schema, name) => {
+	if (baseDef(schema).type === "boolean") throw new TypeError(`url boolean fields must use z.stringbool() — a URL carries strings, and "false" is not false to z.boolean() or z.coerce.boolean(): ${name}`);
 };
 const createUrlCodec = (schema) => {
 	const info = analyzeSchema(schema, "url");
 	const { keys, defaults } = info;
-	const multi = new Set(keys.filter((key) => baseDef(info.shape[key]).type === "array"));
+	const items = /* @__PURE__ */ new Map();
+	for (const key of keys) {
+		const base = baseDef(info.shape[key]);
+		if (base.type === "array") {
+			if (!sameValue(defaults[key], [])) throw new TypeError(`url array fields must default to [] — an absent param and an empty list are the same URL: ${key}`);
+			const item = base.element;
+			refuseBoolean(item, `${key}[]`);
+			items.set(key, item);
+		} else refuseBoolean(info.shape[key], key);
+	}
 	const parse = (input) => {
 		const raw = {};
 		for (const key of keys) {
 			const got = readAll(input, key);
 			if (got.length === 0) continue;
-			raw[key] = multi.has(key) ? got : got[0];
+			raw[key] = items.has(key) ? got : got[0];
 		}
 		return parseWithSalvage(info, raw);
 	};
@@ -40,16 +65,24 @@ const createUrlCodec = (schema) => {
 		for (const key of keys) {
 			const value = key in values ? values[key] : defaults[key];
 			if (value === void 0 || sameValue(defaults[key], value)) continue;
-			if (Array.isArray(value)) for (const item of value) params.append(key, serializeValue(key, item));
-			else params.append(key, serializeValue(key, value));
+			const field = info.shape[key];
+			if (Array.isArray(value)) {
+				const item = items.get(key) ?? field;
+				for (const each of value) params.append(key, serializeValue(item, key, each));
+			} else params.append(key, serializeValue(field, key, value));
 		}
 		return params.toString();
 	};
-	const salvage = (values) => {
-		const own = {};
-		for (const key of keys) if (key in values) own[key] = values[key];
-		return parseWithSalvage(info, own);
-	};
+	/**
+	* The values as they will come back: written to a query string and read
+	* again. Going through the URL rather than handing the typed values
+	* straight to the schema is what makes a one-way spelling work — the
+	* `string → boolean` of `z.stringbool()` never sees a boolean, exactly as
+	* on arrival — and it is the only reading under which `update()` and a
+	* visitor's URL are the same path. A value with no URL spelling throws
+	* here, which is the earliest anyone can be told.
+	*/
+	const salvage = (values) => parse(new URLSearchParams(search(values)));
 	return {
 		keys,
 		defaults,

package/dist/use-app-state.d.mts

@@ -1,15 +1,20 @@
+import { StateSchema } from "./schema/object.mjs";
+import { CookieState } from "./cookie-state.mjs";
 import { OutputOf, PageState } from "./page-state.mjs";
-import { LocalState } from "./local-state.mjs";
+import { LocalState, SessionState } from "./storage-state.mjs";
 import { MemoryState } from "./memory-state.mjs";
 import { UpdateHandle } from "./store/core.mjs";
 import { UpdateOptions } from "./store/page-store.mjs";
 import { output } from "zod/v4/core";
 //#region src/use-app-state.d.ts
-type AnyState = PageState | LocalState | MemoryState;
-type StateOf<Def> = Def extends PageState<infer Url, infer Entry> ? OutputOf<Url> & OutputOf<Entry> : Def extends LocalState<infer Schema> ? output<Schema> : Def extends MemoryState<infer Values> ? Values : never;
+export type AnyState = PageState | LocalState | SessionState | CookieState | MemoryState;
+type StateOf<Def> = Def extends PageState<infer Url, infer Entry> ? OutputOf<Url> & OutputOf<Entry> : Def extends LocalState<infer Schema> ? output<Schema> : Def extends SessionState<infer Schema> ? output<Schema> : Def extends CookieState<infer Schema> ? output<Schema> : Def extends MemoryState<infer Values> ? Values : never;
 type UrlStateOf<Def> = Def extends PageState<infer Url> ? OutputOf<Url> : never;
 type UpdateFn<Def> = (patch: Readonly<Partial<StateOf<Def>>> | ((current: StateOf<Def>) => Partial<StateOf<Def>>), ...rest: Def extends PageState ? [options?: UpdateOptions] : []) => UpdateHandle;
-type OptionsFor<Def> = Def extends PageState ? {
+type OptionsFor<Def> = Def extends {
+  kind: 'page';
+  url: StateSchema;
+} ? {
   /**
    * The RSC-parsed url state, passed down as a prop. It seeds SSR and
    * the hydration render; without it those two renders see the defaults,
@@ -17,8 +22,15 @@ type OptionsFor<Def> = Def extends PageState ? {
    * server-side source, so it always starts from defaults there.
    */
   initialUrl?: Readonly<UrlStateOf<Def>>;
-} : Record<never, never>;
-declare function useAppState<Def extends AnyState>(def: Def, options?: OptionsFor<Def>): [StateOf<Def>, UpdateFn<Def>];
-declare function useAppState<Def extends AnyState, const Key extends Extract<keyof StateOf<Def>, string>>(def: Def, keys: readonly Key[], options?: OptionsFor<Def>): [Pick<StateOf<Def>, Key>, UpdateFn<Def>];
-//#endregion
-export { AnyState, useAppState };
+} : Def extends CookieState<infer Schema> ? {
+  /**
+   * What `parseCookies(request.cookies)` returned on the server, passed
+   * down as a prop. It seeds SSR and the hydration render; without it
+   * those two renders see the defaults, which flashes once the cookie
+   * is read in the browser.
+   */
+  initialCookie?: Readonly<output<Schema>>;
+} : never;
+export declare function useAppState<Def extends AnyState>(def: Def, options?: OptionsFor<Def>): [StateOf<Def>, UpdateFn<Def>];
+export declare function useAppState<Def extends AnyState, const Key extends Extract<keyof StateOf<Def>, string>>(def: Def, keys: readonly Key[], options?: OptionsFor<Def>): [Pick<StateOf<Def>, Key>, UpdateFn<Def>];
+//#endregion

package/dist/use-app-state.mjs

@@ -1,11 +1,12 @@
 "use client";
-import { localInitialSnapshot, localStoreOf } from "./store/local-store.mjs";
+import { cookieInitialSnapshot, cookieStoreOf } from "./store/cookie-store.mjs";
 import { memoryInitialSnapshot, memoryStoreOf } from "./store/memory-store.mjs";
 import { pageInitialSnapshot, pageStoreOf } from "./store/page-store.mjs";
+import { localStoreOf, sessionStoreOf, storageInitialSnapshot } from "./store/storage-store.mjs";
 import { useCallback, useMemo, useSyncExternalStore } from "react";
 //#region src/use-app-state.ts
-const storeOf = (def) => def.kind === "page" ? pageStoreOf(def) : def.kind === "local" ? localStoreOf(def) : memoryStoreOf(def);
-const initialOf = (def, initialUrl) => def.kind === "page" ? pageInitialSnapshot(def, initialUrl) : def.kind === "local" ? localInitialSnapshot(def) : memoryInitialSnapshot(def);
+const storeOf = (def) => def.kind === "page" ? pageStoreOf(def) : def.kind === "local" ? localStoreOf(def) : def.kind === "session" ? sessionStoreOf(def) : def.kind === "cookie" ? cookieStoreOf(def) : memoryStoreOf(def);
+const initialOf = (def, options) => def.kind === "page" ? pageInitialSnapshot(def, options?.initialUrl) : def.kind === "local" || def.kind === "session" ? storageInitialSnapshot(def) : def.kind === "cookie" ? cookieInitialSnapshot(def, options?.initialCookie) : memoryInitialSnapshot(def);
 const FULL = "*";
 function useAppState(def, keysOrOptions, maybeOptions) {
 	const gotKeys = Array.isArray(keysOrOptions);
@@ -19,25 +20,23 @@ function useAppState(def, keysOrOptions, maybeOptions) {
 		keys
 	]);
 	const initialUrl = options?.initialUrl;
-	const getServerSnapshot = useMemo(() => {
-		let cached;
-		return () => {
-			if (cached === void 0) {
-				const base = initialOf(def, initialUrl);
-				if (keys === null) cached = base;
-				else {
-					const pick = {};
-					for (const key of keys) pick[key] = base[key];
-					cached = pick;
-				}
-			}
-			return cached;
-		};
+	const initialCookie = options?.initialCookie;
+	const serverSnapshot = useMemo(() => {
+		const base = initialOf(def, {
+			initialUrl,
+			initialCookie
+		});
+		if (keys === null) return base;
+		const pick = {};
+		for (const key of keys) pick[key] = base[key];
+		return pick;
 	}, [
 		def,
 		initialUrl,
+		initialCookie,
 		keys
 	]);
+	const getServerSnapshot = useCallback(() => serverSnapshot, [serverSnapshot]);
 	return [useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot), useCallback((patch, updateOptions) => storeOf(def).update(patch, updateOptions), [def])];
 }
 //#endregion