Interface: PlasmaClient<S, M>
Interface: PlasmaClient<S, M>
Section titled “Interface: PlasmaClient<S, M>”Defined in: client/src/sync/client.ts:422
Type Parameters
Section titled “Type Parameters”S extends Schema<Record<string, AnyTable>>
M
Properties
Section titled “Properties”
readonlydb:Db<S>
Defined in: client/src/sync/client.ts:423
userActionRequired
Section titled “userActionRequired”
readonlyuserActionRequired:boolean
Defined in: client/src/sync/client.ts:424
Methods
Section titled “Methods”mutate()
Section titled “mutate()”mutate<
K>(name,args):Promise<void>
Defined in: client/src/sync/client.ts:426
Enqueue and locally apply a mutation. Push is triggered automatically.
Type Parameters
Section titled “Type Parameters”K extends string
Parameters
Section titled “Parameters”K
MutatorArgs<M, K>
Returns
Section titled “Returns”Promise<void>
newId()
Section titled “newId()”newId():
string
Defined in: client/src/sync/client.ts:433
Generate a fresh id suitable for passing into a mutator’s args.id.
Optimistic + canonical runs must agree on the id — the mutator itself
only sees args, so ids MUST be produced at the call site (here) and
threaded through. Uses crypto.randomUUID().
Returns
Section titled “Returns”string
pullOnce()
Section titled “pullOnce()”pullOnce():
Promise<void>
Defined in: client/src/sync/client.ts:435
Force a pull now; resolves when the patch has been applied locally.
Returns
Section titled “Returns”Promise<void>
pushOnce()
Section titled “pushOnce()”pushOnce():
Promise<void>
Defined in: client/src/sync/client.ts:437
Force a push of the current outbox now.
Returns
Section titled “Returns”Promise<void>
start()
Section titled “start()”start():
void
Defined in: client/src/sync/client.ts:439
Begin the background poll loop.
Returns
Section titled “Returns”void
stop()
Section titled “stop()”stop():
void
Defined in: client/src/sync/client.ts:441
Stop the background poll loop.
Returns
Section titled “Returns”void
flush()
Section titled “flush()”flush():
Promise<void>
Defined in: client/src/sync/client.ts:443
Await this before shutdown to make sure buffered writes have flushed.
Returns
Section titled “Returns”Promise<void>
getOutboxDepth()
Section titled “getOutboxDepth()”getOutboxDepth():
Promise<number>
Defined in: client/src/sync/client.ts:449
Read the current number of un-confirmed mutations in the outbox. Useful for a “N unsaved changes” UI hint or a shutdown gate. Reads IDB, so treat as async — expect single-digit-ms latency.
Returns
Section titled “Returns”Promise<number>
getPendingResetDiagnostics()
Section titled “getPendingResetDiagnostics()”getPendingResetDiagnostics():
Promise<PendingResetDiagnostics>
Defined in: client/src/sync/client.ts:450
Returns
Section titled “Returns”Promise<PendingResetDiagnostics>
resetLocalState()
Section titled “resetLocalState()”resetLocalState():
Promise<void>
Defined in: client/src/sync/client.ts:464
Clear every locally-cached row + the pull cookie + the outbox + every
blob-related store so the client re-hydrates from the server on its
next pull. Used by onSchemaMismatch returning "reset" and callable
directly for user-initiated resets. The clientID is deliberately
rotated during reset — keeping the old id would leave the server’s
last_mutation_id watermark at N, so every re-numbered post-reset
mutation (1..N) would silently drop as a duplicate. The
clientGroupID is untouched.
Throws when PlasmaClientOptions.offline is true — the offline outbox
is unrecoverable without a server to re-hydrate from.
Returns
Section titled “Returns”Promise<void>
readFile()
Section titled “readFile()”readFile(
ref,options?):Promise<PlasmaFileReadResult>
Defined in: client/src/sync/client.ts:472
Read the bytes for a FileRef — either from local IndexedDB cache
(upload-in-flight or previously fetched) or from the sync API,
caching the result on the way through. BrokenFileRef sentinels
decode to { status: "missing" } so a corrupt manifest cell never
throws at the call site.
Parameters
Section titled “Parameters”FileRef | BrokenFileRef
options?
Section titled “options?”signal?
Section titled “signal?”AbortSignal
Returns
Section titled “Returns”Promise<PlasmaFileReadResult>
retryBlobUpload()
Section titled “retryBlobUpload()”retryBlobUpload(
hash):Promise<void>
Defined in: client/src/sync/client.ts:482
Reset a failed blob upload back to queued and nudge the upload
worker. Intended for a UI “Retry” affordance after the user has
addressed whatever produced the permanent failure (regained
connectivity, freed R2 quota, resigned auth, …).
Parameters
Section titled “Parameters”string
Returns
Section titled “Returns”Promise<void>
discardMutation()
Section titled “discardMutation()”discardMutation(
mutationID):Promise<void>
Defined in: client/src/sync/client.ts:491
Abandon a queued mutation. Removes it from the outbox and drops its
blob dependency mapping. Local bytes in _plasma_blobs_local are
kept — they are content-addressed and may be shared with other
mutations. The mutation’s local optimistic effect is not reverted
here; call pullOnce() afterwards to let the server’s canonical
state overwrite it.
Parameters
Section titled “Parameters”mutationID
Section titled “mutationID”number
Returns
Section titled “Returns”Promise<void>