react-mnemonic 1.0.0-beta.0 → 1.1.0-beta0

package/README.md

@@ -3,7 +3,9 @@
 Persistent, type-safe state management for React.
 
 [![npm version](https://img.shields.io/npm/v/react-mnemonic.svg)](https://www.npmjs.com/package/react-mnemonic)
-[![bundle size](https://img.shields.io/bundlephobia/minzip/react-mnemonic)](https://bundlephobia.com/package/react-mnemonic)
+[![docs](https://img.shields.io/badge/docs-online-0A7EA4.svg)](https://thirtytwobits.github.io/react-mnemonic/)
+[![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=thirtytwobits_react-mnemonic&metric=security_rating)](https://sonarcloud.io/summary/new_code?id=thirtytwobits_react-mnemonic)
+[![dependencies](https://img.shields.io/badge/dependencies-0-success.svg)](https://www.npmjs.com/package/react-mnemonic)
 [![license](https://img.shields.io/npm/l/react-mnemonic.svg)](./LICENSE.md)
 [![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue.svg)](https://www.typescriptlang.org/)
 
@@ -11,8 +13,16 @@ Persistent, type-safe state management for React.
 page refreshes, synchronize across tabs, and stay type-safe end-to-end -- all
 through a single hook that works like `useState`.
 
-`1.0.0` is currently being shipped as a beta on the npm `beta` dist-tag while
-the release candidate hardening work finishes.
+`1.1.0-beta0` is the current prerelease on the npm `latest` dist-tag. This minor
+`beta0` cut lands ahead of the `beta1` stabilization milestone, which is
+expected to receive only fixes and polish before the first production release.
+
+If you are evaluating alternatives, see the
+[Comparison Guide](https://thirtytwobits.github.io/react-mnemonic/docs/guides/comparisons-and-benchmarks).
+It publishes reproducible bundle measurements, an AI-friendliness benchmark
+built around one-shot app-building prompts, and controlled SSR/API tradeoff
+notes for `react-mnemonic`, Zustand persist, Jotai `atomWithStorage`,
+`use-local-storage-state`, and `usehooks-ts`.
 
 ## Features
 
@@ -20,29 +30,31 @@ the release candidate hardening work finishes.
 - **JSON Schema validation** -- optional schema-based validation using a built-in JSON Schema subset
 - **Namespace isolation** -- `MnemonicProvider` prefixes every key to prevent collisions
 - **Cross-tab sync** -- opt-in `listenCrossTab` uses the browser `storage` event
-- **Pluggable storage** -- bring your own backend via the `StorageLike` interface (IndexedDB, sessionStorage, etc.)
+- **Pluggable storage** -- use `localStorage`, `sessionStorage`, or a synchronous `StorageLike` facade over custom persistence
 - **Schema versioning and migration** -- upgrade stored data with versioned schemas and migration rules
+- **Typed schema cohesion helpers** -- define one schema object and reuse it across runtime validation, key descriptors, and migrations
 - **Structural migration helpers** -- optional tree utilities for idempotent insert/rename/dedupe migration steps
 - **Read-time reconciliation** -- selectively enforce new defaults on persisted values without clearing the whole key
 - **Recovery helpers** -- build user-facing soft reset and hard reset flows with namespace-scoped clear helpers
 - **Write-time normalization** -- migrations where `fromVersion === toVersion` run on every write
+- **First-class key descriptors** -- define canonical, reusable key contracts once with `defineMnemonicKey(...)`
 - **Lifecycle callbacks** -- `onMount` and `onChange` hooks
 - **DevTools** -- inspect and mutate state from the browser console
-- **SSR-safe** -- returns defaults when `window` is unavailable
+- **SSR-safe with explicit controls** -- defaults to `defaultValue` on the server, with optional `ssr.serverValue` and `client-only` hydration
 - **Tree-shakeable, zero dependencies** -- ships ESM + CJS with full TypeScript declarations
 
 ## Installation
 
 ```bash
-npm install react-mnemonic@beta
+npm install react-mnemonic
 ```
 
 ```bash
-yarn add react-mnemonic@beta
+yarn add react-mnemonic
 ```
 
 ```bash
-pnpm add react-mnemonic@beta
+pnpm add react-mnemonic
 ```
 
 ### Peer dependencies
@@ -91,6 +103,35 @@ export default function App() {
 The counter value persists in `localStorage` under the key `my-app.count` and
 survives full page reloads.
 
+In server-rendered apps, `useMnemonicKey(...)` renders `defaultValue` on the
+server by default and then hydrates to persisted storage on the client. When
+you need a deterministic server placeholder or want to delay storage reads
+until after mount, use `ssr.serverValue` and `ssr.hydration: "client-only"`.
+See the
+[Server Rendering guide](https://thirtytwobits.github.io/react-mnemonic/docs/guides/server-rendering)
+for Next.js and Remix examples.
+
+If the same key is used in multiple components, consider defining it once with
+`defineMnemonicKey(...)` and reusing that descriptor everywhere. This keeps the
+contract importable and explicit for both humans and AI-assisted tooling.
+
+For a deterministic implementation reference aimed at AI agents and advanced
+users, see the
+[AI docs overview](https://thirtytwobits.github.io/react-mnemonic/docs/ai).
+The canonical agent-facing prose lives under
+[`website/docs/ai/`](https://github.com/thirtytwobits/react-mnemonic/tree/main/website/docs/ai),
+with compact retrieval surfaces published as
+[`llms.txt`](https://thirtytwobits.github.io/react-mnemonic/llms.txt),
+[`llms-full.txt`](https://thirtytwobits.github.io/react-mnemonic/llms-full.txt),
+and
+[`ai-contract.json`](https://thirtytwobits.github.io/react-mnemonic/ai-contract.json).
+Agents should import published types from `react-mnemonic` and must not invent
+local `.d.ts` shims for the package.
+
+If you need evidence for where `react-mnemonic` is heavier, more explicit, or
+better suited to SSR-sensitive persistence than lighter hooks, see the
+[Comparison Guide](https://thirtytwobits.github.io/react-mnemonic/docs/guides/comparisons-and-benchmarks).
+
 Persist only the durable slice of your app state. `useMnemonicKey` stores
 whatever you pass to `set`, so keep transient UI state like loading flags,
 hover state, and draft search text in plain React state unless you explicitly
@@ -110,6 +151,125 @@ while `reset()` writes the default again. See the
 [Clearable Persisted Values guide](https://thirtytwobits.github.io/react-mnemonic/docs/guides/clearable-persisted-values)
 for the canonical nullable pattern.
 
+## Canonical key definitions
+
+When the same persisted key appears in more than one component, define it once
+and reuse it:
+
+```tsx
+import { defineMnemonicKey, useMnemonicKey } from "react-mnemonic";
+
+export const themeKey = defineMnemonicKey("theme", {
+    defaultValue: "light" as "light" | "dark",
+    listenCrossTab: true,
+});
+
+function ThemeToggle() {
+    const { value: theme, set } = useMnemonicKey(themeKey);
+    return <button onClick={() => set(theme === "light" ? "dark" : "light")}>{theme}</button>;
+}
+
+function ThemePreview() {
+    const { value: theme } = useMnemonicKey(themeKey);
+    return <p>Current theme: {theme}</p>;
+}
+```
+
+Descriptors help with:
+
+- keeping one canonical key contract per persisted value
+- reusing the same `defaultValue`, `schema`, `codec`, and `reconcile` logic
+- making AI-assisted code generation and refactors less ambiguous
+
+The original lightweight form still works:
+
+```ts
+const { value, set } = useMnemonicKey("theme", {
+    defaultValue: "light" as "light" | "dark",
+});
+```
+
+## Single source of truth schemas
+
+If you want the same schema object to drive both runtime validation and
+TypeScript inference, use the typed schema helpers:
+
+```tsx
+import {
+    MnemonicProvider,
+    createSchemaRegistry,
+    defineKeySchema,
+    defineMnemonicKey,
+    defineMigration,
+    mnemonicSchema,
+    useMnemonicKey,
+} from "react-mnemonic";
+
+const profileV1 = defineKeySchema(
+    "profile",
+    1,
+    mnemonicSchema.object({
+        name: mnemonicSchema.string(),
+    }),
+);
+
+const profileV2 = defineKeySchema(
+    "profile",
+    2,
+    mnemonicSchema.object({
+        name: mnemonicSchema.string(),
+        email: mnemonicSchema.string(),
+    }),
+);
+
+const profileKey = defineMnemonicKey(profileV2, {
+    defaultValue: { name: "", email: "" },
+    reconcile: (value) => ({
+        ...value,
+        email: value.email.trim().toLowerCase(),
+    }),
+});
+
+const registry = createSchemaRegistry({
+    schemas: [profileV1, profileV2],
+    migrations: [
+        defineMigration(profileV1, profileV2, (value) => ({
+            ...value,
+            email: "",
+        })),
+    ],
+});
+
+function ProfileForm() {
+    const { value: profile, set } = useMnemonicKey(profileKey);
+    return <button onClick={() => set({ ...profile, email: "hello@example.com" })}>Save</button>;
+}
+
+export default function App() {
+    return (
+        <MnemonicProvider namespace="my-app" schemaMode="default" schemaRegistry={registry}>
+            <ProfileForm />
+        </MnemonicProvider>
+    );
+}
+```
+
+This path gives you:
+
+- one schema object reused in the registry, key descriptor, and migrations
+- inferred types for `defaultValue`, `value`, `set`, and `reconcile`
+- typed migration callbacks via `defineMigration(...)`
+
+Tradeoffs versus the lightweight JSON-only path:
+
+- more setup upfront
+- best fit when a key is schema-managed and long-lived
+- not necessary for simple keys where `defaultValue` inference is already enough
+
+For a side-by-side comparison against competing persistence libraries, including
+bundle-size measurements and qualitative SSR/API notes, see the
+[Comparison Guide](https://thirtytwobits.github.io/react-mnemonic/docs/guides/comparisons-and-benchmarks).
+
 ## API
 
 ### `<MnemonicProvider>`
@@ -130,11 +290,42 @@ Context provider that scopes storage keys under a namespace.
 
 Multiple providers with different namespaces can coexist in the same app.
 
-### `useMnemonicKey<T>(key, options)`
+### `defineMnemonicKey(key, options)`
+
+Define a reusable descriptor for a single persisted key.
+
+```ts
+const themeKey = defineMnemonicKey("theme", {
+    defaultValue: "light" as "light" | "dark",
+    listenCrossTab: true,
+});
+```
+
+The returned descriptor can be imported and passed directly to `useMnemonicKey`.
+
+### `mnemonicSchema`, `defineKeySchema`, and `defineMigration`
+
+Use these helpers when you want a schema-managed key to have one source of
+truth for runtime validation and TypeScript inference.
+
+```ts
+const themeSchema = defineKeySchema("theme", 1, mnemonicSchema.enum(["light", "dark"] as const));
+
+const themeKey = defineMnemonicKey(themeSchema, {
+    defaultValue: "light",
+});
+```
+
+`defineMigration(fromSchema, toSchema, migrate)` infers the migration callback
+from the source and target schemas, while `defineWriteMigration(schema, migrate)`
+creates a typed same-version normalizer.
+
+### `useMnemonicKey<T>(descriptor)` / `useMnemonicKey<T>(key, options)`
 
 Hook for reading and writing a single persistent value.
 
 ```ts
+const { value, set, reset, remove } = useMnemonicKey(themeKey);
 const { value, set, reset, remove } = useMnemonicKey<T>(key, options);
 ```
 
@@ -221,6 +412,13 @@ interface StorageLike {
 }
 ```
 
+`StorageLike` is intentionally synchronous in v1 because Mnemonic's core
+store is built on React's synchronous snapshot contract. Async backends are
+still possible, but they need a synchronous facade: keep an in-memory cache for
+`getItem`/`setItem`/`removeItem`, then flush to IndexedDB or another async
+system outside the hook contract. Promise-returning `StorageLike` methods are
+unsupported and are treated as a storage misuse fallback at runtime.
+
 `onExternalChange` enables cross-tab sync for non-localStorage backends (e.g.
 IndexedDB over `BroadcastChannel`). The library handles all error cases
 internally -- see the `StorageLike` JSDoc for the full error-handling contract.
@@ -509,22 +707,40 @@ version and remount the provider.
 import { MnemonicProvider } from "react-mnemonic";
 import type { StorageLike } from "react-mnemonic";
 
+const cache = new Map<string, string>();
+const queueIndexedDbWrite = (key: string, value: string) => {
+    // application-specific async persistence
+};
+const queueIndexedDbDelete = (key: string) => {
+    // application-specific async persistence
+};
+
 const idbStorage: StorageLike = {
-  getItem: (key) => /* read from IndexedDB */,
-  setItem: (key, value) => /* write to IndexedDB */,
-  removeItem: (key) => /* delete from IndexedDB */,
-  onExternalChange: (cb) => {
-    const bc = new BroadcastChannel("my-app-sync");
-    bc.onmessage = (e) => cb(e.data.keys);
-    return () => bc.close();
-  },
+    getItem: (key) => cache.get(key) ?? null,
+    setItem: (key, value) => {
+        cache.set(key, value);
+        queueIndexedDbWrite(key, value);
+    },
+    removeItem: (key) => {
+        cache.delete(key);
+        queueIndexedDbDelete(key);
+    },
+    onExternalChange: (cb) => {
+        const bc = new BroadcastChannel("my-app-sync");
+        bc.onmessage = (e) => cb(e.data.keys);
+        return () => bc.close();
+    },
 };
 
 <MnemonicProvider namespace="my-app" storage={idbStorage}>
-  <App />
-</MnemonicProvider>
+    <App />
+</MnemonicProvider>;
 ```
 
+If your real persistence layer is async, initialize that adapter before
+rendering the provider and return a synchronous `StorageLike` facade, like the
+IndexedDB demo in the docs site.
+
 ### DevTools
 
 Enable the console inspector in development:
@@ -555,6 +771,7 @@ All public types are re-exported from the package root:
 import type {
     Codec,
     StorageLike,
+    MnemonicKeyDescriptor,
     MnemonicProviderOptions,
     MnemonicProviderProps,
     UseMnemonicKeyOptions,