@livestore/common 0.3.0-dev.46 → 0.3.0-dev.48

package/src/sync/syncstate.ts

@@ -2,7 +2,7 @@ import { casesHandled, LS_DEV, shouldNeverHappen } from '@livestore/utils'
 import { Match, ReadonlyArray, Schema } from '@livestore/utils/effect'
 
 import { UnexpectedError } from '../adapter-types.js'
-import * as EventId from '../schema/EventId.js'
+import * as EventSequenceNumber from '../schema/EventSequenceNumber.js'
 import * as LiveStoreEvent from '../schema/LiveStoreEvent.js'
 
 /**
@@ -45,14 +45,14 @@ import * as LiveStoreEvent from '../schema/LiveStoreEvent.js'
 export class SyncState extends Schema.Class<SyncState>('SyncState')({
   pending: Schema.Array(LiveStoreEvent.EncodedWithMeta),
   /** What this node expects the next upstream node to have as its own local head */
-  upstreamHead: EventId.EventId,
+  upstreamHead: EventSequenceNumber.EventSequenceNumber,
   /** Equivalent to `pending.at(-1)?.id` if there are pending events */
-  localHead: EventId.EventId,
+  localHead: EventSequenceNumber.EventSequenceNumber,
 }) {
   toJSON = (): any => ({
     pending: this.pending.map((e) => e.toJSON()),
-    upstreamHead: EventId.toString(this.upstreamHead),
-    localHead: EventId.toString(this.localHead),
+    upstreamHead: EventSequenceNumber.toString(this.upstreamHead),
+    localHead: EventSequenceNumber.toString(this.localHead),
   })
 }
 
@@ -148,13 +148,13 @@ export class MergeResultRebase extends Schema.Class<MergeResultRebase>('MergeRes
 export class MergeResultReject extends Schema.Class<MergeResultReject>('MergeResultReject')({
   _tag: Schema.Literal('reject'),
   /** The minimum id that the new events must have */
-  expectedMinimumId: EventId.EventId,
+  expectedMinimumId: EventSequenceNumber.EventSequenceNumber,
   mergeContext: MergeContext,
 }) {
   toJSON = (): any => {
     return {
       _tag: this._tag,
-      expectedMinimumId: EventId.toString(this.expectedMinimumId),
+      expectedMinimumId: EventSequenceNumber.toString(this.expectedMinimumId),
       mergeContext: this.mergeContext.toJSON(),
     }
   }
@@ -185,7 +185,7 @@ const unexpectedError = (cause: unknown): MergeResultUnexpectedError => {
 
 // TODO Idea: call merge recursively through hierarchy levels
 /*
-Idea: have a map that maps from `globalEventId` to Array<ClientEvents>
+Idea: have a map that maps from `globalEventSequenceNumber` to Array<ClientEvents>
 The same applies to even further hierarchy levels
 
 TODO: possibly even keep the client events in a separate table in the client leader
@@ -214,12 +214,12 @@ export const merge = ({
       const rollbackEvents = [...payload.rollbackEvents, ...syncState.pending]
 
       // Get the last new event's ID as the new upstream head
-      const newUpstreamHead = payload.newEvents.at(-1)?.id ?? syncState.upstreamHead
+      const newUpstreamHead = payload.newEvents.at(-1)?.seqNum ?? syncState.upstreamHead
 
       // Rebase pending events on top of the new events
       const rebasedPending = rebaseEvents({
         events: syncState.pending,
-        baseEventId: newUpstreamHead,
+        baseEventSequenceNumber: newUpstreamHead,
         isClientEvent,
       })
 
@@ -229,7 +229,7 @@ export const merge = ({
           newSyncState: new SyncState({
             pending: rebasedPending,
             upstreamHead: newUpstreamHead,
-            localHead: rebasedPending.at(-1)?.id ?? newUpstreamHead,
+            localHead: rebasedPending.at(-1)?.seqNum ?? newUpstreamHead,
           }),
           newEvents: [...payload.newEvents, ...rebasedPending],
           rollbackEvents,
@@ -256,26 +256,26 @@ export const merge = ({
         )
       }
 
-      // Validate that newEvents are sorted in ascending order by eventId
+      // Validate that newEvents are sorted in ascending order by eventNum
       for (let i = 1; i < payload.newEvents.length; i++) {
-        if (EventId.isGreaterThan(payload.newEvents[i - 1]!.id, payload.newEvents[i]!.id)) {
+        if (EventSequenceNumber.isGreaterThan(payload.newEvents[i - 1]!.seqNum, payload.newEvents[i]!.seqNum)) {
           return unexpectedError(
-            `Events must be sorted in ascending order by eventId. Received: [${payload.newEvents.map((e) => EventId.toString(e.id)).join(', ')}]`,
+            `Events must be sorted in ascending order by event number. Received: [${payload.newEvents.map((e) => EventSequenceNumber.toString(e.seqNum)).join(', ')}]`,
           )
         }
       }
 
       // Validate that incoming events are larger than upstream head
       if (
-        EventId.isGreaterThan(syncState.upstreamHead, payload.newEvents[0]!.id) ||
-        EventId.isEqual(syncState.upstreamHead, payload.newEvents[0]!.id)
+        EventSequenceNumber.isGreaterThan(syncState.upstreamHead, payload.newEvents[0]!.seqNum) ||
+        EventSequenceNumber.isEqual(syncState.upstreamHead, payload.newEvents[0]!.seqNum)
       ) {
         return unexpectedError(
-          `Incoming events must be greater than upstream head. Expected greater than: ${EventId.toString(syncState.upstreamHead)}. Received: [${payload.newEvents.map((e) => EventId.toString(e.id)).join(', ')}]`,
+          `Incoming events must be greater than upstream head. Expected greater than: ${EventSequenceNumber.toString(syncState.upstreamHead)}. Received: [${payload.newEvents.map((e) => EventSequenceNumber.toString(e.seqNum)).join(', ')}]`,
         )
       }
 
-      const newUpstreamHead = payload.newEvents.at(-1)!.id
+      const newUpstreamHead = payload.newEvents.at(-1)!.seqNum
 
       const divergentPendingIndex = findDivergencePoint({
         existingEvents: syncState.pending,
@@ -287,8 +287,12 @@ export const merge = ({
 
       // No divergent pending events, thus we can just advance (some of) the pending events
       if (divergentPendingIndex === -1) {
-        const pendingEventIds = new Set(syncState.pending.map((e) => `${e.id.global},${e.id.client}`))
-        const newEvents = payload.newEvents.filter((e) => !pendingEventIds.has(`${e.id.global},${e.id.client}`))
+        const pendingEventSequenceNumbers = new Set(
+          syncState.pending.map((e) => `${e.seqNum.global},${e.seqNum.client}`),
+        )
+        const newEvents = payload.newEvents.filter(
+          (e) => !pendingEventSequenceNumbers.has(`${e.seqNum.global},${e.seqNum.client}`),
+        )
 
         // In the case where the incoming events are a subset of the pending events,
         // we need to split the pending events into two groups:
@@ -318,7 +322,8 @@ export const merge = ({
             newSyncState: new SyncState({
               pending: pendingRemaining,
               upstreamHead: newUpstreamHead,
-              localHead: pendingRemaining.at(-1)?.id ?? EventId.max(syncState.localHead, newUpstreamHead),
+              localHead:
+                pendingRemaining.at(-1)?.seqNum ?? EventSequenceNumber.max(syncState.localHead, newUpstreamHead),
             }),
             newEvents,
             confirmedEvents: pendingMatching,
@@ -329,7 +334,7 @@ export const merge = ({
         const divergentPending = syncState.pending.slice(divergentPendingIndex)
         const rebasedPending = rebaseEvents({
           events: divergentPending,
-          baseEventId: newUpstreamHead,
+          baseEventSequenceNumber: newUpstreamHead,
           isClientEvent,
         })
 
@@ -347,7 +352,7 @@ export const merge = ({
             newSyncState: new SyncState({
               pending: rebasedPending,
               upstreamHead: newUpstreamHead,
-              localHead: rebasedPending.at(-1)!.id,
+              localHead: rebasedPending.at(-1)!.seqNum,
             }),
             newEvents: [...payload.newEvents.slice(divergentNewEventsIndex), ...rebasedPending],
             rollbackEvents: divergentPending,
@@ -373,10 +378,11 @@ export const merge = ({
       }
 
       const newEventsFirst = payload.newEvents.at(0)!
-      const invalidEventId = EventId.isGreaterThan(newEventsFirst.id, syncState.localHead) === false
+      const invalidEventSequenceNumber =
+        EventSequenceNumber.isGreaterThan(newEventsFirst.seqNum, syncState.localHead) === false
 
-      if (invalidEventId) {
-        const expectedMinimumId = EventId.nextPair(syncState.localHead, true).id
+      if (invalidEventSequenceNumber) {
+        const expectedMinimumId = EventSequenceNumber.nextPair(syncState.localHead, true).seqNum
         return validateMergeResult(
           MergeResultReject.make({
             _tag: 'reject',
@@ -391,7 +397,7 @@ export const merge = ({
             newSyncState: new SyncState({
               pending: [...syncState.pending, ...payload.newEvents],
               upstreamHead: syncState.upstreamHead,
-              localHead: payload.newEvents.at(-1)!.id,
+              localHead: payload.newEvents.at(-1)!.seqNum,
             }),
             newEvents: payload.newEvents,
             confirmedEvents: [],
@@ -436,9 +442,11 @@ export const findDivergencePoint = ({
 
     if (divergencePointWithoutClientEvents === -1) return -1
 
-    const divergencePointEventId = existingEvents[divergencePointWithoutClientEvents]!.id
+    const divergencePointEventSequenceNumber = existingEvents[divergencePointWithoutClientEvents]!.seqNum
     // Now find the divergence point in the original array
-    return existingEvents.findIndex((event) => EventId.isEqual(event.id, divergencePointEventId))
+    return existingEvents.findIndex((event) =>
+      EventSequenceNumber.isEqual(event.seqNum, divergencePointEventSequenceNumber),
+    )
   }
 
   return existingEvents.findIndex((existingEvent, index) => {
@@ -450,18 +458,18 @@ export const findDivergencePoint = ({
 
 const rebaseEvents = ({
   events,
-  baseEventId,
+  baseEventSequenceNumber,
   isClientEvent,
 }: {
   events: ReadonlyArray<LiveStoreEvent.EncodedWithMeta>
-  baseEventId: EventId.EventId
+  baseEventSequenceNumber: EventSequenceNumber.EventSequenceNumber
   isClientEvent: (event: LiveStoreEvent.EncodedWithMeta) => boolean
 }): ReadonlyArray<LiveStoreEvent.EncodedWithMeta> => {
-  let prevEventId = baseEventId
+  let prevEventSequenceNumber = baseEventSequenceNumber
   return events.map((event) => {
     const isLocal = isClientEvent(event)
-    const newEvent = event.rebase(prevEventId, isLocal)
-    prevEventId = newEvent.id
+    const newEvent = event.rebase(prevEventSequenceNumber, isLocal)
+    prevEventSequenceNumber = newEvent.seqNum
     return newEvent
   })
 }
@@ -477,9 +485,9 @@ const _flattenMergeResults = (_updateResults: ReadonlyArray<MergeResult>) => {}
 
 const validatePayload = (payload: typeof Payload.Type) => {
   for (let i = 1; i < payload.newEvents.length; i++) {
-    if (EventId.isGreaterThanOrEqual(payload.newEvents[i - 1]!.id, payload.newEvents[i]!.id)) {
+    if (EventSequenceNumber.isGreaterThanOrEqual(payload.newEvents[i - 1]!.seqNum, payload.newEvents[i]!.seqNum)) {
       return unexpectedError(
-        `Events must be ordered in monotonically ascending order by eventId. Received: [${payload.newEvents.map((e) => EventId.toString(e.id)).join(', ')}]`,
+        `Events must be ordered in monotonically ascending order by eventNum. Received: [${payload.newEvents.map((e) => EventSequenceNumber.toString(e.seqNum)).join(', ')}]`,
       )
     }
   }
@@ -491,9 +499,9 @@ const validateSyncState = (syncState: SyncState) => {
     const nextEvent = syncState.pending[i + 1]
     if (nextEvent === undefined) break // Reached end of chain
 
-    if (EventId.isGreaterThanOrEqual(event.id, nextEvent.id)) {
+    if (EventSequenceNumber.isGreaterThanOrEqual(event.seqNum, nextEvent.seqNum)) {
       shouldNeverHappen(
-        `Events must be ordered in monotonically ascending order by eventId. Received: [${syncState.pending.map((e) => EventId.toString(e.id)).join(', ')}]`,
+        `Events must be ordered in monotonically ascending order by eventNum. Received: [${syncState.pending.map((e) => EventSequenceNumber.toString(e.seqNum)).join(', ')}]`,
         {
           event,
           nextEvent,
@@ -502,11 +510,11 @@ const validateSyncState = (syncState: SyncState) => {
     }
 
     // If the global id has increased, then the client id must be 0
-    const globalIdHasIncreased = nextEvent.id.global > event.id.global
+    const globalIdHasIncreased = nextEvent.seqNum.global > event.seqNum.global
     if (globalIdHasIncreased) {
-      if (nextEvent.id.client !== 0) {
+      if (nextEvent.seqNum.client !== 0) {
         shouldNeverHappen(
-          `New global events must point to clientId 0 in the parentId. Received: (${EventId.toString(nextEvent.id)})`,
+          `New global events must point to clientId 0 in the parentSeqNum. Received: (${EventSequenceNumber.toString(nextEvent.seqNum)})`,
           syncState.pending,
           {
             event,
@@ -515,9 +523,9 @@ const validateSyncState = (syncState: SyncState) => {
         )
       }
     } else {
-      // Otherwise, the parentId must be the same as the previous event's id
-      if (EventId.isEqual(nextEvent.parentId, event.id) === false) {
-        shouldNeverHappen('Events must be linked in a continuous chain via the parentId', syncState.pending, {
+      // Otherwise, the parentSeqNum must be the same as the previous event's id
+      if (EventSequenceNumber.isEqual(nextEvent.parentSeqNum, event.seqNum) === false) {
+        shouldNeverHappen('Events must be linked in a continuous chain via the parentSeqNum', syncState.pending, {
           event,
           nextEvent,
         })
@@ -532,7 +540,7 @@ const validateMergeResult = (mergeResult: typeof MergeResult.Type) => {
   validateSyncState(mergeResult.newSyncState)
 
   // Ensure local head is always greater than or equal to upstream head
-  if (EventId.isGreaterThan(mergeResult.newSyncState.upstreamHead, mergeResult.newSyncState.localHead)) {
+  if (EventSequenceNumber.isGreaterThan(mergeResult.newSyncState.upstreamHead, mergeResult.newSyncState.localHead)) {
     shouldNeverHappen('Local head must be greater than or equal to upstream head', {
       localHead: mergeResult.newSyncState.localHead,
       upstreamHead: mergeResult.newSyncState.upstreamHead,
@@ -541,8 +549,10 @@ const validateMergeResult = (mergeResult: typeof MergeResult.Type) => {
 
   // Ensure new local head is greater than or equal to the previous local head
   if (
-    EventId.isGreaterThanOrEqual(mergeResult.newSyncState.localHead, mergeResult.mergeContext.syncState.localHead) ===
-    false
+    EventSequenceNumber.isGreaterThanOrEqual(
+      mergeResult.newSyncState.localHead,
+      mergeResult.mergeContext.syncState.localHead,
+    ) === false
   ) {
     shouldNeverHappen('New local head must be greater than or equal to the previous local head', {
       localHead: mergeResult.newSyncState.localHead,
@@ -552,7 +562,7 @@ const validateMergeResult = (mergeResult: typeof MergeResult.Type) => {
 
   // Ensure new upstream head is greater than or equal to the previous upstream head
   if (
-    EventId.isGreaterThanOrEqual(
+    EventSequenceNumber.isGreaterThanOrEqual(
       mergeResult.newSyncState.upstreamHead,
       mergeResult.mergeContext.syncState.upstreamHead,
     ) === false

package/src/sync/validate-push-payload.ts

@@ -1,20 +1,20 @@
 import { Effect } from '@livestore/utils/effect'
 
-import type { EventId, LiveStoreEvent } from '../schema/mod.js'
+import type { EventSequenceNumber, LiveStoreEvent } from '../schema/mod.js'
 import { InvalidPushError } from './sync.js'
 
 // TODO proper batch validation
 export const validatePushPayload = (
   batch: ReadonlyArray<LiveStoreEvent.AnyEncodedGlobal>,
-  currentEventId: EventId.GlobalEventId,
+  currentEventSequenceNumber: EventSequenceNumber.GlobalEventSequenceNumber,
 ) =>
   Effect.gen(function* () {
-    if (batch[0]!.id <= currentEventId) {
+    if (batch[0]!.seqNum <= currentEventSequenceNumber) {
       return yield* InvalidPushError.make({
         reason: {
           _tag: 'ServerAhead',
-          minimumExpectedId: currentEventId + 1,
-          providedId: batch[0]!.id,
+          minimumExpectedNum: currentEventSequenceNumber + 1,
+          providedNum: batch[0]!.seqNum,
         },
       })
     }

package/src/version.ts

@@ -2,7 +2,7 @@
 // import packageJson from '../package.json' with { type: 'json' }
 // export const liveStoreVersion = packageJson.version
 
-export const liveStoreVersion = '0.3.0-dev.46' as const
+export const liveStoreVersion = '0.3.0-dev.48' as const
 
 /**
  * This version number is incremented whenever the internal storage format changes in a breaking way.
@@ -11,4 +11,4 @@ export const liveStoreVersion = '0.3.0-dev.46' as const
  * While LiveStore is in alpha, this might happen more frequently.
  * In the future, LiveStore will provide a migration path for older database files to avoid the impression of data loss.
  */
-export const liveStoreStorageFormatVersion = 3
+export const liveStoreStorageFormatVersion = 4

package/src/schema/EventId.test.ts

@@ -1,12 +0,0 @@
-import { Vitest } from '@livestore/utils-dev/node-vitest'
-import { expect } from 'vitest'
-
-import { EventId } from './mod.js'
-
-Vitest.describe('EventId', () => {
-  Vitest.test('nextPair', () => {
-    const e_0_0 = EventId.make({ global: 0, client: 0 })
-    expect(EventId.nextPair(e_0_0, false).id).toStrictEqual({ global: 1, client: 0 })
-    expect(EventId.nextPair(e_0_0, true).id).toStrictEqual({ global: 0, client: 1 })
-  })
-})

package/src/schema/EventId.ts

@@ -1,106 +0,0 @@
-import { Brand, Schema } from '@livestore/utils/effect'
-
-export type ClientEventId = Brand.Branded<number, 'ClientEventId'>
-export const localEventId = Brand.nominal<ClientEventId>()
-export const ClientEventId = Schema.fromBrand(localEventId)(Schema.Int)
-
-export type GlobalEventId = Brand.Branded<number, 'GlobalEventId'>
-export const globalEventId = Brand.nominal<GlobalEventId>()
-export const GlobalEventId = Schema.fromBrand(globalEventId)(Schema.Int)
-
-export const clientDefault = 0 as any as ClientEventId
-
-/**
- * LiveStore event id value consisting of a globally unique event sequence number
- * and a client sequence number.
- *
- * The client sequence number is only used for clientOnly events and starts from 0 for each global sequence number.
- */
-export type EventId = { global: GlobalEventId; client: ClientEventId }
-
-// export const EventSequenceNumber = Schema.Struct({})
-// export const EventNumber = Schema.Struct({})
-// export const ClientEventNumber = Schema.Struct({})
-// export const GlobalEventNumber = Schema.Struct({})
-
-/**
- * NOTE: Client mutation events with a non-0 client id, won't be synced to the sync backend.
- */
-export const EventId = Schema.Struct({
-  global: GlobalEventId,
-  /** Only increments for clientOnly events */
-  client: ClientEventId,
-
-  // TODO also provide a way to see "confirmation level" of event (e.g. confirmed by leader/sync backend)
-
-  // TODO: actually add this field
-  // Client only
-  // generation: Schema.Number.pipe(Schema.optional),
-}).annotations({ title: 'LiveStore.EventId' })
-
-/**
- * Compare two event ids i.e. checks if the first event id is less than the second.
- */
-export const compare = (a: EventId, b: EventId) => {
-  if (a.global !== b.global) {
-    return a.global - b.global
-  }
-  return a.client - b.client
-}
-
-/**
- * Convert an event id to a string representation.
- */
-export const toString = (id: EventId) => (id.client === 0 ? `e${id.global}` : `e${id.global}+${id.client}`)
-
-/**
- * Convert a string representation of an event id to an event id.
- */
-export const fromString = (str: string): EventId => {
-  const [global, client] = str.slice(1, -1).split(',').map(Number)
-  if (global === undefined || client === undefined) {
-    throw new Error('Invalid event id string')
-  }
-  return { global, client } as EventId
-}
-
-export const isEqual = (a: EventId, b: EventId) => a.global === b.global && a.client === b.client
-
-export type EventIdPair = { id: EventId; parentId: EventId }
-
-export const ROOT = { global: 0 as any as GlobalEventId, client: clientDefault } satisfies EventId
-
-export const isGreaterThan = (a: EventId, b: EventId) => {
-  return a.global > b.global || (a.global === b.global && a.client > b.client)
-}
-
-export const isGreaterThanOrEqual = (a: EventId, b: EventId) => {
-  return a.global > b.global || (a.global === b.global && a.client >= b.client)
-}
-
-export const max = (a: EventId, b: EventId) => {
-  return a.global > b.global || (a.global === b.global && a.client > b.client) ? a : b
-}
-
-export const diff = (a: EventId, b: EventId) => {
-  return {
-    global: a.global - b.global,
-    client: a.client - b.client,
-  }
-}
-
-export const make = (id: EventId | typeof EventId.Encoded): EventId => {
-  return Schema.is(EventId)(id) ? id : Schema.decodeSync(EventId)(id)
-}
-
-export const nextPair = (id: EventId, isLocal: boolean): EventIdPair => {
-  if (isLocal) {
-    return { id: { global: id.global, client: (id.client + 1) as any as ClientEventId }, parentId: id }
-  }
-
-  return {
-    id: { global: (id.global + 1) as any as GlobalEventId, client: clientDefault },
-    // NOTE we always point to `client: 0` for non-clientOnly events
-    parentId: { global: id.global, client: clientDefault },
-  }
-}