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

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
+}

package/src/schema/EventDef/facts.ts

@@ -0,0 +1,135 @@
+/**
+ * Facts System for Event Constraints (Experimental)
+ *
+ * The facts system enables defining constraints and dependencies between events.
+ * Facts are key-value pairs that events can read, set, or require, allowing
+ * LiveStore to understand event relationships for:
+ * - History constraints (ordering requirements)
+ * - Event compaction (which events can be safely merged)
+ * - Conflict detection during sync
+ *
+ * @experimental This system is not fully implemented yet.
+ *
+ * @example
+ * ```ts
+ * const facts = defineFacts({
+ *   todoExists: (id: string) => [`todo:${id}`, true],
+ *   userOwns: (userId: string, todoId: string) => [`owns:${userId}:${todoId}`, true],
+ * })
+ *
+ * const todoCreated = Events.synced({
+ *   name: 'v1.TodoCreated',
+ *   schema: Schema.Struct({ id: Schema.String, userId: Schema.String }),
+ *   facts: ({ id, userId }) => ({
+ *     modify: { set: [facts.todoExists(id), facts.userOwns(userId, id)] },
+ *     require: [],
+ *   }),
+ * })
+ * ```
+ * @module
+ */
+
+/** String key identifying a fact (e.g., `"todo:abc123"` or `"user:owner:xyz"`). */
+export type EventDefKey = string
+
+/** String identifier for a fact type. */
+export type EventDefFact = string
+
+/** Immutable map of fact keys to their current values. */
+export type EventDefFacts = ReadonlyMap<string, any>
+
+/**
+ * Groups of facts that an event interacts with.
+ * Used internally to track how events modify and depend on facts.
+ */
+export type EventDefFactsGroup = {
+  /** Facts this event sets to a new value. */
+  modifySet: EventDefFacts
+
+  /** Facts this event removes/unsets. */
+  modifyUnset: EventDefFacts
+
+  /**
+   * Facts this event requires to exist with specific values.
+   * Events on independent dependency branches are commutative,
+   * which can facilitate more prioritized syncing.
+   */
+  depRequire: EventDefFacts
+
+  /** Facts this event reads (but doesn't require). */
+  depRead: EventDefFacts
+}
+
+/** Mutable snapshot of facts state at a point in time. */
+export type EventDefFactsSnapshot = Map<string, any>
+
+/**
+ * Input format for specifying a fact.
+ * Either a simple key string (value defaults to `true`) or a `[key, value]` tuple.
+ *
+ * @example
+ * ```ts
+ * // Simple key (value = true)
+ * const fact1: EventDefFactInput = 'todo:abc123'
+ *
+ * // Key-value tuple
+ * const fact2: EventDefFactInput = ['todo:abc123', { status: 'active' }]
+ * ```
+ */
+export type EventDefFactInput = string | readonly [string, any]
+
+/**
+ * Callback function that defines how an event interacts with the facts system.
+ * Called during event processing to determine fact constraints.
+ *
+ * @example
+ * ```ts
+ * const factsCallback: FactsCallback<{ id: string }> = (args, currentFacts) => ({
+ *   modify: {
+ *     set: [`item:${args.id}`],  // Create/update this fact
+ *     unset: [],                  // No facts to remove
+ *   },
+ *   require: currentFacts.has('initialized') ? [] : ['initialized'],
+ * })
+ * ```
+ */
+export type FactsCallback<TTo> = (
+  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 with specific values for this event to be valid. */
+  require: Iterable<EventDefFactInput>
+}
+
+/**
+ * Helper to define a typed record of fact constructors.
+ * Returns the input unchanged but provides type inference.
+ *
+ * @example
+ * ```ts
+ * const facts = defineFacts({
+ *   // Simple fact (value = true)
+ *   initialized: 'system:initialized',
+ *
+ *   // Parameterized fact constructor
+ *   todoExists: (id: string) => [`todo:${id}`, true] as const,
+ *
+ *   // Fact with complex value
+ *   todoStatus: (id: string, status: string) => [`todo:${id}:status`, status] as const,
+ * })
+ *
+ * // Usage
+ * facts.todoExists('abc')  // => ['todo:abc', true]
+ * ```
+ */
+export const defineFacts = <
+  TRecord extends Record<string, EventDefFactInput | ((...args: any[]) => EventDefFactInput)>,
+>(
+  record: TRecord,
+): TRecord => record

package/src/schema/EventDef/materializer.ts

@@ -0,0 +1,172 @@
+/**
+ * Materializer System
+ *
+ * Materializers transform events into SQL mutations (INSERT, UPDATE, DELETE).
+ * Every non-derived event must have a corresponding materializer that defines
+ * how it affects the SQLite database state.
+ *
+ * Materializers are pure functions that receive the event arguments and return
+ * SQL operations. They can also query current state when needed for complex
+ * transformations.
+ *
+ * @example
+ * ```ts
+ * import { State } from '@livestore/livestore'
+ *
+ * const materializers = State.SQLite.materializers(events, {
+ *   'v1.TodoCreated': ({ id, text }) =>
+ *     tables.todos.insert({ id, text, completed: false }),
+ *
+ *   'v1.TodoCompleted': ({ id }) =>
+ *     tables.todos.update({ completed: true }).where({ id }),
+ *
+ *   'v1.TodoDeleted': ({ id, deletedAt }) =>
+ *     tables.todos.update({ deletedAt }).where({ id }),
+ * })
+ * ```
+ * @module
+ */
+
+import type { SingleOrReadonlyArray } from '@livestore/utils'
+
+import type { BindValues } from '../../sql-queries/sql-queries.ts'
+import type { ParamsObject } from '../../util.ts'
+import type * as LiveStoreEvent from '../LiveStoreEvent/mod.ts'
+import type { QueryBuilder } from '../state/sqlite/query-builder/mod.ts'
+import type { EventDef } from './event-def.ts'
+import type { EventDefFacts } from './facts.ts'
+
+/**
+ * Result type for materializer functions.
+ *
+ * Can be one of:
+ * - A QueryBuilder operation (recommended for type safety)
+ * - A raw SQL string
+ * - An object with SQL, bind values, and optional write table tracking
+ */
+export type MaterializerResult =
+  | {
+      sql: string
+      bindValues: BindValues
+      writeTables?: ReadonlySet<string>
+    }
+  | QueryBuilder.Any
+  | string
+
+/**
+ * Function signature for querying current state within a materializer.
+ *
+ * Allows materializers to read existing data when computing mutations.
+ * Can be called with either raw SQL or a type-safe QueryBuilder.
+ *
+ * @example
+ * ```ts
+ * 'v1.TodoUpdated': ({ id, text }, { query }) => {
+ *   const existing = query(tables.todos.select().where({ id }).first())
+ *   if (!existing) return []  // No-op if todo doesn't exist
+ *   return tables.todos.update({ text }).where({ id })
+ * }
+ * ```
+ */
+export type MaterializerContextQuery = {
+  /** Query with raw SQL and bind values. */
+  (args: { query: string; bindValues: ParamsObject }): ReadonlyArray<unknown>
+  /** Query with a type-safe QueryBuilder. */
+  <TResult>(qb: QueryBuilder<TResult, any, any>): TResult
+}
+
+/**
+ * Function type for transforming an event into database mutations.
+ *
+ * Materializers are the bridge between events and SQLite state. They receive
+ * the decoded event arguments and return SQL operations to execute.
+ *
+ * @example
+ * ```ts
+ * const todoCreatedMaterializer: Materializer<typeof todoCreated> =
+ *   ({ id, text }) => tables.todos.insert({ id, text, completed: false })
+ * ```
+ */
+export type Materializer<TEventDef extends EventDef.AnyWithoutFn = EventDef.AnyWithoutFn> = (
+  /** Decoded event arguments. */
+  event: TEventDef['schema']['Type'],
+  context: {
+    /** Current facts state (experimental). */
+    currentFacts: EventDefFacts
+    /** The event definition being materialized. */
+    eventDef: TEventDef
+    /** Function to query current database state. */
+    query: MaterializerContextQuery
+    /** Full event metadata including clientId, sessionId, sequence numbers. */
+    event: LiveStoreEvent.Client.Decoded
+  },
+) => SingleOrReadonlyArray<MaterializerResult>
+
+/**
+ * Type-safe wrapper for defining a single materializer.
+ *
+ * Useful when defining materializers separately from the `materializers()` builder.
+ * The first argument provides type inference for the second.
+ *
+ * @example
+ * ```ts
+ * const todoCreatedHandler = defineMaterializer(
+ *   events.todoCreated,
+ *   ({ id, text }) => tables.todos.insert({ id, text, completed: false })
+ * )
+ * ```
+ */
+export const defineMaterializer = <TEventDef extends EventDef.AnyWithoutFn>(
+  _eventDef: TEventDef,
+  materializer: Materializer<TEventDef>,
+): Materializer<TEventDef> => {
+  return materializer
+}
+
+/**
+ * Builder function for creating a type-safe materializer map.
+ *
+ * This is the primary way to define materializers in LiveStore. It ensures:
+ * - Every non-derived event has a corresponding materializer
+ * - Materializer argument types match their event schemas
+ * - Derived events are excluded from the required handlers
+ *
+ * @example
+ * ```ts
+ * import { State } from '@livestore/livestore'
+ *
+ * const handlers = State.SQLite.materializers(events, {
+ *   // Handler for each event - argument types are inferred
+ *   'v1.TodoCreated': ({ id, text, completed }) =>
+ *     tables.todos.insert({ id, text, completed }),
+ *
+ *   'v1.TodoUpdated': ({ id, text }) =>
+ *     tables.todos.update({ text }).where({ id }),
+ *
+ *   // Can return multiple operations
+ *   'v1.UserCreatedWithDefaults': ({ userId, name }) => [
+ *     tables.users.insert({ id: userId, name }),
+ *     tables.settings.insert({ userId, theme: 'light' }),
+ *   ],
+ *
+ *   // Can query current state
+ *   'v1.TodoToggled': ({ id }, { query }) => {
+ *     const todo = query(tables.todos.select().where({ id }).first())
+ *     return tables.todos.update({ completed: !todo?.completed }).where({ id })
+ *   },
+ * })
+ * ```
+ */
+export const materializers = <TInputRecord extends Record<string, EventDef.AnyWithoutFn>>(
+  _eventDefRecord: TInputRecord,
+  handlers: {
+    [TEventName in TInputRecord[keyof TInputRecord]['name'] as Extract<
+      TInputRecord[keyof TInputRecord],
+      { name: TEventName }
+    >['options']['derived'] extends true
+      ? never
+      : TEventName]: Materializer<Extract<TInputRecord[keyof TInputRecord], { name: TEventName }>>
+  },
+) => {
+  return handlers
+}

package/src/schema/EventDef/mod.ts

@@ -0,0 +1,4 @@
+export * from './define.ts'
+export * from './event-def.ts'
+export * from './facts.ts'
+export * from './materializer.ts'