react-mnemonic 1.3.0 → 1.4.0

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

@@ -528,6 +528,19 @@ interface MnemonicProviderOptions {
      * ```
      */
     ssr?: MnemonicProviderSSRConfig;
+    /**
+     * Optional bootstrap snapshot used to seed the provider cache before the
+     * first hook subscribes.
+     *
+     * Pass the object returned by `recallMnemonic(...)` when you synchronously
+     * read values before React renders, for example to apply a theme attribute
+     * before first paint and then ensure the first `useMnemonicKey(...)` read
+     * sees the same raw storage snapshot without re-reading storage.
+     *
+     * This seed is consumed only during the provider's initial mount. Later
+     * prop changes are ignored so rerenders do not recreate the internal store.
+     */
+    bootstrap?: MnemonicBootstrapSeed;
 }
 /**
  * Controls how the provider enforces versioned schemas on stored values.
@@ -585,6 +598,64 @@ interface MnemonicProviderSSRConfig {
      */
     hydration?: MnemonicHydrationMode;
 }
+/**
+ * Initial bootstrap seed for a provider's in-memory cache.
+ *
+ * This is primarily used with `recallMnemonic(...)` from
+ * `react-mnemonic/bootstrap`, allowing apps to synchronously recall values
+ * before React renders and then hand the raw snapshot to `MnemonicProvider`
+ * so the first hook read does not hit storage again.
+ *
+ * The provider currently consumes `raw` to seed its internal cache. `values`
+ * are included so callers can carry the same snapshot object through app
+ * initialization without splitting it apart.
+ *
+ * @template TValues - Decoded values keyed by unprefixed storage key
+ */
+type MnemonicBootstrapSeed<TValues extends Record<string, unknown> = Record<string, unknown>> = {
+    /**
+     * Raw storage strings keyed by the unprefixed mnemonic key name.
+     *
+     * Only keys that were read successfully should appear here.
+     *
+     * A present `null` entry means the key was confirmed absent when the
+     * bootstrap snapshot was taken. Providers may still choose to revalidate
+     * that absence on first access, so only non-null string entries are
+     * guaranteed to short-circuit an initial storage read.
+     *
+     * If storage was unavailable or unreadable during bootstrap, omit the key
+     * entirely so the provider can retry a normal read later.
+     */
+    raw?: Record<string, string | null>;
+    /**
+     * Decoded values recalled during the bootstrap step.
+     *
+     * The provider stores raw snapshots internally, but retaining the decoded
+     * values on the same object is convenient for app-level boot code such as
+     * first-paint theme application.
+     */
+    values?: TValues;
+};
+/**
+ * Fully populated snapshot returned by `recallMnemonic(...)`.
+ *
+ * @template TValues - Decoded values keyed by unprefixed storage key
+ */
+type MnemonicBootstrapSnapshot<TValues extends Record<string, unknown> = Record<string, unknown>> = {
+    /**
+     * Raw storage strings keyed by the unprefixed mnemonic key name.
+     *
+     * Keys are only included when the bootstrap read successfully observed the
+     * underlying storage backend. A present `null` still means the key was
+     * confirmed absent at recall time, though providers may revalidate that
+     * absence before the first hook read.
+     */
+    raw: Record<string, string | null>;
+    /**
+     * Decoded values keyed by the unprefixed mnemonic key name.
+     */
+    values: TValues;
+};
 /**
  * Hook-level SSR controls for `useMnemonicKey(...)`.
  *
@@ -1763,4 +1834,4 @@ type ReconcileContext = {
     latestVersion?: number;
 };
 
-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 };
+export { type MnemonicOptionalBridge as A, type OptionalMnemonicKeySSRConfig as B, type Codec as C, type JsonSchema as D, type SchemaBoundKeyOptions as E, type CreateSchemaRegistryOptions as F, type MigrationRule as G, type CompiledValidator as H, type InferJsonSchemaValue as I, JSONCodec as J, type KeySchema as K, type Listener as L, type MnemonicKeyDescriptor as M, type JsonSchemaType as N, type OptionalMnemonicKeyDescriptor as O, type JsonSchemaValidationError as P, type MigrationPath as Q, type ReconcileContext as R, type StorageLike as S, type TypedJsonSchema as T, type UseMnemonicKeyOptions as U, type TypedKeySchema as V, compileSchema as W, mnemonicSchema as X, validateJsonSchema as Y, type SchemaMode as a, type SchemaRegistry as b, type MnemonicBootstrapSnapshot as c, CodecError as d, type MnemonicBootstrapSeed as e, SchemaError as f, createCodec as g, type MnemonicProviderOptions as h, type MnemonicKeyState as i, type Mnemonic as j, type MnemonicDevToolsCapabilities as k, type MnemonicDevToolsMeta as l, type MnemonicDevToolsProviderApi as m, type MnemonicDevToolsProviderDescriptor as n, type MnemonicDevToolsProviderEntry as o, type MnemonicDevToolsRegistry as p, type MnemonicDevToolsWeakRef as q, type MnemonicHydrationMode as r, type MnemonicKeySSRConfig as s, type MnemonicProviderSSRConfig as t, type MnemonicRecoveryAction as u, type MnemonicRecoveryEvent as v, type MnemonicRecoveryHook as w, type Unsubscribe as x, type UseMnemonicRecoveryOptions as y, type OptionalMnemonicKeyOptions as z };

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

@@ -528,6 +528,19 @@ interface MnemonicProviderOptions {
      * ```
      */
     ssr?: MnemonicProviderSSRConfig;
+    /**
+     * Optional bootstrap snapshot used to seed the provider cache before the
+     * first hook subscribes.
+     *
+     * Pass the object returned by `recallMnemonic(...)` when you synchronously
+     * read values before React renders, for example to apply a theme attribute
+     * before first paint and then ensure the first `useMnemonicKey(...)` read
+     * sees the same raw storage snapshot without re-reading storage.
+     *
+     * This seed is consumed only during the provider's initial mount. Later
+     * prop changes are ignored so rerenders do not recreate the internal store.
+     */
+    bootstrap?: MnemonicBootstrapSeed;
 }
 /**
  * Controls how the provider enforces versioned schemas on stored values.
@@ -585,6 +598,64 @@ interface MnemonicProviderSSRConfig {
      */
     hydration?: MnemonicHydrationMode;
 }
+/**
+ * Initial bootstrap seed for a provider's in-memory cache.
+ *
+ * This is primarily used with `recallMnemonic(...)` from
+ * `react-mnemonic/bootstrap`, allowing apps to synchronously recall values
+ * before React renders and then hand the raw snapshot to `MnemonicProvider`
+ * so the first hook read does not hit storage again.
+ *
+ * The provider currently consumes `raw` to seed its internal cache. `values`
+ * are included so callers can carry the same snapshot object through app
+ * initialization without splitting it apart.
+ *
+ * @template TValues - Decoded values keyed by unprefixed storage key
+ */
+type MnemonicBootstrapSeed<TValues extends Record<string, unknown> = Record<string, unknown>> = {
+    /**
+     * Raw storage strings keyed by the unprefixed mnemonic key name.
+     *
+     * Only keys that were read successfully should appear here.
+     *
+     * A present `null` entry means the key was confirmed absent when the
+     * bootstrap snapshot was taken. Providers may still choose to revalidate
+     * that absence on first access, so only non-null string entries are
+     * guaranteed to short-circuit an initial storage read.
+     *
+     * If storage was unavailable or unreadable during bootstrap, omit the key
+     * entirely so the provider can retry a normal read later.
+     */
+    raw?: Record<string, string | null>;
+    /**
+     * Decoded values recalled during the bootstrap step.
+     *
+     * The provider stores raw snapshots internally, but retaining the decoded
+     * values on the same object is convenient for app-level boot code such as
+     * first-paint theme application.
+     */
+    values?: TValues;
+};
+/**
+ * Fully populated snapshot returned by `recallMnemonic(...)`.
+ *
+ * @template TValues - Decoded values keyed by unprefixed storage key
+ */
+type MnemonicBootstrapSnapshot<TValues extends Record<string, unknown> = Record<string, unknown>> = {
+    /**
+     * Raw storage strings keyed by the unprefixed mnemonic key name.
+     *
+     * Keys are only included when the bootstrap read successfully observed the
+     * underlying storage backend. A present `null` still means the key was
+     * confirmed absent at recall time, though providers may revalidate that
+     * absence before the first hook read.
+     */
+    raw: Record<string, string | null>;
+    /**
+     * Decoded values keyed by the unprefixed mnemonic key name.
+     */
+    values: TValues;
+};
 /**
  * Hook-level SSR controls for `useMnemonicKey(...)`.
  *
@@ -1763,4 +1834,4 @@ type ReconcileContext = {
     latestVersion?: number;
 };
 
-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 };
+export { type MnemonicOptionalBridge as A, type OptionalMnemonicKeySSRConfig as B, type Codec as C, type JsonSchema as D, type SchemaBoundKeyOptions as E, type CreateSchemaRegistryOptions as F, type MigrationRule as G, type CompiledValidator as H, type InferJsonSchemaValue as I, JSONCodec as J, type KeySchema as K, type Listener as L, type MnemonicKeyDescriptor as M, type JsonSchemaType as N, type OptionalMnemonicKeyDescriptor as O, type JsonSchemaValidationError as P, type MigrationPath as Q, type ReconcileContext as R, type StorageLike as S, type TypedJsonSchema as T, type UseMnemonicKeyOptions as U, type TypedKeySchema as V, compileSchema as W, mnemonicSchema as X, validateJsonSchema as Y, type SchemaMode as a, type SchemaRegistry as b, type MnemonicBootstrapSnapshot as c, CodecError as d, type MnemonicBootstrapSeed as e, SchemaError as f, createCodec as g, type MnemonicProviderOptions as h, type MnemonicKeyState as i, type Mnemonic as j, type MnemonicDevToolsCapabilities as k, type MnemonicDevToolsMeta as l, type MnemonicDevToolsProviderApi as m, type MnemonicDevToolsProviderDescriptor as n, type MnemonicDevToolsProviderEntry as o, type MnemonicDevToolsRegistry as p, type MnemonicDevToolsWeakRef as q, type MnemonicHydrationMode as r, type MnemonicKeySSRConfig as s, type MnemonicProviderSSRConfig as t, type MnemonicRecoveryAction as u, type MnemonicRecoveryEvent as v, type MnemonicRecoveryHook as w, type Unsubscribe as x, type UseMnemonicRecoveryOptions as y, type OptionalMnemonicKeyOptions as z };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "react-mnemonic",
-    "version": "1.3.0",
+    "version": "1.4.0",
     "description": "Persistent, type-safe state management for React",
     "type": "module",
     "main": "./dist/index.cjs",
@@ -42,6 +42,15 @@
             "import": "./dist/optional.js",
             "require": "./dist/optional.cjs",
             "default": "./dist/optional.js"
+        },
+        "./bootstrap": {
+            "types": {
+                "import": "./dist/bootstrap.d.ts",
+                "require": "./dist/bootstrap.d.cts"
+            },
+            "import": "./dist/bootstrap.js",
+            "require": "./dist/bootstrap.cjs",
+            "default": "./dist/bootstrap.js"
         }
     },
     "files": [