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

package/src/leader-thread/LeaderSyncProcessor.ts

@@ -37,6 +37,11 @@ import { rollback } from './materialize-event.ts'
 import type { InitialBlockingSyncContext, LeaderSyncProcessor } from './types.ts'
 import { LeaderThreadCtx } from './types.ts'
 
+// WORKAROUND: @effect/opentelemetry mis-parses `Span.addEvent(name, attributes)` and treats the attributes object as a
+// time input, causing `TypeError: {} is not iterable` at runtime.
+// Upstream: https://github.com/Effect-TS/effect/pull/5929
+// TODO: simplify back to the 2-arg overload once the upstream fix is released and adopted.
+
 type LocalPushQueueItem = [
   event: LiveStoreEvent.Client.EncodedWithMeta,
   deferred: Deferred.Deferred<void, LeaderAheadError> | undefined,
@@ -476,10 +481,14 @@ const backgroundApplyLocalPushes = ({
       )
 
       if (droppedItems.length > 0) {
-        otelSpan?.addEvent(`push:drop-old-generation`, {
-          droppedCount: droppedItems.length,
-          currentRebaseGeneration,
-        })
+        otelSpan?.addEvent(
+          `push:drop-old-generation`,
+          {
+            droppedCount: droppedItems.length,
+            currentRebaseGeneration,
+          },
+          undefined,
+        )
 
         /**
          * Dropped pushes may still have a deferred awaiting completion.
@@ -517,20 +526,28 @@ const backgroundApplyLocalPushes = ({
 
       switch (mergeResult._tag) {
         case 'unknown-error': {
-          otelSpan?.addEvent(`push:unknown-error`, {
-            batchSize: newEvents.length,
-            newEvents: TRACE_VERBOSE ? JSON.stringify(newEvents) : undefined,
-          })
+          otelSpan?.addEvent(
+            `push:unknown-error`,
+            {
+              batchSize: newEvents.length,
+              newEvents: TRACE_VERBOSE ? JSON.stringify(newEvents) : undefined,
+            },
+            undefined,
+          )
           return yield* new UnknownError({ cause: mergeResult.message })
         }
         case 'rebase': {
           return shouldNeverHappen('The leader thread should never have to rebase due to a local push')
         }
         case 'reject': {
-          otelSpan?.addEvent(`push:reject`, {
-            batchSize: newEvents.length,
-            mergeResult: TRACE_VERBOSE ? JSON.stringify(mergeResult) : undefined,
-          })
+          otelSpan?.addEvent(
+            `push:reject`,
+            {
+              batchSize: newEvents.length,
+              mergeResult: TRACE_VERBOSE ? JSON.stringify(mergeResult) : undefined,
+            },
+            undefined,
+          )
 
           // TODO: how to test this?
           const nextRebaseGeneration = currentRebaseGeneration + 1
@@ -585,10 +602,14 @@ const backgroundApplyLocalPushes = ({
         leaderHead: mergeResult.newSyncState.localHead,
       })
 
-      otelSpan?.addEvent(`push:advance`, {
-        batchSize: newEvents.length,
-        mergeResult: TRACE_VERBOSE ? JSON.stringify(mergeResult) : undefined,
-      })
+      otelSpan?.addEvent(
+        `push:advance`,
+        {
+          batchSize: newEvents.length,
+          mergeResult: TRACE_VERBOSE ? JSON.stringify(mergeResult) : undefined,
+        },
+        undefined,
+      )
 
       // Don't sync client-local events
       const filteredBatch = mergeResult.newEvents.filter((eventEncoded) => {
@@ -719,10 +740,14 @@ const backgroundBackendPulling = ({
         if (mergeResult._tag === 'reject') {
           return shouldNeverHappen('The leader thread should never reject upstream advances')
         } else if (mergeResult._tag === 'unknown-error') {
-          otelSpan?.addEvent(`pull:unknown-error`, {
-            newEventsCount: newEvents.length,
-            newEvents: TRACE_VERBOSE ? JSON.stringify(newEvents) : undefined,
-          })
+          otelSpan?.addEvent(
+            `pull:unknown-error`,
+            {
+              newEventsCount: newEvents.length,
+              newEvents: TRACE_VERBOSE ? JSON.stringify(newEvents) : undefined,
+            },
+            undefined,
+          )
           return yield* new UnknownError({ cause: mergeResult.message })
         }
 
@@ -731,12 +756,16 @@ const backgroundBackendPulling = ({
         Eventlog.updateBackendHead(dbEventlog, newBackendHead)
 
         if (mergeResult._tag === 'rebase') {
-          otelSpan?.addEvent(`pull:rebase[${mergeResult.newSyncState.localHead.rebaseGeneration}]`, {
-            newEventsCount: newEvents.length,
-            newEvents: TRACE_VERBOSE ? JSON.stringify(newEvents) : undefined,
-            rollbackCount: mergeResult.rollbackEvents.length,
-            mergeResult: TRACE_VERBOSE ? JSON.stringify(mergeResult) : undefined,
-          })
+          otelSpan?.addEvent(
+            `pull:rebase[${mergeResult.newSyncState.localHead.rebaseGeneration}]`,
+            {
+              newEventsCount: newEvents.length,
+              newEvents: TRACE_VERBOSE ? JSON.stringify(newEvents) : undefined,
+              rollbackCount: mergeResult.rollbackEvents.length,
+              mergeResult: TRACE_VERBOSE ? JSON.stringify(mergeResult) : undefined,
+            },
+            undefined,
+          )
 
           const globalRebasedPendingEvents = mergeResult.newSyncState.pending.filter((event) => {
             const eventDef = schema.eventsDefsMap.get(event.name)
@@ -757,10 +786,14 @@ const backgroundBackendPulling = ({
             leaderHead: mergeResult.newSyncState.localHead,
           })
         } else {
-          otelSpan?.addEvent(`pull:advance`, {
-            newEventsCount: newEvents.length,
-            mergeResult: TRACE_VERBOSE ? JSON.stringify(mergeResult) : undefined,
-          })
+          otelSpan?.addEvent(
+            `pull:advance`,
+            {
+              newEventsCount: newEvents.length,
+              mergeResult: TRACE_VERBOSE ? JSON.stringify(mergeResult) : undefined,
+            },
+            undefined,
+          )
 
           // Ensure push fiber is active after advance by restarting with current pending (non-client) events
           const globalPendingEvents = mergeResult.newSyncState.pending.filter((event) => {
@@ -870,10 +903,14 @@ const backgroundBackendPushing = ({
         yield* devtoolsLatch.await
       }
 
-      otelSpan?.addEvent('backend-push', {
-        batchSize: queueItems.length,
-        batch: TRACE_VERBOSE ? JSON.stringify(queueItems) : undefined,
-      })
+      otelSpan?.addEvent(
+        'backend-push',
+        {
+          batchSize: queueItems.length,
+          batch: TRACE_VERBOSE ? JSON.stringify(queueItems) : undefined,
+        },
+        undefined,
+      )
 
       // Push with declarative retry/backoff using Effect schedules
       // - Exponential backoff starting at 1s and doubling (1s, 2s, 4s, 8s, 16s, 30s ...)
@@ -900,15 +937,19 @@ const backgroundBackendPushing = ({
 
         const retries = iteration.recurrence
         if (retries > 0 && pushResult._tag === 'Right') {
-          otelSpan?.addEvent('backend-push-retry-success', { retries, batchSize: queueItems.length })
+          otelSpan?.addEvent('backend-push-retry-success', { retries, batchSize: queueItems.length }, undefined)
         }
 
         if (pushResult._tag === 'Left') {
-          otelSpan?.addEvent('backend-push-error', {
-            error: pushResult.left.toString(),
-            retries,
-            batchSize: queueItems.length,
-          })
+          otelSpan?.addEvent(
+            'backend-push-error',
+            {
+              error: pushResult.left.toString(),
+              retries,
+              batchSize: queueItems.length,
+            },
+            undefined,
+          )
           const error = pushResult.left
           if (
             error._tag === 'IsOfflineError' ||

package/src/leader-thread/leader-worker-devtools.ts

@@ -138,6 +138,17 @@ const listenToDevtools = ({
 
           switch (decodedEvent._tag) {
             case 'LSD.Leader.Ping': {
+              // Check version mismatch and respond with VersionMismatch if versions don't match
+              if (decodedEvent.liveStoreVersion !== liveStoreVersion) {
+                yield* sendMessage(
+                  Devtools.Leader.VersionMismatch.make({
+                    ...reqPayload,
+                    appVersion: liveStoreVersion,
+                    receivedVersion: decodedEvent.liveStoreVersion,
+                  }),
+                )
+                return
+              }
               yield* sendMessage(Devtools.Leader.Pong.make({ ...reqPayload }))
               return
             }

package/src/leader-thread/make-leader-thread-layer.ts

@@ -55,6 +55,8 @@ export interface MakeLeaderThreadLayerParams {
   dbEventlog: LeaderSqliteDb
   devtoolsOptions: DevtoolsOptions
   shutdownChannel: ShutdownChannel
+  /** Boot warning to emit (e.g., OPFS unavailable in private browsing) */
+  bootWarning?: BootStatus
   params?: {
     localPushBatchSize?: number
     backendPushBatchSize?: number
@@ -80,6 +82,7 @@ export const makeLeaderThreadLayer = ({
   dbEventlog,
   devtoolsOptions,
   shutdownChannel,
+  bootWarning,
   params,
   testing,
 }: MakeLeaderThreadLayerParams): Layer.Layer<LeaderThreadCtx, UnknownError, Scope.Scope | HttpClient.HttpClient> =>
@@ -89,6 +92,11 @@ export const makeLeaderThreadLayer = ({
 
     const bootStatusQueue = yield* Queue.unbounded<BootStatus>().pipe(Effect.acquireRelease(Queue.shutdown))
 
+    // Emit boot warning if present (e.g., OPFS unavailable in private browsing)
+    if (bootWarning !== undefined) {
+      yield* Queue.offer(bootStatusQueue, bootWarning)
+    }
+
     const dbEventlogMissing = !hasEventlogTables(dbEventlog)
 
     // Either happens on initial boot or if schema changes

package/src/leader-thread/materialize-event.ts

@@ -3,6 +3,7 @@ import { Effect, Option, ReadonlyArray, Schema } from '@livestore/utils/effect'
 
 import { MaterializeError, MaterializerHashMismatchError, type SqliteDb } from '../adapter-types.ts'
 import { getExecStatementsFromMaterializer, hashMaterializerResults } from '../materializer-helper.ts'
+import { logDeprecationWarnings } from '../schema/EventDef/deprecated.ts'
 import type { LiveStoreSchema } from '../schema/mod.ts'
 import { EventSequenceNumber, resolveEventDef, SystemTables, UNKNOWN_EVENT_SCHEMA_HASH } from '../schema/mod.ts'
 import { insertRow } from '../sql-queries/index.ts'
@@ -62,6 +63,9 @@ export const makeMaterializeEvent = ({
 
         const { eventDef, materializer } = resolution
 
+        // Log deprecation warnings for deprecated events/fields
+        yield* logDeprecationWarnings(eventDef, eventEncoded.args as Record<string, unknown>)
+
         const execArgsArr = getExecStatementsFromMaterializer({
           eventDef,
           materializer,

package/src/schema/EventDef/define.ts

@@ -69,6 +69,21 @@ export type DefineEventOptions<TTo, TDerived extends boolean = false> = {
    * @default false
    */
   derived?: TDerived
+
+  /**
+   * Marks the entire event as deprecated with a reason message.
+   * When this event is committed, a warning will be logged.
+   *
+   * @example
+   * ```ts
+   * Events.synced({
+   *   name: 'v1.TodoRenamed',
+   *   schema: Schema.Struct({ id: Schema.String, name: Schema.String }),
+   *   deprecated: "Use 'v1.TodoUpdated' instead",
+   * })
+   * ```
+   */
+  deprecated?: string
 }
 
 /**
@@ -125,6 +140,7 @@ export const defineEvent = <TName extends string, TType, TEncoded = TType, TDeri
           }
         : undefined,
       derived: options?.derived ?? false,
+      deprecated: options?.deprecated,
     } satisfies EventDef.Any['options'],
   })
 

package/src/schema/EventDef/deprecated.test.ts

@@ -0,0 +1,128 @@
+import { Effect, Logger, Schema } from '@livestore/utils/effect'
+import { afterEach, beforeEach, describe, expect, test } from 'vitest'
+
+import { synced } from './define.ts'
+import {
+  deprecated,
+  findDeprecatedFieldsWithValues,
+  getDeprecatedReason,
+  isDeprecated,
+  logDeprecationWarnings,
+  resetDeprecationWarnings,
+} from './deprecated.ts'
+
+describe('deprecated annotations', () => {
+  test('adds deprecation annotation to schema', () => {
+    const schema = Schema.String.pipe(deprecated('Use newField instead'))
+    expect(isDeprecated(schema)).toBe(true)
+    expect(getDeprecatedReason(schema)._tag).toBe('Some')
+  })
+
+  test('works with optional fields in Struct', () => {
+    const struct = Schema.Struct({
+      oldField: Schema.optional(Schema.String).pipe(deprecated('Legacy')),
+    })
+    expect(findDeprecatedFieldsWithValues(struct, { oldField: 'x' })).toEqual([{ field: 'oldField', reason: 'Legacy' }])
+  })
+
+  test('non-deprecated schemas return false', () => {
+    expect(isDeprecated(Schema.String)).toBe(false)
+  })
+
+  test('ignores deprecated fields without values', () => {
+    const schema = Schema.Struct({
+      id: Schema.String,
+      old: Schema.optional(Schema.String).pipe(deprecated('x')),
+    })
+    expect(findDeprecatedFieldsWithValues(schema, { id: '1' })).toEqual([])
+  })
+
+  test('finds multiple deprecated fields', () => {
+    const schema = Schema.Struct({
+      a: Schema.optional(Schema.String).pipe(deprecated('A')),
+      b: Schema.optional(Schema.String).pipe(deprecated('B')),
+    })
+    const result = findDeprecatedFieldsWithValues(schema, { a: '1', b: '2' })
+    expect(result).toHaveLength(2)
+  })
+})
+
+describe('logDeprecationWarnings', () => {
+  let logs: unknown[][]
+
+  beforeEach(() => {
+    resetDeprecationWarnings()
+    logs = []
+  })
+
+  afterEach(() => resetDeprecationWarnings())
+
+  const run = (effect: Effect.Effect<void>) =>
+    Effect.runSync(
+      effect.pipe(
+        Effect.provide(
+          Logger.replace(
+            Logger.defaultLogger,
+            Logger.make(({ message }) => logs.push(message as unknown[])),
+          ),
+        ),
+      ),
+    )
+
+  test('logs event deprecation warning', () => {
+    const event = synced({ name: 'Old', schema: Schema.Struct({ id: Schema.String }), deprecated: 'Use New' })
+    run(logDeprecationWarnings(event, { id: '1' }))
+    expect(logs).toEqual([['@livestore/schema:deprecated-event', { event: 'Old', reason: 'Use New' }]])
+  })
+
+  test('logs field deprecation warning', () => {
+    const event = synced({
+      name: 'Ev',
+      schema: Schema.Struct({ old: Schema.optional(Schema.String).pipe(deprecated('Use new')) }),
+    })
+    run(logDeprecationWarnings(event, { old: 'x' }))
+    expect(logs).toEqual([['@livestore/schema:deprecated-field', { event: 'Ev', field: 'old', reason: 'Use new' }]])
+  })
+
+  test('deduplicates event warnings', () => {
+    const event = synced({ name: 'Dup', schema: Schema.Struct({ id: Schema.String }), deprecated: 'x' })
+    run(logDeprecationWarnings(event, { id: '1' }))
+    run(logDeprecationWarnings(event, { id: '2' }))
+    expect(logs).toHaveLength(1)
+  })
+
+  test('deduplicates field warnings', () => {
+    const event = synced({
+      name: 'DupField',
+      schema: Schema.Struct({ old: Schema.optional(Schema.String).pipe(deprecated('x')) }),
+    })
+    run(logDeprecationWarnings(event, { old: 'a' }))
+    run(logDeprecationWarnings(event, { old: 'b' }))
+    expect(logs).toHaveLength(1)
+  })
+
+  test('no warning for non-deprecated event', () => {
+    const event = synced({ name: 'Normal', schema: Schema.Struct({ id: Schema.String }) })
+    run(logDeprecationWarnings(event, { id: '1' }))
+    expect(logs).toHaveLength(0)
+  })
+
+  test('no warning when deprecated field is undefined', () => {
+    const event = synced({
+      name: 'Unused',
+      schema: Schema.Struct({ old: Schema.optional(Schema.String).pipe(deprecated('x')) }),
+    })
+    run(logDeprecationWarnings(event, {}))
+    expect(logs).toHaveLength(0)
+  })
+
+  test('logs both event and field warnings', () => {
+    const event = synced({
+      name: 'Both',
+      schema: Schema.Struct({ old: Schema.optional(Schema.String).pipe(deprecated('F')) }),
+      deprecated: 'E',
+    })
+    run(logDeprecationWarnings(event, { old: 'x' }))
+    expect(logs).toHaveLength(2)
+  })
+})

package/src/schema/EventDef/deprecated.ts

@@ -0,0 +1,175 @@
+/**
+ * Deprecation Annotations for Events
+ *
+ * This module provides utilities for marking event fields and entire events as deprecated.
+ * When a deprecated field is used or a deprecated event is committed, a warning is logged.
+ *
+ * @example
+ * ```ts
+ * import { Events } from '@livestore/livestore'
+ * import { Schema } from 'effect'
+ * import { deprecated } from '@livestore/common/schema'
+ *
+ * // Field-level deprecation
+ * const todoUpdated = Events.synced({
+ *   name: 'v1.TodoUpdated',
+ *   schema: Schema.Struct({
+ *     id: Schema.String,
+ *     title: Schema.optional(Schema.String).pipe(deprecated("Use 'text' instead")),
+ *     text: Schema.optional(Schema.String),
+ *   }),
+ * })
+ *
+ * // Event-level deprecation
+ * const todoRenamed = Events.synced({
+ *   name: 'v1.TodoRenamed',
+ *   schema: Schema.Struct({ id: Schema.String, name: Schema.String }),
+ *   deprecated: "Use 'v1.TodoUpdated' instead",
+ * })
+ * ```
+ * @module
+ */
+
+import type { Schema } from '@livestore/utils/effect'
+import { Effect, Option, SchemaAST } from '@livestore/utils/effect'
+
+import type { EventDef } from './event-def.ts'
+
+/** Symbol used to mark schemas as deprecated. */
+export const DeprecatedId = Symbol.for('livestore/schema/annotations/deprecated')
+
+/**
+ * Marks a schema field as deprecated with a reason message.
+ * When an event is committed with a deprecated field that has a value,
+ * a warning will be logged.
+ *
+ * Works with both Schema types and PropertySignatures (from Schema.optional).
+ *
+ * @param reason - Explanation of why this field is deprecated and what to use instead
+ * @returns A function that adds the deprecation annotation to the schema
+ *
+ * @example
+ * ```ts
+ * const schema = Schema.Struct({
+ *   oldField: Schema.optional(Schema.String).pipe(deprecated("Use 'newField' instead")),
+ *   newField: Schema.optional(Schema.String),
+ * })
+ * ```
+ */
+export const deprecated =
+  (reason: string) =>
+  <T extends { annotations: (annotations: { readonly [DeprecatedId]?: string }) => T }>(schema: T): T =>
+    schema.annotations({ [DeprecatedId]: reason })
+
+/**
+ * Checks if a schema has a deprecation annotation.
+ *
+ * @param schema - The schema to check
+ * @returns The deprecation reason if deprecated, None otherwise
+ */
+export const getDeprecatedReason = <A, I, R>(schema: Schema.Schema<A, I, R>): Option.Option<string> =>
+  SchemaAST.getAnnotation<string>(DeprecatedId)(schema.ast)
+
+/**
+ * Checks if a schema is deprecated.
+ *
+ * @param schema - The schema to check
+ * @returns true if the schema is deprecated
+ */
+export const isDeprecated = <A, I, R>(schema: Schema.Schema<A, I, R>): boolean =>
+  Option.isSome(getDeprecatedReason(schema))
+
+/**
+ * Finds deprecated fields with values in the given event arguments.
+ * This walks through a Struct schema and checks each property for deprecation.
+ *
+ * @param schema - The event schema (expected to be a Struct)
+ * @param args - The event arguments
+ * @returns Array of objects containing field name and deprecation reason
+ */
+export const findDeprecatedFieldsWithValues = (
+  schema: Schema.Schema.All,
+  args: Record<string, unknown>,
+): Array<{ field: string; reason: string }> => {
+  const result: Array<{ field: string; reason: string }> = []
+  const ast = schema.ast
+
+  // Handle TypeLiteral (Struct) schemas
+  if (ast._tag === 'TypeLiteral') {
+    for (const prop of ast.propertySignatures) {
+      const fieldName = String(prop.name)
+      const fieldValue = args[fieldName]
+
+      // Only check fields that have a value (not undefined)
+      if (fieldValue !== undefined) {
+        // Check deprecation on the property signature itself (for Schema.optional(...).pipe(deprecated(...)))
+        const propAnnotations = prop.annotations as Record<symbol, unknown> | undefined
+        const deprecationReason = propAnnotations?.[DeprecatedId] as string | undefined
+
+        // Also check deprecation on the type (for direct field deprecation)
+        const typeDeprecation = SchemaAST.getAnnotation<string>(DeprecatedId)(prop.type)
+
+        const reason = deprecationReason ?? (Option.isSome(typeDeprecation) ? typeDeprecation.value : undefined)
+        if (reason !== undefined) {
+          result.push({ field: fieldName, reason })
+        }
+      }
+    }
+  }
+
+  return result
+}
+
+/** Set of event names that have already logged deprecation warnings. */
+const warnedDeprecatedEvents = new Set<string>()
+
+/** Map of event+field combinations that have already logged deprecation warnings. */
+const warnedDeprecatedFields = new Set<string>()
+
+/**
+ * Logs deprecation warnings for an event using Effect.logWarning.
+ * Checks both event-level and field-level deprecation, with deduplication.
+ *
+ * @param eventDef - The event definition to check
+ * @param args - The event arguments
+ * @returns An Effect that logs warnings for any deprecations found
+ */
+export const logDeprecationWarnings = (
+  eventDef: EventDef.AnyWithoutFn,
+  args: Record<string, unknown>,
+): Effect.Effect<void> =>
+  Effect.gen(function* () {
+    const eventName = eventDef.name
+
+    // Check for event-level deprecation
+    const eventDeprecation = eventDef.options.deprecated
+    if (eventDeprecation !== undefined && !warnedDeprecatedEvents.has(eventName)) {
+      warnedDeprecatedEvents.add(eventName)
+      yield* Effect.logWarning('@livestore/schema:deprecated-event', {
+        event: eventName,
+        reason: eventDeprecation,
+      })
+    }
+
+    // Check for deprecated fields with values
+    const deprecatedFields = findDeprecatedFieldsWithValues(eventDef.schema, args)
+    for (const { field, reason } of deprecatedFields) {
+      const key = `${eventName}:${field}`
+      if (!warnedDeprecatedFields.has(key)) {
+        warnedDeprecatedFields.add(key)
+        yield* Effect.logWarning('@livestore/schema:deprecated-field', {
+          event: eventName,
+          field,
+          reason,
+        })
+      }
+    }
+  })
+
+/**
+ * Resets the deprecation warning state. Useful for testing.
+ */
+export const resetDeprecationWarnings = (): void => {
+  warnedDeprecatedEvents.clear()
+  warnedDeprecatedFields.clear()
+}

package/src/schema/EventDef/event-def.ts

@@ -51,6 +51,11 @@ export type EventDef<TName extends string, TType, TEncoded = TType, TDerived ext
 
     /** Whether this is a derived event. Derived events cannot have materializers. */
     derived: TDerived
+
+    /**
+     * Deprecation reason for this event. When set, a warning is logged at commit time.
+     */
+    deprecated: string | undefined
   }
 
   /**

package/src/schema/EventDef/mod.ts

@@ -1,4 +1,5 @@
 export * from './define.ts'
+export * from './deprecated.ts'
 export * from './event-def.ts'
 export * from './facts.ts'
 export * from './materializer.ts'