DefineSyncWorkerOptions
Defined in: packages/client/src/worker/define-sync-worker.ts:114
Type Parameters
Section titled “Type Parameters”TRegistry
Section titled “TRegistry”TRegistry extends SyncTableRegistry
Properties
Section titled “Properties”batchEventUrl?
Section titled “batchEventUrl?”
optionalbatchEventUrl?:string
Defined in: packages/client/src/worker/define-sync-worker.ts:167
The Event lane’s ingestion endpoint (ADR-0053 decision 3). Omit it and the worker derives it from
batchWriteUrl (…/api/mutations → …/api/events). See createSyncClient’s batchEventUrl.
batchWriteUrl
Section titled “batchWriteUrl”batchWriteUrl:
string
Defined in: packages/client/src/worker/define-sync-worker.ts:154
build?
Section titled “build?”
optionalbuild?:PostgresBuild
Defined in: packages/client/src/worker/define-sync-worker.ts:143
The Postgres build this worker’s stores run on: the boot’s own mint, the provision mint and every spare
mint (never on the wire — code cannot cross it). Defaults to cBuild. Pass createCBuild({ assets }) to
boot over assets warmed in the worker. It must be the registry’s declared storage.build (default
"c", ADR-0063): a mismatch throws StorageBuildMismatchError before any store is touched. A store a
createStore factory returns is checked against its own pg.build the same way.
codec?
Section titled “codec?”
optionalcodec?:BridgeCodec
Defined in: packages/client/src/worker/define-sync-worker.ts:212
Injected codec (ADR-0032 S2 §1). Defaults to the v1 identity codec.
controlPlaneUrl
Section titled “controlPlaneUrl”controlPlaneUrl:
string
Defined in: packages/client/src/worker/define-sync-worker.ts:151
The pgxsinkit control plane — subscribe, token re-mint, convergence barrier (ADR-0055).
convergenceIntervalMs?
Section titled “convergenceIntervalMs?”
optionalconvergenceIntervalMs?:number
Defined in: packages/client/src/worker/define-sync-worker.ts:186
The worker’s own convergence cadence (ms) — the interval trigger FALLBACK only. Local writes
flush immediately via the event-driven requestPass seam and tab wake signals, so this
interval exists purely for retry/recovery sweeps; each idle pass still costs real worker CPU
(flush + reconcile queries). Default 15000.
createStore?
Section titled “createStore?”
optionalcreateStore?: (storePath,backendOverride?) =>Promise<PgwasmWithLive>
Defined in: packages/client/src/worker/define-sync-worker.ts:135
How the worker creates its raw pgwasm store (provision + fresh-attach paths). Defaults to
createPgwasmClient, which loads pgwasm’s own boot assets — in a browser worker those hit the
same-origin HTTP cache the tab’s login-screen warm already primed (ADR-0032 S3). Injected in tests.
Takes a plain store PATH (ADR-0036); the internal backendOverride is the test lane’s memory selection.
Parameters
Section titled “Parameters”storePath
Section titled “storePath”string
backendOverride?
Section titled “backendOverride?”"memory"
Returns
Section titled “Returns”Promise<PgwasmWithLive>
events?
Section titled “events?”
optionalevents?:EventLaneOptions
Defined in: packages/client/src/worker/define-sync-worker.ts:174
The Event lane’s client-level flush policy (ADR-0053): batch caps, the fallback interval, backoff, the acked ledger’s retention (ADR-0060), and per-Event-stream overrides. A worker-ENTRY option, never an attach option — flush cadence is one engine-wide policy, and the Outbox it drains is shared by every attached tab.
executionLimit?
Section titled “executionLimit?”
optionalexecutionLimit?:ExecutionLimitConfig
Defined in: packages/client/src/worker/define-sync-worker.ts:195
The opt-in engine-construction EXECUTION LIMIT (ADR-0049 D5), threaded into the ROUTER when this
SharedWorker lands in elected-worker placement (router-only mode). DISABLED by default (undefined /
absent maxDispatchMs) — no finite worst-case query duration exists, so an absent limit means the router
forwards no probe and queries run unbounded; enabling it is a deliberate consumer choice.
Elected placement ONLY: on SW-direct (shared-worker) the engine home is in-scope and there is no control
channel to probe, so an enabled value is rejected as unsupported before engine boot.
installGlobal?
Section titled “installGlobal?”
optionalinstallGlobal?:boolean
Defined in: packages/client/src/worker/define-sync-worker.ts:210
Injected transport binder. Defaults to auto-detecting the SharedWorker/dedicated-worker global scope.
liveQueries?
Section titled “liveQueries?”
optionalliveQueries?:object
Defined in: packages/client/src/worker/define-sync-worker.ts:258
Bounded zero-subscriber keep-alive for the live-query manager (ADR-0040 decision 4). When an entry’s last
subscriber leaves, a nonzero effective keep-alive retains its pgwasm registration + diff state for a grace
period so a matching resubscribe (e.g. a re-mounted route across tabs) reuses it verbatim — no ~400 ms
re-materialization. Bounded by explicit budgets; DEFAULTS OFF (defaultKeepAliveMs: 0 → tear a query
down the instant its last consumer leaves). The 0 default is justified: a retained entry STILL pays a
full SQL rerun + diff on every dependent write — pgwasm live queries cannot be paused — so retention
only pays off for a genuinely hot, re-mounted query, and the default keeps worker memory bounded with
no surprise standing SQL reruns.
defaultKeepAliveMs?
Section titled “defaultKeepAliveMs?”
optionaldefaultKeepAliveMs?:number
Baseline retention (ms) for a zero-subscriber entry; floored by each subscriber’s own hint. Default 0.
maxRetainedQueries?
Section titled “maxRetainedQueries?”
optionalmaxRetainedQueries?:number
Max simultaneously-retained (zero-subscriber) entries — LRU-evicted past this. Default 16.
maxRetainedRows?
Section titled “maxRetainedRows?”
optionalmaxRetainedRows?:number
Max total rows across all retained entries — LRU-evicted past this. Default 50_000.
loadStoreEngineModule?
Section titled “loadStoreEngineModule?”
optionalloadStoreEngineModule?:StoreEngineModuleLoader
Defined in: packages/client/src/worker/define-sync-worker.ts:149
How this scope imports a DECLARED store-engine module (ADR-0050 addendum 2026-09-08). Defaults to the
scope’s own dynamic import(); injected by a unit test that has no module to load. It is consulted
only when the store’s bound declaration carries storage.engine, and never for the built-in store.
maxMutationAttempts?
Section titled “maxMutationAttempts?”
optionalmaxMutationAttempts?:number
Defined in: packages/client/src/worker/define-sync-worker.ts:161
pgwasmInstance?
Section titled “pgwasmInstance?”
optionalpgwasmInstance?:PgwasmWithLive
Defined in: packages/client/src/worker/define-sync-worker.ts:221
A fully-provisioned pgwasm (forwarded to CreateSyncClientOptions.pgwasmInstance; caller owns schema).
precreatedPgwasm?
Section titled “precreatedPgwasm?”
optionalprecreatedPgwasm?:Promise<PgwasmWithLive>
Defined in: packages/client/src/worker/define-sync-worker.ts:219
A raw pgwasm the worker uses instead of creating its own (forwarded to createSyncClient’s
CreateSyncClientOptions.precreatedPgwasm) — the client still applies schema/reconcile. In a
browser worker the store is minted internally (storePath); this is the seam for a prepopulated store in
tests, and the future spare-worker claim (ADR-0032 decision 5).
prepareLocalDbAfterSchema?
Section titled “prepareLocalDbAfterSchema?”
optionalprepareLocalDbAfterSchema?: (pgwasm) =>Promise<void>
Defined in: packages/client/src/worker/define-sync-worker.ts:247
App-level schema prep run IN THE WORKER, against the engine’s own local store, AFTER the registry schema exec — forwarded verbatim to CreateSyncClientOptions.prepareLocalDbAfterSchema, same timing as the in-process client. Like prepareLocalDbBeforeSchema this is a worker-ENTRY option, never an attach option (the tab never sees it — functions cannot cross the bridge). Use it for app-level indexes, views, or migrations that depend on the registry’s local tables, which DO exist by the time this runs.
Runs on the storePath, precreatedPgwasm, and restore boots; SKIPPED entirely on the pgwasmInstance path (the caller owns schema/prepare/reconcile there).
Parameters
Section titled “Parameters”pgwasm
Section titled “pgwasm”PgwasmWithLive
Returns
Section titled “Returns”Promise<void>
prepareLocalDbBeforeSchema?
Section titled “prepareLocalDbBeforeSchema?”
optionalprepareLocalDbBeforeSchema?: (pgwasm) =>Promise<void>
Defined in: packages/client/src/worker/define-sync-worker.ts:236
App-level schema prep run IN THE WORKER, against the engine’s own local store, BEFORE the registry schema exec — forwarded verbatim to CreateSyncClientOptions.prepareLocalDbBeforeSchema, same timing as the in-process client. This is a worker-ENTRY option (baked into the worker file as code), NOT an attach option: the hook is a function and functions cannot cross the bridge, so a tab can never supply it — the worker owns it. Use it for DDL that must precede the registry’s local tables (extensions, a bespoke schema search_path). On a fresh store the registry-derived local tables do NOT yet exist when this runs (that ordering is what distinguishes it from prepareLocalDbAfterSchema).
Runs on the storePath, precreatedPgwasm, and restore boots; SKIPPED entirely on the pgwasmInstance path (the caller owns schema/prepare/reconcile there). On a restore boot it still runs, but the store already carries the registry tables from the backup’s datadir, so the “tables absent” invariant does not hold there.
Parameters
Section titled “Parameters”pgwasm
Section titled “pgwasm”PgwasmWithLive
Returns
Section titled “Returns”Promise<void>
provisionAdoptionBudgetMs?
Section titled “provisionAdoptionBudgetMs?”
optionalprovisionAdoptionBudgetMs?:number
Defined in: packages/client/src/worker/define-sync-worker.ts:208
How long an attach may wait for the engine’s IN-FLIGHT spare provision (ADR-0032 decision 5) before it
fails typed with ProvisionStalledError instead of waiting. Measured from the provision attempt’s
START, not from the attach — a tab attaching late inherits however much of the budget the spare has
already burned. The stalled attempt is LEFT RUNNING (an in-flight OPFS/IDB store open cannot be safely
abandoned — a second open against the same store is an ownership conflict), so a later attach still
ADOPTS it if it completes; refusing costs at most one extra initdb, never data (the spare is schemaless
and holds no writes). Default 20000. Number.POSITIVE_INFINITY restores the unbounded wait (NOT
recommended: a stalled spare then hangs every attach forever). Must be > 0 — anything else throws at
construction. This bounds the ACCELERATOR only; nothing is inferred from it about engine liveness
(ADR-0049 D5’s refusal of timing-based engine-death detection is unchanged).
registry
Section titled “registry”registry:
TRegistry
Defined in: packages/client/src/worker/define-sync-worker.ts:120
The sync registry — imported as CODE by the worker file, never cloned into it (ADR-0032 decision 4). When resolveRegistry is also given this is the DEFAULT (used when the attach carries no role or an unknown one).
requestHeaders?
Section titled “requestHeaders?”
optionalrequestHeaders?:Record<string,string>
Defined in: packages/client/src/worker/define-sync-worker.ts:156
Static headers on every read + write request (e.g. a gateway apikey). See createSyncClient.
resolveRegistry?
Section titled “resolveRegistry?”
optionalresolveRegistry?: (role) =>TRegistry|undefined
Defined in: packages/client/src/worker/define-sync-worker.ts:128
Resolve the registry to boot from the attach’s config.role (ADR-0032 S3). A single worker file can
bake BOTH role variants (e.g. the board’s admin/member registries — same TS shape, different write
capability) and pick per-attach, which the spare flow needs: the spare is provisioned role-agnostic
(before the user is known) and the role is only settled at claim/attach. Returns undefined to fall
back to registry.
Parameters
Section titled “Parameters”string | undefined
Returns
Section titled “Returns”TRegistry | undefined
storePath?
Section titled “storePath?”
optionalstorePath?:string
Defined in: packages/client/src/worker/define-sync-worker.ts:160
Default plain store PATH (ADR-0036) if the first attach carries none — a name, not a storage URL.
streamBaseUrl
Section titled “streamBaseUrl”streamBaseUrl:
string
Defined in: packages/client/src/worker/define-sync-worker.ts:153
The edge that serves durable-streams reads.
syncEnabled?
Section titled “syncEnabled?”
optionalsyncEnabled?:boolean
Defined in: packages/client/src/worker/define-sync-worker.ts:162
tokenExpiryMarginMs?
Section titled “tokenExpiryMarginMs?”
optionaltokenExpiryMarginMs?:number
Defined in: packages/client/src/worker/define-sync-worker.ts:179
How close to expiry (ms) a cached token may be before a read/write that needs it triggers a pull broadcast (ADR-0032 decision 3). Default 30s — comfortably ahead of a long-poll cycle.
writeRequestHeaders?
Section titled “writeRequestHeaders?”
optionalwriteRequestHeaders?:Record<string,string>
Defined in: packages/client/src/worker/define-sync-worker.ts:158
Write-only headers merged over requestHeaders (e.g. region/DB-affinity). See createSyncClient.