@livestore/common 0.4.0-dev.9 → 0.5.0-dev.0

package/src/materializer-helper.ts

@@ -1,11 +1,10 @@
-import { isDevEnv, isNil, isReadonlyArray } from '@livestore/utils'
-import { Hash, Option, Schema } from '@livestore/utils/effect'
+import { isDevEnv } from '@livestore/utils'
+import { Hash, Option, Predicate, ReadonlyArray, Schema } from '@livestore/utils/effect'
 
 import type { SqliteDb } from './adapter-types.ts'
-import { SessionIdSymbol } from './adapter-types.ts'
-import type { EventDef, Materializer, MaterializerContextQuery, MaterializerResult } from './schema/EventDef.ts'
-import type * as LiveStoreEvent from './schema/LiveStoreEvent.ts'
-import { getEventDef, type LiveStoreSchema } from './schema/schema.ts'
+import type { EventDef, Materializer, MaterializerContextQuery, MaterializerResult } from './schema/EventDef/mod.ts'
+import type * as LiveStoreEvent from './schema/LiveStoreEvent/mod.ts'
+import type { LiveStoreSchema } from './schema/schema.ts'
 import type { QueryBuilder } from './schema/state/sqlite/query-builder/api.ts'
 import { isQueryBuilder } from './schema/state/sqlite/query-builder/api.ts'
 import { getResultSchema } from './schema/state/sqlite/query-builder/impl.ts'
@@ -24,8 +23,8 @@ export const getExecStatementsFromMaterializer = ({
   dbState: SqliteDb
   /** Both encoded and decoded events are supported to reduce the number of times we need to decode/encode */
   event:
-    | { decoded: LiveStoreEvent.AnyDecoded; encoded: undefined }
-    | { decoded: undefined; encoded: LiveStoreEvent.AnyEncoded }
+    | { decoded: LiveStoreEvent.Client.Decoded; encoded: undefined }
+    | { decoded: undefined; encoded: LiveStoreEvent.Client.Encoded }
 }): ReadonlyArray<{
   statementSql: string
   bindValues: PreparedBindValues
@@ -34,14 +33,15 @@ export const getExecStatementsFromMaterializer = ({
   const eventDecoded =
     event.decoded === undefined
       ? {
-          ...event.encoded!,
-          args: Schema.decodeUnknownSync(eventDef.schema)(event.encoded!.args),
+          ...event.encoded,
+          args: Schema.decodeUnknownSync(eventDef.schema)(event.encoded.args),
         }
       : event.decoded
 
-  const eventArgsEncoded = isNil(event.decoded?.args)
-    ? undefined
-    : Schema.encodeUnknownSync(eventDef.schema)(event.decoded!.args)
+  const eventArgsEncoded =
+    Predicate.isNotUndefined(event.decoded) === true && Predicate.isNotNullish(event.decoded.args) === true
+      ? Schema.encodeUnknownSync(eventDef.schema)(event.decoded.args)
+      : undefined
 
   const query: MaterializerContextQuery = (
     rawQueryOrQueryBuilder:
@@ -51,11 +51,11 @@ export const getExecStatementsFromMaterializer = ({
         }
       | QueryBuilder.Any,
   ) => {
-    if (isQueryBuilder(rawQueryOrQueryBuilder)) {
+    if (isQueryBuilder(rawQueryOrQueryBuilder) === true) {
       const { query, bindValues } = rawQueryOrQueryBuilder.asSql()
       const rawResults = dbState.select(query, prepareBindValues(bindValues, query))
       const resultSchema = getResultSchema(rawQueryOrQueryBuilder)
-      return Schema.decodeSync(resultSchema)(rawResults)
+      return Schema.decodeUnknownSync(resultSchema)(rawResults)
     } else {
       const { query, bindValues } = rawQueryOrQueryBuilder
       return dbState.select(query, prepareBindValues(bindValues, query))
@@ -85,9 +85,20 @@ export const getExecStatementsFromMaterializer = ({
 
 export const makeMaterializerHash =
   ({ schema, dbState }: { schema: LiveStoreSchema; dbState: SqliteDb }) =>
-  (event: LiveStoreEvent.AnyEncoded): Option.Option<number> => {
-    if (isDevEnv()) {
-      const { eventDef, materializer } = getEventDef(schema, event.name)
+  (event: LiveStoreEvent.Client.Encoded): Option.Option<number> => {
+    if (isDevEnv() === true) {
+      // Hashing is only needed during dev-mode diagnostics. Skip work entirely for
+      // unknown events (no definition/materializer) so we do not introduce noisy
+      // warnings while still returning `Option.none()` to disable hash checks.
+      const eventDef = schema.eventsDefsMap.get(event.name)
+      const materializer = schema.state.materializers.get(event.name)
+      if (eventDef === undefined || materializer === undefined) {
+        return Option.none()
+      }
+      // For known events we replay the materializer with the encoded payload and
+      // hash the resulting SQL statements. This lets us cheaply detect
+      // side-effects or logic drift between leader/client materializers without
+      // mutating the underlying state.
       const materializerResults = getExecStatementsFromMaterializer({
         eventDef,
         materializer,
@@ -115,10 +126,10 @@ const fromMaterializerResult = (
   bindValues: BindValues
   writeTables: ReadonlySet<string> | undefined
 }> => {
-  if (isReadonlyArray(materializerResult)) {
+  if (ReadonlyArray.isArray<MaterializerResult | ReadonlyArray<MaterializerResult>>(materializerResult) === true) {
     return materializerResult.flatMap(fromMaterializerResult)
   }
-  if (isQueryBuilder(materializerResult)) {
+  if (isQueryBuilder(materializerResult) === true) {
     const { query, bindValues, usedTables } = materializerResult.asSql()
     return [{ sql: query, bindValues: bindValues as BindValues, writeTables: usedTables }]
   } else if (typeof materializerResult === 'string') {
@@ -133,32 +144,3 @@ const fromMaterializerResult = (
     ]
   }
 }
-
-// NOTE we should explore whether there is a more elegant solution
-// e.g. by leveraging the schema to replace the sessionIdSymbol
-export const replaceSessionIdSymbol = (
-  bindValues: Record<string, unknown> | ReadonlyArray<unknown>,
-  sessionId: string,
-) => {
-  deepReplaceValue(bindValues, SessionIdSymbol, sessionId)
-}
-
-const deepReplaceValue = <S, R>(input: any, searchValue: S, replaceValue: R): void => {
-  if (Array.isArray(input)) {
-    for (const i in input) {
-      if (input[i] === searchValue) {
-        input[i] = replaceValue
-      } else {
-        deepReplaceValue(input[i], searchValue, replaceValue)
-      }
-    }
-  } else if (typeof input === 'object' && input !== null) {
-    for (const key in input) {
-      if (input[key] === searchValue) {
-        input[key] = replaceValue
-      } else {
-        deepReplaceValue(input[key], searchValue, replaceValue)
-      }
-    }
-  }
-}

package/src/otel.ts

@@ -1,28 +1,30 @@
+import * as otel from '@opentelemetry/api'
+
 import { makeNoopTracer } from '@livestore/utils'
+import type { Tracer } from '@livestore/utils/effect'
 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 = OtelTracer.layerWithoutOtelTracer.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>> => {
+  <A, E, R>(effect: Effect.Effect<A, E, R>): Effect.Effect<A, E, Exclude<R, OtelTracer.OtelTracer | Tracer.Tracer>> => {
     const OtelTracerLive = Layer.succeed(OtelTracer.OtelTracer, otelTracer ?? makeNoopTracer())
 
-    const TracingLive = Layer.unwrapEffect(Effect.map(OtelTracer.make, Layer.setTracer)).pipe(
+    const TracingLive = OtelTracer.layerWithoutOtelTracer.pipe(
       Layer.provideMerge(OtelTracerLive),
-    ) as any as Layer.Layer<OtelTracer.OtelTracer>
+    ) as any as Layer.Layer<OtelTracer.OtelTracer | Tracer.Tracer>
 
     return effect.pipe(
-      parentSpanContext
+      parentSpanContext !== undefined
         ? Effect.withParentSpan(OtelTracer.makeExternalSpan(otel.trace.getSpanContext(parentSpanContext)!))
         : identity,
       Effect.provide(TracingLive),
     )
   }
-
-export const getDurationMsFromSpan = (span: otel.Span): number => {
-  const durationHr: [seconds: number, nanos: number] = (span as any)._duration
-  return durationHr[0] * 1000 + durationHr[1] / 1_000_000
-}
-
-export const getStartTimeHighResFromSpan = (span: otel.Span): DOMHighResTimeStamp =>
-  (span as any)._performanceStartTime as DOMHighResTimeStamp

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 { Effect, Option, ReadonlyArray as EffectArray, 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, 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.fromJsonString(Schema.Unknown))
+
+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,105 +24,115 @@ 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 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 hashEventDef = memoizeByRef((event: EventDef.AnyWithoutFn) => Schema.hash(event.schema))
 
-    const processEvent = (row: SystemTables.EventlogMetaRow) =>
-      Effect.gen(function* () {
-        const eventDef = getEventDef(schema, row.name)
-
-        if (hashEventDef(eventDef.eventDef) !== row.schemaHash) {
-          yield* Effect.logWarning(
-            `Schema hash mismatch for event definition ${row.name}. Trying to materialize event anyway.`,
-          )
-        }
-
-        const args = JSON.parse(row.argsJson)
-
-        // 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 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,
+    })
+
+    const eventDef = schema.eventsDefsMap.get(row.name)
+    const materializer = schema.state.materializers.get(row.name)
+
+    if (eventDef === undefined || materializer === undefined) {
+      // Route unknown events through the normal materialization boundary so
+      // they advance the state snapshot head as no-ops.
+      yield* materializeEvent(eventEncoded, { skipEventlog: true })
+      return
+    }
+
+    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.decodeUnknownEffect(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`))
-
-    const CHUNK_SIZE = 100
-
-    const stmt = dbEventlog.prepare(sql`\
+        }),
+      ),
+    )
+
+    yield* materializeEvent(eventEncoded, { skipEventlog: true })
+  })
+
+  const CHUNK_SIZE = 100
+
+  const stmt = dbEventlog.prepare(sql`\
 SELECT * FROM ${SystemTables.EVENTLOG_META_TABLE} 
 WHERE seqNumGlobal > $seqNumGlobal OR (seqNumGlobal = $seqNumGlobal AND seqNumClient > $seqNumClient)
 ORDER BY seqNumGlobal ASC, seqNumClient ASC
 LIMIT ${CHUNK_SIZE}
 `)
 
-    let processedEvents = 0
-
-    yield* Stream.unfoldChunk<
-      Chunk.Chunk<SystemTables.EventlogMetaRow> | { _tag: 'Initial' },
-      SystemTables.EventlogMetaRow
-    >({ _tag: 'Initial' }, (item) => {
-      // End stream if no more rows
-      if (Chunk.isChunk(item) && item.length === 0) return Option.none()
-
-      const lastId = Chunk.isChunk(item)
-        ? Chunk.last(item).pipe(
-            Option.map((_) => ({ global: _.seqNumGlobal, client: _.seqNumClient })),
-            Option.getOrElse(() => EventSequenceNumber.ROOT),
-          )
-        : EventSequenceNumber.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()
-      return Option.some([prevItem, nextItem])
-    }).pipe(
-      Stream.bufferChunks({ capacity: 2 }),
-      Stream.tap((row) =>
-        Effect.gen(function* () {
-          yield* processEvent(row)
-
-          processedEvents++
-          yield* onProgress({ done: processedEvents, total: eventsCount })
-        }),
-      ),
-      Stream.runDrain,
-    )
-  }).pipe(
-    Effect.withPerformanceMeasure('@livestore/common:rematerializeFromEventlog'),
-    Effect.withSpan('@livestore/common:rematerializeFromEventlog'),
+  let processedEvents = 0
+
+  yield* Stream.paginate(EventSequenceNumber.Client.ROOT, (lastId) =>
+    Effect.sync(() => {
+      const rows = stmt.select<SystemTables.EventlogMetaRow>({
+        $seqNumGlobal: lastId.global,
+        $seqNumClient: lastId.client,
+      } as any as PreparedBindValues)
+
+      if (EffectArray.isReadonlyArrayNonEmpty(rows) === false) {
+        const done: readonly [
+          ReadonlyArray<SystemTables.EventlogMetaRow>,
+          Option.Option<EventSequenceNumber.Client.Composite>,
+        ] = [rows, Option.none()]
+        return done
+      }
+
+      const lastRow = EffectArray.lastNonEmpty(rows)
+      const nextCursor = EventSequenceNumber.Client.Composite.make({
+        global: lastRow.seqNumGlobal,
+        client: lastRow.seqNumClient,
+        rebaseGeneration: lastRow.seqNumRebaseGeneration,
+      })
+      const next: readonly [
+        ReadonlyArray<SystemTables.EventlogMetaRow>,
+        Option.Option<EventSequenceNumber.Client.Composite>,
+      ] = [rows, Option.some(nextCursor)]
+      return next
+    }),
+  ).pipe(
+    Stream.bufferArray({ capacity: 2 }),
+    Stream.tap((row) =>
+      Effect.gen(function* () {
+        yield* processEvent(row)
+
+        processedEvents++
+        yield* onProgress({ done: processedEvents, total: eventsCount })
+      }),
+    ),
+    Stream.runDrain,
   )
+}, Effect.withPerformanceMeasure('@livestore/common:rematerializeFromEventlog'))

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

@@ -0,0 +1,28 @@
+import { describe, expect, test } from 'vitest'
+
+import { Schema } from '@livestore/utils/effect'
+
+import { synced } from './define.ts'
+
+describe('synced event wire schema', () => {
+  const occurredAt = new Date('2026-07-17T10:15:30.000Z')
+  const event = synced({
+    name: 'v1.Occurred',
+    schema: Schema.Struct({
+      occurredAt: Schema.DateFromString,
+    }),
+  })
+  const jsonSchema = Schema.fromJsonString(event.schema)
+
+  test('roundtrips a valid date through JSON', () => {
+    const encoded = Schema.encodeSync(jsonSchema)({ occurredAt })
+
+    expect(encoded).toBe('{"occurredAt":"2026-07-17T10:15:30.000Z"}')
+    expect(Schema.decodeSync(jsonSchema)(encoded)).toEqual({ occurredAt })
+  })
+
+  test('rejects invalid dates on encode and decode', () => {
+    expect(() => Schema.encodeSync(jsonSchema)({ occurredAt: new Date(Number.NaN) })).toThrow()
+    expect(() => Schema.decodeSync(jsonSchema)('{"occurredAt":"not-a-date"}')).toThrow()
+  })
+})

package/src/schema/EventDef/define.ts

@@ -0,0 +1,218 @@
+/**
+ * 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 { Result, 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.Codec<TType, TEncoded>
+  } & DefineEventOptions<TType, TDerived>,
+): EventDef<TName, TType, TEncoded, TDerived> => {
+  const { name, schema, ...options } = args
+
+  const makePartialEvent = (args: TType) => {
+    const res = Schema.decodeResult(Schema.toType(schema))(args)
+    if (Result.isFailure(res) === true) {
+      shouldNeverHappen(`Invalid event args for event '${name}':`, res.failure.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.Codec<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.Literals(['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.Codec<TType, TEncoded>
+  } & Omit<DefineEventOptions<TType>, 'derived' | 'clientOnly'>,
+): EventDef<TName, TType, TEncoded> => defineEvent({ ...args, clientOnly: true })