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

package/src/sync/mock-sync-backend.ts

@@ -1,8 +1,9 @@
 import type { Schema, Scope } from '@livestore/utils/effect'
-import { Effect, Mailbox, Option, Queue, Stream, SubscriptionRef } from '@livestore/utils/effect'
+import { Effect, Mailbox, Option, Queue, Ref, Stream, SubscriptionRef } from '@livestore/utils/effect'
+
 import { UnknownError } from '../errors.ts'
 import { EventSequenceNumber, type LiveStoreEvent } from '../schema/mod.ts'
-import { InvalidPushError } from './errors.ts'
+import { type BackendIdMismatchError, type ServerAheadError } from './errors.ts'
 import * as SyncBackend from './sync-backend.ts'
 import { validatePushPayload } from './validate-push-payload.ts'
 
@@ -12,10 +13,17 @@ export interface MockSyncBackend {
   disconnect: Effect.Effect<void>
   makeSyncBackend: Effect.Effect<SyncBackend.SyncBackend, UnknownError, Scope.Scope>
   advance: (...batch: LiveStoreEvent.Global.Encoded[]) => Effect.Effect<void>
-  /** Fail the next N push calls with an InvalidPushError (or custom error) */
+  /** Fail the next N push calls with an UnknownError, ServerAheadError, BackendIdMismatchError, or custom error */
   failNextPushes: (
     count: number,
-    error?: (batch: ReadonlyArray<LiveStoreEvent.Global.Encoded>) => Effect.Effect<never, InvalidPushError>,
+    error?: (
+      batch: ReadonlyArray<LiveStoreEvent.Global.Encoded>,
+    ) => Effect.Effect<never, UnknownError | ServerAheadError | BackendIdMismatchError>,
+  ) => Effect.Effect<void>
+  /** Fail the next N pull calls with an UnknownError, BackendIdMismatchError, or custom error */
+  failNextPulls: (
+    count: number,
+    error?: () => Effect.Effect<never, UnknownError | BackendIdMismatchError>,
   ) => Effect.Effect<void>
 }
 
@@ -31,107 +39,136 @@ export const makeMockSyncBackend = (
   options?: MockSyncBackendOptions,
 ): Effect.Effect<MockSyncBackend, UnknownError, Scope.Scope> =>
   Effect.gen(function* () {
-    const syncEventSequenceNumberRef = { current: EventSequenceNumber.Client.ROOT.global }
+    const span = yield* Effect.currentSpan.pipe(Effect.orDie)
+    const semaphore = yield* Effect.makeSemaphore(1)
+
+    // State refs
+    const syncHeadRef = yield* Ref.make(EventSequenceNumber.Client.ROOT.global)
+    const allEventsRef = yield* Ref.make<LiveStoreEvent.Global.Encoded[]>([])
+    const syncIsConnectedRef = yield* SubscriptionRef.make(options?.startConnected ?? false)
+
+    // Queues for streaming
     const syncPullQueue = yield* Queue.unbounded<LiveStoreEvent.Global.Encoded>()
     const pushedEventsQueue = yield* Mailbox.make<LiveStoreEvent.Global.Encoded>()
-    const syncIsConnectedRef = yield* SubscriptionRef.make(options?.startConnected ?? false)
-    const allEventsRef: { current: LiveStoreEvent.Global.Encoded[] } = { current: [] }
 
-    const span = yield* Effect.currentSpan.pipe(Effect.orDie)
+    // Failure simulation state
+    const failPushRef = yield* Ref.make<
+      FailureState<UnknownError | ServerAheadError | BackendIdMismatchError, [ReadonlyArray<LiveStoreEvent.Global.Encoded>]>
+    >({ remaining: 0, error: undefined })
+    const failPullRef = yield* Ref.make<FailureState<UnknownError | BackendIdMismatchError, []>>({
+      remaining: 0,
+      error: undefined,
+    })
 
-    const semaphore = yield* Effect.makeSemaphore(1)
+    const nonLiveChunkSize = Math.max(1, options?.nonLiveChunkSize ?? 100)
+
+    /** Check and consume a simulated failure, returning the error effect if one should fire */
+    const checkFailure = <E, Args extends unknown[]>(
+      ref: Ref.Ref<FailureState<E, Args>>,
+      defaultError: E,
+      ...args: Args
+    ): Effect.Effect<void, E> =>
+      Ref.modify(ref, (state) => {
+        if (state.remaining <= 0) {
+          return [Option.none(), state] as const
+        }
+        const error = state.error?.(...args) ?? Effect.fail(defaultError)
+        return [Option.some(error), { ...state, remaining: state.remaining - 1 }] as const
+      }).pipe(
+        Effect.flatMap(
+          Option.match({
+            onNone: () => Effect.void,
+            onSome: (errorEffect) => errorEffect,
+          }),
+        ),
+      )
+
+    const pullNonLive = (cursor: Option.Option<{ eventSequenceNumber: EventSequenceNumber.Global.Type }>) =>
+      Effect.gen(function* () {
+        const lastSeen = Option.match(cursor, {
+          onNone: () => EventSequenceNumber.Client.ROOT.global,
+          onSome: (_) => _.eventSequenceNumber,
+        })
+        const allEvents = yield* Ref.get(allEventsRef)
+        const slice = allEvents.filter((e) => e.seqNum > lastSeen)
+
+        // Split into chunks with remaining count for pageInfo
+        const chunks: Array<{ events: LiveStoreEvent.Global.Encoded[]; remaining: number }> = []
+        for (let i = 0; i < slice.length; i += nonLiveChunkSize) {
+          const end = Math.min(i + nonLiveChunkSize, slice.length)
+          chunks.push({
+            events: slice.slice(i, end),
+            remaining: Math.max(slice.length - end, 0),
+          })
+        }
+        // Always return at least one empty chunk
+        if (chunks.length === 0) {
+          chunks.push({ events: [], remaining: 0 })
+        }
+        return chunks
+      }).pipe(
+        Effect.map((chunks) =>
+          Stream.fromIterable(chunks).pipe(
+            Stream.map(({ events, remaining }) => ({
+              batch: events.map((eventEncoded) => ({ eventEncoded, metadata: Option.none() })),
+              pageInfo: remaining > 0 ? SyncBackend.pageInfoMoreKnown(remaining) : SyncBackend.pageInfoNoMore,
+            })),
+          ),
+        ),
+        Stream.fromEffect,
+        Stream.flatten(),
+      )
 
-    // TODO improve the API and implementation of simulating errors
-    const failCounterRef = yield* SubscriptionRef.make(0)
-    const failEffectRef = yield* SubscriptionRef.make<
-      ((batch: ReadonlyArray<LiveStoreEvent.Global.Encoded>) => Effect.Effect<never, InvalidPushError>) | undefined
-    >(undefined)
+    const pullLive = Stream.concat(
+      Stream.make(SyncBackend.pullResItemEmpty()),
+      Stream.fromQueue(syncPullQueue).pipe(
+        Stream.chunks,
+        Stream.map((chunk) => ({
+          batch: [...chunk].map((eventEncoded) => ({ eventEncoded, metadata: Option.none() })),
+          pageInfo: SyncBackend.pageInfoNoMore,
+        })),
+      ),
+    )
 
     const makeSyncBackend = Effect.gen(function* () {
-      const nonLiveChunkSize = Math.max(1, options?.nonLiveChunkSize ?? 100)
-
       // TODO consider making offline state actively error pull/push.
       // Currently, offline only reflects in `isConnected`, while operations still succeed,
       // mirroring how some real providers behave during transient disconnects.
-      return SyncBackend.of<Schema.JsonValue>({
+      return SyncBackend.of({
         isConnected: syncIsConnectedRef,
         connect: SubscriptionRef.set(syncIsConnectedRef, true),
         ping: Effect.void,
-        pull: (cursor, options) =>
-          (options?.live
-            ? Stream.concat(
-                Stream.make(SyncBackend.pullResItemEmpty()),
-                Stream.fromQueue(syncPullQueue).pipe(
-                  Stream.chunks,
-                  Stream.map((chunk) => ({
-                    batch: [...chunk].map((eventEncoded) => ({ eventEncoded, metadata: Option.none() })),
-                    pageInfo: SyncBackend.pageInfoNoMore,
-                  })),
-                ),
-              )
-            : Stream.fromEffect(
-                Effect.sync(() => {
-                  const lastSeen = cursor.pipe(
-                    Option.match({
-                      onNone: () => EventSequenceNumber.Client.ROOT.global,
-                      onSome: (_) => _.eventSequenceNumber,
-                    }),
-                  )
-                  // All events with seqNum greater than lastSeen
-                  const slice = allEventsRef.current.filter((e) => e.seqNum > lastSeen)
-                  // Split into configured chunk size
-                  const chunks: { events: LiveStoreEvent.Global.Encoded[]; remaining: number }[] = []
-                  for (let i = 0; i < slice.length; i += nonLiveChunkSize) {
-                    const end = Math.min(i + nonLiveChunkSize, slice.length)
-                    const remaining = Math.max(slice.length - end, 0)
-                    chunks.push({ events: slice.slice(i, end), remaining })
-                  }
-                  if (chunks.length === 0) {
-                    chunks.push({ events: [], remaining: 0 })
-                  }
-                  return chunks
-                }),
-              ).pipe(
-                Stream.flatMap((chunks) =>
-                  Stream.fromIterable(chunks).pipe(
-                    Stream.map(({ events, remaining }) => ({
-                      batch: events.map((eventEncoded) => ({ eventEncoded, metadata: Option.none() })),
-                      pageInfo: remaining > 0 ? SyncBackend.pageInfoMoreKnown(remaining) : SyncBackend.pageInfoNoMore,
-                    })),
-                  ),
-                ),
-              )
-          ).pipe(Stream.withSpan('MockSyncBackend:pull', { parent: span })),
+        pull: (cursor, pullOptions) =>
+          Stream.fromEffect(
+            checkFailure(
+              failPullRef,
+              new UnknownError({ cause: new Error('MockSyncBackend: simulated pull failure') }),
+            ),
+          ).pipe(
+            Stream.flatMap(() => (pullOptions?.live === true ? pullLive : pullNonLive(cursor))),
+            Stream.withSpan('MockSyncBackend:pull', { parent: span }),
+          ),
         push: (batch) =>
           Effect.gen(function* () {
-            yield* validatePushPayload(batch, syncEventSequenceNumberRef.current)
-
-            const remaining = yield* SubscriptionRef.get(failCounterRef)
-            if (remaining > 0) {
-              const maybeFail = yield* SubscriptionRef.get(failEffectRef)
-              // decrement counter first
-              yield* SubscriptionRef.set(failCounterRef, remaining - 1)
-              if (maybeFail) {
-                return yield* maybeFail(batch)
-              }
-              return yield* new InvalidPushError({
-                cause: new UnknownError({ cause: new Error('MockSyncBackend: simulated push failure') }),
-              })
-            }
+            const currentHead = yield* Ref.get(syncHeadRef)
+            yield* validatePushPayload(batch, currentHead)
+
+            yield* checkFailure(
+              failPushRef,
+              new UnknownError({ cause: new Error('MockSyncBackend: simulated push failure') }),
+              batch,
+            )
 
             yield* Effect.sleep(10).pipe(Effect.withSpan('MockSyncBackend:push:sleep')) // Simulate network latency
 
             yield* pushedEventsQueue.offerAll(batch)
             yield* syncPullQueue.offerAll(batch)
-            allEventsRef.current = allEventsRef.current.concat(batch)
-
-            syncEventSequenceNumberRef.current = batch.at(-1)!.seqNum
+            yield* Ref.update(allEventsRef, (events) => events.concat(batch))
+            yield* Ref.set(syncHeadRef, batch.at(-1)!.seqNum)
           }).pipe(
             Effect.withSpan('MockSyncBackend:push', {
               parent: span,
-              attributes: {
-                nums: batch.map((_) => _.seqNum),
-              },
+              attributes: { nums: batch.map((_) => _.seqNum) },
             }),
             semaphore.withPermits(1),
           ),
@@ -148,8 +185,8 @@ export const makeMockSyncBackend = (
 
     const advance = (...batch: LiveStoreEvent.Global.Encoded[]) =>
       Effect.gen(function* () {
-        syncEventSequenceNumberRef.current = batch.at(-1)!.seqNum
-        allEventsRef.current = allEventsRef.current.concat(batch)
+        yield* Ref.set(syncHeadRef, batch.at(-1)!.seqNum)
+        yield* Ref.update(allEventsRef, (events) => events.concat(batch))
         yield* syncPullQueue.offerAll(batch)
       }).pipe(
         Effect.withSpan('MockSyncBackend:advance', {
@@ -159,26 +196,31 @@ export const makeMockSyncBackend = (
         semaphore.withPermits(1),
       )
 
-    const connect = SubscriptionRef.set(syncIsConnectedRef, true)
-    const disconnect = SubscriptionRef.set(syncIsConnectedRef, false)
-
     const failNextPushes = (
       count: number,
-      error?: (batch: ReadonlyArray<LiveStoreEvent.Global.Encoded>) => Effect.Effect<never, InvalidPushError>,
-    ) =>
-      Effect.gen(function* () {
-        yield* SubscriptionRef.set(failCounterRef, count)
-        yield* SubscriptionRef.set(failEffectRef, error)
-      })
+      error?: (
+        batch: ReadonlyArray<LiveStoreEvent.Global.Encoded>,
+      ) => Effect.Effect<never, UnknownError | ServerAheadError | BackendIdMismatchError>,
+    ) => Ref.set(failPushRef, { remaining: count, error })
+
+    const failNextPulls = (
+      count: number,
+      error?: () => Effect.Effect<never, UnknownError | BackendIdMismatchError>,
+    ) => Ref.set(failPullRef, { remaining: count, error })
 
     return {
-      syncEventSequenceNumberRef,
-      syncPullQueue,
       pushedEvents: Mailbox.toStream(pushedEventsQueue),
-      connect,
-      disconnect,
+      connect: SubscriptionRef.set(syncIsConnectedRef, true),
+      disconnect: SubscriptionRef.set(syncIsConnectedRef, false),
       makeSyncBackend,
       advance,
       failNextPushes,
+      failNextPulls,
     }
   }).pipe(Effect.withSpanScoped('MockSyncBackend'))
+
+/** Internal state for simulating failures */
+interface FailureState<E, Args extends unknown[]> {
+  remaining: number
+  error: ((...args: Args) => Effect.Effect<never, E>) | undefined
+}

package/src/sync/next/compact-events.ts

@@ -16,7 +16,7 @@ export const compactEvents = (inputDag: HistoryDag): { dag: HistoryDag; compacte
   const dag = inputDag.copy()
   const compactedEventCount = 0
 
-  const orderedEventSequenceNumberStrs = dag.topologicalNodeIds().reverse()
+  const orderedEventSequenceNumberStrs = dag.topologicalNodeIds().toReversed()
 
   // drop root
   orderedEventSequenceNumberStrs.pop()
@@ -29,7 +29,7 @@ export const compactEvents = (inputDag: HistoryDag): { dag: HistoryDag; compacte
     const subDagsForEvent = Array.from(makeSubDagsForEvent(dag, eventNumStr))
     for (const subDag of subDagsForEvent) {
       let shouldRetry = true
-      while (shouldRetry) {
+      while (shouldRetry === true) {
         const subDagsInHistory = findSubDagsInHistory(dag, subDag, eventNumStr)
 
         // console.debug(
@@ -64,7 +64,7 @@ export const compactEvents = (inputDag: HistoryDag): { dag: HistoryDag; compacte
   return { dag, compactedEventCount }
 }
 
-function* makeSubDagsForEvent(inputDag: HistoryDag, eventNumStr: string): Generator<HistoryDag> {
+const makeSubDagsForEvent = function* (inputDag: HistoryDag, eventNumStr: string): Generator<HistoryDag> {
   /** Map from eventNumStr to array of eventNumStrs that are dependencies */
   let nextIterationEls: Map<string, string[]> = new Map([[eventNumStr, []]])
   let previousDag: HistoryDag | undefined
@@ -131,7 +131,7 @@ const findSubDagsInHistory = (
         allOutsideDependencies.push(outsideDependencies)
       }
 
-      if (outsideDependencies.length === 0 && dagReplacesDag(subDag, targetSubDag)) {
+      if (outsideDependencies.length === 0 && dagReplacesDag(subDag, targetSubDag) === true) {
         subDags.push(subDag)
       } else {
         break
@@ -171,7 +171,7 @@ const dagDependsOnDag = (dagA: HistoryDag, dagB: HistoryDag, inputDag: HistoryDa
     for (const edgeEntryA of inputDag.inboundEdgeEntries(nodeAIdStr)) {
       if (edgeEntryA.attributes.type === 'facts') {
         const depNodeIdStr = edgeEntryA.target
-        if (dagB.hasNode(depNodeIdStr)) {
+        if (dagB.hasNode(depNodeIdStr) === true) {
           return true
         }
       }

package/src/sync/next/facts.ts

@@ -1,4 +1,5 @@
 import { notYetImplemented } from '@livestore/utils'
+
 import type {
   EventDefFactInput,
   EventDefFacts,
@@ -129,7 +130,7 @@ const isSubSetMapByValue = (setA: EventDefFacts, setB: EventDefFacts) => {
 /** Check if setA is a subset of setB */
 const isSubSetMapByKey = (setA: EventDefFacts, setB: EventDefFacts) => {
   for (const [key, _value] of setA) {
-    if (!setB.has(key)) {
+    if (setB.has(key) === false) {
       return false
     }
   }
@@ -167,7 +168,7 @@ export const factsToString = (facts: EventDefFacts) => {
 
 export const factsIntersect = (setA: EventDefFacts, setB: EventDefFacts): boolean => {
   for (const [key, _value] of setA) {
-    if (setB.has(key)) {
+    if (setB.has(key) === true) {
       return true
     }
   }
@@ -198,7 +199,7 @@ export const getFactsGroupForEventArgs = ({
         }
       }
 
-      notYetImplemented(`getFactsGroupForEventArgs: ${prop.toString()} is not yet implemented`)
+      return notYetImplemented(`getFactsGroupForEventArgs: ${prop.toString()} is not yet implemented`)
     },
   })
 
@@ -215,9 +216,9 @@ export const getFactsGroupForEventArgs = ({
     return map
   }
   const facts = {
-    modifySet: factsRes?.modify.set ? iterableToMap(factsRes.modify.set) : new Map(),
-    modifyUnset: factsRes?.modify.unset ? iterableToMap(factsRes.modify.unset) : new Map(),
-    depRequire: factsRes?.require ? iterableToMap(factsRes.require) : new Map(),
+    modifySet: factsRes?.modify.set !== undefined ? iterableToMap(factsRes.modify.set) : new Map(),
+    modifyUnset: factsRes?.modify.unset !== undefined ? iterableToMap(factsRes.modify.unset) : new Map(),
+    depRequire: factsRes?.require !== undefined ? iterableToMap(factsRes.require) : new Map(),
     depRead,
   }
 

package/src/sync/next/history-dag-common.ts

@@ -1,5 +1,6 @@
 import { shouldNeverHappen } from '@livestore/utils'
 import { Graph } from '@livestore/utils/effect'
+
 import type { EventDefFactsGroup } from '../../schema/EventDef/mod.ts'
 import * as EventSequenceNumber from '../../schema/EventSequenceNumber/mod.ts'
 
@@ -74,13 +75,13 @@ export class HistoryDag {
   }) {
     this.graph = graph
     this.options = { ...defaultOptions, ...options }
-    this.idToIndex = idToIndex ? new Map(idToIndex) : new Map()
-    this.indexToId = indexToId ? new Map(indexToId) : new Map()
+    this.idToIndex = idToIndex !== undefined ? new Map(idToIndex) : new Map()
+    this.indexToId = indexToId !== undefined ? new Map(indexToId) : new Map()
   }
 
   static create(options?: Partial<HistoryDagOptions>): HistoryDag {
     const graph = Graph.beginMutation(Graph.directed<HistoryDagNode, HistoryDagEdgeAttributes>())
-    return options ? new HistoryDag({ graph, options }) : new HistoryDag({ graph })
+    return options !== undefined ? new HistoryDag({ graph, options }) : new HistoryDag({ graph })
   }
 
   copy(): HistoryDag {
@@ -103,11 +104,13 @@ export class HistoryDag {
   topologicalNodeIds(): Array<string> {
     const walker = Graph.topo(this.graph)
     const indices = Array.from(Graph.indices(walker))
-    return indices.map((index) => this.indexToId.get(index) ?? shouldNeverHappen(`Missing node id for index ${index}`))
+    return indices.map(
+      (index) => this.indexToId.get(index) ?? shouldNeverHappen(`Missing node id for index ${String(index)}`),
+    )
   }
 
   addNode(id: string, attributes: HistoryDagNode): void {
-    if (this.idToIndex.has(id)) {
+    if (this.idToIndex.has(id) === true) {
       shouldNeverHappen(`HistoryDag node ${id} already exists`)
     }
 
@@ -183,7 +186,7 @@ export class HistoryDag {
       return []
     }
     const incoming = this.graph.reverseAdjacency.get(index)
-    return incoming ? [...incoming] : []
+    return incoming !== undefined ? [...incoming] : []
   }
 
   outboundEdgeEntries(id: string): Array<HistoryDagEdgeEntry> {

package/src/sync/next/history-dag.ts

@@ -43,12 +43,12 @@ export const historyDagFromNodes = (dagNodes: HistoryDagNode[], options?: { skip
 
         while (currentSeqNumStr !== EventSequenceNumber.Client.toString(rootParentNum)) {
           const parentEdge = dag.inEdges(currentSeqNumStr).find((e) => dag.getEdgeAttribute(e, 'type') === 'parent')
-          if (!parentEdge) return null
+          if (parentEdge == null) return null
 
           const parentSeqNumStr = dag.source(parentEdge)
           const parentNode = dag.getNodeAttributes(parentSeqNumStr)
 
-          if (parentNode.factsGroup.modifySet.has(factKey) || parentNode.factsGroup.modifyUnset.has(factKey)) {
+          if (parentNode.factsGroup.modifySet.has(factKey) === true || parentNode.factsGroup.modifyUnset.has(factKey) === true) {
             return parentNode
           }
 
@@ -58,7 +58,7 @@ export const historyDagFromNodes = (dagNodes: HistoryDagNode[], options?: { skip
         return null
       })()
 
-      if (depNode) {
+      if (depNode !== null) {
         const depNodeIdStr = EventSequenceNumber.Client.toString(depNode.seqNum)
         const nodeIdStr = EventSequenceNumber.Client.toString(node.seqNum)
         if (dag.edges(depNodeIdStr, nodeIdStr).filter((e) => dag.getEdgeAttributes(e).type === 'facts').length === 0) {

package/src/sync/next/rebase-events.ts

@@ -31,7 +31,7 @@ export type RebaseOutput = {
 export type RebaseFn = (input: RebaseInput) => RebaseOutput
 
 export const defaultRebaseFn: RebaseFn = ({ pendingLocalEvents }) => {
-  if (pendingLocalEvents.some((_) => _.conflictType === 'missing-requirement')) {
+  if (pendingLocalEvents.some((_) => _.conflictType === 'missing-requirement') === true) {
     throw new Error('missing-requirement conflicts must be resolved before rebasing')
   }
 

package/src/sync/next/test/compact-events.calculator.test.ts

@@ -1,6 +1,7 @@
+import { describe, expect, it } from 'vitest'
+
 import { defineEvent } from '@livestore/common/schema'
 import { Schema } from '@livestore/utils/effect'
-import { describe, expect, it } from 'vitest'
 
 import { compactEvents } from '../compact-events.ts'
 import { historyDagFromNodes } from '../history-dag.ts'
@@ -33,7 +34,7 @@ const eventDefs = {
     schema: Schema.Struct({ value: Schema.Number }),
     facts: ({ value }, currentFacts) => ({
       modify: {
-        set: value === 0 || currentFacts.has(facts.multiplyByZero) ? [facts.multiplyByZero] : [],
+        set: value === 0 || currentFacts.has(facts.multiplyByZero) === true ? [facts.multiplyByZero] : [],
         unset: value === 0 ? [] : [facts.multiplyByZero],
       },
     }),

package/src/sync/next/test/compact-events.test.ts

@@ -1,10 +1,11 @@
-import type { EventDefFacts } from '@livestore/common/schema'
 import { describe, expect, it } from 'vitest'
 
+import type { EventDefFacts } from '@livestore/common/schema'
+
 import { compactEvents } from '../compact-events.ts'
-import { historyDagFromNodes } from '../history-dag.ts'
 import type { HistoryDagNode } from '../history-dag-common.ts'
 import { EMPTY_FACT_VALUE } from '../history-dag-common.ts'
+import { historyDagFromNodes } from '../history-dag.ts'
 import { events as eventDefs, printEvent, toEventNodes } from './event-fixtures.ts'
 
 const customStringify = (value: any): string => {
@@ -19,7 +20,7 @@ const customStringify = (value: any): string => {
   if (type === 'number' || type === 'boolean') {
     return String(value)
   }
-  if (Array.isArray(value)) {
+  if (Array.isArray(value) === true) {
     const elements = value.map((el) => customStringify(el))
     return `[${elements.join(', ')}]`
   }

package/src/sync/next/test/event-fixtures.ts

@@ -4,9 +4,9 @@ import type { EventDef } from '../../../schema/EventDef/mod.ts'
 import { defineEvent, defineFacts } from '../../../schema/EventDef/mod.ts'
 import * as EventSequenceNumber from '../../../schema/EventSequenceNumber/mod.ts'
 import { factsSnapshotForDag, getFactsGroupForEventArgs } from '../facts.ts'
-import { historyDagFromNodes } from '../history-dag.ts'
 import type { HistoryDagNode } from '../history-dag-common.ts'
 import { rootEventNode } from '../history-dag-common.ts'
+import { historyDagFromNodes } from '../history-dag.ts'
 
 export const printEvent = ({ seqNum, parentSeqNum, factsGroup, ...rest }: HistoryDagNode) => ({
   seqNum: EventSequenceNumber.Client.toString(seqNum),
@@ -45,7 +45,7 @@ export const events = {
     // {
     facts: ({ id }, currentFacts) =>
       // TODO enable an API along the lines of `map.has(key, value)`
-      currentFacts.has(facts.todoExists(id)) && currentFacts.get(facts.todoIsWriteable(id, true)[0]) === false
+      currentFacts.has(facts.todoExists(id)) === true && currentFacts.get(facts.todoIsWriteable(id, true)[0]) === false
         ? { require: [facts.todoExists(id), facts.todoIsWriteable(id, true)] }
         : { modify: { set: [facts.todoExists(id), facts.todoIsWriteable(id, true), facts.todoTextUpdated(id)] } },
   }),

package/src/sync/sync-backend-kv.ts

@@ -1,4 +1,5 @@
 import { Effect, KeyValueStore, Option } from '@livestore/utils/effect'
+
 import { UnknownError } from '../errors.ts'
 
 export const makeBackendIdHelper = Effect.gen(function* () {

package/src/sync/sync-backend.ts

@@ -9,10 +9,11 @@ import {
   type Stream,
   type SubscriptionRef,
 } from '@livestore/utils/effect'
+
 import type { UnknownError } from '../adapter-types.ts'
 import type * as LiveStoreEvent from '../schema/LiveStoreEvent/mod.ts'
 import type { EventSequenceNumber } from '../schema/mod.ts'
-import type { InvalidPullError, InvalidPushError, IsOfflineError } from './errors.ts'
+import type { BackendIdMismatchError, IsOfflineError, ServerAheadError } from './errors.ts'
 
 export * from './sync-backend-kv.ts'
 
@@ -60,7 +61,7 @@ export type SyncBackend<TSyncMetadata = Schema.JsonValue> = {
        */
       live?: boolean
     },
-  ) => Stream.Stream<PullResItem<TSyncMetadata>, IsOfflineError | InvalidPullError>
+  ) => Stream.Stream<PullResItem<TSyncMetadata>, IsOfflineError | BackendIdMismatchError | UnknownError >
   // TODO support transactions (i.e. group of mutation events which need to be applied together)
   push: (
     /**
@@ -69,7 +70,7 @@ export type SyncBackend<TSyncMetadata = Schema.JsonValue> = {
      * - sequence numbers must be in ascending order
      * */
     batch: ReadonlyArray<LiveStoreEvent.Global.Encoded>,
-  ) => Effect.Effect<void, IsOfflineError | InvalidPushError>
+  ) => Effect.Effect<void, IsOfflineError | BackendIdMismatchError | UnknownError | ServerAheadError>
   ping: Effect.Effect<void, IsOfflineError | UnknownError | Cause.TimeoutException>
   // TODO also expose latency information additionally to whether the backend is connected
   isConnected: SubscriptionRef.SubscriptionRef<boolean>
@@ -178,7 +179,7 @@ export const cursorFromPullResItem = <TSyncMetadata = Schema.JsonValue>(
   metadata: Option.Option<TSyncMetadata>
 }> => {
   const lastEvent = item.batch.at(-1)
-  if (!lastEvent) {
+  if (lastEvent == null) {
     return Option.none()
   }
   return Option.some({ eventSequenceNumber: lastEvent.eventEncoded.seqNum, metadata: lastEvent.metadata })

package/src/sync/sync.ts

@@ -2,6 +2,7 @@ export * from './errors.ts'
 export * as SyncBackend from './sync-backend.ts'
 
 import type { Schema } from '@livestore/utils/effect'
+
 import type { InitialSyncOptions } from '../leader-thread/types.ts'
 import type { SyncBackendConstructor } from './sync-backend.ts'
 
@@ -19,6 +20,26 @@ export type SyncOptions<TPayload = Schema.JsonValue> = {
    * @default 'ignore'
    * */
   onSyncError?: 'shutdown' | 'ignore'
+  /**
+   * What to do when the sync backend identity has changed (i.e. the backend was reset).
+   *
+   * This commonly happens during development when:
+   * - The sync backend state is deleted (e.g. `.wrangler/state` for Cloudflare)
+   * - Running with a `--reset` flag
+   * - Schema changes require re-backfilling data
+   *
+   * Options:
+   * - `'reset'`: Clear local storage (eventlog and state databases) and shutdown.
+   *   The app will need to restart and will sync fresh data from the backend.
+   *   This is the recommended option for development.
+   * - `'shutdown'`: Shutdown without clearing local storage.
+   *   On restart, the client will still have stale data and hit the same error.
+   * - `'ignore'`: Log the error and continue running.
+   *   The client will show stale data but keep running (effectively offline mode).
+   *
+   * @default 'reset'
+   */
+  onBackendIdMismatch?: 'reset' | 'shutdown' | 'ignore'
   /**
    * Whether the sync backend should reactively pull new events from the sync backend
    * @default true