react-mnemonic 1.2.0-beta1 → 1.3.0

package/dist/key-Bad1hAKN.d.cts

@@ -0,0 +1,47 @@
+import { u as UseMnemonicRecoveryOptions, q as MnemonicRecoveryHook, U as UseMnemonicKeyOptions, a as MnemonicKeyDescriptor, K as KeySchema, z as JsonSchema, A as SchemaBoundKeyOptions } from './types-DcdXbmVl.cjs';
+
+/**
+ * Hook for namespace-scoped recovery actions such as hard reset and selective clear.
+ *
+ * Applications can use this to offer self-service recovery UX for corrupt or
+ * legacy persisted state. The hook operates on the current provider namespace.
+ *
+ * See the
+ * [Reset and Recovery guide](https://thirtytwobits.github.io/react-mnemonic/docs/guides/reset-and-recovery)
+ * for soft-reset and hard-reset patterns.
+ *
+ * @param options - Optional recovery callback for telemetry/auditing
+ * @returns Namespace recovery helpers
+ *
+ * @throws {Error} If used outside of a MnemonicProvider
+ */
+declare function useMnemonicRecovery(options?: UseMnemonicRecoveryOptions): MnemonicRecoveryHook;
+
+/**
+ * Define a reusable, importable contract for a persisted key.
+ *
+ * This packages the storage key and the canonical `useMnemonicKey(...)`
+ * options into a single object that can be shared across components, docs,
+ * and generated code.
+ *
+ * @template K - The literal storage key name
+ * @template T - The decoded value type for the key
+ *
+ * @param key - The unprefixed storage key
+ * @param options - Canonical hook options for the key
+ * @returns A descriptor that can be passed directly to `useMnemonicKey(...)`
+ *
+ * @example
+ * ```typescript
+ * const themeKey = defineMnemonicKey("theme", {
+ *   defaultValue: "light" as "light" | "dark",
+ *   listenCrossTab: true,
+ * });
+ *
+ * const { value, set } = useMnemonicKey(themeKey);
+ * ```
+ */
+declare function defineMnemonicKey<const K extends string, T>(key: K, options: UseMnemonicKeyOptions<T>): MnemonicKeyDescriptor<T, K>;
+declare function defineMnemonicKey<const K extends string, TSchema extends KeySchema<unknown, K, JsonSchema>>(keySchema: TSchema, options: SchemaBoundKeyOptions<TSchema extends KeySchema<infer TValue, string, JsonSchema> ? TValue : never>): MnemonicKeyDescriptor<TSchema extends KeySchema<infer TValue, string, JsonSchema> ? TValue : never, TSchema["key"]>;
+
+export { defineMnemonicKey as d, useMnemonicRecovery as u };

package/dist/key-QIDPiubI.d.ts

@@ -0,0 +1,47 @@
+import { u as UseMnemonicRecoveryOptions, q as MnemonicRecoveryHook, U as UseMnemonicKeyOptions, a as MnemonicKeyDescriptor, K as KeySchema, z as JsonSchema, A as SchemaBoundKeyOptions } from './types-DcdXbmVl.js';
+
+/**
+ * Hook for namespace-scoped recovery actions such as hard reset and selective clear.
+ *
+ * Applications can use this to offer self-service recovery UX for corrupt or
+ * legacy persisted state. The hook operates on the current provider namespace.
+ *
+ * See the
+ * [Reset and Recovery guide](https://thirtytwobits.github.io/react-mnemonic/docs/guides/reset-and-recovery)
+ * for soft-reset and hard-reset patterns.
+ *
+ * @param options - Optional recovery callback for telemetry/auditing
+ * @returns Namespace recovery helpers
+ *
+ * @throws {Error} If used outside of a MnemonicProvider
+ */
+declare function useMnemonicRecovery(options?: UseMnemonicRecoveryOptions): MnemonicRecoveryHook;
+
+/**
+ * Define a reusable, importable contract for a persisted key.
+ *
+ * This packages the storage key and the canonical `useMnemonicKey(...)`
+ * options into a single object that can be shared across components, docs,
+ * and generated code.
+ *
+ * @template K - The literal storage key name
+ * @template T - The decoded value type for the key
+ *
+ * @param key - The unprefixed storage key
+ * @param options - Canonical hook options for the key
+ * @returns A descriptor that can be passed directly to `useMnemonicKey(...)`
+ *
+ * @example
+ * ```typescript
+ * const themeKey = defineMnemonicKey("theme", {
+ *   defaultValue: "light" as "light" | "dark",
+ *   listenCrossTab: true,
+ * });
+ *
+ * const { value, set } = useMnemonicKey(themeKey);
+ * ```
+ */
+declare function defineMnemonicKey<const K extends string, T>(key: K, options: UseMnemonicKeyOptions<T>): MnemonicKeyDescriptor<T, K>;
+declare function defineMnemonicKey<const K extends string, TSchema extends KeySchema<unknown, K, JsonSchema>>(keySchema: TSchema, options: SchemaBoundKeyOptions<TSchema extends KeySchema<infer TValue, string, JsonSchema> ? TValue : never>): MnemonicKeyDescriptor<TSchema extends KeySchema<infer TValue, string, JsonSchema> ? TValue : never, TSchema["key"]>;
+
+export { defineMnemonicKey as d, useMnemonicRecovery as u };

package/dist/optional.cjs

@@ -0,0 +1,166 @@
+'use strict';
+
+var react = require('react');
+
+// src/Mnemonic/use-key-optional.ts
+var MnemonicOptionalBridgeContext = react.createContext(null);
+function useMnemonicOptionalBridge() {
+  return react.useContext(MnemonicOptionalBridgeContext);
+}
+function toPublicMnemonicOptionalBridge(bridge) {
+  if (!bridge) {
+    return null;
+  }
+  return {
+    namespace: bridge.namespace,
+    capabilities: bridge.capabilities
+  };
+}
+
+// src/Mnemonic/use-key-optional.ts
+var SSR_SNAPSHOT_TOKEN = /* @__PURE__ */ Symbol("mnemonic:optional-ssr-snapshot");
+function resolveOptionalDescriptor(keyOrDescriptor, options) {
+  if (typeof keyOrDescriptor !== "string") {
+    return keyOrDescriptor;
+  }
+  if (!options) {
+    throw new Error("useMnemonicKeyOptional requires options when called with a string key");
+  }
+  return {
+    key: keyOrDescriptor,
+    options
+  };
+}
+function resolveOptionalDefaultValue(defaultValue) {
+  return typeof defaultValue === "function" ? defaultValue() : defaultValue;
+}
+function resolveOptionalServerValue(options) {
+  const serverValue = options.ssr?.serverValue;
+  if (serverValue !== void 0) {
+    return typeof serverValue === "function" ? serverValue() : serverValue;
+  }
+  return resolveOptionalDefaultValue(options.defaultValue);
+}
+function useMnemonicOptional() {
+  const bridge = useMnemonicOptionalBridge();
+  return react.useMemo(() => toPublicMnemonicOptionalBridge(bridge), [bridge]);
+}
+function useMnemonicKeyOptional(keyOrDescriptor, options) {
+  const bridge = useMnemonicOptionalBridge();
+  const descriptor = resolveOptionalDescriptor(keyOrDescriptor, options);
+  const key = descriptor.key;
+  const resolvedOptions = descriptor.options;
+  const { defaultValue, onMount, onChange } = resolvedOptions;
+  const hasBridge = bridge !== null;
+  const getFallback = react.useCallback(() => resolveOptionalDefaultValue(defaultValue), [defaultValue]);
+  const getServerValue = react.useCallback(() => resolveOptionalServerValue(resolvedOptions), [resolvedOptions]);
+  const [memoryValue, setMemoryValue] = react.useState(() => getServerValue());
+  const raw = react.useSyncExternalStore(
+    react.useCallback(
+      (listener) => {
+        if (!bridge) {
+          return () => void 0;
+        }
+        return bridge.subscribeRaw(key, listener);
+      },
+      [bridge, key]
+    ),
+    react.useCallback(() => bridge ? bridge.getRawSnapshot(key) : null, [bridge, key]),
+    react.useCallback(
+      () => resolvedOptions.ssr?.serverValue === void 0 ? null : SSR_SNAPSHOT_TOKEN,
+      [resolvedOptions.ssr?.serverValue]
+    )
+  );
+  const bridgeSnapshot = react.useMemo(() => {
+    if (!bridge) {
+      return null;
+    }
+    if (raw === SSR_SNAPSHOT_TOKEN) {
+      return {
+        value: getServerValue()
+      };
+    }
+    return bridge.decodeSnapshot(key, raw, resolvedOptions);
+  }, [bridge, getServerValue, key, raw, resolvedOptions]);
+  react.useEffect(() => {
+    if (!bridge || !bridgeSnapshot || raw === SSR_SNAPSHOT_TOKEN) {
+      return;
+    }
+    bridge.commitSnapshot(key, raw, bridgeSnapshot);
+  }, [bridge, bridgeSnapshot, key, raw]);
+  const value = hasBridge ? bridgeSnapshot?.value ?? memoryValue : memoryValue;
+  const mountedRef = react.useRef(false);
+  const previousRef = react.useRef(value);
+  react.useEffect(() => {
+    if (mountedRef.current) {
+      return;
+    }
+    mountedRef.current = true;
+    onMount?.(value);
+    previousRef.current = value;
+  }, []);
+  react.useEffect(() => {
+    const previous = previousRef.current;
+    if (Object.is(previous, value)) {
+      return;
+    }
+    previousRef.current = value;
+    onChange?.(value, previous);
+  }, [onChange, value]);
+  const set = react.useMemo(
+    () => (next) => {
+      if (bridge) {
+        const nextValue = typeof next === "function" ? next(
+          bridge.decodeSnapshot(key, bridge.getRawSnapshot(key), resolvedOptions).value
+        ) : next;
+        bridge.setValue(key, nextValue, resolvedOptions);
+        return;
+      }
+      setMemoryValue((current) => typeof next === "function" ? next(current) : next);
+    },
+    [bridge, key, resolvedOptions]
+  );
+  const reset = react.useMemo(
+    () => () => {
+      if (bridge) {
+        bridge.setValue(key, getFallback(), resolvedOptions);
+        return;
+      }
+      setMemoryValue(getFallback());
+    },
+    [bridge, getFallback, key, resolvedOptions]
+  );
+  const remove = react.useMemo(
+    () => () => {
+      if (bridge) {
+        bridge.removeValue(key);
+        return;
+      }
+      setMemoryValue(getFallback());
+    },
+    [bridge, getFallback, key]
+  );
+  return react.useMemo(
+    () => ({
+      value,
+      set,
+      reset,
+      remove
+    }),
+    [remove, reset, set, value]
+  );
+}
+
+// src/Mnemonic/key-optional.ts
+function defineMnemonicKey(key, options) {
+  return Object.freeze({
+    key,
+    options
+  });
+}
+
+exports.defineMnemonicKey = defineMnemonicKey;
+exports.useMnemonicKeyOptional = useMnemonicKeyOptional;
+exports.useMnemonicOptional = useMnemonicOptional;
+//# sourceMappingURL=optional.cjs.map
+//# sourceMappingURL=optional.cjs.map

package/dist/optional.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/Mnemonic/optional-bridge.tsx","../src/Mnemonic/use-key-optional.ts","../src/Mnemonic/key-optional.ts"],"names":["createContext","useContext","useMemo","useCallback","useState","useSyncExternalStore","useEffect","useRef"],"mappings":"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","file":"optional.cjs","sourcesContent":["// SPDX-License-Identifier: MIT\n// Copyright Scott Dixon\n\nimport { createContext, useContext } from \"react\";\nimport type { KeySchema, Listener, MnemonicOptionalBridge, OptionalMnemonicKeyOptions, Unsubscribe } from \"./types\";\n\nexport type OptionalReadResult<T> = {\n    value: T;\n    rewriteRaw?: string;\n    pendingSchema?: KeySchema;\n};\n\nexport interface MnemonicOptionalBridgeInternal extends MnemonicOptionalBridge {\n    subscribeRaw(key: string, listener: Listener): Unsubscribe;\n    getRawSnapshot(key: string): string | null;\n    decodeSnapshot<T>(key: string, raw: string | null, options: OptionalMnemonicKeyOptions<T>): OptionalReadResult<T>;\n    setValue<T>(key: string, nextValue: T, options: OptionalMnemonicKeyOptions<T>): void;\n    removeValue(key: string): void;\n    commitSnapshot<T>(key: string, raw: string | null, snapshot: OptionalReadResult<T>): void;\n}\n\nexport const MnemonicOptionalBridgeContext = createContext<MnemonicOptionalBridgeInternal | null>(null);\n\nexport function useMnemonicOptionalBridge(): MnemonicOptionalBridgeInternal | null {\n    return useContext(MnemonicOptionalBridgeContext);\n}\n\nexport function toPublicMnemonicOptionalBridge(\n    bridge: MnemonicOptionalBridgeInternal | null,\n): MnemonicOptionalBridge | null {\n    if (!bridge) {\n        return null;\n    }\n    return {\n        namespace: bridge.namespace,\n        capabilities: bridge.capabilities,\n    };\n}\n","// SPDX-License-Identifier: MIT\n// Copyright Scott Dixon\n\nimport { useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore } from \"react\";\nimport { toPublicMnemonicOptionalBridge, useMnemonicOptionalBridge } from \"./optional-bridge\";\nimport type {\n    MnemonicKeyState,\n    MnemonicOptionalBridge,\n    OptionalMnemonicKeyDescriptor,\n    OptionalMnemonicKeyOptions,\n} from \"./types\";\n\nconst SSR_SNAPSHOT_TOKEN = Symbol(\"mnemonic:optional-ssr-snapshot\");\n\nfunction resolveOptionalDescriptor<T>(\n    keyOrDescriptor: string | OptionalMnemonicKeyDescriptor<T, string>,\n    options?: OptionalMnemonicKeyOptions<T>,\n): OptionalMnemonicKeyDescriptor<T, string> {\n    if (typeof keyOrDescriptor !== \"string\") {\n        return keyOrDescriptor;\n    }\n    if (!options) {\n        throw new Error(\"useMnemonicKeyOptional requires options when called with a string key\");\n    }\n    return {\n        key: keyOrDescriptor,\n        options,\n    };\n}\n\nfunction resolveOptionalDefaultValue<T>(defaultValue: OptionalMnemonicKeyOptions<T>[\"defaultValue\"]): T {\n    return typeof defaultValue === \"function\" ? (defaultValue as () => T)() : defaultValue;\n}\n\nfunction resolveOptionalServerValue<T>(options: OptionalMnemonicKeyOptions<T>): T {\n    const serverValue = options.ssr?.serverValue;\n    if (serverValue !== undefined) {\n        return typeof serverValue === \"function\" ? (serverValue as () => T)() : serverValue;\n    }\n    return resolveOptionalDefaultValue(options.defaultValue);\n}\n\nexport function useMnemonicOptional(): MnemonicOptionalBridge | null {\n    const bridge = useMnemonicOptionalBridge();\n    return useMemo(() => toPublicMnemonicOptionalBridge(bridge), [bridge]);\n}\n\nexport function useMnemonicKeyOptional<T, K extends string>(\n    descriptor: OptionalMnemonicKeyDescriptor<T, K>,\n): MnemonicKeyState<T>;\nexport function useMnemonicKeyOptional<T>(key: string, options: OptionalMnemonicKeyOptions<T>): MnemonicKeyState<T>;\nexport function useMnemonicKeyOptional<T>(\n    keyOrDescriptor: string | OptionalMnemonicKeyDescriptor<T, string>,\n    options?: OptionalMnemonicKeyOptions<T>,\n): MnemonicKeyState<T> {\n    const bridge = useMnemonicOptionalBridge();\n    const descriptor = resolveOptionalDescriptor(keyOrDescriptor, options);\n    const key = descriptor.key;\n    const resolvedOptions = descriptor.options;\n    const { defaultValue, onMount, onChange } = resolvedOptions;\n    const hasBridge = bridge !== null;\n\n    const getFallback = useCallback(() => resolveOptionalDefaultValue(defaultValue), [defaultValue]);\n    const getServerValue = useCallback(() => resolveOptionalServerValue(resolvedOptions), [resolvedOptions]);\n\n    const [memoryValue, setMemoryValue] = useState<T>(() => getServerValue());\n    const raw = useSyncExternalStore<string | null | typeof SSR_SNAPSHOT_TOKEN>(\n        useCallback(\n            (listener: () => void) => {\n                if (!bridge) {\n                    return () => undefined;\n                }\n                return bridge.subscribeRaw(key, listener);\n            },\n            [bridge, key],\n        ),\n        useCallback(() => (bridge ? bridge.getRawSnapshot(key) : null), [bridge, key]),\n        useCallback(\n            () => (resolvedOptions.ssr?.serverValue === undefined ? null : SSR_SNAPSHOT_TOKEN),\n            [resolvedOptions.ssr?.serverValue],\n        ),\n    );\n\n    const bridgeSnapshot = useMemo(() => {\n        if (!bridge) {\n            return null;\n        }\n        if (raw === SSR_SNAPSHOT_TOKEN) {\n            return {\n                value: getServerValue(),\n            };\n        }\n        return bridge.decodeSnapshot(key, raw, resolvedOptions);\n    }, [bridge, getServerValue, key, raw, resolvedOptions]);\n\n    useEffect(() => {\n        if (!bridge || !bridgeSnapshot || raw === SSR_SNAPSHOT_TOKEN) {\n            return;\n        }\n        bridge.commitSnapshot(key, raw, bridgeSnapshot);\n    }, [bridge, bridgeSnapshot, key, raw]);\n\n    const value = hasBridge ? (bridgeSnapshot?.value ?? memoryValue) : memoryValue;\n\n    const mountedRef = useRef(false);\n    const previousRef = useRef(value);\n\n    useEffect(() => {\n        if (mountedRef.current) {\n            return;\n        }\n        mountedRef.current = true;\n        onMount?.(value);\n        previousRef.current = value;\n        // eslint-disable-next-line react-hooks/exhaustive-deps\n    }, []);\n\n    useEffect(() => {\n        const previous = previousRef.current;\n        if (Object.is(previous, value)) {\n            return;\n        }\n        previousRef.current = value;\n        onChange?.(value, previous);\n    }, [onChange, value]);\n\n    const set = useMemo<MnemonicKeyState<T>[\"set\"]>(\n        () => (next) => {\n            if (bridge) {\n                const nextValue =\n                    typeof next === \"function\"\n                        ? (next as (current: T) => T)(\n                              bridge.decodeSnapshot(key, bridge.getRawSnapshot(key), resolvedOptions).value,\n                          )\n                        : next;\n                bridge.setValue(key, nextValue, resolvedOptions);\n                return;\n            }\n\n            setMemoryValue((current) => (typeof next === \"function\" ? (next as (current: T) => T)(current) : next));\n        },\n        [bridge, key, resolvedOptions],\n    );\n\n    const reset = useMemo<MnemonicKeyState<T>[\"reset\"]>(\n        () => () => {\n            if (bridge) {\n                bridge.setValue(key, getFallback(), resolvedOptions);\n                return;\n            }\n            setMemoryValue(getFallback());\n        },\n        [bridge, getFallback, key, resolvedOptions],\n    );\n\n    const remove = useMemo<MnemonicKeyState<T>[\"remove\"]>(\n        () => () => {\n            if (bridge) {\n                bridge.removeValue(key);\n                return;\n            }\n            setMemoryValue(getFallback());\n        },\n        [bridge, getFallback, key],\n    );\n\n    return useMemo(\n        () => ({\n            value,\n            set,\n            reset,\n            remove,\n        }),\n        [remove, reset, set, value],\n    );\n}\n","// SPDX-License-Identifier: MIT\n// Copyright Scott Dixon\n\nimport type { OptionalMnemonicKeyDescriptor, OptionalMnemonicKeyOptions } from \"./types\";\n\n/**\n * Define a reusable, importable contract for a lean optionally persistent key.\n */\nexport function defineMnemonicKey<const K extends string, T>(\n    key: K,\n    options: OptionalMnemonicKeyOptions<T>,\n): OptionalMnemonicKeyDescriptor<T, K> {\n    return Object.freeze({\n        key,\n        options,\n    });\n}\n"]}

package/dist/optional.d.cts

@@ -0,0 +1,13 @@
+import { O as OptionalMnemonicKeyDescriptor, b as MnemonicKeyState, w as OptionalMnemonicKeyOptions, x as MnemonicOptionalBridge } from './types-DcdXbmVl.cjs';
+export { C as Codec, y as OptionalMnemonicKeySSRConfig } from './types-DcdXbmVl.cjs';
+
+declare function useMnemonicOptional(): MnemonicOptionalBridge | null;
+declare function useMnemonicKeyOptional<T, K extends string>(descriptor: OptionalMnemonicKeyDescriptor<T, K>): MnemonicKeyState<T>;
+declare function useMnemonicKeyOptional<T>(key: string, options: OptionalMnemonicKeyOptions<T>): MnemonicKeyState<T>;
+
+/**
+ * Define a reusable, importable contract for a lean optionally persistent key.
+ */
+declare function defineMnemonicKey<const K extends string, T>(key: K, options: OptionalMnemonicKeyOptions<T>): OptionalMnemonicKeyDescriptor<T, K>;
+
+export { OptionalMnemonicKeyDescriptor as MnemonicKeyDescriptor, MnemonicKeyState, MnemonicOptionalBridge, OptionalMnemonicKeyDescriptor, OptionalMnemonicKeyOptions, OptionalMnemonicKeyOptions as UseMnemonicKeyOptions, defineMnemonicKey, useMnemonicKeyOptional, useMnemonicOptional };

package/dist/optional.d.ts

@@ -0,0 +1,13 @@
+import { O as OptionalMnemonicKeyDescriptor, b as MnemonicKeyState, w as OptionalMnemonicKeyOptions, x as MnemonicOptionalBridge } from './types-DcdXbmVl.js';
+export { C as Codec, y as OptionalMnemonicKeySSRConfig } from './types-DcdXbmVl.js';
+
+declare function useMnemonicOptional(): MnemonicOptionalBridge | null;
+declare function useMnemonicKeyOptional<T, K extends string>(descriptor: OptionalMnemonicKeyDescriptor<T, K>): MnemonicKeyState<T>;
+declare function useMnemonicKeyOptional<T>(key: string, options: OptionalMnemonicKeyOptions<T>): MnemonicKeyState<T>;
+
+/**
+ * Define a reusable, importable contract for a lean optionally persistent key.
+ */
+declare function defineMnemonicKey<const K extends string, T>(key: K, options: OptionalMnemonicKeyOptions<T>): OptionalMnemonicKeyDescriptor<T, K>;
+
+export { OptionalMnemonicKeyDescriptor as MnemonicKeyDescriptor, MnemonicKeyState, MnemonicOptionalBridge, OptionalMnemonicKeyDescriptor, OptionalMnemonicKeyOptions, OptionalMnemonicKeyOptions as UseMnemonicKeyOptions, defineMnemonicKey, useMnemonicKeyOptional, useMnemonicOptional };

package/dist/optional.js

@@ -0,0 +1,162 @@
+import { createContext, useMemo, useCallback, useState, useSyncExternalStore, useEffect, useRef, useContext } from 'react';
+
+// src/Mnemonic/use-key-optional.ts
+var MnemonicOptionalBridgeContext = createContext(null);
+function useMnemonicOptionalBridge() {
+  return useContext(MnemonicOptionalBridgeContext);
+}
+function toPublicMnemonicOptionalBridge(bridge) {
+  if (!bridge) {
+    return null;
+  }
+  return {
+    namespace: bridge.namespace,
+    capabilities: bridge.capabilities
+  };
+}
+
+// src/Mnemonic/use-key-optional.ts
+var SSR_SNAPSHOT_TOKEN = /* @__PURE__ */ Symbol("mnemonic:optional-ssr-snapshot");
+function resolveOptionalDescriptor(keyOrDescriptor, options) {
+  if (typeof keyOrDescriptor !== "string") {
+    return keyOrDescriptor;
+  }
+  if (!options) {
+    throw new Error("useMnemonicKeyOptional requires options when called with a string key");
+  }
+  return {
+    key: keyOrDescriptor,
+    options
+  };
+}
+function resolveOptionalDefaultValue(defaultValue) {
+  return typeof defaultValue === "function" ? defaultValue() : defaultValue;
+}
+function resolveOptionalServerValue(options) {
+  const serverValue = options.ssr?.serverValue;
+  if (serverValue !== void 0) {
+    return typeof serverValue === "function" ? serverValue() : serverValue;
+  }
+  return resolveOptionalDefaultValue(options.defaultValue);
+}
+function useMnemonicOptional() {
+  const bridge = useMnemonicOptionalBridge();
+  return useMemo(() => toPublicMnemonicOptionalBridge(bridge), [bridge]);
+}
+function useMnemonicKeyOptional(keyOrDescriptor, options) {
+  const bridge = useMnemonicOptionalBridge();
+  const descriptor = resolveOptionalDescriptor(keyOrDescriptor, options);
+  const key = descriptor.key;
+  const resolvedOptions = descriptor.options;
+  const { defaultValue, onMount, onChange } = resolvedOptions;
+  const hasBridge = bridge !== null;
+  const getFallback = useCallback(() => resolveOptionalDefaultValue(defaultValue), [defaultValue]);
+  const getServerValue = useCallback(() => resolveOptionalServerValue(resolvedOptions), [resolvedOptions]);
+  const [memoryValue, setMemoryValue] = useState(() => getServerValue());
+  const raw = useSyncExternalStore(
+    useCallback(
+      (listener) => {
+        if (!bridge) {
+          return () => void 0;
+        }
+        return bridge.subscribeRaw(key, listener);
+      },
+      [bridge, key]
+    ),
+    useCallback(() => bridge ? bridge.getRawSnapshot(key) : null, [bridge, key]),
+    useCallback(
+      () => resolvedOptions.ssr?.serverValue === void 0 ? null : SSR_SNAPSHOT_TOKEN,
+      [resolvedOptions.ssr?.serverValue]
+    )
+  );
+  const bridgeSnapshot = useMemo(() => {
+    if (!bridge) {
+      return null;
+    }
+    if (raw === SSR_SNAPSHOT_TOKEN) {
+      return {
+        value: getServerValue()
+      };
+    }
+    return bridge.decodeSnapshot(key, raw, resolvedOptions);
+  }, [bridge, getServerValue, key, raw, resolvedOptions]);
+  useEffect(() => {
+    if (!bridge || !bridgeSnapshot || raw === SSR_SNAPSHOT_TOKEN) {
+      return;
+    }
+    bridge.commitSnapshot(key, raw, bridgeSnapshot);
+  }, [bridge, bridgeSnapshot, key, raw]);
+  const value = hasBridge ? bridgeSnapshot?.value ?? memoryValue : memoryValue;
+  const mountedRef = useRef(false);
+  const previousRef = useRef(value);
+  useEffect(() => {
+    if (mountedRef.current) {
+      return;
+    }
+    mountedRef.current = true;
+    onMount?.(value);
+    previousRef.current = value;
+  }, []);
+  useEffect(() => {
+    const previous = previousRef.current;
+    if (Object.is(previous, value)) {
+      return;
+    }
+    previousRef.current = value;
+    onChange?.(value, previous);
+  }, [onChange, value]);
+  const set = useMemo(
+    () => (next) => {
+      if (bridge) {
+        const nextValue = typeof next === "function" ? next(
+          bridge.decodeSnapshot(key, bridge.getRawSnapshot(key), resolvedOptions).value
+        ) : next;
+        bridge.setValue(key, nextValue, resolvedOptions);
+        return;
+      }
+      setMemoryValue((current) => typeof next === "function" ? next(current) : next);
+    },
+    [bridge, key, resolvedOptions]
+  );
+  const reset = useMemo(
+    () => () => {
+      if (bridge) {
+        bridge.setValue(key, getFallback(), resolvedOptions);
+        return;
+      }
+      setMemoryValue(getFallback());
+    },
+    [bridge, getFallback, key, resolvedOptions]
+  );
+  const remove = useMemo(
+    () => () => {
+      if (bridge) {
+        bridge.removeValue(key);
+        return;
+      }
+      setMemoryValue(getFallback());
+    },
+    [bridge, getFallback, key]
+  );
+  return useMemo(
+    () => ({
+      value,
+      set,
+      reset,
+      remove
+    }),
+    [remove, reset, set, value]
+  );
+}
+
+// src/Mnemonic/key-optional.ts
+function defineMnemonicKey(key, options) {
+  return Object.freeze({
+    key,
+    options
+  });
+}
+
+export { defineMnemonicKey, useMnemonicKeyOptional, useMnemonicOptional };
+//# sourceMappingURL=optional.js.map
+//# sourceMappingURL=optional.js.map

package/dist/optional.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/Mnemonic/optional-bridge.tsx","../src/Mnemonic/use-key-optional.ts","../src/Mnemonic/key-optional.ts"],"names":[],"mappings":"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","file":"optional.js","sourcesContent":["// SPDX-License-Identifier: MIT\n// Copyright Scott Dixon\n\nimport { createContext, useContext } from \"react\";\nimport type { KeySchema, Listener, MnemonicOptionalBridge, OptionalMnemonicKeyOptions, Unsubscribe } from \"./types\";\n\nexport type OptionalReadResult<T> = {\n    value: T;\n    rewriteRaw?: string;\n    pendingSchema?: KeySchema;\n};\n\nexport interface MnemonicOptionalBridgeInternal extends MnemonicOptionalBridge {\n    subscribeRaw(key: string, listener: Listener): Unsubscribe;\n    getRawSnapshot(key: string): string | null;\n    decodeSnapshot<T>(key: string, raw: string | null, options: OptionalMnemonicKeyOptions<T>): OptionalReadResult<T>;\n    setValue<T>(key: string, nextValue: T, options: OptionalMnemonicKeyOptions<T>): void;\n    removeValue(key: string): void;\n    commitSnapshot<T>(key: string, raw: string | null, snapshot: OptionalReadResult<T>): void;\n}\n\nexport const MnemonicOptionalBridgeContext = createContext<MnemonicOptionalBridgeInternal | null>(null);\n\nexport function useMnemonicOptionalBridge(): MnemonicOptionalBridgeInternal | null {\n    return useContext(MnemonicOptionalBridgeContext);\n}\n\nexport function toPublicMnemonicOptionalBridge(\n    bridge: MnemonicOptionalBridgeInternal | null,\n): MnemonicOptionalBridge | null {\n    if (!bridge) {\n        return null;\n    }\n    return {\n        namespace: bridge.namespace,\n        capabilities: bridge.capabilities,\n    };\n}\n","// SPDX-License-Identifier: MIT\n// Copyright Scott Dixon\n\nimport { useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore } from \"react\";\nimport { toPublicMnemonicOptionalBridge, useMnemonicOptionalBridge } from \"./optional-bridge\";\nimport type {\n    MnemonicKeyState,\n    MnemonicOptionalBridge,\n    OptionalMnemonicKeyDescriptor,\n    OptionalMnemonicKeyOptions,\n} from \"./types\";\n\nconst SSR_SNAPSHOT_TOKEN = Symbol(\"mnemonic:optional-ssr-snapshot\");\n\nfunction resolveOptionalDescriptor<T>(\n    keyOrDescriptor: string | OptionalMnemonicKeyDescriptor<T, string>,\n    options?: OptionalMnemonicKeyOptions<T>,\n): OptionalMnemonicKeyDescriptor<T, string> {\n    if (typeof keyOrDescriptor !== \"string\") {\n        return keyOrDescriptor;\n    }\n    if (!options) {\n        throw new Error(\"useMnemonicKeyOptional requires options when called with a string key\");\n    }\n    return {\n        key: keyOrDescriptor,\n        options,\n    };\n}\n\nfunction resolveOptionalDefaultValue<T>(defaultValue: OptionalMnemonicKeyOptions<T>[\"defaultValue\"]): T {\n    return typeof defaultValue === \"function\" ? (defaultValue as () => T)() : defaultValue;\n}\n\nfunction resolveOptionalServerValue<T>(options: OptionalMnemonicKeyOptions<T>): T {\n    const serverValue = options.ssr?.serverValue;\n    if (serverValue !== undefined) {\n        return typeof serverValue === \"function\" ? (serverValue as () => T)() : serverValue;\n    }\n    return resolveOptionalDefaultValue(options.defaultValue);\n}\n\nexport function useMnemonicOptional(): MnemonicOptionalBridge | null {\n    const bridge = useMnemonicOptionalBridge();\n    return useMemo(() => toPublicMnemonicOptionalBridge(bridge), [bridge]);\n}\n\nexport function useMnemonicKeyOptional<T, K extends string>(\n    descriptor: OptionalMnemonicKeyDescriptor<T, K>,\n): MnemonicKeyState<T>;\nexport function useMnemonicKeyOptional<T>(key: string, options: OptionalMnemonicKeyOptions<T>): MnemonicKeyState<T>;\nexport function useMnemonicKeyOptional<T>(\n    keyOrDescriptor: string | OptionalMnemonicKeyDescriptor<T, string>,\n    options?: OptionalMnemonicKeyOptions<T>,\n): MnemonicKeyState<T> {\n    const bridge = useMnemonicOptionalBridge();\n    const descriptor = resolveOptionalDescriptor(keyOrDescriptor, options);\n    const key = descriptor.key;\n    const resolvedOptions = descriptor.options;\n    const { defaultValue, onMount, onChange } = resolvedOptions;\n    const hasBridge = bridge !== null;\n\n    const getFallback = useCallback(() => resolveOptionalDefaultValue(defaultValue), [defaultValue]);\n    const getServerValue = useCallback(() => resolveOptionalServerValue(resolvedOptions), [resolvedOptions]);\n\n    const [memoryValue, setMemoryValue] = useState<T>(() => getServerValue());\n    const raw = useSyncExternalStore<string | null | typeof SSR_SNAPSHOT_TOKEN>(\n        useCallback(\n            (listener: () => void) => {\n                if (!bridge) {\n                    return () => undefined;\n                }\n                return bridge.subscribeRaw(key, listener);\n            },\n            [bridge, key],\n        ),\n        useCallback(() => (bridge ? bridge.getRawSnapshot(key) : null), [bridge, key]),\n        useCallback(\n            () => (resolvedOptions.ssr?.serverValue === undefined ? null : SSR_SNAPSHOT_TOKEN),\n            [resolvedOptions.ssr?.serverValue],\n        ),\n    );\n\n    const bridgeSnapshot = useMemo(() => {\n        if (!bridge) {\n            return null;\n        }\n        if (raw === SSR_SNAPSHOT_TOKEN) {\n            return {\n                value: getServerValue(),\n            };\n        }\n        return bridge.decodeSnapshot(key, raw, resolvedOptions);\n    }, [bridge, getServerValue, key, raw, resolvedOptions]);\n\n    useEffect(() => {\n        if (!bridge || !bridgeSnapshot || raw === SSR_SNAPSHOT_TOKEN) {\n            return;\n        }\n        bridge.commitSnapshot(key, raw, bridgeSnapshot);\n    }, [bridge, bridgeSnapshot, key, raw]);\n\n    const value = hasBridge ? (bridgeSnapshot?.value ?? memoryValue) : memoryValue;\n\n    const mountedRef = useRef(false);\n    const previousRef = useRef(value);\n\n    useEffect(() => {\n        if (mountedRef.current) {\n            return;\n        }\n        mountedRef.current = true;\n        onMount?.(value);\n        previousRef.current = value;\n        // eslint-disable-next-line react-hooks/exhaustive-deps\n    }, []);\n\n    useEffect(() => {\n        const previous = previousRef.current;\n        if (Object.is(previous, value)) {\n            return;\n        }\n        previousRef.current = value;\n        onChange?.(value, previous);\n    }, [onChange, value]);\n\n    const set = useMemo<MnemonicKeyState<T>[\"set\"]>(\n        () => (next) => {\n            if (bridge) {\n                const nextValue =\n                    typeof next === \"function\"\n                        ? (next as (current: T) => T)(\n                              bridge.decodeSnapshot(key, bridge.getRawSnapshot(key), resolvedOptions).value,\n                          )\n                        : next;\n                bridge.setValue(key, nextValue, resolvedOptions);\n                return;\n            }\n\n            setMemoryValue((current) => (typeof next === \"function\" ? (next as (current: T) => T)(current) : next));\n        },\n        [bridge, key, resolvedOptions],\n    );\n\n    const reset = useMemo<MnemonicKeyState<T>[\"reset\"]>(\n        () => () => {\n            if (bridge) {\n                bridge.setValue(key, getFallback(), resolvedOptions);\n                return;\n            }\n            setMemoryValue(getFallback());\n        },\n        [bridge, getFallback, key, resolvedOptions],\n    );\n\n    const remove = useMemo<MnemonicKeyState<T>[\"remove\"]>(\n        () => () => {\n            if (bridge) {\n                bridge.removeValue(key);\n                return;\n            }\n            setMemoryValue(getFallback());\n        },\n        [bridge, getFallback, key],\n    );\n\n    return useMemo(\n        () => ({\n            value,\n            set,\n            reset,\n            remove,\n        }),\n        [remove, reset, set, value],\n    );\n}\n","// SPDX-License-Identifier: MIT\n// Copyright Scott Dixon\n\nimport type { OptionalMnemonicKeyDescriptor, OptionalMnemonicKeyOptions } from \"./types\";\n\n/**\n * Define a reusable, importable contract for a lean optionally persistent key.\n */\nexport function defineMnemonicKey<const K extends string, T>(\n    key: K,\n    options: OptionalMnemonicKeyOptions<T>,\n): OptionalMnemonicKeyDescriptor<T, K> {\n    return Object.freeze({\n        key,\n        options,\n    });\n}\n"]}