Skip to content
plasma

@sh1n4ps/plasma-client

@sh1n4ps/plasma-client is the browser-side runtime. It uses IndexedDB as its storage layer, the same @sh1n4ps/plasma-core DSL for queries, and maintains its own outbox + sync loop.

createPlasmaClient(options) — every option

Section titled “createPlasmaClient(options) — every option”

Complete PlasmaClientOptions field list with defaults:

Required

Section titled “Required”
Option What
schema The isomorphic schema created via defineSchema({...})
mutators The registry created via defineMutators<S, Ctx>()({...})
dbName Local IDB database name (unique per app / tenant)
endpoint Server sync base URL. Resolved against location.origin in the browser; must be absolute in Node/Workers. Required even with offline: true (never fetched)
schemaVersion Must match SyncHandlerOptions.schemaVersion on the server. Mismatch triggers a 409 handshake. See Migrations
clientGroupID Logical installation identifier — usually the user ID. All tabs of the same user share this. See clientID vs clientGroupID
getContext () => Promise<Ctx> | Ctx — called before every mutator invocation. Provides ctx for the mutator body

Sync loop / transport

Section titled “Sync loop / transport”
Option Default What
pollIntervalMs 5000 Milliseconds between pull polls
retry { maxAttempts: 5, initialDelayMs: 500, maxDelayMs: 30_000 } Retry policy for push/pull HTTP failures (5xx, 429, network). Set maxAttempts: 1 to disable
pullPageSize (server default) If set, pull sends ?limit=N and follows the hasMore chain until drained. Use to bound memory on large initial hydration
authHeaders — async () => ({ authorization: "Bearer ..." }) — called on every push/pull. Ideal for refreshed-token auth
fetcher globalThis.fetch Override fetch — testing use, or to route through a service worker
subscribe — Optional realtime nudge: (onPoke) => () => void. Pair with createWebSocketSubscription({...}). See Presence
onError — (err: SyncClientError) => void — observability hook. See Sync errors
onSchemaMismatch "stay" ({ phase }) => "reset" | "stay" — how to handle a 409 mismatch. "reset" wipes local state + rotates clientID

Blob / file

Section titled “Blob / file”
Option Default What
blobUploadRetry { maxAttempts: 5, initialDelayMs: 500, maxDelayMs: 30_000 } Retry policy specifically for R2 PUT uploads. Independent of retry. See Files and Blobs

Encryption

Section titled “Encryption”
Option Default What
encryption — { dek: Uint8Array, keyId: string }. Enables transparent at-rest encryption for columns marked with .encrypted(). See Encryption

Offline

Section titled “Offline”
Option Default What
offline false Skip the sync loop entirely (native / desktop / air-gapped). start() / pushOnce() / pullOnce() become no-ops. Outbox still accumulates. See Offline mode

PlasmaClient — every method

Section titled “PlasmaClient — every method”
Method Description
start() Opens the poll timer, WebSocket subscription (if subscribe was supplied), and blob upload worker. Idempotent
stop() Tears down poll timer + WebSocket + upload worker. Outbox writes still happen; they just don’t sync
flush(): Promise<void> Awaits until buffered outbox writes have made a best-effort push. Call before unload for graceful shutdown
getOutboxDepth(): Promise<number> Number of un-confirmed mutations waiting in the outbox. 0 means everything you’ve done is durable on the server. Reads IDB — single-digit-ms
mutate(name, args): Promise<void> Invoke a mutator: optimistic IDB apply + outbox enqueue + return. Rejects if the mutator body throws locally
pushOnce(): Promise<void> Manual push trigger. Useful in beforeunload (flush pending writes) or after batched updates
pullOnce(): Promise<void> Manual pull trigger. Useful on window focus (freshen state after user returns)
readFile(ref) Resolves a FileRef to PlasmaFileReadResult — bytes from local cache or via /sync/blob/*
retryBlobUpload(hash) Re-queue a failed R2 upload with a fresh attempt budget
discardMutation(mutationID) Drop a queued outbox entry. Optimistic view reverts on next rebase
resetLocalState() Wipe all IDB stores, cookie, outbox. Rotates clientID. Throws in offline mode
newId(): string Fresh UUID string, for use as the caller-supplied primary key
db The Db<Schema> builder — db.select().from(...) etc.

Symbol overview

Section titled “Symbol overview”
  • Client factory — createPlasmaClient, PlasmaClient<S, M>, PlasmaClientOptions
  • Engine — createIdbEngine, IdbEngine, IdbEngineOptions (accepts its own encryption for standalone use)
  • IVM — classifyIvm, IvmKind, IvmLiveQueryLike, RowChange, RowDelta, isIvmEligible
  • File uploads — FileInput (File | Blob | FileRef, NOT Uint8Array/ArrayBuffer), ClientArg, PlasmaFileReadResult
  • WebSocket transport — createWebSocketSubscription, WebSocketSubscriptionOptions (see Presence for full option set)
  • Error hook — SyncClientError — 6 kinds: push-http, pull-http, network, rebase-replay, schema-mismatch, blob-upload-failed. See Sync errors

When to reach for the manual controls

Section titled “When to reach for the manual controls”
  • beforeunload handler: await client.flush() — best-effort to push pending writes before tab close
  • Window focus event: client.pullOnce() — freshen state faster than the poll interval
  • After a batched admin script: client.pushOnce() — kick the sync loop instead of waiting
  • User signs out: client.stop() + client.resetLocalState() (both awaited)
  • User signs in as a different account: Reconstruct the client with the new clientGroupID

Full symbol index

Section titled “Full symbol index”

Under reference/generated/plasma-client/src.

Where to go from here

Section titled “Where to go from here”