Class: StackSyncHandle

Defined in: packages/client/src/core/sync/index.ts:315

One stack's replication: its lifecycle, its filter, and its convergence state.

Created by ClientStack.sync - construct it through the stack rather than directly, so the stack can cancel it when it closes.

Dispatches DOM events, matching the rest of DocStack: "status" on every state change (detail is a SyncStatus), plus "change", "active", "idle", "denied", "error" and "complete".

Example

const sync = await stack.sync({ remote: () => driveDb });

sync.addEventListener("status", (event) => {
    const status = (event as CustomEvent<SyncStatus>).detail;
    ui.setSyncBadge(status.state, status.lastConvergedAt);
});

await sync.waitForConvergence();

Extends

• EventTarget

Methods

cancel()

cancel(): void;

Defined in: packages/client/src/core/sync/index.ts:400

Stops replicating and releases the changes-feed listeners.

Idempotent. Called for every live handle when the stack closes.

Returns

void

---

getRemote()

getRemote(): Database<{
}>;

Defined in: packages/client/src/core/sync/index.ts:351

The resolved remote, once start has run.

Returns

Database<{ }>

---

getStatus()

getStatus(): SyncStatus;

Defined in: packages/client/src/core/sync/index.ts:346

The current reading. Safe to call at any time; returns a copy.

Returns

SyncStatus

---

restart()

restart(): Promise<StackSyncHandle>;

Defined in: packages/client/src/core/sync/index.ts:425

Cancels and starts again, re-resolving the remote.

This is the call to make when a credential is refreshed: a RemoteResolver function runs again, so the new replication is built on the new token while the counters and lastConvergedAt this handle has accumulated stay put.

Returns

Promise<StackSyncHandle>

This handle, once replication is running again.

---

start()

start(): Promise<StackSyncHandle>;

Defined in: packages/client/src/core/sync/index.ts:362

Resolves the remote, runs the schema gate and starts replicating.

Returns

Promise<StackSyncHandle>

This handle, once replication is running. Rejects if the remote cannot be resolved or the gate refuses; the handle is left "error" in that case.

Throws

When the remote is ahead of this device.

---

waitForConvergence()

waitForConvergence(timeoutMs): Promise<SyncStatus>;

Defined in: packages/client/src/core/sync/index.ts:437

Resolves the next time the replica converges.

Parameters

Parameter	Type	Default value	Description
timeoutMs	number	30000	How long to wait before rejecting. Defaults to 30 seconds; pass 0 to wait indefinitely.

Returns

Promise<SyncStatus>

The status at the moment of convergence.