DefineSyncWorkerOptions
Defined in: packages/client/src/worker/define-sync-worker.ts:115
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:151
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:138
codec?
Section titled “codec?”
optionalcodec?:BridgeCodec
Defined in: packages/client/src/worker/define-sync-worker.ts:182
Injected codec (ADR-0032 S2 §1). Defaults to the v1 identity codec.
convergenceIntervalMs?
Section titled “convergenceIntervalMs?”
optionalconvergenceIntervalMs?:number
Defined in: packages/client/src/worker/define-sync-worker.ts:169
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.
createPglite?
Section titled “createPglite?”
optionalcreatePglite?: (storePath,backendOverride?) =>Promise<ClientPGlite>
Defined in: packages/client/src/worker/define-sync-worker.ts:136
How the worker creates its raw PGlite store (provision + fresh-attach paths). Defaults to
createClientPGlite, which loads PGlite’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<ClientPGlite>
electricUrl
Section titled “electricUrl”electricUrl:
string
Defined in: packages/client/src/worker/define-sync-worker.ts:137
events?
Section titled “events?”
optionalevents?:EventLaneOptions
Defined in: packages/client/src/worker/define-sync-worker.ts:157
The Event lane’s client-level flush policy (ADR-0053): batch caps, the fallback interval, backoff, 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:178
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:180
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:228
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 PGlite 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 — PGlite 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.
maxMutationAttempts?
Section titled “maxMutationAttempts?”
optionalmaxMutationAttempts?:number
Defined in: packages/client/src/worker/define-sync-worker.ts:145
pgliteInstance?
Section titled “pgliteInstance?”
optionalpgliteInstance?:ClientPGlite
Defined in: packages/client/src/worker/define-sync-worker.ts:191
A fully-provisioned PGlite (forwarded to CreateSyncClientOptions.pgliteInstance; caller owns schema).
precreatedPglite?
Section titled “precreatedPglite?”
optionalprecreatedPglite?:Promise<ClientPGlite>
Defined in: packages/client/src/worker/define-sync-worker.ts:189
A raw PGlite the worker uses instead of creating its own (forwarded to createSyncClient’s
CreateSyncClientOptions.precreatedPglite) — 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?: (pglite) =>Promise<void>
Defined in: packages/client/src/worker/define-sync-worker.ts:217
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, precreatedPglite, and restore boots; SKIPPED entirely on the pgliteInstance path (the caller owns schema/prepare/reconcile there).
Parameters
Section titled “Parameters”pglite
Section titled “pglite”Returns
Section titled “Returns”Promise<void>
prepareLocalDbBeforeSchema?
Section titled “prepareLocalDbBeforeSchema?”
optionalprepareLocalDbBeforeSchema?: (pglite) =>Promise<void>
Defined in: packages/client/src/worker/define-sync-worker.ts:206
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, precreatedPglite, and restore boots; SKIPPED entirely on the pgliteInstance 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”pglite
Section titled “pglite”Returns
Section titled “Returns”Promise<void>
registry
Section titled “registry”registry:
TRegistry
Defined in: packages/client/src/worker/define-sync-worker.ts:121
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:140
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:129
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:144
Default plain store PATH (ADR-0036) if the first attach carries none — a name, not a storage URL.
syncEnabled?
Section titled “syncEnabled?”
optionalsyncEnabled?:boolean
Defined in: packages/client/src/worker/define-sync-worker.ts:146
tokenExpiryMarginMs?
Section titled “tokenExpiryMarginMs?”
optionaltokenExpiryMarginMs?:number
Defined in: packages/client/src/worker/define-sync-worker.ts:162
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:142
Write-only headers merged over requestHeaders (e.g. region/DB-affinity). See createSyncClient.