@livestore/common 0.4.0-dev.8 → 0.4.0

package/src/rematerialize-from-eventlog.ts

@@ -1,14 +1,17 @@
 import { memoizeByRef } from '@livestore/utils'
 import { Chunk, Effect, Option, Schema, Stream } from '@livestore/utils/effect'
 
-import { type SqliteDb, UnexpectedError } from './adapter-types.ts'
+import { type SqliteDb, UnknownError } from './adapter-types.ts'
 import type { MaterializeEvent } from './leader-thread/mod.ts'
 import type { EventDef, LiveStoreSchema } from './schema/mod.ts'
-import { EventSequenceNumber, getEventDef, LiveStoreEvent, SystemTables } from './schema/mod.ts'
+import { EventSequenceNumber, LiveStoreEvent, resolveEventDef, SystemTables } from './schema/mod.ts'
 import type { PreparedBindValues } from './util.ts'
 import { sql } from './util.ts'
 
-export const rematerializeFromEventlog = ({
+/** Parse JSON string to unknown value */
+const jsonParse = Schema.decodeUnknownSync(Schema.parseJson())
+
+export const rematerializeFromEventlog = Effect.fn('@livestore/common:rematerializeFromEventlog')(function* ({
   dbEventlog,
   // TODO re-use this db when bringing back the boot in-memory db implementation
   // db,
@@ -21,59 +24,69 @@ export const rematerializeFromEventlog = ({
   schema: LiveStoreSchema
   onProgress: (_: { done: number; total: number }) => Effect.Effect<void>
   materializeEvent: MaterializeEvent
-}) =>
-  Effect.gen(function* () {
+}) {
     const eventsCount = dbEventlog.select<{ count: number }>(
       `SELECT COUNT(*) AS count FROM ${SystemTables.EVENTLOG_META_TABLE}`,
     )[0]!.count
 
     const hashEventDef = memoizeByRef((event: EventDef.AnyWithoutFn) => Schema.hash(event.schema))
 
-    const processEvent = (row: SystemTables.EventlogMetaRow) =>
-      Effect.gen(function* () {
-        const eventDef = getEventDef(schema, row.name)
+    const processEvent = Effect.fn(`@livestore/common:rematerializeFromEventlog:processEvent`)(function* (
+      row: SystemTables.EventlogMetaRow,
+    ) {
+      const args = jsonParse(row.argsJson)
+      const eventEncoded = LiveStoreEvent.Client.EncodedWithMeta.make({
+        name: row.name,
+        args,
+        seqNum: {
+          global: row.seqNumGlobal,
+          client: row.seqNumClient,
+          rebaseGeneration: row.seqNumRebaseGeneration,
+        },
+        parentSeqNum: {
+          global: row.parentSeqNumGlobal,
+          client: row.parentSeqNumClient,
+          rebaseGeneration: row.parentSeqNumRebaseGeneration,
+        },
+        clientId: row.clientId,
+        sessionId: row.sessionId,
+      })
 
-        if (hashEventDef(eventDef.eventDef) !== row.schemaHash) {
-          yield* Effect.logWarning(
-            `Schema hash mismatch for event definition ${row.name}. Trying to materialize event anyway.`,
-          )
-        }
+      const resolution = yield* resolveEventDef(schema, {
+        operation: '@livestore/common:rematerializeFromEventlog:processEvent',
+        event: eventEncoded,
+      }).pipe(UnknownError.mapToUnknownError)
 
-        const args = JSON.parse(row.argsJson)
+      if (resolution._tag === 'unknown') {
+        // Old snapshots can contain newer events. Skip until the runtime has
+        // been updated; the event stays in the log for future replays.
+        return
+      }
 
-        // Checking whether the schema has changed in an incompatible way
-        yield* Schema.decodeUnknown(eventDef.eventDef.schema)(args).pipe(
-          Effect.mapError((cause) =>
-            UnexpectedError.make({
-              cause,
-              note: `\
+      const { eventDef } = resolution
+
+      if (hashEventDef(eventDef) !== row.schemaHash) {
+        yield* Effect.logWarning(
+          `Schema hash mismatch for event definition ${row.name}. Trying to materialize event anyway.`,
+        )
+      }
+
+      // Checking whether the schema has changed in an incompatible way
+      yield* Schema.decodeUnknown(eventDef.schema)(args).pipe(
+        Effect.mapError((cause) =>
+          UnknownError.make({
+            cause,
+            note: `\
 There was an error during rematerializing from the eventlog while decoding
 the persisted event args for event definition "${row.name}".
 This likely means the schema has changed in an incompatible way.
 `,
-            }),
-          ),
-        )
+          }),
+        ),
+      )
 
-        const eventEncoded = LiveStoreEvent.EncodedWithMeta.make({
-          seqNum: {
-            global: row.seqNumGlobal,
-            client: row.seqNumClient,
-            rebaseGeneration: row.seqNumRebaseGeneration,
-          },
-          parentSeqNum: {
-            global: row.parentSeqNumGlobal,
-            client: row.parentSeqNumClient,
-            rebaseGeneration: row.parentSeqNumRebaseGeneration,
-          },
-          name: row.name,
-          args,
-          clientId: row.clientId,
-          sessionId: row.sessionId,
-        })
-
-        yield* materializeEvent(eventEncoded, { skipEventlog: true })
-      }).pipe(Effect.withSpan(`@livestore/common:rematerializeFromEventlog:processEvent`))
+      yield* materializeEvent(eventEncoded, { skipEventlog: true })
+    })
 
     const CHUNK_SIZE = 100
 
@@ -91,21 +104,21 @@ LIMIT ${CHUNK_SIZE}
       SystemTables.EventlogMetaRow
     >({ _tag: 'Initial' }, (item) => {
       // End stream if no more rows
-      if (Chunk.isChunk(item) && item.length === 0) return Option.none()
+      if (Chunk.isChunk(item) === true && item.length === 0) return Option.none()
 
-      const lastId = Chunk.isChunk(item)
+      const lastId = Chunk.isChunk(item) === true
         ? Chunk.last(item).pipe(
             Option.map((_) => ({ global: _.seqNumGlobal, client: _.seqNumClient })),
-            Option.getOrElse(() => EventSequenceNumber.ROOT),
+            Option.getOrElse(() => EventSequenceNumber.Client.ROOT),
           )
-        : EventSequenceNumber.ROOT
+        : EventSequenceNumber.Client.ROOT
       const nextItem = Chunk.fromIterable(
         stmt.select<SystemTables.EventlogMetaRow>({
           $seqNumGlobal: lastId?.global,
           $seqNumClient: lastId?.client,
         } as any as PreparedBindValues),
       )
-      const prevItem = Chunk.isChunk(item) ? item : Chunk.empty()
+      const prevItem = Chunk.isChunk(item) === true ? item : Chunk.empty()
       return Option.some([prevItem, nextItem])
     }).pipe(
       Stream.bufferChunks({ capacity: 2 }),
@@ -119,7 +132,4 @@ LIMIT ${CHUNK_SIZE}
       ),
       Stream.runDrain,
     )
-  }).pipe(
-    Effect.withPerformanceMeasure('@livestore/common:rematerializeFromEventlog'),
-    Effect.withSpan('@livestore/common:rematerializeFromEventlog'),
-  )
+}, Effect.withPerformanceMeasure('@livestore/common:rematerializeFromEventlog'))

package/src/schema/EventDef/define.ts

@@ -0,0 +1,217 @@
+/**
+ * Event Definition Functions
+ *
+ * This module provides functions for creating event definitions in LiveStore.
+ * Events are the core unit of state change - all mutations to the database
+ * happen through events that are committed to the eventlog.
+ *
+ * @example
+ * ```ts
+ * import { Events } from '@livestore/livestore'
+ * import { Schema } from 'effect'
+ *
+ * // Define events for your application
+ * export const events = {
+ *   // Synced events are sent to the sync backend
+ *   todoCreated: Events.synced({
+ *     name: 'v1.TodoCreated',
+ *     schema: Schema.Struct({ id: Schema.String, text: Schema.String }),
+ *   }),
+ *
+ *   // Client-only events stay local (useful for UI state)
+ *   uiStateSet: Events.clientOnly({
+ *     name: 'UiStateSet',
+ *     schema: Schema.Struct({ selectedId: Schema.NullOr(Schema.String) }),
+ *   }),
+ * }
+ * ```
+ * @module
+ */
+
+import { shouldNeverHappen } from '@livestore/utils'
+import { Schema } from '@livestore/utils/effect'
+
+import type { EventDef } from './event-def.ts'
+import type { EventDefFactInput, EventDefFacts } from './facts.ts'
+
+/** Options for defining an event. */
+export type DefineEventOptions<TTo, TDerived extends boolean = false> = {
+  /**
+   * Callback defining fact constraints for this event.
+   * @experimental This feature is not fully implemented yet.
+   */
+  facts?: (
+    args: TTo,
+    currentFacts: EventDefFacts,
+  ) => {
+    modify?: {
+      /** Facts to set (create or update). */
+      set?: Iterable<EventDefFactInput>
+      /** Facts to unset (remove). */
+      unset?: Iterable<EventDefFactInput>
+    }
+    /**
+     * Facts that must exist for this event to be valid.
+     * Used for history constraints and compaction rules.
+     */
+    require?: Iterable<EventDefFactInput>
+  }
+
+  /**
+   * When true, the event is only synced within the same client's sessions
+   * but never sent to the sync backend. Useful for UI state.
+   * @default false
+   */
+  clientOnly?: boolean
+
+  /**
+   * When true, marks this as a derived event that cannot have materializers.
+   * @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
+}
+
+/**
+ * Creates an event definition with full control over all options.
+ *
+ * This is the low-level function for creating events. For most cases,
+ * prefer using `synced()` or `clientOnly()` which provide simpler APIs.
+ *
+ * @example
+ * ```ts
+ * const customEvent = defineEvent({
+ *   name: 'v1.CustomEvent',
+ *   schema: Schema.Struct({ data: Schema.String }),
+ *   clientOnly: false,
+ *   derived: false,
+ * })
+ * ```
+ */
+export const defineEvent = <TName extends string, TType, TEncoded = TType, TDerived extends boolean = false>(
+  args: {
+    name: TName
+    schema: Schema.Schema<TType, TEncoded>
+  } & DefineEventOptions<TType, TDerived>,
+): EventDef<TName, TType, TEncoded, TDerived> => {
+  const { name, schema, ...options } = args
+
+  const makePartialEvent = (args: TType) => {
+    const res = Schema.validateEither(schema)(args)
+    if (res._tag === 'Left') {
+      shouldNeverHappen(`Invalid event args for event '${name}':`, res.left.message, '\n')
+    }
+    return { name: name, args }
+  }
+
+  Object.defineProperty(makePartialEvent, 'name', { value: name })
+  Object.defineProperty(makePartialEvent, 'schema', { value: schema })
+  Object.defineProperty(makePartialEvent, 'encoded', {
+    value: (args: TEncoded) => ({ name: name, args }),
+  })
+
+  Object.defineProperty(makePartialEvent, 'options', {
+    value: {
+      clientOnly: options?.clientOnly ?? false,
+      facts: options?.facts !== undefined
+        ? (args, currentFacts) => {
+            const res = options.facts!(args, currentFacts)
+            return {
+              modify: {
+                set: res.modify?.set !== undefined ? new Set(res.modify.set) : new Set(),
+                unset: res.modify?.unset !== undefined ? new Set(res.modify.unset) : new Set(),
+              },
+              require: res.require !== undefined ? new Set(res.require) : new Set(),
+            }
+          }
+        : undefined,
+      derived: options?.derived ?? false,
+      deprecated: options?.deprecated,
+    } satisfies EventDef.Any['options'],
+  })
+
+  return makePartialEvent as EventDef<TName, TType, TEncoded, TDerived>
+}
+
+/**
+ * Creates a synced event definition.
+ *
+ * Synced events are sent to the sync backend and distributed to all connected
+ * clients. Use this for collaborative data that should be shared across users
+ * and devices.
+ *
+ * Event names should be versioned (e.g., `v1.TodoCreated`) to support
+ * schema evolution over time.
+ *
+ * @example
+ * ```ts
+ * import { Events } from '@livestore/livestore'
+ * import { Schema } from 'effect'
+ *
+ * const todoCreated = Events.synced({
+ *   name: 'v1.TodoCreated',
+ *   schema: Schema.Struct({
+ *     id: Schema.String,
+ *     text: Schema.String,
+ *     completed: Schema.Boolean,
+ *   }),
+ * })
+ *
+ * // Commit the event
+ * store.commit(todoCreated({ id: 'abc', text: 'Buy milk', completed: false }))
+ * ```
+ */
+export const synced = <TName extends string, TType, TEncoded = TType>(
+  args: {
+    name: TName
+    schema: Schema.Schema<TType, TEncoded>
+  } & Omit<DefineEventOptions<TType>, 'derived' | 'clientOnly'>,
+): EventDef<TName, TType, TEncoded> => defineEvent({ ...args, clientOnly: false })
+
+/**
+ * Creates a client-only event definition.
+ *
+ * Client-only events are synced within the same client's sessions (e.g., across
+ * browser tabs) but are never sent to the sync backend. Use this for local UI
+ * state like selected items, filter settings, or draft content.
+ *
+ * Note: Client-only events still require materializers and are stored in the
+ * local eventlog, they just don't participate in server-side sync.
+ *
+ * @example
+ * ```ts
+ * import { Events } from '@livestore/livestore'
+ * import { Schema } from 'effect'
+ *
+ * const uiStateSet = Events.clientOnly({
+ *   name: 'UiStateSet',
+ *   schema: Schema.Struct({
+ *     selectedTodoId: Schema.NullOr(Schema.String),
+ *     filterMode: Schema.Literal('all', 'active', 'completed'),
+ *   }),
+ * })
+ *
+ * // Update local UI state
+ * store.commit(uiStateSet({ selectedTodoId: 'abc', filterMode: 'active' }))
+ * ```
+ */
+export const clientOnly = <TName extends string, TType, TEncoded = TType>(
+  args: {
+    name: TName
+    schema: Schema.Schema<TType, TEncoded>
+  } & Omit<DefineEventOptions<TType>, 'derived' | 'clientOnly'>,
+): EventDef<TName, TType, TEncoded> => defineEvent({ ...args, clientOnly: true })

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

@@ -0,0 +1,129 @@
+import { afterEach, beforeEach, describe, expect, test } from 'vitest'
+
+import { Effect, Logger, Schema } from '@livestore/utils/effect'
+
+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) === 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()
+}