react-mnemonic 0.1.1-alpha.0 → 1.0.0-beta.0

package/README.md

@@ -7,16 +7,13 @@ Persistent, type-safe state management for React.
 [![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/)
 
-> **⚠️ Alpha Software** — This library is in active development. APIs may
-> change between releases without prior notice. Use in production at your own
-> risk.
-
----
-
 **react-mnemonic** gives your React components persistent memory. Values survive
 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.
+
 ## Features
 
 - **`useState`-like API** -- `useMnemonicKey` returns `{ value, set, reset, remove }`
@@ -25,6 +22,9 @@ through a single hook that works like `useState`.
 - **Cross-tab sync** -- opt-in `listenCrossTab` uses the browser `storage` event
 - **Pluggable storage** -- bring your own backend via the `StorageLike` interface (IndexedDB, sessionStorage, etc.)
 - **Schema versioning and migration** -- upgrade stored data with versioned schemas and migration rules
+- **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
 - **Lifecycle callbacks** -- `onMount` and `onChange` hooks
 - **DevTools** -- inspect and mutate state from the browser console
@@ -34,20 +34,21 @@ through a single hook that works like `useState`.
 ## Installation
 
 ```bash
-npm install react-mnemonic
+npm install react-mnemonic@beta
 ```
 
 ```bash
-yarn add react-mnemonic
+yarn add react-mnemonic@beta
 ```
 
 ```bash
-pnpm add react-mnemonic
+pnpm add react-mnemonic@beta
 ```
 
 ### Peer dependencies
 
-React 18 or later is required.
+React 18 or later is required. CI verifies packaged-consumer installs against
+React 18 and React 19.
 
 ```json
 {
@@ -90,6 +91,25 @@ export default function App() {
 The counter value persists in `localStorage` under the key `my-app.count` and
 survives full page reloads.
 
+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
+want them to rehydrate after reload. See the
+[Persisted vs Ephemeral State guide](https://thirtytwobits.github.io/react-mnemonic/docs/guides/persisted-vs-ephemeral-state)
+for patterns and an interactive example.
+
+For self-service recovery UX, pair your per-key hooks with
+`useMnemonicRecovery` so users can clear stale filters, reset broken settings,
+or fully wipe a namespace without opening DevTools. See the
+[Reset and Recovery guide](https://thirtytwobits.github.io/react-mnemonic/docs/guides/reset-and-recovery)
+for soft-reset and hard-reset recipes.
+
+If a field must stay cleared across reloads, model it as nullable and persist
+`null` explicitly. `remove()` deletes the key and falls back to `defaultValue`,
+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.
+
 ## API
 
 ### `<MnemonicProvider>`
@@ -125,16 +145,48 @@ const { value, set, reset, remove } = useMnemonicKey<T>(key, options);
 | `reset`  | `() => void`                         | Reset to `defaultValue` and persist it        |
 | `remove` | `() => void`                         | Delete the key from storage entirely          |
 
+For clearable fields, remember the semantic split:
+
+- `set(null)` persists a cleared value and stays cleared after reload
+- `remove()` deletes the key, so the next read falls back to `defaultValue`
+- `reset()` persists `defaultValue`
+
 #### Options
 
-| Option           | Type                                              | Default     | Description                                         |
-| ---------------- | ------------------------------------------------- | ----------- | --------------------------------------------------- |
-| `defaultValue`   | `T \| ((error?: CodecError \| SchemaError) => T)` | _required_  | Fallback value or error-aware factory               |
-| `codec`          | `Codec<T>`                                        | `JSONCodec` | Encode/decode strategy (bypasses schema validation) |
-| `onMount`        | `(value: T) => void`                              | --          | Called once with the initial value                  |
-| `onChange`       | `(value: T, prev: T) => void`                     | --          | Called on every value change                        |
-| `listenCrossTab` | `boolean`                                         | `false`     | Sync via the browser `storage` event                |
-| `schema`         | `{ version?: number }`                            | --          | Pin writes to a specific schema version             |
+| Option           | Type                                              | Default     | Description                                                   |
+| ---------------- | ------------------------------------------------- | ----------- | ------------------------------------------------------------- |
+| `defaultValue`   | `T \| ((error?: CodecError \| SchemaError) => T)` | _required_  | Fallback value or error-aware factory                         |
+| `codec`          | `Codec<T>`                                        | `JSONCodec` | Encode/decode strategy (bypasses schema validation)           |
+| `reconcile`      | `(value: T, context: ReconcileContext) => T`      | --          | Adjust a persisted value after read and persist if it changes |
+| `onMount`        | `(value: T) => void`                              | --          | Called once with the initial value                            |
+| `onChange`       | `(value: T, prev: T) => void`                     | --          | Called on every value change                                  |
+| `listenCrossTab` | `boolean`                                         | `false`     | Sync via the browser `storage` event                          |
+| `schema`         | `{ version?: number }`                            | --          | Pin writes to a specific schema version                       |
+
+### `useMnemonicRecovery(options)`
+
+Hook for namespace-scoped recovery actions such as "clear saved filters" or
+"reset all persisted app data".
+
+```ts
+const { namespace, canEnumerateKeys, listKeys, clearAll, clearKeys, clearMatching } = useMnemonicRecovery({
+    onRecover: (event) => console.log(event.action, event.clearedKeys),
+});
+```
+
+| Return             | Type                                                | Description                                           |
+| ------------------ | --------------------------------------------------- | ----------------------------------------------------- |
+| `namespace`        | `string`                                            | Current provider namespace                            |
+| `canEnumerateKeys` | `boolean`                                           | Whether the storage backend can list namespace keys   |
+| `listKeys`         | `() => string[]`                                    | List visible unprefixed keys in the current namespace |
+| `clearAll`         | `() => string[]`                                    | Clear every key in the namespace                      |
+| `clearKeys`        | `(keys: readonly string[]) => string[]`             | Clear an explicit set of unprefixed keys              |
+| `clearMatching`    | `(predicate: (key: string) => boolean) => string[]` | Clear keys whose names match a predicate              |
+
+`clearAll()` and `clearMatching()` require an enumerable storage backend such
+as `localStorage` or `sessionStorage`. If your custom storage does not support
+`length` and `key(index)`, use `clearKeys([...])` with the explicit durable-key
+list your app owns.
 
 ### Codecs
 
@@ -172,6 +224,8 @@ interface StorageLike {
 `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.
+Namespace-wide recovery helpers can only enumerate keys when the backend also
+implements `length` and `key(index)`.
 
 ### `validateJsonSchema(schema, value)`
 
@@ -318,84 +372,109 @@ const normalizer: MigrationRule = {
 };
 ```
 
+### Reconciliation
+
+Use `reconcile` when you want to keep persisted data but selectively enforce
+new application defaults after the value has been decoded and any read-time
+migrations have already run.
+
+```ts
+const { value } = useMnemonicKey("preferences", {
+    defaultValue: { theme: "dark", density: "comfortable", accents: true },
+    reconcile: (persisted, { persistedVersion }) => ({
+        ...persisted,
+        accents: persistedVersion === 0 ? true : persisted.accents,
+    }),
+});
+```
+
+Use a schema migration when the stored shape must move from one explicit version
+to another. Use `reconcile` for conditional, field-level policy changes such as
+rolling out a new default while preserving the rest of a user's stored data.
+
+### Structural migration helpers
+
+For layout-like data that already uses `id` and `children`, Mnemonic ships
+optional pure helpers for common idempotent migration steps:
+
+```ts
+import { insertChildIfMissing, renameNode, dedupeChildrenBy } from "react-mnemonic";
+
+const migrated = dedupeChildrenBy(
+    renameNode(insertChildIfMissing(layout, "sidebar", { id: "search", title: "Search" }), "prefs", "preferences"),
+    (node) => node.id,
+);
+```
+
+Use these inside your `MigrationRule.migrate` functions when you want repeatable
+tree edits without hand-writing the same traversal logic each time. See the
+[Schema Migration guide](https://thirtytwobits.github.io/react-mnemonic/docs/guides/schema-migration)
+for a cookbook example and custom adapter usage.
+
 ### Example schema registry
 
 A schema registry stores versioned schemas for each key, and resolves migration
-paths to upgrade stored data. Schemas are plain JSON (serializable); migrations
-are procedural functions.
+paths to upgrade stored data. For the common immutable case, use
+`createSchemaRegistry(...)` instead of hand-rolling the indexing boilerplate.
 
 ```tsx
 import {
+    createSchemaRegistry,
     MnemonicProvider,
     useMnemonicKey,
-    type SchemaRegistry,
     type KeySchema,
     type MigrationRule,
 } from "react-mnemonic";
 
-const schemas = new Map<string, KeySchema>();
-const migrations: MigrationRule[] = [];
-
-const registry: SchemaRegistry = {
-    getSchema: (key, version) => schemas.get(`${key}:${version}`),
-    getLatestSchema: (key) =>
-        Array.from(schemas.values())
-            .filter((schema) => schema.key === key)
-            .sort((a, b) => b.version - a.version)[0],
-    getMigrationPath: (key, fromVersion, toVersion) => {
-        const byKey = migrations.filter((rule) => rule.key === key);
-        const path: MigrationRule[] = [];
-        let cur = fromVersion;
-        while (cur < toVersion) {
-            const next = byKey.find((rule) => rule.fromVersion === cur);
-            if (!next) return null;
-            path.push(next);
-            cur = next.toVersion;
-        }
-        return path;
-    },
-    getWriteMigration: (key, version) => {
-        return migrations.find((r) => r.key === key && r.fromVersion === version && r.toVersion === version);
-    },
-    registerSchema: (schema) => {
-        const id = `${schema.key}:${schema.version}`;
-        if (schemas.has(id)) throw new Error(`Schema already registered for ${id}`);
-        schemas.set(id, schema);
+const schemas: KeySchema[] = [
+    {
+        key: "profile",
+        version: 1,
+        schema: {
+            type: "object",
+            properties: { name: { type: "string" }, email: { type: "string" } },
+            required: ["name", "email"],
+        },
     },
-};
-
-registry.registerSchema({
-    key: "profile",
-    version: 1,
-    schema: {
-        type: "object",
-        properties: { name: { type: "string" }, email: { type: "string" } },
-        required: ["name", "email"],
+    {
+        key: "profile",
+        version: 2,
+        schema: {
+            type: "object",
+            properties: {
+                name: { type: "string" },
+                email: { type: "string" },
+                migratedAt: { type: "string" },
+            },
+            required: ["name", "email", "migratedAt"],
+        },
     },
-});
-
-migrations.push({
-    key: "profile",
-    fromVersion: 1,
-    toVersion: 2,
-    migrate: (value) => {
-        const v1 = value as { name: string; email: string };
-        return { ...v1, migratedAt: new Date().toISOString() };
+];
+
+const migrations: MigrationRule[] = [
+    {
+        key: "profile",
+        fromVersion: 1,
+        toVersion: 2,
+        migrate: (value) => {
+            const v1 = value as { name: string; email: string };
+            return { ...v1, migratedAt: new Date().toISOString() };
+        },
     },
-});
-
-registry.registerSchema({
-    key: "profile",
-    version: 2,
-    schema: {
-        type: "object",
-        properties: {
-            name: { type: "string" },
-            email: { type: "string" },
-            migratedAt: { type: "string" },
+    {
+        key: "profile",
+        fromVersion: 2,
+        toVersion: 2,
+        migrate: (value) => {
+            const profile = value as { name: string; email: string; migratedAt: string };
+            return { ...profile, email: profile.email.trim().toLowerCase() };
         },
-        required: ["name", "email", "migratedAt"],
     },
+];
+
+const registry = createSchemaRegistry({
+    schemas,
+    migrations,
 });
 
 function ProfileEditor() {
@@ -410,6 +489,11 @@ function ProfileEditor() {
 </MnemonicProvider>;
 ```
 
+`createSchemaRegistry` validates duplicate schemas and ambiguous migration
+graphs up front. If you need runtime schema registration for
+`schemaMode="autoschema"`, keep a custom mutable `SchemaRegistry`
+implementation.
+
 ### Registry immutability
 
 In `default` and `strict` modes, the schema registry is treated as immutable for
@@ -452,12 +536,14 @@ Enable the console inspector in development:
 Then in the browser console:
 
 ```js
-__REACT_MNEMONIC_DEVTOOLS__.app.dump(); // table of all keys
-__REACT_MNEMONIC_DEVTOOLS__.app.get("theme"); // read a decoded value
-__REACT_MNEMONIC_DEVTOOLS__.app.set("theme", "dark"); // write
-__REACT_MNEMONIC_DEVTOOLS__.app.remove("theme"); // delete
-__REACT_MNEMONIC_DEVTOOLS__.app.keys(); // list all keys
-__REACT_MNEMONIC_DEVTOOLS__.app.clear(); // remove all keys
+const app = window.__REACT_MNEMONIC_DEVTOOLS__?.resolve("app");
+
+app?.dump(); // table of all keys
+app?.get("theme"); // read a decoded value
+app?.set("theme", "dark"); // write
+app?.remove("theme"); // delete
+app?.keys(); // list all keys
+app?.clear(); // remove all keys
 ```
 
 ## TypeScript