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

package/src/logging.ts

@@ -0,0 +1,62 @@
+import { isDevEnv } from '@livestore/utils'
+import { Effect, type Layer, Logger, LogLevel } from '@livestore/utils/effect'
+
+/**
+ * Optional Effect logger configuration that LiveStore entry points accept.
+ *
+ * When provided, `logger` replaces the default pretty logger for the runtime.
+ * Use `logLevel` to control verbosity. Set to `LogLevel.None` to disable logging
+ * entirely while keeping the same logger implementation.
+ */
+export type WithLoggerOptions = {
+  /** Optional Effect logger layer to control logging output. */
+  logger?: Layer.Layer<never> | undefined
+  /** Optional minimum log level for the runtime. */
+  logLevel?: LogLevel.LogLevel | undefined
+}
+
+/**
+ * Common defaults for resolving a logger configuration.
+ * - `threadName` is used by the default pretty logger when `logger` is not provided.
+ * - `mode` selects pretty logger mode (e.g. 'browser' for web workers).
+ * - `defaultLogLevel` is used when `logLevel` is not provided.
+ */
+export type LoggerDefaults = {
+  threadName?: string
+  mode?: 'tty' | 'browser'
+  defaultLogLevel?: LogLevel.LogLevel
+  /** Optional default logger layer to use when `config.logger` is not provided. */
+  defaultLogger?: Layer.Layer<never>
+}
+
+/**
+ * Resolve the logger layer to provide to the Effect runtime.
+ */
+export const resolveLoggerLayer = (config?: WithLoggerOptions, defaults?: LoggerDefaults): Layer.Layer<never> => {
+  if (config?.logger) return config.logger
+  if (defaults?.defaultLogger) return defaults.defaultLogger
+  const threadName = defaults?.threadName ?? 'livestore'
+  const mode = defaults?.mode
+  return Logger.prettyWithThread(threadName, mode ? { mode } : {})
+}
+
+/**
+ * Resolve the minimum log level, falling back to `defaults.defaultLogLevel` then `LogLevel.Debug`.
+ */
+export const resolveLogLevel = (config?: WithLoggerOptions, defaults?: LoggerDefaults): LogLevel.LogLevel => {
+  if (config?.logLevel !== undefined) return config.logLevel
+  if (defaults?.defaultLogLevel !== undefined) return defaults.defaultLogLevel
+  return isDevEnv() ? LogLevel.Debug : LogLevel.Info
+}
+
+/**
+ * Wrap an effect by applying the resolved minimum log level and providing the resolved logger layer.
+ */
+export const withLoggerConfig = <TEnv, TError, TOut>(
+  config?: WithLoggerOptions,
+  defaults?: LoggerDefaults,
+): ((effect: Effect.Effect<TOut, TError, TEnv>) => Effect.Effect<TOut, TError, TEnv>) => {
+  const level = resolveLogLevel(config, defaults)
+  const layer = resolveLoggerLayer(config, defaults)
+  return (effect) => effect.pipe(Logger.withMinimumLogLevel(level), Effect.provide(layer))
+}

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'
@@ -33,6 +33,7 @@ export const makeClientSession = <R>({
   webmeshMode,
   registerBeforeUnload,
   debugInstanceId,
+  origin,
 }: AdapterArgs & {
   clientId: string
   sessionId: string
@@ -43,9 +44,11 @@ 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 */
+  origin: string | undefined
 }): Effect.Effect<ClientSession, never, Scope.Scope | R> =>
   Effect.gen(function* () {
     const devtools: ClientSession['devtools'] = devtoolsEnabled
@@ -67,11 +70,14 @@ export const makeClientSession = <R>({
           sessionId,
           schemaAlias,
           isLeader,
+          origin,
         })
 
         yield* connectWebmeshNode({ webmeshNode, sessionInfo })
 
-        const sessionInfoBroadcastChannel = yield* Devtools.makeSessionInfoBroadcastChannel(webmeshNode)
+        const sessionInfoBroadcastChannel = yield* Devtools.makeSessionInfoBroadcastChannel(webmeshNode, {
+          origin,
+        })
 
         yield* Devtools.SessionInfo.provideSessionInfo({
           webChannel: sessionInfoBroadcastChannel,

package/src/materializer-helper.ts

@@ -3,9 +3,9 @@ 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 { 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,15 +24,20 @@ 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
   writeTables: ReadonlySet<string> | undefined
 }> => {
-  const eventArgsDecoded =
-    event.decoded === undefined ? Schema.decodeUnknownSync(eventDef.schema)(event.encoded!.args) : event.decoded.args
+  const eventDecoded =
+    event.decoded === undefined
+      ? {
+          ...event.encoded!,
+          args: Schema.decodeUnknownSync(eventDef.schema)(event.encoded!.args),
+        }
+      : event.decoded
 
   const eventArgsEncoded = isNil(event.decoded?.args)
     ? undefined
@@ -58,11 +63,12 @@ export const getExecStatementsFromMaterializer = ({
   }
 
   const statementResults = fromMaterializerResult(
-    materializer(eventArgsDecoded, {
+    materializer(eventDecoded.args, {
       eventDef,
       query,
       // TODO properly implement this
       currentFacts: new Map(),
+      event: eventDecoded,
     }),
   )
 
@@ -79,9 +85,20 @@ 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()) {
-      const { eventDef, materializer } = getEventDef(schema, event.name)
+      // 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,

package/src/rematerialize-from-eventlog.ts

@@ -1,10 +1,10 @@
 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'
 
@@ -31,20 +31,47 @@ export const rematerializeFromEventlog = ({
 
     const processEvent = (row: SystemTables.EventlogMetaRow) =>
       Effect.gen(function* () {
-        const eventDef = getEventDef(schema, row.name)
+        const args = JSON.parse(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 resolution = yield* resolveEventDef(schema, {
+          operation: '@livestore/common:rematerializeFromEventlog:processEvent',
+          event: eventEncoded,
+        }).pipe(UnknownError.mapToUnknownError)
+
+        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
+        }
 
-        if (hashEventDef(eventDef.eventDef) !== row.schemaHash) {
+        const { eventDef } = resolution
+
+        if (hashEventDef(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(
+        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
@@ -55,23 +82,6 @@ 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`))
 
@@ -96,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
+}