react-mnemonic 1.2.0-beta1 → 1.3.0

package/dist/{key-BvFvcKiR.d.cts → types-DcdXbmVl.d.cts}

@@ -1405,6 +1405,93 @@ interface MnemonicKeyDescriptor<T, K extends string = string> {
      */
     readonly options: UseMnemonicKeyOptions<T>;
 }
+/**
+ * Server-rendered seed value for lean optional persistence.
+ *
+ * Unlike the full `MnemonicKeySSRConfig`, the lean optional entrypoint only
+ * supports supplying an initial server value. Hydration policy remains an
+ * application/provider concern so reusable component libraries can stay tiny.
+ */
+interface OptionalMnemonicKeySSRConfig<T> {
+    /**
+     * Value exposed during SSR and the first hydration snapshot.
+     */
+    serverValue?: T | (() => T);
+}
+/**
+ * Reusable, importable contract for a single optionally persistent key.
+ *
+ * This is the descriptor shape consumed by `react-mnemonic/optional`.
+ */
+interface OptionalMnemonicKeyDescriptor<T, K extends string = string> {
+    /**
+     * Unprefixed storage key name.
+     */
+    readonly key: K;
+    /**
+     * Canonical options for the optional hook contract.
+     */
+    readonly options: OptionalMnemonicKeyOptions<T>;
+}
+/**
+ * Lean configuration options for `useMnemonicKeyOptional(...)`.
+ *
+ * These options are intentionally smaller than `UseMnemonicKeyOptions<T>` so
+ * component libraries can depend on a tiny fallback-first shim while still
+ * passing persistence metadata through to an application-provided adapter.
+ */
+type OptionalMnemonicKeyOptions<T> = {
+    /**
+     * Default value used when no persisted value exists or no provider is mounted.
+     */
+    defaultValue: T | (() => T);
+    /**
+     * Codec metadata forwarded to a provider-backed adapter when one exists.
+     *
+     * Ignored by the in-memory fallback path.
+     */
+    codec?: Codec<T>;
+    /**
+     * Invoked once after the initial value resolves.
+     */
+    onMount?: (value: T) => void;
+    /**
+     * Invoked after the visible value changes.
+     */
+    onChange?: (value: T, previous: T) => void;
+    /**
+     * Minimal SSR support for the lean optional hook.
+     */
+    ssr?: OptionalMnemonicKeySSRConfig<T>;
+    /**
+     * Schema version metadata forwarded to schema-capable providers when present.
+     *
+     * Ignored by the in-memory fallback path and by providers without schema
+     * capabilities.
+     */
+    schema?: {
+        version: number;
+    };
+};
+/**
+ * Public metadata exposed by `react-mnemonic/optional`.
+ *
+ * This intentionally avoids exposing the full low-level store API. Applications
+ * that need raw store access should use the required-provider entrypoints.
+ */
+interface MnemonicOptionalBridge {
+    /**
+     * Active namespace when a provider-backed bridge is mounted.
+     */
+    namespace: string;
+    /**
+     * Capabilities supported by the active provider-backed bridge.
+     */
+    capabilities: {
+        persistence: true;
+        schema: boolean;
+    };
+}
 /**
  * Key descriptor options inferred from a typed key schema.
  *
@@ -1676,48 +1763,4 @@ type ReconcileContext = {
     latestVersion?: number;
 };
 
-/**
- * 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 { type JsonSchema as A, type MigrationRule as B, type Codec as C, type CompiledValidator as D, type JsonSchemaType as E, type JsonSchemaValidationError as F, type MigrationPath as G, type SchemaBoundKeyOptions as H, type InferJsonSchemaValue as I, JSONCodec as J, type KeySchema as K, type Listener as L, type MnemonicProviderOptions as M, type TypedKeySchema as N, compileSchema as O, mnemonicSchema as P, validateJsonSchema as Q, type ReconcileContext as R, SchemaError as S, type TypedJsonSchema as T, type UseMnemonicKeyOptions as U, type MnemonicKeyDescriptor as a, type MnemonicKeyState as b, CodecError as c, type Mnemonic as d, type MnemonicDevToolsCapabilities as e, type MnemonicDevToolsMeta as f, type MnemonicDevToolsProviderApi as g, type MnemonicDevToolsProviderDescriptor as h, type MnemonicDevToolsProviderEntry as i, type MnemonicDevToolsRegistry as j, type MnemonicDevToolsWeakRef as k, type MnemonicHydrationMode as l, type MnemonicKeySSRConfig as m, type MnemonicProviderSSRConfig as n, type MnemonicRecoveryAction as o, type MnemonicRecoveryEvent as p, type MnemonicRecoveryHook as q, type SchemaMode as r, type StorageLike as s, type Unsubscribe as t, type UseMnemonicRecoveryOptions as u, createCodec as v, defineMnemonicKey as w, useMnemonicRecovery as x, type CreateSchemaRegistryOptions as y, type SchemaRegistry as z };
+export { type SchemaBoundKeyOptions as A, type CreateSchemaRegistryOptions as B, type Codec as C, type SchemaRegistry as D, type MigrationRule as E, type CompiledValidator as F, type JsonSchemaType as G, type JsonSchemaValidationError as H, type InferJsonSchemaValue as I, JSONCodec as J, type KeySchema as K, type Listener as L, type MnemonicProviderOptions as M, type MigrationPath as N, type OptionalMnemonicKeyDescriptor as O, type TypedKeySchema as P, compileSchema as Q, type ReconcileContext as R, SchemaError as S, type TypedJsonSchema as T, type UseMnemonicKeyOptions as U, mnemonicSchema as V, validateJsonSchema as W, type MnemonicKeyDescriptor as a, type MnemonicKeyState as b, CodecError as c, type Mnemonic as d, type MnemonicDevToolsCapabilities as e, type MnemonicDevToolsMeta as f, type MnemonicDevToolsProviderApi as g, type MnemonicDevToolsProviderDescriptor as h, type MnemonicDevToolsProviderEntry as i, type MnemonicDevToolsRegistry as j, type MnemonicDevToolsWeakRef as k, type MnemonicHydrationMode as l, type MnemonicKeySSRConfig as m, type MnemonicProviderSSRConfig as n, type MnemonicRecoveryAction as o, type MnemonicRecoveryEvent as p, type MnemonicRecoveryHook as q, type SchemaMode as r, type StorageLike as s, type Unsubscribe as t, type UseMnemonicRecoveryOptions as u, createCodec as v, type OptionalMnemonicKeyOptions as w, type MnemonicOptionalBridge as x, type OptionalMnemonicKeySSRConfig as y, type JsonSchema as z };

package/dist/{key-BvFvcKiR.d.ts → types-DcdXbmVl.d.ts}

@@ -1405,6 +1405,93 @@ interface MnemonicKeyDescriptor<T, K extends string = string> {
      */
     readonly options: UseMnemonicKeyOptions<T>;
 }
+/**
+ * Server-rendered seed value for lean optional persistence.
+ *
+ * Unlike the full `MnemonicKeySSRConfig`, the lean optional entrypoint only
+ * supports supplying an initial server value. Hydration policy remains an
+ * application/provider concern so reusable component libraries can stay tiny.
+ */
+interface OptionalMnemonicKeySSRConfig<T> {
+    /**
+     * Value exposed during SSR and the first hydration snapshot.
+     */
+    serverValue?: T | (() => T);
+}
+/**
+ * Reusable, importable contract for a single optionally persistent key.
+ *
+ * This is the descriptor shape consumed by `react-mnemonic/optional`.
+ */
+interface OptionalMnemonicKeyDescriptor<T, K extends string = string> {
+    /**
+     * Unprefixed storage key name.
+     */
+    readonly key: K;
+    /**
+     * Canonical options for the optional hook contract.
+     */
+    readonly options: OptionalMnemonicKeyOptions<T>;
+}
+/**
+ * Lean configuration options for `useMnemonicKeyOptional(...)`.
+ *
+ * These options are intentionally smaller than `UseMnemonicKeyOptions<T>` so
+ * component libraries can depend on a tiny fallback-first shim while still
+ * passing persistence metadata through to an application-provided adapter.
+ */
+type OptionalMnemonicKeyOptions<T> = {
+    /**
+     * Default value used when no persisted value exists or no provider is mounted.
+     */
+    defaultValue: T | (() => T);
+    /**
+     * Codec metadata forwarded to a provider-backed adapter when one exists.
+     *
+     * Ignored by the in-memory fallback path.
+     */
+    codec?: Codec<T>;
+    /**
+     * Invoked once after the initial value resolves.
+     */
+    onMount?: (value: T) => void;
+    /**
+     * Invoked after the visible value changes.
+     */
+    onChange?: (value: T, previous: T) => void;
+    /**
+     * Minimal SSR support for the lean optional hook.
+     */
+    ssr?: OptionalMnemonicKeySSRConfig<T>;
+    /**
+     * Schema version metadata forwarded to schema-capable providers when present.
+     *
+     * Ignored by the in-memory fallback path and by providers without schema
+     * capabilities.
+     */
+    schema?: {
+        version: number;
+    };
+};
+/**
+ * Public metadata exposed by `react-mnemonic/optional`.
+ *
+ * This intentionally avoids exposing the full low-level store API. Applications
+ * that need raw store access should use the required-provider entrypoints.
+ */
+interface MnemonicOptionalBridge {
+    /**
+     * Active namespace when a provider-backed bridge is mounted.
+     */
+    namespace: string;
+    /**
+     * Capabilities supported by the active provider-backed bridge.
+     */
+    capabilities: {
+        persistence: true;
+        schema: boolean;
+    };
+}
 /**
  * Key descriptor options inferred from a typed key schema.
  *
@@ -1676,48 +1763,4 @@ type ReconcileContext = {
     latestVersion?: number;
 };
 
-/**
- * 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 { type JsonSchema as A, type MigrationRule as B, type Codec as C, type CompiledValidator as D, type JsonSchemaType as E, type JsonSchemaValidationError as F, type MigrationPath as G, type SchemaBoundKeyOptions as H, type InferJsonSchemaValue as I, JSONCodec as J, type KeySchema as K, type Listener as L, type MnemonicProviderOptions as M, type TypedKeySchema as N, compileSchema as O, mnemonicSchema as P, validateJsonSchema as Q, type ReconcileContext as R, SchemaError as S, type TypedJsonSchema as T, type UseMnemonicKeyOptions as U, type MnemonicKeyDescriptor as a, type MnemonicKeyState as b, CodecError as c, type Mnemonic as d, type MnemonicDevToolsCapabilities as e, type MnemonicDevToolsMeta as f, type MnemonicDevToolsProviderApi as g, type MnemonicDevToolsProviderDescriptor as h, type MnemonicDevToolsProviderEntry as i, type MnemonicDevToolsRegistry as j, type MnemonicDevToolsWeakRef as k, type MnemonicHydrationMode as l, type MnemonicKeySSRConfig as m, type MnemonicProviderSSRConfig as n, type MnemonicRecoveryAction as o, type MnemonicRecoveryEvent as p, type MnemonicRecoveryHook as q, type SchemaMode as r, type StorageLike as s, type Unsubscribe as t, type UseMnemonicRecoveryOptions as u, createCodec as v, defineMnemonicKey as w, useMnemonicRecovery as x, type CreateSchemaRegistryOptions as y, type SchemaRegistry as z };
+export { type SchemaBoundKeyOptions as A, type CreateSchemaRegistryOptions as B, type Codec as C, type SchemaRegistry as D, type MigrationRule as E, type CompiledValidator as F, type JsonSchemaType as G, type JsonSchemaValidationError as H, type InferJsonSchemaValue as I, JSONCodec as J, type KeySchema as K, type Listener as L, type MnemonicProviderOptions as M, type MigrationPath as N, type OptionalMnemonicKeyDescriptor as O, type TypedKeySchema as P, compileSchema as Q, type ReconcileContext as R, SchemaError as S, type TypedJsonSchema as T, type UseMnemonicKeyOptions as U, mnemonicSchema as V, validateJsonSchema as W, type MnemonicKeyDescriptor as a, type MnemonicKeyState as b, CodecError as c, type Mnemonic as d, type MnemonicDevToolsCapabilities as e, type MnemonicDevToolsMeta as f, type MnemonicDevToolsProviderApi as g, type MnemonicDevToolsProviderDescriptor as h, type MnemonicDevToolsProviderEntry as i, type MnemonicDevToolsRegistry as j, type MnemonicDevToolsWeakRef as k, type MnemonicHydrationMode as l, type MnemonicKeySSRConfig as m, type MnemonicProviderSSRConfig as n, type MnemonicRecoveryAction as o, type MnemonicRecoveryEvent as p, type MnemonicRecoveryHook as q, type SchemaMode as r, type StorageLike as s, type Unsubscribe as t, type UseMnemonicRecoveryOptions as u, createCodec as v, type OptionalMnemonicKeyOptions as w, type MnemonicOptionalBridge as x, type OptionalMnemonicKeySSRConfig as y, type JsonSchema as z };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "react-mnemonic",
-    "version": "1.2.0-beta1",
+    "version": "1.3.0",
     "description": "Persistent, type-safe state management for React",
     "type": "module",
     "main": "./dist/index.cjs",
@@ -33,6 +33,15 @@
             "import": "./dist/schema.js",
             "require": "./dist/schema.cjs",
             "default": "./dist/schema.js"
+        },
+        "./optional": {
+            "types": {
+                "import": "./dist/optional.d.ts",
+                "require": "./dist/optional.d.cts"
+            },
+            "import": "./dist/optional.js",
+            "require": "./dist/optional.cjs",
+            "default": "./dist/optional.js"
         }
     },
     "files": [
@@ -44,12 +53,15 @@
         "test": "vitest run",
         "test:consumers": "node ./scripts/run-consumer-fixtures.mjs",
         "test:coverage": "vitest run --coverage",
+        "test:optional-bundle": "node ./scripts/check-optional-bundle.mjs",
         "test:watch": "vitest",
         "ai:check": "node ./website/scripts/generate-ai-assets.mjs --check && node ./scripts/generate-agent-instructions.mjs --check",
         "lint": "tsc -p tsconfig.json --noEmit",
         "format": "prettier --write .",
         "format:check": "prettier --check .",
         "docs:ai": "node ./website/scripts/generate-ai-assets.mjs && node ./scripts/generate-agent-instructions.mjs",
+        "docs:version": "npm --prefix website run typedoc && npm run docs:ai && npm --prefix website run docusaurus -- docs:version",
+        "release:prepare": "node ./scripts/prepare-release.mjs",
         "docs": "typedoc",
         "docs:watch": "typedoc --watch",
         "docs:site": "npm --prefix website run build",