SyncState

Defined in: packages/@livestore/common/dist/sync/syncstate.d.ts:92

SyncState represents the current sync state of a sync node relative to an upstream node. Events flow from local to upstream, with each state maintaining its own event head.

Example:

                +------------------------+
                |     PENDING EVENTS     |
                +------------------------+
              ▼                       ▼
       Upstream Head             Local Head
             e1        e1.1, e1.2, e2

Pending Events: Events awaiting acknowledgment from the upstream.

• Can be confirmed or rejected by the upstream.
• Subject to rebase if rejected.

Payloads:

• PayloadUpstreamRebase: Upstream has performed a rebase, so downstream must roll back to the specified event and rebase the pending events on top of the new events.
• PayloadUpstreamAdvance: Upstream has advanced, so downstream must rebase the pending events on top of the new events.
• PayloadLocalPush: Local push payload

Invariants:

1. Chain Continuity: Each event must reference its immediate parent.
2. Head Ordering: Upstream Head ≤ Local Head.
3. Event number sequence: Must follow the pattern e1→e1.1→e1.2→e2.

A few further notes to help form an intuition:

• The goal is to keep the pending events as small as possible (i.e. to have synced with the next upstream node)
• There are 2 cases for rebasing:
  • The conflicting event only conflicts with the pending events -> only (some of) the pending events need to be rolled back

The merge function processes updates to the sync state based on incoming payloads, handling cases such as upstream rebase, advance and local push.

Extends

• SyncState_base

Constructors

Constructor

new SyncState(props, options?): SyncState

Defined in: .pnpm-home/store/v11/links/@/effect/3.21.0/5f824b960b722ac9cc27ad83fe3b2945d775b034a0e1eb327a0ff67a4a7c6da7/node_modules/effect/dist/dts/Schema.d.ts:4266

Parameters

props

localHead

{ client: number & Brand<"ClientEventSequenceNumber">; global: number & Brand<"GlobalEventSequenceNumber">; rebaseGeneration: number; }

localHead.client

number & Brand<"ClientEventSequenceNumber">

localHead.global

number & Brand<"GlobalEventSequenceNumber">

localHead.rebaseGeneration

number

pending

readonly EncodedWithMeta[]

upstreamHead

{ client: number & Brand<"ClientEventSequenceNumber">; global: number & Brand<"GlobalEventSequenceNumber">; rebaseGeneration: number; }

upstreamHead.client

number & Brand<"ClientEventSequenceNumber">

upstreamHead.global

number & Brand<"GlobalEventSequenceNumber">

upstreamHead.rebaseGeneration

number

options?

MakeOptions

Returns

SyncState

Inherited from

SyncState_base.constructor

Properties

localHead

readonly localHead: object

Defined in: packages/@livestore/common/dist/sync/syncstate.d.ts:15

Equivalent to pending.at(-1)?.id if there are pending events

client

readonly client: number & Brand<"ClientEventSequenceNumber">

global

readonly global: number & Brand<"GlobalEventSequenceNumber">

rebaseGeneration

readonly rebaseGeneration: number

Inherited from

SyncState_base.localHead

---

pending

readonly pending: readonly EncodedWithMeta[]

Defined in: packages/@livestore/common/dist/sync/syncstate.d.ts:5

Inherited from

SyncState_base.pending

---

toJSON()

toJSON: () => any

Defined in: packages/@livestore/common/dist/sync/syncstate.d.ts:93

Returns

any

---

upstreamHead

readonly upstreamHead: object

Defined in: packages/@livestore/common/dist/sync/syncstate.d.ts:7

What this node expects the next upstream node to have as its own local head

client

readonly client: number & Brand<"ClientEventSequenceNumber">

global

readonly global: number & Brand<"GlobalEventSequenceNumber">

rebaseGeneration

readonly rebaseGeneration: number

Inherited from

SyncState_base.upstreamHead