@livestore/common 0.4.0-dev.21 → 0.4.0-dev.23

package/src/sync/syncstate.ts

@@ -1,5 +1,5 @@
-import { casesHandled, LS_DEV, shouldNeverHappen } from '@livestore/utils'
-import { Match, ReadonlyArray, Schema } from '@livestore/utils/effect'
+import { casesHandled } from '@livestore/utils'
+import { Effect, Match, ReadonlyArray, Schema } from '@livestore/utils/effect'
 
 import * as EventSequenceNumber from '../schema/EventSequenceNumber/mod.ts'
 import * as LiveStoreEvent from '../schema/LiveStoreEvent/mod.ts'
@@ -159,16 +159,10 @@ export class MergeResultReject extends Schema.Class<MergeResultReject>('MergeRes
   }
 }
 
-export class MergeResultUnknownError extends Schema.Class<MergeResultUnknownError>('MergeResultUnknownError')({
-  _tag: Schema.Literal('unknown-error'),
-  message: Schema.String,
-}) {}
-
 export class MergeResult extends Schema.Union(
   MergeResultAdvance,
   MergeResultRebase,
   MergeResultReject,
-  MergeResultUnknownError,
 ) {}
 
 export const payloadFromMergeResult = (
@@ -187,15 +181,6 @@ export const payloadFromMergeResult = (
     Match.exhaustive,
   )
 
-const unknownError = (message: string): MergeResultUnknownError => {
-  if (LS_DEV) {
-    // biome-ignore lint/suspicious/noDebugger: debug
-    debugger
-  }
-
-  return MergeResultUnknownError.make({ _tag: 'unknown-error', message })
-}
-
 // TODO Idea: call merge recursively through hierarchy levels
 /*
 Idea: have a map that maps from `globalEventSequenceNumber` to Array<ClientEvents>
@@ -203,7 +188,7 @@ The same applies to even further hierarchy levels
 
 TODO: possibly even keep the client events in a separate table in the client leader
 */
-export const merge = ({
+export const merge = Effect.fnUntraced(function* ({
   syncState,
   payload,
   isClientEvent,
@@ -216,9 +201,9 @@ export const merge = ({
   isEqualEvent: (a: LiveStoreEvent.Client.EncodedWithMeta, b: LiveStoreEvent.Client.EncodedWithMeta) => boolean
   /** This is used in the leader which should ignore client events when receiving an upstream-advance payload */
   ignoreClientEvents?: boolean
-}): typeof MergeResult.Type => {
-  validateSyncState(syncState)
-  validatePayload(payload)
+}) {
+  yield* validateSyncState(syncState)
+  yield* validatePayload(payload)
 
   const mergeContext = MergeContext.make({ payload, syncState })
 
@@ -236,7 +221,7 @@ export const merge = ({
         isClientEvent,
       })
 
-      return validateMergeResult(
+      return yield* validateMergeResult(
         MergeResultRebase.make({
           _tag: 'rebase',
           newSyncState: new SyncState({
@@ -251,10 +236,10 @@ export const merge = ({
       )
     }
 
-    // #region upstream-advance
+    //#region upstream-advance
     case 'upstream-advance': {
       if (payload.newEvents.length === 0) {
-        return validateMergeResult(
+        return yield* validateMergeResult(
           MergeResultAdvance.make({
             _tag: 'advance',
             newSyncState: new SyncState({
@@ -271,8 +256,11 @@ export const merge = ({
 
       // Validate that newEvents are sorted in ascending order by eventNum
       for (let i = 1; i < payload.newEvents.length; i++) {
-        if (EventSequenceNumber.Client.isGreaterThan(payload.newEvents[i - 1]!.seqNum, payload.newEvents[i]!.seqNum)) {
-          return unknownError(
+        if (
+          EventSequenceNumber.Client.isGreaterThan(payload.newEvents[i - 1]!.seqNum, payload.newEvents[i]!.seqNum) ===
+          true
+        ) {
+          return yield* Effect.dieDebugger(
             `Events must be sorted in ascending order by event number. Received: [${payload.newEvents.map((e) => EventSequenceNumber.Client.toString(e.seqNum)).join(', ')}]`,
           )
         }
@@ -280,10 +268,10 @@ export const merge = ({
 
       // Validate that incoming events are larger than upstream head
       if (
-        EventSequenceNumber.Client.isGreaterThan(syncState.upstreamHead, payload.newEvents[0]!.seqNum) ||
-        EventSequenceNumber.Client.isEqual(syncState.upstreamHead, payload.newEvents[0]!.seqNum)
+        EventSequenceNumber.Client.isGreaterThan(syncState.upstreamHead, payload.newEvents[0]!.seqNum) === true ||
+        EventSequenceNumber.Client.isEqual(syncState.upstreamHead, payload.newEvents[0]!.seqNum) === true
       ) {
-        return unknownError(
+        return yield* Effect.dieDebugger(
           `Incoming events must be greater than upstream head. Expected greater than: ${EventSequenceNumber.Client.toString(syncState.upstreamHead)}. Received: [${payload.newEvents.map((e) => EventSequenceNumber.Client.toString(e.seqNum)).join(', ')}]`,
         )
       }
@@ -316,20 +304,20 @@ export const merge = ({
         const [pendingMatching, pendingRemaining] = ReadonlyArray.splitWhere(
           syncState.pending,
           (pendingEvent, index) => {
-            if (ignoreClientEvents && isClientEvent(pendingEvent)) {
+            if (ignoreClientEvents === true && isClientEvent(pendingEvent) === true) {
               clientIndexOffset++
               return false
             }
 
             const newEvent = payload.newEvents.at(index - clientIndexOffset)
-            if (!newEvent) {
+            if (newEvent == null) {
               return true
             }
-            return isEqualEvent(pendingEvent, newEvent) === false
+            return !isEqualEvent(pendingEvent, newEvent)
           },
         )
 
-        return validateMergeResult(
+        return yield* validateMergeResult(
           MergeResultAdvance.make({
             _tag: 'advance',
             newSyncState: new SyncState({
@@ -359,7 +347,7 @@ export const merge = ({
           ignoreClientEvents,
         })
 
-        return validateMergeResult(
+        return yield* validateMergeResult(
           MergeResultRebase.make({
             _tag: 'rebase',
             newSyncState: new SyncState({
@@ -374,12 +362,12 @@ export const merge = ({
         )
       }
     }
-    // #endregion
+    //#endregion upstream-advance
 
     // This is the same as what's running in the sync backend
     case 'local-push': {
       if (payload.newEvents.length === 0) {
-        return validateMergeResult(
+        return yield* validateMergeResult(
           MergeResultAdvance.make({
             _tag: 'advance',
             newSyncState: syncState,
@@ -391,15 +379,17 @@ export const merge = ({
       }
 
       const newEventsFirst = payload.newEvents.at(0)!
-      const invalidEventSequenceNumber =
-        EventSequenceNumber.Client.isGreaterThan(newEventsFirst.seqNum, syncState.localHead) === false
+      const invalidEventSequenceNumber = !EventSequenceNumber.Client.isGreaterThan(
+        newEventsFirst.seqNum,
+        syncState.localHead,
+      )
 
-      if (invalidEventSequenceNumber) {
+      if (invalidEventSequenceNumber === true) {
         const expectedMinimumId = EventSequenceNumber.Client.nextPair({
           seqNum: syncState.localHead,
           isClient: true,
         }).seqNum
-        return validateMergeResult(
+        return yield* validateMergeResult(
           MergeResultReject.make({
             _tag: 'reject',
             expectedMinimumId,
@@ -407,14 +397,13 @@ export const merge = ({
           }),
         )
       } else {
-        const nonClientEvents = ignoreClientEvents
-          ? payload.newEvents.filter((event) => !isClientEvent(event))
-          : payload.newEvents
+        const nonClientEvents =
+          ignoreClientEvents === true ? payload.newEvents.filter((event) => !isClientEvent(event)) : payload.newEvents
         const newPending = [...syncState.pending, ...nonClientEvents]
         const newLocalHead =
           newPending.at(-1)?.seqNum ?? EventSequenceNumber.Client.max(syncState.localHead, syncState.upstreamHead)
 
-        return validateMergeResult(
+        return yield* validateMergeResult(
           MergeResultAdvance.make({
             _tag: 'advance',
             newSyncState: new SyncState({
@@ -430,11 +419,10 @@ export const merge = ({
       }
     }
 
-    default: {
-      casesHandled(payload)
-    }
+    default:
+      return casesHandled(payload)
   }
-}
+  })
 
 /**
  * Gets the index relative to `existingEvents` where the divergence point is
@@ -453,7 +441,7 @@ export const findDivergencePoint = ({
   isClientEvent: (event: LiveStoreEvent.Client.EncodedWithMeta) => boolean
   ignoreClientEvents: boolean
 }): number => {
-  if (ignoreClientEvents) {
+  if (ignoreClientEvents === true) {
     const filteredExistingEvents = existingEvents.filter((event) => !isClientEvent(event))
     const divergencePointWithoutClientEvents = findDivergencePoint({
       existingEvents: filteredExistingEvents,
@@ -475,7 +463,7 @@ export const findDivergencePoint = ({
   return existingEvents.findIndex((existingEvent, index) => {
     const incomingEvent = incomingEvents[index]
     // return !incomingEvent || !isEqualEvent(existingEvent, incomingEvent)
-    return incomingEvent && !isEqualEvent(existingEvent, incomingEvent)
+    return incomingEvent !== undefined && isEqualEvent(existingEvent, incomingEvent) === false
   })
 }
 
@@ -511,69 +499,75 @@ const rebaseEvents = ({
  */
 const _flattenMergeResults = (_updateResults: ReadonlyArray<MergeResult>) => {}
 
-const validatePayload = (payload: typeof Payload.Type) => {
-  for (let i = 1; i < payload.newEvents.length; i++) {
-    if (
-      EventSequenceNumber.Client.isGreaterThanOrEqual(payload.newEvents[i - 1]!.seqNum, payload.newEvents[i]!.seqNum)
-    ) {
-      return unknownError(
-        `Events must be ordered in monotonically ascending order by eventNum. Received: [${payload.newEvents.map((e) => EventSequenceNumber.Client.toString(e.seqNum)).join(', ')}]`,
-      )
+const validatePayload = (payload: typeof Payload.Type) =>
+  Effect.gen(function* () {
+    for (let i = 1; i < payload.newEvents.length; i++) {
+      if (
+        EventSequenceNumber.Client.isGreaterThanOrEqual(
+          payload.newEvents[i - 1]!.seqNum,
+          payload.newEvents[i]!.seqNum,
+        ) === true
+      ) {
+        return yield* Effect.dieDebugger(
+          `Events must be ordered in monotonically ascending order by eventNum. Received: [${payload.newEvents.map((e) => EventSequenceNumber.Client.toString(e.seqNum)).join(', ')}]`,
+        )
+      }
     }
-  }
-}
+  })
 
-const validateSyncState = (syncState: SyncState) => {
+const validateSyncState = Effect.fnUntraced(function* (
+  syncState: SyncState,
+) {
   for (let i = 0; i < syncState.pending.length; i++) {
     const event = syncState.pending[i]!
     const nextEvent = syncState.pending[i + 1]
     if (nextEvent === undefined) break // Reached end of chain
 
-    if (EventSequenceNumber.Client.isGreaterThanOrEqual(event.seqNum, nextEvent.seqNum)) {
-      shouldNeverHappen(
+    if (EventSequenceNumber.Client.isGreaterThanOrEqual(event.seqNum, nextEvent.seqNum) === true) {
+      return yield* Effect.dieDebugger(
         `Events must be ordered in monotonically ascending order by eventNum. Received: [${syncState.pending.map((e) => EventSequenceNumber.Client.toString(e.seqNum)).join(', ')}]`,
-        {
-          event,
-          nextEvent,
-        },
+        { event, nextEvent },
       )
     }
 
     // If the global id has increased, then the client id must be 0
     const globalIdHasIncreased = nextEvent.seqNum.global > event.seqNum.global
-    if (globalIdHasIncreased) {
+    if (globalIdHasIncreased === true) {
       if (nextEvent.seqNum.client !== 0) {
-        shouldNeverHappen(
+        return yield* Effect.dieDebugger(
           `New global events must point to clientId 0 in the parentSeqNum. Received: (${EventSequenceNumber.Client.toString(nextEvent.seqNum)})`,
           syncState.pending,
-          {
-            event,
-            nextEvent,
-          },
+          { event, nextEvent },
         )
       }
     } else {
       // Otherwise, the parentSeqNum must be the same as the previous event's id
       if (EventSequenceNumber.Client.isEqual(nextEvent.parentSeqNum, event.seqNum) === false) {
-        shouldNeverHappen('Events must be linked in a continuous chain via the parentSeqNum', syncState.pending, {
-          event,
-          nextEvent,
-        })
+        return yield* Effect.dieDebugger(
+          'Events must be linked in a continuous chain via the parentSeqNum',
+          syncState.pending,
+          { event, nextEvent },
+        )
       }
     }
   }
-}
+})
 
-const validateMergeResult = (mergeResult: typeof MergeResult.Type) => {
-  if (mergeResult._tag === 'unknown-error' || mergeResult._tag === 'reject') return mergeResult
+const validateMergeResult = Effect.fnUntraced(function* (
+  mergeResult: typeof MergeResult.Type,
+) {
+  if (mergeResult._tag === 'reject') return mergeResult
 
-  validateSyncState(mergeResult.newSyncState)
+  yield* validateSyncState(mergeResult.newSyncState)
 
   // Ensure local head is always greater than or equal to upstream head
   if (
-    EventSequenceNumber.Client.isGreaterThan(mergeResult.newSyncState.upstreamHead, mergeResult.newSyncState.localHead)
+    EventSequenceNumber.Client.isGreaterThan(
+      mergeResult.newSyncState.upstreamHead,
+      mergeResult.newSyncState.localHead,
+    ) === true
   ) {
-    shouldNeverHappen('Local head must be greater than or equal to upstream head', {
+    return yield* Effect.dieDebugger('Local head must be greater than or equal to upstream head', {
       localHead: mergeResult.newSyncState.localHead,
       upstreamHead: mergeResult.newSyncState.upstreamHead,
     })
@@ -586,7 +580,7 @@ const validateMergeResult = (mergeResult: typeof MergeResult.Type) => {
       mergeResult.mergeContext.syncState.localHead,
     ) === false
   ) {
-    shouldNeverHappen('New local head must be greater than or equal to the previous local head', {
+    return yield* Effect.dieDebugger('New local head must be greater than or equal to the previous local head', {
       localHead: mergeResult.newSyncState.localHead,
       previousLocalHead: mergeResult.mergeContext.syncState.localHead,
     })
@@ -599,11 +593,11 @@ const validateMergeResult = (mergeResult: typeof MergeResult.Type) => {
       mergeResult.mergeContext.syncState.upstreamHead,
     ) === false
   ) {
-    shouldNeverHappen('New upstream head must be greater than or equal to the previous upstream head', {
+    return yield* Effect.dieDebugger('New upstream head must be greater than or equal to the previous upstream head', {
       upstreamHead: mergeResult.newSyncState.upstreamHead,
       previousUpstreamHead: mergeResult.mergeContext.syncState.upstreamHead,
     })
   }
 
   return mergeResult
-}
+})

package/src/sync/transport-chunking.ts

@@ -27,7 +27,7 @@ export interface ChunkingOptions<A> {
  * both item count and encoded byte size limits. Designed for transports with
  * strict frame caps (e.g. Cloudflare hibernated WebSockets).
  */
-export class OversizeChunkItemError extends Schema.TaggedError<OversizeChunkItemError>()('OversizeChunkItemError', {
+export class OversizeChunkItemError extends Schema.TaggedError<OversizeChunkItemError>('~@livestore/common/OversizeChunkItemError')('OversizeChunkItemError', {
   size: Schema.Number,
   maxBytes: Schema.Number,
 }) {}
@@ -69,7 +69,7 @@ export const splitChunkBySize =
         current.push(item)
         const exceedsLimit = current.length > maxItems || computeSize(current) > maxBytes
 
-        if (exceedsLimit) {
+        if (exceedsLimit === true) {
           // remove the item we just added and emit the previous chunk if it exists
           const last = current.pop()!
           flushCurrent()
@@ -77,7 +77,7 @@ export const splitChunkBySize =
           if (last !== undefined) {
             current = [last]
             const singleItemTooLarge = computeSize(current) > maxBytes
-            if (singleItemTooLarge || current.length > maxItems) {
+            if (singleItemTooLarge === true || current.length > maxItems) {
               return yield* new OversizeChunkItemError({ size: computeSize([last]), maxBytes })
             }
           }

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

@@ -1,7 +1,7 @@
 import { Effect } from '@livestore/utils/effect'
 
 import { EventSequenceNumber, type LiveStoreEvent } from '../schema/mod.ts'
-import { InvalidPushError, ServerAheadError } from './sync.ts'
+import { ServerAheadError } from './sync.ts'
 
 // TODO proper batch validation
 export const validatePushPayload = (
@@ -10,11 +10,9 @@ export const validatePushPayload = (
 ) =>
   Effect.gen(function* () {
     if (batch[0]!.seqNum <= currentEventSequenceNumber) {
-      return yield* InvalidPushError.make({
-        cause: new ServerAheadError({
-          minimumExpectedNum: EventSequenceNumber.Global.make(currentEventSequenceNumber + 1),
-          providedNum: EventSequenceNumber.Global.make(batch[0]!.seqNum),
-        }),
+      return yield* new ServerAheadError({
+        minimumExpectedNum: EventSequenceNumber.Global.make(currentEventSequenceNumber + 1),
+        providedNum: EventSequenceNumber.Global.make(batch[0]!.seqNum),
       })
     }
   })

package/src/util.ts

@@ -47,11 +47,11 @@ export const sql = (template: TemplateStringsArray, ...args: unknown[]): string
  * TODO: Also make sure that the SQLite binding limit of 1000 is respected
  */
 export const prepareBindValues = (values: Bindable, statement: string): PreparedBindValues => {
-  if (Array.isArray(values)) return values as any as PreparedBindValues
+  if (Array.isArray(values) === true) return values as any as PreparedBindValues
 
   const result: ParamsObject = {}
   for (const [key, value] of Object.entries(values)) {
-    if (statement.includes(key)) {
+    if (statement.includes(key) === true) {
       result[`$${key}`] = value
     }
   }

package/src/version.ts

@@ -1,8 +1,12 @@
-// TODO bring back when Expo and Playwright supports `with` imports
-// import packageJson from '../package.json' with { type: 'json' }
-// export const liveStoreVersion = packageJson.version
+import pkg from '../package.json' with { type: 'json' }
 
-export const liveStoreVersion = '0.4.0-dev.21' as const
+/**
+ * Current LiveStore version used for DevTools version compatibility checks.
+ *
+ * Can be overridden at runtime via `globalThis.__LIVESTORE_VERSION_OVERRIDE__` for testing purposes.
+ * This allows Playwright tests to simulate version mismatch scenarios without rebuilding.
+ */
+export const liveStoreVersion: string = (globalThis as any).__LIVESTORE_VERSION_OVERRIDE__ ?? pkg.version
 
 /**
  * CRITICAL: Increment this version whenever you modify client-side EVENTLOG table schemas.