@livestore/common 0.4.0-dev.18 → 0.4.0-dev.19

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

@@ -18,7 +18,7 @@ import {
   type MaterializerHashMismatchError,
   type SqliteDb,
   type SqliteError,
-  UnexpectedError,
+  UnknownError,
 } from '../adapter-types.ts'
 import type { MigrationsReport } from '../defs.ts'
 import type * as Devtools from '../devtools/mod.ts'
@@ -82,7 +82,7 @@ export const makeLeaderThreadLayer = ({
   shutdownChannel,
   params,
   testing,
-}: MakeLeaderThreadLayerParams): Layer.Layer<LeaderThreadCtx, UnexpectedError, Scope.Scope | HttpClient.HttpClient> =>
+}: MakeLeaderThreadLayerParams): Layer.Layer<LeaderThreadCtx, UnknownError, Scope.Scope | HttpClient.HttpClient> =>
   Effect.gen(function* () {
     const syncPayloadDecoded =
       syncPayloadEncoded === undefined ? undefined : yield* Schema.decodeUnknown(syncPayloadSchema)(syncPayloadEncoded)
@@ -192,7 +192,7 @@ export const makeLeaderThreadLayer = ({
       dbState,
       dbEventlog,
       makeSqliteDb,
-      eventSchema: LiveStoreEvent.makeEventDefSchema(schema),
+      eventSchema: LiveStoreEvent.Client.makeSchema(schema),
       shutdownStateSubRef: yield* SubscriptionRef.make<ShutdownState>('running'),
       shutdownChannel,
       syncBackend,
@@ -220,7 +220,7 @@ export const makeLeaderThreadLayer = ({
   }).pipe(
     Effect.withSpan('@livestore/common:leader-thread:boot'),
     Effect.withSpanScoped('@livestore/common:leader-thread'),
-    UnexpectedError.mapToUnexpectedError,
+    UnknownError.mapToUnknownError,
     Effect.tapCauseLogPretty,
     Layer.unwrapScoped,
   )
@@ -257,10 +257,12 @@ const getInitialSyncState = ({
   dbEventlogMissing: boolean
 }) => {
   const initialBackendHead = dbEventlogMissing
-    ? EventSequenceNumber.ROOT.global
+    ? EventSequenceNumber.Client.ROOT.global
     : Eventlog.getBackendHeadFromDb(dbEventlog)
 
-  const initialLocalHead = dbEventlogMissing ? EventSequenceNumber.ROOT : Eventlog.getClientHeadFromDb(dbEventlog)
+  const initialLocalHead = dbEventlogMissing
+    ? EventSequenceNumber.Client.ROOT
+    : Eventlog.getClientHeadFromDb(dbEventlog)
 
   if (initialBackendHead > initialLocalHead.global) {
     return shouldNeverHappen(
@@ -272,8 +274,8 @@ const getInitialSyncState = ({
     localHead: initialLocalHead,
     upstreamHead: {
       global: initialBackendHead,
-      client: EventSequenceNumber.clientDefault,
-      rebaseGeneration: EventSequenceNumber.rebaseGenerationDefault,
+      client: EventSequenceNumber.Client.DEFAULT,
+      rebaseGeneration: EventSequenceNumber.Client.REBASE_GENERATION_DEFAULT,
     },
     pending: dbEventlogMissing
       ? []
@@ -282,7 +284,7 @@ const getInitialSyncState = ({
           dbState,
           since: {
             global: initialBackendHead,
-            client: EventSequenceNumber.clientDefault,
+            client: EventSequenceNumber.Client.DEFAULT,
             rebaseGeneration: initialLocalHead.rebaseGeneration,
           },
         }),
@@ -350,7 +352,7 @@ const bootLeaderThread = ({
   devtoolsOptions: DevtoolsOptions
 }): Effect.Effect<
   LeaderThreadCtx['Type']['initialState'],
-  UnexpectedError | SqliteError | IsOfflineError | InvalidPullError | MaterializerHashMismatchError,
+  UnknownError | SqliteError | IsOfflineError | InvalidPullError | MaterializerHashMismatchError,
   LeaderThreadCtx | Scope.Scope | HttpClient.HttpClient
 > =>
   Effect.gen(function* () {

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

@@ -155,7 +155,7 @@ export const makeMaterializeEvent = ({
           attributes: {
             eventName: eventEncoded.name,
             eventNum: eventEncoded.seqNum,
-            'span.label': `${EventSequenceNumber.toString(eventEncoded.seqNum)} ${eventEncoded.name}`,
+            'span.label': `${EventSequenceNumber.Client.toString(eventEncoded.seqNum)} ${eventEncoded.name}`,
           },
         }),
         // Effect.logDuration('@livestore/common:leader-thread:materializeEvent'),
@@ -169,7 +169,7 @@ export const rollback = ({
 }: {
   dbState: SqliteDb
   dbEventlog: SqliteDb
-  eventNumsToRollback: EventSequenceNumber.EventSequenceNumber[]
+  eventNumsToRollback: EventSequenceNumber.Client.Composite[]
 }) =>
   Effect.gen(function* () {
     const rollbackEvents = dbState
@@ -185,7 +185,7 @@ export const rollback = ({
         changeset: _.changeset,
         debug: _.debug,
       }))
-      .toSorted((a, b) => EventSequenceNumber.compare(a.seqNum, b.seqNum))
+      .toSorted((a, b) => EventSequenceNumber.Client.compare(a.seqNum, b.seqNum))
 
     // Apply changesets in reverse order
     for (let i = rollbackEvents.length - 1; i >= 0; i--) {

package/src/leader-thread/recreate-db.ts

@@ -10,7 +10,7 @@ import {
   rematerializeFromEventlog,
   type SqliteDb,
   type SqliteError,
-  UnexpectedError,
+  UnknownError,
 } from '../index.ts'
 import type { LiveStoreSchema } from '../schema/mod.ts'
 import { configureConnection } from './connection.ts'
@@ -28,7 +28,7 @@ export const recreateDb = ({
   schema: LiveStoreSchema
   bootStatusQueue: Queue.Queue<BootStatus>
   materializeEvent: MaterializeEvent
-}): Effect.Effect<{ migrationsReport: MigrationsReport }, UnexpectedError | MaterializeError | SqliteError> =>
+}): Effect.Effect<{ migrationsReport: MigrationsReport }, UnknownError | MaterializeError | SqliteError> =>
   Effect.gen(function* () {
     const migrationOptions = schema.state.sqlite.migrations
     let migrationsReport: MigrationsReport
@@ -48,7 +48,7 @@ export const recreateDb = ({
 
     const initDb = (hooks: Partial<MigrationHooks> | undefined) =>
       Effect.gen(function* () {
-        yield* Effect.tryAll(() => hooks?.init?.(tmpDb)).pipe(UnexpectedError.mapToUnexpectedError)
+        yield* Effect.tryAll(() => hooks?.init?.(tmpDb)).pipe(UnknownError.mapToUnknownError)
 
         const migrationsReport = yield* migrateDb({
           db: tmpDb,
@@ -57,7 +57,7 @@ export const recreateDb = ({
             Queue.offer(bootStatusQueue, { stage: 'migrating', progress: { done, total } }),
         })
 
-        yield* Effect.tryAll(() => hooks?.pre?.(tmpDb)).pipe(UnexpectedError.mapToUnexpectedError)
+        yield* Effect.tryAll(() => hooks?.pre?.(tmpDb)).pipe(UnknownError.mapToUnknownError)
 
         return { migrationsReport, tmpDb }
       })
@@ -78,7 +78,7 @@ export const recreateDb = ({
             Queue.offer(bootStatusQueue, { stage: 'rehydrating', progress: { done, total } }),
         })
 
-        yield* Effect.tryAll(() => hooks?.post?.(initResult.tmpDb)).pipe(UnexpectedError.mapToUnexpectedError)
+        yield* Effect.tryAll(() => hooks?.post?.(initResult.tmpDb)).pipe(UnknownError.mapToUnknownError)
 
         break
       }
@@ -88,7 +88,7 @@ export const recreateDb = ({
         migrationsReport = { migrations: [] }
 
         const newDbData = yield* Effect.tryAll(() => migrationOptions.migrate(oldDbData)).pipe(
-          UnexpectedError.mapToUnexpectedError,
+          UnknownError.mapToUnknownError,
         )
 
         tmpDb.import(newDbData)

package/src/leader-thread/shutdown-channel.ts

@@ -7,12 +7,12 @@ import {
   InvalidPushError,
   IsOfflineError,
   MaterializeError,
-  UnexpectedError,
+  UnknownError,
 } from '../index.ts'
 
 export class All extends Schema.Union(
   IntentionalShutdownCause,
-  UnexpectedError,
+  UnknownError,
   IsOfflineError,
   InvalidPushError,
   InvalidPullError,

package/src/leader-thread/types.ts

@@ -22,7 +22,7 @@ import type {
   PersistenceInfo,
   SqliteDb,
   SyncBackend,
-  UnexpectedError,
+  UnknownError,
 } from '../index.ts'
 import type { EventSequenceNumber, LiveStoreEvent, LiveStoreSchema } from '../schema/mod.ts'
 import type * as SyncState from '../sync/syncstate.ts'
@@ -43,7 +43,7 @@ export const InitialSyncOptions = Schema.Union(InitialSyncOptionsSkip, InitialSy
 export type InitialSyncOptions = typeof InitialSyncOptions.Type
 
 export type InitialSyncInfo = Option.Option<{
-  eventSequenceNumber: EventSequenceNumber.GlobalEventSequenceNumber
+  eventSequenceNumber: EventSequenceNumber.Global.Type
   metadata: Option.Option<Schema.JsonValue>
 }>
 
@@ -66,7 +66,7 @@ export type DevtoolsOptions =
           persistenceInfo: PersistenceInfoPair
           mode: 'proxy' | 'direct'
         },
-        UnexpectedError,
+        UnknownError,
         Scope.Scope | HttpClient.HttpClient | LeaderThreadCtx
       >
     }
@@ -96,13 +96,13 @@ export class LeaderThreadCtx extends Context.Tag('LeaderThreadCtx')<
     // TODO we should find a more elegant way to handle cases which need this ref for their implementation
     shutdownStateSubRef: SubscriptionRef.SubscriptionRef<ShutdownState>
     shutdownChannel: ShutdownChannel
-    eventSchema: LiveStoreEvent.ForEventDefRecord<any>
+    eventSchema: LiveStoreEvent.ForEventDef.ForRecord<any>
     devtools: DevtoolsContext
     syncBackend: SyncBackend.SyncBackend | undefined
     syncProcessor: LeaderSyncProcessor
     materializeEvent: MaterializeEvent
     initialState: {
-      leaderHead: EventSequenceNumber.EventSequenceNumber
+      leaderHead: EventSequenceNumber.Client.Composite
       migrationsReport: MigrationsReport
     }
     /**
@@ -116,7 +116,7 @@ export class LeaderThreadCtx extends Context.Tag('LeaderThreadCtx')<
 >() {}
 
 export type MaterializeEvent = (
-  eventEncoded: LiveStoreEvent.EncodedWithMeta,
+  eventEncoded: LiveStoreEvent.Client.EncodedWithMeta,
   options?: {
     /** Needed for rematerializeFromEventlog */
     skipEventlog?: boolean
@@ -137,17 +137,17 @@ export type InitialBlockingSyncContext = {
 export interface LeaderSyncProcessor {
   /** Used by client sessions to subscribe to upstream sync state changes */
   pull: (args: {
-    cursor: EventSequenceNumber.EventSequenceNumber
-  }) => Stream.Stream<{ payload: typeof SyncState.PayloadUpstream.Type }, UnexpectedError>
+    cursor: EventSequenceNumber.Client.Composite
+  }) => Stream.Stream<{ payload: typeof SyncState.PayloadUpstream.Type }, UnknownError>
   /** The `pullQueue` API can be used instead of `pull` when more convenient */
   pullQueue: (args: {
-    cursor: EventSequenceNumber.EventSequenceNumber
-  }) => Effect.Effect<Queue.Queue<{ payload: typeof SyncState.PayloadUpstream.Type }>, UnexpectedError, Scope.Scope>
+    cursor: EventSequenceNumber.Client.Composite
+  }) => Effect.Effect<Queue.Queue<{ payload: typeof SyncState.PayloadUpstream.Type }>, UnknownError, Scope.Scope>
 
   /** Used by client sessions to push events to the leader thread */
   push: (
     /** `batch` needs to follow the same rules as `batch` in `SyncBackend.push` */
-    batch: ReadonlyArray<LiveStoreEvent.EncodedWithMeta>,
+    batch: ReadonlyArray<LiveStoreEvent.Client.EncodedWithMeta>,
     options?: {
       /**
        * If true, the effect will only finish when the local push has been processed (i.e. succeeded or was rejected).
@@ -160,14 +160,14 @@ export interface LeaderSyncProcessor {
 
   /** Currently only used by devtools which don't provide their own event numbers */
   pushPartial: (args: {
-    event: LiveStoreEvent.PartialAnyEncoded
+    event: LiveStoreEvent.Input.Encoded
     clientId: string
     sessionId: string
-  }) => Effect.Effect<void, UnexpectedError>
+  }) => Effect.Effect<void, UnknownError>
 
   boot: Effect.Effect<
-    { initialLeaderHead: EventSequenceNumber.EventSequenceNumber },
-    UnexpectedError,
+    { initialLeaderHead: EventSequenceNumber.Client.Composite },
+    UnknownError,
     LeaderThreadCtx | Scope.Scope | HttpClient.HttpClient
   >
   syncState: Subscribable.Subscribable<SyncState.SyncState>

package/src/make-client-session.ts

@@ -8,7 +8,7 @@ import type {
   ClientSessionLeaderThreadProxy,
   LockStatus,
   SqliteDb,
-  UnexpectedError,
+  UnknownError,
 } from './adapter-types.ts'
 import * as Devtools from './devtools/mod.ts'
 import { liveStoreVersion } from './version.ts'
@@ -44,7 +44,7 @@ export const makeClientSession = <R>({
   connectWebmeshNode: (args: {
     webmeshNode: Webmesh.MeshNode
     sessionInfo: Devtools.SessionInfo.SessionInfo
-  }) => Effect.Effect<void, UnexpectedError, Scope.Scope | R>
+  }) => Effect.Effect<void, UnknownError, Scope.Scope | R>
   webmeshMode: 'direct' | 'proxy'
   registerBeforeUnload: (onBeforeUnload: () => void) => () => void
   /** Browser origin of the client session; used for origin-scoped DevTools mesh channels */

package/src/materializer-helper.ts

@@ -3,8 +3,8 @@ import { Hash, Option, 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 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'
@@ -24,8 +24,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
@@ -85,7 +85,7 @@ export const getExecStatementsFromMaterializer = ({
 
 export const makeMaterializerHash =
   ({ schema, dbState }: { schema: LiveStoreSchema; dbState: SqliteDb }) =>
-  (event: LiveStoreEvent.AnyEncoded): Option.Option<number> => {
+  (event: LiveStoreEvent.Client.Encoded): Option.Option<number> => {
     if (isDevEnv()) {
       // Hashing is only needed during dev-mode diagnostics. Skip work entirely for
       // unknown events (no definition/materializer) so we do not introduce noisy

package/src/rematerialize-from-eventlog.ts

@@ -1,7 +1,7 @@
 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, LiveStoreEvent, resolveEventDef, SystemTables } from './schema/mod.ts'
@@ -32,7 +32,7 @@ export const rematerializeFromEventlog = ({
     const processEvent = (row: SystemTables.EventlogMetaRow) =>
       Effect.gen(function* () {
         const args = JSON.parse(row.argsJson)
-        const eventEncoded = LiveStoreEvent.EncodedWithMeta.make({
+        const eventEncoded = LiveStoreEvent.Client.EncodedWithMeta.make({
           name: row.name,
           args,
           seqNum: {
@@ -52,7 +52,7 @@ export const rematerializeFromEventlog = ({
         const resolution = yield* resolveEventDef(schema, {
           operation: '@livestore/common:rematerializeFromEventlog:processEvent',
           event: eventEncoded,
-        }).pipe(UnexpectedError.mapToUnexpectedError)
+        }).pipe(UnknownError.mapToUnknownError)
 
         if (resolution._tag === 'unknown') {
           // Old snapshots can contain newer events. Skip until the runtime has
@@ -71,7 +71,7 @@ export const rematerializeFromEventlog = ({
         // Checking whether the schema has changed in an incompatible way
         yield* Schema.decodeUnknown(eventDef.schema)(args).pipe(
           Effect.mapError((cause) =>
-            UnexpectedError.make({
+            UnknownError.make({
               cause,
               note: `\
 There was an error during rematerializing from the eventlog while decoding
@@ -106,9 +106,9 @@ LIMIT ${CHUNK_SIZE}
       const lastId = Chunk.isChunk(item)
         ? 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,

package/src/schema/EventDef/define.ts

@@ -0,0 +1,201 @@
+/**
+ * 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
+}
+
+/**
+ * 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
+        ? (args, currentFacts) => {
+            const res = options.facts!(args, currentFacts)
+            return {
+              modify: {
+                set: res.modify?.set ? new Set(res.modify.set) : new Set(),
+                unset: res.modify?.unset ? new Set(res.modify.unset) : new Set(),
+              },
+              require: res.require ? new Set(res.require) : new Set(),
+            }
+          }
+        : undefined,
+      derived: options?.derived ?? false,
+    } 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, false>, '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, false>, 'derived' | 'clientOnly'>,
+): EventDef<TName, TType, TEncoded> => defineEvent({ ...args, clientOnly: true })

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

@@ -0,0 +1,120 @@
+import type { Schema } from '@livestore/utils/effect'
+
+import type { FactsCallback } from './facts.ts'
+
+/**
+ * Core type representing an event definition in LiveStore.
+ *
+ * An EventDef defines the structure and behavior of an event type, including:
+ * - A unique name identifying the event type (conventionally versioned, e.g., `v1.TodoCreated`)
+ * - A schema for validating and encoding/decoding event arguments
+ * - Options controlling sync behavior and constraints
+ *
+ * EventDefs are callable - invoking them creates a partial event object suitable for `store.commit()`.
+ *
+ * @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,
+ *   }),
+ * })
+ *
+ * // Use the EventDef as a constructor
+ * store.commit(todoCreated({ id: 'abc', text: 'Buy milk' }))
+ * ```
+ */
+export type EventDef<TName extends string, TType, TEncoded = TType, TDerived extends boolean = false> = {
+  /** Unique identifier for this event type. Conventionally versioned (e.g., `v1.TodoCreated`). */
+  name: TName
+
+  /** Effect Schema used for validating and encoding/decoding event arguments. */
+  schema: Schema.Schema<TType, TEncoded>
+
+  options: {
+    /**
+     * When true, the event is only synced within the same client's sessions (e.g., across tabs)
+     * but never sent to the sync backend. Useful for UI state like selected items or filters.
+     */
+    clientOnly: boolean
+
+    /**
+     * Callback defining fact constraints for this event.
+     * @experimental This feature is not fully implemented yet.
+     */
+    facts: FactsCallback<TType> | undefined
+
+    /** Whether this is a derived event. Derived events cannot have materializers. */
+    derived: TDerived
+  }
+
+  /**
+   * Callable signature - creates a partial event with decoded arguments.
+   * The returned object can be passed directly to `store.commit()`.
+   */
+  (
+    args: TType,
+  ): {
+    name: TName
+    args: TType
+  }
+
+  /**
+   * Creates a partial event with pre-encoded arguments.
+   * Useful when working with already-serialized data.
+   */
+  encoded: (args: TEncoded) => {
+    name: TName
+    args: TEncoded
+  }
+
+  /** Type helper for accessing the event's shape with name and decoded args. */
+  readonly Event: {
+    name: TName
+    args: TType
+  }
+}
+
+export namespace EventDef {
+  /**
+   * Wildcard type matching any EventDef regardless of type parameters.
+   * Used as a type constraint in generic functions and collections.
+   */
+  export type Any = EventDef<string, any, any, boolean>
+
+  /**
+   * EventDef without the callable function signature.
+   * Used in contexts where only the metadata (name, schema, options) is needed,
+   * such as materializer definitions.
+   */
+  export type AnyWithoutFn = Pick<Any, 'name' | 'schema' | 'options'>
+}
+
+/**
+ * Container holding a Map of event definitions keyed by name.
+ * Used internally by LiveStoreSchema.
+ */
+export type EventDefMap = {
+  map: Map<string, EventDef.Any>
+}
+
+/**
+ * Plain object record of event definitions keyed by name.
+ * This is the typical shape when defining events in user code.
+ *
+ * @example
+ * ```ts
+ * const events = {
+ *   todoCreated: Events.synced({ name: 'v1.TodoCreated', schema: ... }),
+ *   todoDeleted: Events.synced({ name: 'v1.TodoDeleted', schema: ... }),
+ * } satisfies EventDefRecord
+ * ```
+ */
+export type EventDefRecord = {
+  [name: string]: EventDef.Any
+}