Interface: PlasmaClientOptions<S, TCtx, M>

Interface: PlasmaClientOptions<S, TCtx, M>

Defined in: client/src/sync/client.ts:116

Type Parameters

S

S extends Schema<Record<string, AnyTable>>

TCtx

TCtx

M

M extends AnyMutators<S, TCtx>

Properties

schema

readonly schema: S

Defined in: client/src/sync/client.ts:121

---

dbName

readonly dbName: string

Defined in: client/src/sync/client.ts:122

---

endpoint

readonly endpoint: string

Defined in: client/src/sync/client.ts:124

Base URL for the sync endpoints, e.g. “https://api.example.com/sync”.

---

schemaVersion

readonly schemaVersion: string

Defined in: client/src/sync/client.ts:125

---

clientGroupID

readonly clientGroupID: string

Defined in: client/src/sync/client.ts:127

Durable per-installation identifier (persist this in the app’s own settings).

---

mutators

readonly mutators: M

Defined in: client/src/sync/client.ts:132

The isomorphic mutators. Same record shape as the server side; users typically define them once and import from both.

---

getContext

readonly getContext: () => TCtx | Promise<TCtx>

Defined in: client/src/sync/client.ts:138

Called before every locally-executed mutation to obtain the ctx that the mutator receives. Kept as a getter (not a constant) so identity changes (e.g. user logs out) reflect without recreating the client.

Returns

TCtx | Promise<TCtx>

---

pollIntervalMs?

readonly optional pollIntervalMs?: number

Defined in: client/src/sync/client.ts:140

Milliseconds between poll pulls. Defaults to 5000.

---

authHeaders?

readonly optional authHeaders?: () => Record<string, string> | Promise<Record<string, string>>

Defined in: client/src/sync/client.ts:142

Optional headers to attach to every push / pull request.

Returns

Record<string, string> | Promise<Record<string, string>>

---

fetcher?

readonly optional fetcher?: (request) => Promise<Response>

Defined in: client/src/sync/client.ts:144

Override the global fetch — used in tests to route to an in-process handler.

Parameters

request

Request

Returns

Promise<Response>

---

subscribe?

readonly optional subscribe?: (onPoke) => () => void

Defined in: client/src/sync/client.ts:155

Optional realtime nudge. start() invokes this once and expects the caller to fire onPoke() whenever the server has news. Return an unsubscribe function so stop() can tear the transport down.

The canonical transport is a WebSocket connected to the plasma SyncCoordinator Durable Object; use createWebSocketSubscription from @sh1n4ps/plasma-client for the standard implementation. The polling fallback continues to run so a dropped connection still catches up.

Parameters

onPoke

() => void

Returns

() => void

---

onError?

readonly optional onError?: (event) => void

Defined in: client/src/sync/client.ts:162

Observability sink for the sync loop. Called with a discriminated SyncClientError when a push / pull / rebase step fails so callers can surface a toast or forward to Sentry. The client keeps retrying on the next tick — this hook does not affect control flow.

Parameters

event

SyncClientError

Returns

void

---

retry?

readonly optional retry?: { maxAttempts?: number; initialDelayMs?: number; maxDelayMs?: number; }

Defined in: client/src/sync/client.ts:169

Retry policy for push / pull HTTP failures. The client retries on network errors, 5xx, and 429 with exponential backoff + jitter. Default: 5 attempts starting at 500 ms, doubling to a cap of 30 s. Set maxAttempts to 1 to disable retries.

maxAttempts?

readonly optional maxAttempts?: number

initialDelayMs?

readonly optional initialDelayMs?: number

maxDelayMs?

readonly optional maxDelayMs?: number

---

blobUploadRetry?

readonly optional blobUploadRetry?: { maxAttempts?: number; initialDelayMs?: number; maxDelayMs?: number; }

Defined in: client/src/sync/client.ts:183

Retry policy for blob PUT uploads. Independent from retry so a caller can be aggressive about push / pull retries while giving uploads a longer runway (large file, unstable link). Defaults: 5 attempts, initial 500ms, max 30s — same shape as retry but a different budget. Explicit override:

blobUploadRetry: { maxAttempts: 8, initialDelayMs: 1_000 }

maxAttempts?

readonly optional maxAttempts?: number

initialDelayMs?

readonly optional initialDelayMs?: number

maxDelayMs?

readonly optional maxDelayMs?: number

---

pullPageSize?

readonly optional pullPageSize?: number

Defined in: client/src/sync/client.ts:194

When set, pull requests carry ?limit=N so the server returns at most N change records per response. The client chains follow-up pulls until the server signals hasMore: false. Use this to bound memory on the initial hydration of a huge table.

---

encryption?

readonly optional encryption?: { dek: Uint8Array; keyId: string; }

Defined in: client/src/sync/client.ts:203

End-to-end encryption keys. When present, columns declared with .encrypted() in the schema are automatically transparent-encrypted on their way to the server (via a helper the caller applies inside mutators) and transparent-decrypted on pull before landing in IDB. The DEK must be 32+ bytes of high-entropy material. The caller manages storage / rotation of the key.

dek

readonly dek: Uint8Array

keyId

readonly keyId: string

---

onSchemaMismatch?

readonly optional onSchemaMismatch?: (info) => "reset" | "stay" | Promise<"reset" | "stay">

Defined in: client/src/sync/client.ts:214

Handler invoked when the server responds with 409 schema-mismatch. Return "reset" to have plasma wipe the local base + optimistic stores and start over on the next pull (typical for prompt-and-reload apps); return "stay" to leave the local IDB alone and just surface the mismatch through onError. Omitted → "stay".

Parameters

info

phase

"push" | "pull"

Returns

"reset" | "stay" | Promise<"reset" | "stay">

---

offline?

readonly optional offline?: boolean

Defined in: client/src/sync/client.ts:238

Offline-only mode (native / desktop apps, tests, air-gapped environments). When true the client:

• Skips the sync loop entirely — start() does not open a poll interval / online listener / websocket subscription, and pushOnce() / pullOnce() become no-ops.
• Runs mutations locally through the IndexedDB engine only. The outbox still accumulates envelopes so PlasmaClientOptions.offline can be flipped back to false later without losing history.
• Serves readFile(ref) from _plasma_blobs_local only, returning { status: "missing" } when the bytes are absent.
• Fires no upload workers, no blob PUT retries, and no SyncClientError.blob-upload-failed events.

Ideal for React-Native / Tauri / Electron shells that build on plasma’s reactive query DSL but never talk to a plasma sync server. endpoint is still required (dummy value is fine — it is never fetched); flip offline back to false at runtime by reconstructing the client with the same dbName.