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

package/src/leader-thread/stream-events.ts

@@ -0,0 +1,201 @@
+import type { Subscribable } from '@livestore/utils/effect'
+import { Chunk, Effect, Option, Queue, Stream } from '@livestore/utils/effect'
+import { EventSequenceNumber, type LiveStoreEvent } from '../schema/mod.ts'
+import type * as SyncState from '../sync/syncstate.ts'
+import * as Eventlog from './eventlog.ts'
+import type { LeaderSqliteDb, StreamEventsOptions } from './types.ts'
+
+/**
+ * Streams events for leader-thread adapters.
+ *
+ * Provides a continuous stream from the eventlog as the upstream head advances.
+ * When an until event is passed in the stream finalizes upon reaching it.
+ *
+ * The batch size is set to 100 by default as this was meassured to provide the
+ * best performance and 1000 as the upper limit.
+ *
+ * Adapters that call this helper:
+ * - `packages/@livestore/adapter-web/src/in-memory/in-memory-adapter.ts`
+ * - `packages/@livestore/adapter-web/src/web-worker/leader-worker/make-leader-worker.ts`
+ * - `packages/@livestore/adapter-node/src/client-session/adapter.ts`
+ * - `packages/@livestore/adapter-node/src/make-leader-worker.ts`
+ * - `packages/@livestore/adapter-cloudflare/src/make-adapter.ts`
+ *
+ * Each caller resolves dependencies inside the leader scope before invoking this helper,
+ * so the stream stays environment-agnostic and does not leak `LeaderThreadCtx` into runtime
+ * entry points such as `Store.eventsStream`.
+ *
+ * Test files:
+ * Unit: `tests/package-common/src/leader-thread/stream-events.test.ts`
+ * Integration: `packages/@livestore/livestore/src/store/store-eventstream.test.ts`
+ * Performance: `tests/perf-eventlog/tests/suites/event-streaming.test.ts`
+ *
+ * Optimization explorations
+ *
+ * In order to alleviate the occurence of many small queries when the syncState
+ * is sequentially progressing quickly we have explored some time-based batching
+ * approaches. It remains to be determined if and when the added complexity of
+ * these approaches are worth the benefit. They come with some drawbacks such as
+ * degraded time to first event or general performance degredation for larger
+ * query steps. These aspects can likely be mitigated with some more work but
+ * that is best assessed when we have a final implementation of event streaming
+ * with support for session and leader level streams.
+ *
+ * Fetch plans into a Sink
+ * https://gist.github.com/slashv/f1223689f2d1171d2eeb60a2823f4c7c
+ *
+ * Fetch plans into sink and decompose into windows
+ * https://gist.github.com/slashv/a8f55f50121c080937f42e44b4039ac8
+ *
+ * Mailbox and Latch approach (suggestion by Tim Smart)
+ * https://gist.github.com/slashv/d6b12395c85415bf0d3363372a1636c3
+ */
+export const streamEventsWithSyncState = ({
+  dbEventlog,
+  syncState,
+  options,
+}: {
+  dbEventlog: LeaderSqliteDb
+  syncState: Subscribable.Subscribable<SyncState.SyncState>
+  options: StreamEventsOptions
+}): Stream.Stream<LiveStoreEvent.Client.Encoded> => {
+  const initialCursor = options.since ?? EventSequenceNumber.Client.ROOT
+  const batchSize = options.batchSize ?? 100
+
+  return Stream.unwrapScoped(
+    Effect.gen(function* () {
+      /**
+       * Single-element Queue allows suspending the event stream until head
+       * advances because Queue.take is a suspending effect. SubscriptionRef in
+       * comparrison lacks a primitive for suspending a stream until a new value
+       * is set and would require polling.
+       *
+       * The use of a sliding Queue here is useful since it ensures only the
+       * lastest head from syncState is the one present on the queue without the
+       * need for manual substitution.
+       */
+      const headQueue = yield* Queue.sliding<EventSequenceNumber.Client.Composite>(1)
+
+      /**
+       * We run a separate fiber which listens to changes in syncState and
+       * offer the latest head to the headQueue. Keeping track of the previous
+       * value is done to prevent syncState changes unrelated to the
+       * upstreamHead triggering empty queries.
+       *
+       * When we implement support for leader and session level streams
+       * this will need to be adapted to support the relevant value from
+       * syncState that we are interested in tracking.
+       */
+      let prevGlobalHead = -1
+      yield* syncState.changes.pipe(
+        Stream.map((state) => state.upstreamHead),
+        Stream.filter((head) => {
+          if (head.global > prevGlobalHead) {
+            prevGlobalHead = head.global
+            return true
+          }
+          return false
+        }),
+        Stream.runForEach((head) => Queue.offer(headQueue, head)),
+        Effect.forkScoped,
+      )
+
+      return Stream.paginateChunkEffect(
+        { cursor: initialCursor, head: EventSequenceNumber.Client.ROOT },
+        ({ cursor, head }) =>
+          Effect.gen(function* () {
+            /**
+             * Early check guards agains:
+             * since === until : Prevent empty query
+             * since > until : Incorrectly inverted interval
+             */
+            if (options.until && EventSequenceNumber.Client.isGreaterThanOrEqual(cursor, options.until)) {
+              return [Chunk.empty(), Option.none()]
+            }
+
+            /**
+             * There are two scenarios where we take the next head from the headQueue:
+             *
+             * 1. We need to wait for the head to advance
+             * The Stream suspends until a new head is available on the headQueue
+             *
+             * 2. Head has advanced during itteration
+             * While itterating towards the lastest head taken from the headQueue
+             * in increments of batchSize it's possible the head could have
+             * advanced. This leads to a suboptimal amount of queries. Therefor we
+             * check if the headQueue is full which tells us that there's a new
+             * head available to take. Example:
+             *
+             * batchSize: 2
+             *
+             * --> head at: e3
+             * First query: e0 -> e2 (two events)
+             * --> head advances to: e4
+             * Second query: e2 -> e3 (one event but we could have taken 2)
+             * --> Take the new head of e4
+             * Third query: e3 -> e4 (unnecessary third query)
+             *
+             *
+             * To define the target, which will be used as the temporary until
+             * marker for the eventlog query, we select the lowest of three possible values:
+             *
+             * hardStop: A user supplied until marker
+             * current cursor + batchSize: A batchSize step towards the latest head from headQueue
+             * nextHead: The latest head from headQueue
+             */
+            const waitForHead = EventSequenceNumber.Client.isGreaterThanOrEqual(cursor, head)
+            const maybeHead = waitForHead
+              ? yield* Queue.take(headQueue).pipe(Effect.map(Option.some))
+              : yield* Queue.poll(headQueue)
+            const nextHead = Option.getOrElse(maybeHead, () => head)
+            const hardStop = options.until?.global ?? Number.POSITIVE_INFINITY
+            const target = EventSequenceNumber.Client.Composite.make({
+              global: Math.min(hardStop, cursor.global + batchSize, nextHead.global),
+              client: EventSequenceNumber.Client.DEFAULT,
+            })
+
+            /**
+             * Eventlog.getEventsFromEventlog returns a Chunk from each
+             * query which is what we emit at each itteration.
+             */
+            const chunk = yield* Eventlog.getEventsFromEventlog({
+              dbEventlog,
+              options: {
+                ...options,
+                since: cursor,
+                until: target,
+              },
+            })
+
+            /**
+             * We construct the state for the following itteration of the stream
+             * loop by setting the current target as the since cursor and pass
+             * along the latest head.
+             *
+             * If we have the reached the user supplied until marker we signal the
+             * finalization of the stream by passing Option.none() instead.
+             */
+            const reachedUntil =
+              options.until !== undefined && EventSequenceNumber.Client.isGreaterThanOrEqual(target, options.until)
+
+            const nextState: Option.Option<{
+              cursor: EventSequenceNumber.Client.Composite
+              head: EventSequenceNumber.Client.Composite
+            }> = reachedUntil ? Option.none() : Option.some({ cursor: target, head: nextHead })
+
+            const spanAttributes = {
+              'livestore.streamEvents.cursor.global': cursor.global,
+              'livestore.streamEvents.target.global': target.global,
+              'livestore.streamEvents.batchSize': batchSize,
+              'livestore.streamEvents.waitedForHead': waitForHead,
+            }
+
+            return yield* Effect.succeed<[Chunk.Chunk<LiveStoreEvent.Client.Encoded>, typeof nextState]>([
+              chunk,
+              nextState,
+            ]).pipe(Effect.withSpan('@livestore/common:streamEvents:segment', { attributes: spanAttributes }))
+          }),
+      )
+    }),
+  )
+}

package/src/leader-thread/types.ts

@@ -24,7 +24,7 @@ import type {
   SyncBackend,
   UnknownError,
 } from '../index.ts'
-import type { EventSequenceNumber, LiveStoreEvent, LiveStoreSchema } from '../schema/mod.ts'
+import { EventSequenceNumber, type LiveStoreEvent, type LiveStoreSchema } from '../schema/mod.ts'
 import type * as SyncState from '../sync/syncstate.ts'
 import type { ShutdownChannel } from './shutdown-channel.ts'
 
@@ -134,6 +134,54 @@ export type InitialBlockingSyncContext = {
   update: (_: { pageInfo: SyncBackend.PullResPageInfo; processed: number }) => Effect.Effect<void>
 }
 
+export const STREAM_EVENTS_BATCH_SIZE_DEFAULT = 100
+export const STREAM_EVENTS_BATCH_SIZE_MAX = 1_000
+
+export const StreamEventsOptionsFields = {
+  since: Schema.optional(EventSequenceNumber.Client.Composite),
+  until: Schema.optional(EventSequenceNumber.Client.Composite),
+  filter: Schema.optional(Schema.Array(Schema.String)),
+  clientIds: Schema.optional(Schema.Array(Schema.String)),
+  sessionIds: Schema.optional(Schema.Array(Schema.String)),
+  batchSize: Schema.optional(Schema.Int.pipe(Schema.between(1, STREAM_EVENTS_BATCH_SIZE_MAX))),
+  includeClientOnly: Schema.optional(Schema.Boolean),
+} as const
+
+export const StreamEventsOptionsSchema = Schema.Struct(StreamEventsOptionsFields)
+
+export interface StreamEventsOptions {
+  /**
+   * Only include events after this logical timestamp (exclusive).
+   * Defaults to `EventSequenceNumber.Client.ROOT` when omitted.
+   */
+  since?: EventSequenceNumber.Client.Composite
+  /**
+   * Only include events up to this logical timestamp (inclusive).
+   */
+  until?: EventSequenceNumber.Client.Composite
+  /**
+   * Only include events of the given names.
+   */
+  filter?: ReadonlyArray<string>
+  /**
+   * Only include events from specific client identifiers.
+   */
+  clientIds?: ReadonlyArray<string>
+  /**
+   * Only include events from specific session identifiers.
+   */
+  sessionIds?: ReadonlyArray<string>
+  /**
+   * Number of events to fetch in each batch when streaming from the eventlog.
+   * Defaults to 100.
+   */
+  batchSize?: number
+  /**
+   * Include client-only events (i.e. events with a positive client sequence number).
+   */
+  includeClientOnly?: boolean
+}
+
 export interface LeaderSyncProcessor {
   /** Used by client sessions to subscribe to upstream sync state changes */
   pull: (args: {

package/src/otel.ts

@@ -2,6 +2,16 @@ import { makeNoopTracer } from '@livestore/utils'
 import { Effect, identity, Layer, OtelTracer } from '@livestore/utils/effect'
 import * as otel from '@opentelemetry/api'
 
+export const OtelLiveDummy: Layer.Layer<OtelTracer.OtelTracer> = Layer.suspend(() => {
+  const OtelTracerLive = Layer.succeed(OtelTracer.OtelTracer, makeNoopTracer())
+
+  const TracingLive = Layer.unwrapEffect(Effect.map(OtelTracer.make, Layer.setTracer)).pipe(
+    Layer.provideMerge(OtelTracerLive),
+  )
+
+  return TracingLive
+})
+
 export const provideOtel =
   ({ otelTracer, parentSpanContext }: { otelTracer?: otel.Tracer; parentSpanContext?: otel.Context }) =>
   <A, E, R>(effect: Effect.Effect<A, E, R>): Effect.Effect<A, E, Exclude<R, OtelTracer.OtelTracer>> => {

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'