js-bao-wss-client / StorageProvider
Interface: StorageProvider
Key-value storage backend used by the client for local persistence (caches, offline data). Implementations exist for IndexedDB (browser), SQLite (Node.js), and in-memory fallback; supply a custom implementation to control where the client persists data. All operations are namespaced by a store name, and init is called whenever the user context changes.
Methods
clear()
clear(
store):Promise<void>
Clear all entries in a store.
Parameters
store
string
Returns
Promise<void>
close()
close():
Promise<void>
Close the current storage connection.
Returns
Promise<void>
delete()
delete(
store,key):Promise<void>
Delete a key from a store.
Parameters
store
string
key
string
Returns
Promise<void>
get()
get<
T>(store,key):Promise<StorageRecord<T> |null>
Get a value by key from a store.
Type Parameters
T
T = unknown
Parameters
store
string
key
string
Returns
Promise<StorageRecord<T> | null>
has()
has(
store,key):Promise<boolean>
Check if a key exists in a store.
Parameters
store
string
key
string
Returns
Promise<boolean>
init()
init(
namespace):Promise<void>
Initialize the storage provider for a specific namespace. Called when user context changes (e.g., login/logout).
Parameters
namespace
string
Returns
Promise<void>
isReady()
isReady():
boolean
Check if the provider is ready for operations.
Returns
boolean
iterate()
iterate<
T>(store,callback):Promise<void>
Iterate over all entries in a store.
Type Parameters
T
T = unknown
Parameters
store
string
callback
(record) => void | Promise<void>
Returns
Promise<void>
keys()
keys(
store):Promise<string[]>
Get all keys in a store.
Parameters
store
string
Returns
Promise<string[]>
merge()?
optionalmerge<T>(store,key,patch,metadata?):Promise<void>
Shallow-merge patch into a stored record's value, in ONE ATOMIC operation: the read and the write must not be separable, so a writer that lands between them cannot be lost. A key with no stored record is created from patch alone (an upsert). A field patch names overwrites the stored one; every field it does not name is kept.
This is what lets a caller persist a DELTA rather than a whole row. The client's document-open path writes lastOpenedAt this way, so opening one document in one tab cannot regress a field another tab or a listing wrote.
Optional. Without it the client falls back to a read-merge-write, which it serializes against its OWN other writes to the same key — so it is safe against one client's concurrent writes, and nothing else: another process, another tab, or a second client sharing this provider can still lose an update between the two steps. A provider that may be reached from more than one of those should implement this with whatever its backend offers (for IndexedDB, one readwrite transaction containing both the get and the put; for SQLite, one BEGIN IMMEDIATE transaction).
Type Parameters
T
T = unknown
Parameters
store
string
key
string
patch
Partial<T> & Record<string, unknown>
metadata?
Record<string, unknown>
Returns
Promise<void>
put()
put<
T>(store,key,value,metadata?):Promise<void>
Put a value into a store.
Type Parameters
T
T = unknown
Parameters
store
string
key
string
value
T
metadata?
Record<string, unknown>
Returns
Promise<void>
putBatch()?
optionalputBatch<T>(store,records):Promise<void>
Put multiple values into a store in a single transaction. Reduces IDB transaction pressure compared to calling put() N times.
Type Parameters
T
T = unknown
Parameters
store
string
records
object[]
Returns
Promise<void>