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

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) === true ? 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) === false) {
+      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) === false) {
+        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'

package/src/schema/EventSequenceNumber/client.ts

@@ -28,7 +28,7 @@ export const make = ClientBrand
  * const defaultSeq = EventSequenceNumber.Client.DEFAULT // 0
  * ```
  */
-export const DEFAULT = 0 as any as Type
+export const DEFAULT = make(0)
 
 /** Default rebase generation (0). Increments each time the client rebases unconfirmed events. */
 export const REBASE_GENERATION_DEFAULT = 0
@@ -91,7 +91,7 @@ export const toString = (seqNum: Composite) => {
  * For full notation documentation, see: contributor-docs/events-notation.md
  */
 export const fromString = (str: string): Composite => {
-  if (!str.startsWith('e')) {
+  if (str.startsWith('e') === false) {
     throw new Error('Invalid event sequence number string: must start with "e"')
   }
 
@@ -111,24 +111,24 @@ export const fromString = (str: string): Composite => {
   const parts = withoutRebase.split('.')
 
   // Validate that parts contain only digits (and possibly empty for client)
-  if (parts[0] === '' || !/^\d+$/.test(parts[0]!)) {
+  if (parts[0] === '' || /^\d+$/.test(parts[0]!) === false) {
     throw new Error('Invalid event sequence number string: invalid number format')
   }
 
-  if (parts.length > 1 && parts[1] !== undefined && (parts[1] === '' || !/^\d+$/.test(parts[1]))) {
+  if (parts.length > 1 && parts[1] !== undefined && (parts[1] === '' || /^\d+$/.test(parts[1]) === false)) {
     throw new Error('Invalid event sequence number string: invalid number format')
   }
 
   const global = Number.parseInt(parts[0]!, 10)
   const client = parts.length > 1 && parts[1] !== undefined ? Number.parseInt(parts[1], 10) : 0
 
-  if (Number.isNaN(global) || Number.isNaN(client) || Number.isNaN(rebaseGeneration)) {
+  if (Number.isNaN(global) === true || Number.isNaN(client) === true || Number.isNaN(rebaseGeneration) === true) {
     throw new TypeError('Invalid event sequence number string: invalid number format')
   }
 
   return {
-    global: global as any as Global,
-    client: client as any as Type,
+    global: makeGlobal(global),
+    client: make(client),
     rebaseGeneration,
   }
 }
@@ -187,7 +187,7 @@ const CompositeSchema = S.Struct({
  * If rebaseGeneration is omitted, defaults to REBASE_GENERATION_DEFAULT (0).
  */
 const makeComposite = (seqNum: CompositeInput): Composite => {
-  return S.is(CompositeSchema)(seqNum)
+  return S.is(CompositeSchema)(seqNum) === true
     ? seqNum
     : S.decodeSync(CompositeSchema)({
         ...seqNum,
@@ -234,11 +234,11 @@ export const nextPair = ({
   isClient: boolean
   rebaseGeneration?: number
 }): CompositePair => {
-  if (isClient) {
+  if (isClient === true) {
     return {
       seqNum: {
         global: seqNum.global,
-        client: (seqNum.client + 1) as any as Type,
+        client: make(seqNum.client + 1),
         rebaseGeneration: rebaseGeneration ?? seqNum.rebaseGeneration,
       },
       parentSeqNum: seqNum,
@@ -247,7 +247,7 @@ export const nextPair = ({
 
   return {
     seqNum: {
-      global: (seqNum.global + 1) as any as Global,
+      global: makeGlobal(seqNum.global + 1),
       client: DEFAULT,
       rebaseGeneration: rebaseGeneration ?? seqNum.rebaseGeneration,
     },

package/src/schema/EventSequenceNumber.test.ts

@@ -1,6 +1,7 @@
-import { Vitest } from '@livestore/utils-dev/node-vitest'
 import { expect } from 'vitest'
 
+import { Vitest } from '@livestore/utils-dev/node-vitest'
+
 import { EventSequenceNumber } from './mod.ts'
 
 Vitest.describe('EventSequenceNumber', () => {

package/src/schema/LiveStoreEvent/client.test.ts

@@ -0,0 +1,97 @@
+import { expect } from 'vitest'
+
+import { Option } from '@livestore/utils/effect'
+import { Vitest } from '@livestore/utils-dev/node-vitest'
+
+import * as EventSequenceNumber from '../EventSequenceNumber/mod.ts'
+import { EncodedWithMeta, isEqualEncoded, type Encoded } from './client.ts'
+
+Vitest.describe('EncodedWithMeta', () => {
+  Vitest.test('toGlobal() produces numeric seqNums through JSON.stringify', () => {
+    const event = new EncodedWithMeta({
+      name: 'test-v1',
+      args: { id: '1' },
+      seqNum: EventSequenceNumber.Client.Composite.make({ global: 5, client: 0 }),
+      parentSeqNum: EventSequenceNumber.Client.Composite.make({ global: 4, client: 0 }),
+      clientId: 'client-1',
+      sessionId: 'session-1',
+      meta: {
+        sessionChangeset: { _tag: 'unset' },
+        syncMetadata: Option.none(),
+        materializerHashLeader: Option.none(),
+        materializerHashSession: Option.none(),
+      },
+    })
+
+    const global = event.toGlobal()
+    const parsed = JSON.parse(JSON.stringify(global))
+
+    expect(parsed.seqNum).toBe(5)
+    expect(parsed.parentSeqNum).toBe(4)
+  })
+})
+
+Vitest.describe('isEqualEncoded', () => {
+  const makeEncodedEvent = (args: unknown): Encoded => ({
+    name: 'testEvent-v1',
+    args,
+    seqNum: EventSequenceNumber.Client.Composite.make({ global: 1, client: 0 }),
+    parentSeqNum: EventSequenceNumber.Client.Composite.make(EventSequenceNumber.Client.ROOT),
+    clientId: 'client-1',
+    sessionId: 'session-1',
+  })
+
+  Vitest.it('should consider events with identical args as equal', () => {
+    const a = makeEncodedEvent({ id: 'abc', text: 'hello' })
+    const b = makeEncodedEvent({ id: 'abc', text: 'hello' })
+    expect(isEqualEncoded(a, b)).toBe(true)
+  })
+
+  Vitest.it('should consider events with different key order in args as equal', () => {
+    const a = makeEncodedEvent({ b: 2, a: 1 })
+    const b = makeEncodedEvent({ a: 1, b: 2 })
+    expect(isEqualEncoded(a, b)).toBe(true)
+  })
+
+  Vitest.it('should consider events with different key order in nested args as equal', () => {
+    const a = makeEncodedEvent({ outer: { b: 2, a: 1 }, x: 'y' })
+    const b = makeEncodedEvent({ x: 'y', outer: { a: 1, b: 2 } })
+    expect(isEqualEncoded(a, b)).toBe(true)
+  })
+
+  Vitest.it('should consider events with different args values as not equal', () => {
+    const a = makeEncodedEvent({ id: 'abc' })
+    const b = makeEncodedEvent({ id: 'def' })
+    expect(isEqualEncoded(a, b)).toBe(false)
+  })
+
+  Vitest.it('should consider events with different args keys as not equal', () => {
+    const a = makeEncodedEvent({ a: 1 })
+    const b = makeEncodedEvent({ b: 1 })
+    expect(isEqualEncoded(a, b)).toBe(false)
+  })
+
+  Vitest.it('should handle null args', () => {
+    const a = makeEncodedEvent(null)
+    const b = makeEncodedEvent(null)
+    expect(isEqualEncoded(a, b)).toBe(true)
+  })
+
+  Vitest.it('should handle array args', () => {
+    const a = makeEncodedEvent([1, 2, 3])
+    const b = makeEncodedEvent([1, 2, 3])
+    expect(isEqualEncoded(a, b)).toBe(true)
+  })
+
+  Vitest.it('should handle empty object args', () => {
+    const a = makeEncodedEvent({})
+    const b = makeEncodedEvent({})
+    expect(isEqualEncoded(a, b)).toBe(true)
+  })
+
+  Vitest.it('should consider events with different names as not equal', () => {
+    const a = { ...makeEncodedEvent({ id: 'abc' }), name: 'eventA' }
+    const b = { ...makeEncodedEvent({ id: 'abc' }), name: 'eventB' }
+    expect(isEqualEncoded(a, b)).toBe(false)
+  })
+})

package/src/schema/LiveStoreEvent/client.ts

@@ -1,4 +1,4 @@
-import { memoizeByRef } from '@livestore/utils'
+import { deepEqual, memoizeByRef } from '@livestore/utils'
 import { Option, Schema } from '@livestore/utils/effect'
 
 import type { EventDef } from '../EventDef/mod.ts'
@@ -175,9 +175,12 @@ export class EncodedWithMeta extends Schema.Class<EncodedWithMeta>('LiveStoreEve
     })
 
   toGlobal = (): Global.Encoded => ({
-    ...this,
+    name: this.name,
+    args: this.args,
     seqNum: this.seqNum.global,
     parentSeqNum: this.parentSeqNum.global,
+    clientId: this.clientId,
+    sessionId: this.sessionId,
   })
 }
 
@@ -191,7 +194,7 @@ export const isEqualEncoded = (a: Encoded, b: Encoded) =>
   a.name === b.name &&
   a.clientId === b.clientId &&
   a.sessionId === b.sessionId &&
-  JSON.stringify(a.args) === JSON.stringify(b.args) // TODO use schema equality here
+  deepEqual(a.args, b.args) // TODO use schema equality here
 
 /**
  * Creates an Effect Schema union for all event types in a schema (with composite sequence numbers).

package/src/schema/schema.ts

@@ -58,7 +58,12 @@ export const isLiveStoreSchema = (value: unknown): value is LiveStoreSchema<any,
   const hasStateMaterializers = v.state?.materializers instanceof Map
   const hasDevtoolsAlias = typeof v.devtools?.alias === 'string'
 
-  return hasEventsMap && hasStateSqliteTables && hasStateMaterializers && hasDevtoolsAlias
+  return (
+    hasEventsMap === true &&
+    hasStateSqliteTables === true &&
+    hasStateMaterializers === true &&
+    hasDevtoolsAlias === true
+  )
 }
 
 // TODO abstract this further away from sqlite/tables
@@ -103,13 +108,13 @@ export const makeSchema = <TInputSchema extends InputSchema>(
 
   const eventsDefsMap = new Map<string, EventDef.AnyWithoutFn>()
 
-  if (isReadonlyArray(inputSchema.events)) {
+  if (isReadonlyArray(inputSchema.events) === true) {
     for (const eventDef of inputSchema.events) {
       eventsDefsMap.set(eventDef.name, eventDef)
     }
   } else {
     for (const eventDef of Object.values(inputSchema.events ?? {})) {
-      if (eventsDefsMap.has(eventDef.name)) {
+      if (eventsDefsMap.has(eventDef.name) === true) {
         shouldNeverHappen(`Duplicate event name: ${eventDef.name}. Please use unique names for events.`)
       }
       eventsDefsMap.set(eventDef.name, eventDef)
@@ -117,7 +122,7 @@ export const makeSchema = <TInputSchema extends InputSchema>(
   }
 
   for (const tableDef of tables.values()) {
-    if (tableIsClientDocumentTable(tableDef) && eventsDefsMap.has(tableDef.set.name) === false) {
+    if (tableIsClientDocumentTable(tableDef) === true && eventsDefsMap.has(tableDef.set.name) === false) {
       eventsDefsMap.set(tableDef.set.name, tableDef.set)
     }
   }

package/src/schema/state/sqlite/client-document-def.test.ts

@@ -1,9 +1,16 @@
-import { Schema } from '@livestore/utils/effect'
 import { describe, expect, test } from 'vitest'
 
+import { Schema } from '@livestore/utils/effect'
+
 import { tables } from '../../../__tests__/fixture.ts'
 import type * as LiveStoreEvent from '../../LiveStoreEvent/mod.ts'
-import { ClientDocumentTableDefSymbol, clientDocument, mergeDefaultValues } from './client-document-def.ts'
+import {
+  ClientDocumentTableDefSymbol,
+  clientDocument,
+  createOptimisticEventSchema,
+  mergeDefaultValues,
+} from './client-document-def.ts'
+import { getResultSchema } from './query-builder/impl.ts'
 
 describe('client document table', () => {
   test('set event', () => {
@@ -248,6 +255,139 @@ describe('client document table', () => {
       `)
     })
   })
+
+  /** Ensures optimistic decoding stays robust when persisted JSON is incompatible. */
+  describe('optimistic schema', () => {
+    /** Models persisted JSON using epoch numbers + base64 while app code expects Date + Uint8Array. */
+    const valueSchema = Schema.Struct({
+      createdAt: Schema.DateFromNumber,
+      avatar: Schema.Uint8ArrayFromBase64,
+    })
+    const defaultValue = {
+      createdAt: new Date(0),
+      avatar: new Uint8Array(),
+    }
+    const invalidPayloads: Array<{ label: string; value: unknown }> = [
+      { label: 'decoded-shape JSON', value: { createdAt: new Date(0), avatar: new Uint8Array([1, 2]) } },
+      { label: 'wrong types', value: { createdAt: 'not-a-number', avatar: { nested: 'bad' } } },
+      { label: 'missing required fields', value: {} },
+    ]
+    const validPayload = { createdAt: 42, avatar: 'AQI=' }
+    const extraFieldsPayload = { createdAt: 42, avatar: 'AQI=', extra: 'ignored' }
+
+    test.each(invalidPayloads)('decodes invalid persisted JSON ($label)', ({ value }) => {
+      const optimisticSchema = createOptimisticEventSchema({
+        valueSchema,
+        defaultValue,
+        partialSet: false,
+      })
+      const rowSchema = Schema.parseJson(optimisticSchema)
+
+      expect(Schema.decodeUnknownSync(rowSchema)(JSON.stringify(value))).toEqual(defaultValue)
+    })
+
+    test('decodes valid persisted JSON (encoded shape)', () => {
+      const optimisticSchema = createOptimisticEventSchema({
+        valueSchema,
+        defaultValue,
+        partialSet: false,
+      })
+      const rowSchema = Schema.parseJson(optimisticSchema)
+
+      expect(Schema.decodeUnknownSync(rowSchema)(JSON.stringify(validPayload))).toEqual({
+        createdAt: new Date(42),
+        avatar: new Uint8Array([1, 2]),
+      })
+    })
+
+    test('decodes valid persisted JSON with extra fields', () => {
+      const optimisticSchema = createOptimisticEventSchema({
+        valueSchema,
+        defaultValue,
+        partialSet: false,
+      })
+      const rowSchema = Schema.parseJson(optimisticSchema)
+
+      expect(Schema.decodeUnknownSync(rowSchema)(JSON.stringify(extraFieldsPayload))).toEqual({
+        createdAt: new Date(42),
+        avatar: new Uint8Array([1, 2]),
+      })
+    })
+
+    test.each(invalidPayloads)('decodes clientDocument rowSchema with invalid JSON ($label)', ({ value }) => {
+      const Doc = clientDocument({
+        name: 'test_numbers',
+        schema: valueSchema,
+        default: { value: defaultValue },
+        partialSet: false,
+      })
+      const row = {
+        id: 'row-1',
+        value: JSON.stringify(value),
+      }
+
+      expect(Schema.decodeUnknownSync(Doc.rowSchema)(row)).toEqual({ id: 'row-1', value: defaultValue })
+    })
+
+    test('decodes clientDocument rowSchema with valid encoded JSON', () => {
+      const Doc = clientDocument({
+        name: 'test_numbers',
+        schema: valueSchema,
+        default: { value: defaultValue },
+        partialSet: false,
+      })
+      const row = {
+        id: 'row-1',
+        value: JSON.stringify(validPayload),
+      }
+
+      expect(Schema.decodeUnknownSync(Doc.rowSchema)(row)).toEqual({
+        id: 'row-1',
+        value: { createdAt: new Date(42), avatar: new Uint8Array([1, 2]) },
+      })
+    })
+
+    test.each(invalidPayloads)('decodes RowQuery result schema with invalid JSON ($label)', ({ value }) => {
+      const Doc = clientDocument({
+        name: 'test_numbers',
+        schema: valueSchema,
+        default: { value: defaultValue },
+        partialSet: false,
+      })
+      const query = Doc.get('row-1')
+      const resultSchema = getResultSchema(query)
+      const rawDbResults = [
+        {
+          id: 'row-1',
+          value: JSON.stringify(value),
+        },
+      ]
+
+      expect(Schema.decodeUnknownSync(resultSchema)(rawDbResults)).toEqual(defaultValue)
+    })
+
+    test('decodes RowQuery result schema with valid encoded JSON', () => {
+      const Doc = clientDocument({
+        name: 'test_numbers',
+        schema: valueSchema,
+        default: { value: defaultValue },
+        partialSet: false,
+      })
+      const query = Doc.get('row-1')
+      const resultSchema = getResultSchema(query)
+      const rawDbResults = [
+        {
+          id: 'row-1',
+          value: JSON.stringify(validPayload),
+        },
+      ]
+
+      expect(Schema.decodeUnknownSync(resultSchema)(rawDbResults)).toEqual({
+        createdAt: new Date(42),
+        avatar: new Uint8Array([1, 2]),
+      })
+    })
+  })
 })
 
 const patchId = (muationEvent: LiveStoreEvent.Input.Decoded) => {
@@ -255,7 +395,6 @@ const patchId = (muationEvent: LiveStoreEvent.Input.Decoded) => {
   const id = `00000000-0000-0000-0000-000000000000`
   return { ...muationEvent, id }
 }
-
 describe('mergeDefaultValues', () => {
   test('merges values from both objects', () => {
     const defaults = { a: 1, b: 2 }