JavaScript: Sync

sync() pushes the outbox, drives queued attachment uploads when attachments are configured and the outbox is empty, vacuums orphaned attachments once the push has drained, then pulls until the checkpoint closes. It reaches no wire while the connectivity port reports no network, so a call made offline returns without an attempt. The app client already runs this cycle on its own, so a call is for a Sync now button, a pull-to-refresh gesture, or a test that waits for the round trip.

Examples#

Basic#

// src/todo-list.ts
import { kizunasync } from './kizunasync'

await kizunasync.sync()

A Sync now button#

// src/sync-button.ts
import { kizunasync } from './kizunasync'

document.querySelector('#sync-now')?.addEventListener('click', () => {
  kizunasync.sync().catch((error: unknown) => {
    console.warn('Sync failed, and the automatic loop will try again', error)
  })
})

Parameters#

These options are set once on createSupabaseKizunaSync or createKizunaSync; see Initializing.

Options that shape every run#

Returns#

Promise<void> that settles once this call's own push then pull cycle completes. Each sync() call reaches the engine and runs a full cycle of its own; only the scheduler's automatic ticks coalesce into one queued run.

What a run changes#

Events, and what raises them#

Errors#

Retryable failures keep the queued mutations in the outbox for the next run, and AUTH_SESSION_MISSING, AUTH_SESSION_TIMEOUT, the request deadline (30 seconds by default, requestTimeoutMs), PGRST301, and 42501 are all retryable. Only a failure the remote marks permanent counts against the dead-letter budget: SQLSTATE classes 22, 23, and 42 other than 42501, plus exact P0001 and 0A000. A permanent failure is charged only to the slice it names: a lone unbatched write, or an atomic batch, since a request of either shape can own no failure but its own. The fifth consecutive charge against the same head dead-letters it, reverts its optimistic rows to the pre-image, and records a DEAD_LETTER rejection with reason PERMANENT_TRANSPORT; the server's size refusal (KZP02) on an atomic batch dead-letters it on the first charge, with the server's own message, because the batch can never be split to fit. A permanent failure of an unbatched run of several writes names none of them individually, so it charges nothing: the next attempt sends a shorter run instead, halved when the server named the size (KZP02) or cut to the head alone otherwise, until a run of one owns its own failure.

A run also raises whatever the half it is driving raises. UNKNOWN_SIGNAL, MALFORMED_PUSH_RESPONSE, VERDICT_BIJECTION, UNKNOWN_BATCH_OFFENDER, UNKNOWN_VERDICT_REASON, and UNKNOWN_OP mean the exchange broke the wire contract, and they fail loudly rather than counting against the dead-letter budget. Pull once and Push once state the condition behind each one.

The first call that needs the engine opens it. When that open fails, on this call or an earlier one, sync() rejects with the open's typed error, such as ENGINE_UNAVAILABLE in Expo Go or STORE_BUSY, and every later async call on the client rejects with that same error, because nothing opens the engine a second time. Sync health reports the same failure without throwing.

Notes#

The app client syncs by itself, so most apps never call this method. The automatic loop makes its first attempt when the client is first used, then runs again after every local write, on a jittered poll (15 seconds by default), when the network comes back, when the app returns to the foreground, and when the Realtime doorbell rings. A burst of writes or signals collapses into one attempt scheduled 250 milliseconds out. A write applies locally and waits in the outbox until a run delivers it, which is the path Offline writes describes, and the loop reports its phase, failure streak, and last error through Sync health.

Call this method when you want the round trip now and want to know when it finished. Use pullOnce and pushOnce only when you need one half of the cycle.

attachments.vacuum() runs on its own after every successful push, so an object orphaned by that run's writes is collected without a separate call. Nothing else about attachments happens inside sync(): a download stays lazy, fetched only when resolveDownload asks for it.

Related reference#

• Pull once
• Push once
• Outbox depth
• Sync health
• Swift: Sync
• Kotlin: Sync