@livestore/common 0.4.0-dev.9 → 0.5.0-dev.0

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

@@ -0,0 +1,87 @@
+import { describe, expect, it } from 'vitest'
+
+import * as EventSequenceNumber from '../../../schema/EventSequenceNumber/mod.ts'
+import { HistoryDag, type HistoryDagNode } from '../history-dag-common.ts'
+
+const makeNode = (global: number, parentGlobal = global - 1): HistoryDagNode => ({
+  seqNum: EventSequenceNumber.Client.Composite.make({ global, client: 0 }),
+  parentSeqNum: EventSequenceNumber.Client.Composite.make({ global: parentGlobal, client: 0 }),
+  name: `event-${global}`,
+  args: {},
+  factsGroup: {
+    depRead: new Map(),
+    depRequire: new Map(),
+    modifySet: new Map(),
+    modifyUnset: new Map(),
+  },
+  meta: undefined,
+  clientId: 'client-id',
+  sessionId: 'session-id',
+})
+
+describe('HistoryDag', () => {
+  it('preserves parallel edge order and removes incident edges with a node', () => {
+    const dag = HistoryDag.create()
+    dag.addNode('a', makeNode(1))
+    dag.addNode('b', makeNode(2))
+    dag.addNode('c', makeNode(3))
+
+    const parentEdge = dag.addEdge('a', 'b', { type: 'parent' })
+    const factsEdge = dag.addEdge('a', 'b', { type: 'facts' })
+    const incomingEdge = dag.addEdge('c', 'b', { type: 'facts' })
+
+    expect(dag.edges('a', 'b')).toEqual([parentEdge, factsEdge])
+    expect(dag.inEdges('b')).toEqual([parentEdge, factsEdge, incomingEdge])
+    expect(dag.inboundEdgeEntries('b')).toEqual([
+      { edge: parentEdge, source: 'a', target: 'b', attributes: { type: 'parent' } },
+      { edge: factsEdge, source: 'a', target: 'b', attributes: { type: 'facts' } },
+      { edge: incomingEdge, source: 'c', target: 'b', attributes: { type: 'facts' } },
+    ])
+    expect(dag.outboundEdgeEntries('a')).toEqual([
+      { edge: parentEdge, source: 'a', target: 'b', attributes: { type: 'parent' } },
+      { edge: factsEdge, source: 'a', target: 'b', attributes: { type: 'facts' } },
+    ])
+    expect(dag.source(parentEdge)).toBe('a')
+    expect(dag.target(parentEdge)).toBe('b')
+    expect(dag.getEdgeAttribute(parentEdge, 'type')).toBe('parent')
+
+    dag.dropNode('b')
+
+    expect(dag.edges('a', 'b')).toEqual([])
+    expect(dag.outboundEdgeEntries('a')).toEqual([])
+    expect(dag.outboundEdgeEntries('c')).toEqual([])
+  })
+
+  it('keeps the adjacency indexes consistent for self-loops', () => {
+    const dag = HistoryDag.create({ allowSelfLoops: true })
+    dag.addNode('a', makeNode(1))
+
+    const edge = dag.addEdge('a', 'a', { type: 'facts' })
+
+    expect(dag.edges('a', 'a')).toEqual([edge])
+    expect(dag.inEdges('a')).toEqual([edge])
+    expect(dag.inboundEdgeEntries('a')).toEqual([{ edge, source: 'a', target: 'a', attributes: { type: 'facts' } }])
+
+    dag.dropNode('a')
+
+    expect(dag.size).toBe(0)
+    expect(dag.edges('a', 'a')).toEqual([])
+  })
+
+  it('copies nodes, facts, and edges without sharing mutable data', () => {
+    const dag = HistoryDag.create()
+    const nodeA = makeNode(1)
+    nodeA.factsGroup.modifySet = new Map([['key', 'value']])
+    dag.addNode('a', nodeA)
+    dag.addNode('b', makeNode(2))
+    dag.addEdge('a', 'b', { type: 'parent' })
+
+    const copy = dag.copy()
+    const copiedNode = copy.getNodeAttributes('a')
+
+    expect(copiedNode).not.toBe(nodeA)
+    expect(copiedNode.factsGroup.modifySet).not.toBe(nodeA.factsGroup.modifySet)
+    expect(copy.outboundEdgeEntries('a')).toMatchObject([{ source: 'a', target: 'b', attributes: { type: 'parent' } }])
+    expect(copy.getEdgeAttributes(copy.edges('a', 'b')[0]!)).not.toBe(dag.getEdgeAttributes(dag.edges('a', 'b')[0]!))
+  })
+})

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

@@ -1,19 +1,22 @@
 import { Effect, KeyValueStore, Option } from '@livestore/utils/effect'
-import { UnexpectedError } from '../errors.ts'
+
+import { UnknownError } from '../errors.ts'
 
 export const makeBackendIdHelper = Effect.gen(function* () {
   const kv = yield* KeyValueStore.KeyValueStore
 
   const backendIdKey = `backendId`
-  const backendIdRef = { current: yield* kv.get(backendIdKey).pipe(UnexpectedError.mapToUnexpectedError) }
+  const backendIdRef = {
+    current: Option.fromUndefinedOr(yield* kv.get(backendIdKey).pipe(UnknownError.mapToUnknownError)),
+  }
 
   const setBackendId = (backendId: string) =>
     Effect.gen(function* () {
-      if (backendIdRef.current._tag === 'None' || backendIdRef.current.value !== backendId) {
+      if (Option.getOrUndefined(backendIdRef.current) !== backendId) {
         backendIdRef.current = Option.some(backendId)
         yield* kv.set(backendIdKey, backendId)
       }
-    }).pipe(UnexpectedError.mapToUnexpectedError)
+    }).pipe(UnknownError.mapToUnknownError)
 
   return {
     lazySet: setBackendId,

package/src/sync/sync-backend.ts

@@ -9,28 +9,29 @@ import {
   type Stream,
   type SubscriptionRef,
 } from '@livestore/utils/effect'
-import type { UnexpectedError } from '../adapter-types.ts'
-import type * as LiveStoreEvent from '../schema/LiveStoreEvent.ts'
+
+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'
 
 /**
  * Those arguments can be used to implement multi-tenancy etc and are passed in from the store.
  */
-export type MakeBackendArgs = {
+export type MakeBackendArgs<TPayload = Schema.Json> = {
   storeId: string
   clientId: string
-  payload: Schema.JsonValue | undefined
+  payload: TPayload | undefined
 }
 
 // TODO rename to `SyncProviderClientConstructor`
-export type SyncBackendConstructor<TSyncMetadata = Schema.JsonValue> = (
-  args: MakeBackendArgs,
+export type SyncBackendConstructor<TSyncMetadata = Schema.Json, TPayload = Schema.Json> = (
+  args: MakeBackendArgs<TPayload>,
 ) => Effect.Effect<
   SyncBackend<TSyncMetadata>,
-  UnexpectedError,
+  UnknownError,
   Scope.Scope | HttpClient.HttpClient | KeyValueStore.KeyValueStore
 >
 
@@ -41,14 +42,14 @@ export type SyncBackendConstructor<TSyncMetadata = Schema.JsonValue> = (
 //   - data center location (e.g. colo on CF workers)
 
 // TODO rename to `SyncProviderClient`
-export type SyncBackend<TSyncMetadata = Schema.JsonValue> = {
+export type SyncBackend<TSyncMetadata = Schema.Json> = {
   /**
    * Can be implemented to prepare a connection to the sync backend to speed up the first pull/push.
    */
-  connect: Effect.Effect<void, IsOfflineError | UnexpectedError, Scope.Scope>
+  connect: Effect.Effect<void, IsOfflineError | UnknownError, Scope.Scope>
   pull: (
     cursor: Option.Option<{
-      eventSequenceNumber: EventSequenceNumber.GlobalEventSequenceNumber
+      eventSequenceNumber: EventSequenceNumber.Global.Type
       /** Metadata is needed by some sync backends */
       metadata: Option.Option<TSyncMetadata>
     }>,
@@ -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: (
     /**
@@ -68,15 +69,15 @@ export type SyncBackend<TSyncMetadata = Schema.JsonValue> = {
      * - Number of events: 1-100
      * - sequence numbers must be in ascending order
      * */
-    batch: ReadonlyArray<LiveStoreEvent.AnyEncodedGlobal>,
-  ) => Effect.Effect<void, IsOfflineError | InvalidPushError>
-  ping: Effect.Effect<void, IsOfflineError | UnexpectedError | Cause.TimeoutException>
+    batch: ReadonlyArray<LiveStoreEvent.Global.Encoded>,
+  ) => Effect.Effect<void, IsOfflineError | BackendIdMismatchError | UnknownError | ServerAheadError>
+  ping: Effect.Effect<void, IsOfflineError | UnknownError | Cause.TimeoutError>
   // TODO also expose latency information additionally to whether the backend is connected
   isConnected: SubscriptionRef.SubscriptionRef<boolean>
   /**
    * Metadata describing the sync backend. (Currently only used by devtools.)
    */
-  metadata: { name: string; description: string } & Record<string, Schema.JsonValue>
+  metadata: { name: string; description: string } & Record<string, Schema.Json>
   /** Information about the sync backend capabilities. */
   supports: {
     /**
@@ -91,13 +92,61 @@ export type SyncBackend<TSyncMetadata = Schema.JsonValue> = {
   }
 }
 
-export const PullResPageInfo = Schema.Union(
+/**
+ * Connectivity metadata emitted by sync backends.
+ */
+export const NetworkStatus = Schema.Struct({
+  /** True when the upstream sync backend is reachable and responding to health checks. */
+  isConnected: Schema.Boolean,
+  /** Unix epoch timestamp (ms) of the latest connectivity state transition. */
+  timestampMs: Schema.Finite,
+  /** Devtools specific metadata describing simulator overrides. */
+  devtools: Schema.Struct({
+    /** Indicates whether the devtools latch forced the client into an offline state. */
+    latchClosed: Schema.Boolean,
+  }),
+}).annotate({ title: 'NetworkStatus' })
+
+export type NetworkStatus = typeof NetworkStatus.Type
+
+/**
+ * Runtime type guard for SyncBackend objects.
+ * Performs lightweight structural checks on the object shape.
+ */
+export const isSyncBackend = (value: unknown): value is SyncBackend<any> => {
+  if (typeof value !== 'object' || value === null) return false
+
+  const v: any = value
+  const hasCoreFns =
+    typeof v.connect === 'function' &&
+    typeof v.pull === 'function' &&
+    typeof v.push === 'function' &&
+    typeof v.ping === 'function'
+
+  const hasSupports =
+    typeof v.supports === 'object' &&
+    v.supports !== null &&
+    typeof v.supports.pullPageInfoKnown === 'boolean' &&
+    typeof v.supports.pullLive === 'boolean'
+
+  const hasMetadata =
+    typeof v.metadata === 'object' &&
+    v.metadata !== null &&
+    typeof v.metadata.name === 'string' &&
+    typeof v.metadata.description === 'string'
+
+  const hasIsConnected = typeof v.isConnected === 'object' && v.isConnected !== null
+
+  return hasCoreFns && hasSupports && hasMetadata && hasIsConnected
+}
+
+export const PullResPageInfo = Schema.Union([
   Schema.TaggedStruct('MoreUnknown', {}),
   Schema.TaggedStruct('MoreKnown', {
-    remaining: Schema.Number,
+    remaining: Schema.Finite,
   }),
   Schema.TaggedStruct('NoMore', {}),
-)
+])
 
 export type PullResPageInfo = typeof PullResPageInfo.Type
 
@@ -105,32 +154,32 @@ export const pageInfoNoMore: PullResPageInfo = { _tag: 'NoMore' } as const
 export const pageInfoMoreUnknown: PullResPageInfo = { _tag: 'MoreUnknown' } as const
 export const pageInfoMoreKnown = (remaining: number): PullResPageInfo => ({ _tag: 'MoreKnown', remaining })
 
-export const pullResItemEmpty = <TSyncMetadata = Schema.JsonValue>(): PullResItem<TSyncMetadata> => ({
+export const pullResItemEmpty = <TSyncMetadata = Schema.Json>(): PullResItem<TSyncMetadata> => ({
   batch: [],
   pageInfo: pageInfoNoMore,
 })
 
-export interface PullResItem<TSyncMetadata = Schema.JsonValue> {
+export interface PullResItem<TSyncMetadata = Schema.Json> {
   batch: ReadonlyArray<{
-    eventEncoded: LiveStoreEvent.AnyEncodedGlobal
+    eventEncoded: LiveStoreEvent.Global.Encoded
     metadata: Option.Option<TSyncMetadata>
   }>
   pageInfo: PullResPageInfo
 }
 
-export const of = <TSyncMetadata = Schema.JsonValue>(obj: SyncBackend<TSyncMetadata>) => obj
+export const of = <TSyncMetadata = Schema.Json>(obj: SyncBackend<TSyncMetadata>) => obj
 
 /**
  * Useful to continue pulling from the last event in the batch.
  */
-export const cursorFromPullResItem = <TSyncMetadata = Schema.JsonValue>(
+export const cursorFromPullResItem = <TSyncMetadata = Schema.Json>(
   item: PullResItem<TSyncMetadata>,
 ): Option.Option<{
-  eventSequenceNumber: EventSequenceNumber.GlobalEventSequenceNumber
+  eventSequenceNumber: EventSequenceNumber.Global.Type
   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

@@ -1,11 +1,13 @@
 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'
 
-export type SyncOptions = {
-  backend?: SyncBackendConstructor<any>
+export type SyncOptions<TPayload = Schema.Json> = {
+  backend?: SyncBackendConstructor<any, TPayload>
   /** @default { _tag: 'Skip' } */
   initialSyncOptions?: InitialSyncOptions
   /**
@@ -18,6 +20,26 @@ export type SyncOptions = {
    * @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