Type Alias: StorageLike

StorageLike = object

Defined in: src/Mnemonic/types.ts:891

Storage interface compatible with localStorage and synchronous custom storage implementations.

Defines the minimum contract required for a storage backend. Compatible with browser Storage API (localStorage, sessionStorage) and custom implementations for testing or alternative storage solutions.

All methods in this contract are intentionally synchronous. Promise-returning adapters such as React Native AsyncStorage are not directly supported by StorageLike; instead, keep a synchronous in-memory cache and flush to async persistence outside the hook contract.

Remarks

Error handling contract

The library wraps every storage call in a try/catch. Errors are handled as follows:

• DOMException with name === "QuotaExceededError" — Logged once via console.error with the prefix [Mnemonic] Storage quota exceeded. Squelched until a write succeeds, then the flag resets.

• Other DOMException errors (including SecurityError) — Logged once via console.error with the prefix [Mnemonic] Storage access error. Squelched until any storage operation succeeds, then the flag resets.

• All other error types — Not logged.

Custom StorageLike implementations are encouraged to throw DOMException for storage access failures so the library can surface console diagnostics. Throwing other error types is safe and never goes unreported: whatever is thrown reaches MnemonicProviderOptions.onStorageError as an "access" failure, and the key is queued for retry either way. Only the console message is DOMException-specific.

In all error cases the library falls back to its in-memory cache, so components continue to function when the storage backend is unavailable. A mutation that the backend rejected is queued rather than forgotten: the key is reported by Mnemonic.unpersistedKeys and can be re-attempted with Mnemonic.flush once the backend is healthy again. Logging is squelched per failure streak, so those queues and MnemonicProviderOptions.onStorageError — not the console — are the reliable signal that a value is memory-only.

Promise-returning getItem, setItem, or removeItem implementations are treated as an invalid contract at runtime. Mnemonic logs the misuse once and falls back to its in-memory cache for safety.

Example

// In-memory storage for testing
const mockStorage: StorageLike = {
  items: new Map<string, string>(),
  getItem(key) { return this.items.get(key) ?? null; },
  setItem(key, value) { this.items.set(key, value); },
  removeItem(key) { this.items.delete(key); },
  get length() { return this.items.size; },
  key(index) {
    return Array.from(this.items.keys())[index] ?? null;
  }
};

Properties

length?

readonly optional length?: number

Defined in: src/Mnemonic/types.ts:936

The number of items currently stored.

Optional property for enumeration support.

---

onExternalChange?

optional onExternalChange?: (callback) => () => void

Defined in: src/Mnemonic/types.ts:963

Subscribe to notifications when data changes externally.

localStorage has built-in cross-tab notification via the browser's native storage event (used by the listenCrossTab hook option). Non-localStorage backends (IndexedDB, custom stores, etc.) lack this built-in mechanism. Implementing onExternalChange allows those adapters to provide equivalent cross-tab synchronization through their own transport (e.g., BroadcastChannel).

The callback accepts an optional changedKeys parameter:

• callback() or callback(undefined) triggers a blanket reload of all actively subscribed keys.
• callback(["ns.key1", "ns.key2"]) reloads only the specified fully-qualified keys, which is more efficient when the adapter knows exactly which keys changed.
• callback([]) is a no-op.

On a blanket reload the provider re-reads all actively subscribed keys from the storage backend and emits change notifications for any whose values differ from the cache.

Parameters

Parameter	Type	Description
callback	(changedKeys?) => void	Invoked when external data changes

Returns

An unsubscribe function that removes the callback

() => void

Methods

getItem()

getItem(key): string | null

Defined in: src/Mnemonic/types.ts:900

Retrieves the value associated with a key.

Parameters

Parameter	Type	Description
key	string	The storage key to retrieve

Returns

string | null

The stored value as a string, or null if not found

Remarks

Must return synchronously. Returning a Promise is unsupported.

---

key()?

optional key(index): string | null

Defined in: src/Mnemonic/types.ts:929

Returns the key at the specified index in storage.

Optional method for enumeration support.

Parameters

Parameter	Type	Description
index	number	The numeric index

Returns

string | null

The key at the given index, or null if out of bounds

---

removeItem()

removeItem(key): void

Defined in: src/Mnemonic/types.ts:919

Removes a key-value pair from storage.

Parameters

Parameter	Type	Description
key	string	The storage key to remove

Returns

void

Remarks

Must complete synchronously. Returning a Promise is unsupported.

---

setItem()

setItem(key, value): void

Defined in: src/Mnemonic/types.ts:910

Stores a key-value pair.

Parameters

Parameter	Type	Description
key	string	The storage key
value	string	The string value to store

Returns

void

Remarks

Must complete synchronously. Returning a Promise is unsupported.