@livestore/common 0.4.0-dev.8 → 0.4.0

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.JsonValue> = {
   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.JsonValue, TPayload = Schema.JsonValue> = (
+  args: MakeBackendArgs<TPayload>,
 ) => Effect.Effect<
   SyncBackend<TSyncMetadata>,
-  UnexpectedError,
+  UnknownError,
   Scope.Scope | HttpClient.HttpClient | KeyValueStore.KeyValueStore
 >
 
@@ -45,10 +46,10 @@ export type SyncBackend<TSyncMetadata = Schema.JsonValue> = {
   /**
    * 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,9 +69,9 @@ 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.TimeoutException>
   // TODO also expose latency information additionally to whether the backend is connected
   isConnected: SubscriptionRef.SubscriptionRef<boolean>
   /**
@@ -91,6 +92,54 @@ export type SyncBackend<TSyncMetadata = Schema.JsonValue> = {
   }
 }
 
+/**
+ * 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.Number,
+  /** Devtools specific metadata describing simulator overrides. */
+  devtools: Schema.Struct({
+    /** Indicates whether the devtools latch forced the client into an offline state. */
+    latchClosed: Schema.Boolean,
+  }),
+}).annotations({ 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', {
@@ -112,7 +161,7 @@ export const pullResItemEmpty = <TSyncMetadata = Schema.JsonValue>(): PullResIte
 
 export interface PullResItem<TSyncMetadata = Schema.JsonValue> {
   batch: ReadonlyArray<{
-    eventEncoded: LiveStoreEvent.AnyEncodedGlobal
+    eventEncoded: LiveStoreEvent.Global.Encoded
     metadata: Option.Option<TSyncMetadata>
   }>
   pageInfo: PullResPageInfo
@@ -126,11 +175,11 @@ export const of = <TSyncMetadata = Schema.JsonValue>(obj: SyncBackend<TSyncMetad
 export const cursorFromPullResItem = <TSyncMetadata = Schema.JsonValue>(
   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.JsonValue> = {
+  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