@livestore/common 0.4.0-dev.9 → 0.4.0

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

@@ -0,0 +1,125 @@
+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
+
+    /**
+     * Deprecation reason for this event. When set, a warning is logged at commit time.
+     */
+    deprecated: string | undefined
+  }
+
+  /**
+   * 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,5 @@
+export * from './define.ts'
+export * from './deprecated.ts'
+export * from './event-def.ts'
+export * from './facts.ts'
+export * from './materializer.ts'

package/src/schema/EventSequenceNumber/client.ts

@@ -0,0 +1,257 @@
+import { Brand, Schema as S } from '@livestore/utils/effect'
+
+import { type Type as Global, Schema as GlobalSchema, make as makeGlobal } from './global.ts'
+
+/** Branded integer type for client-local sequence numbers. */
+export type Type = Brand.Branded<number, 'ClientEventSequenceNumber'>
+
+const ClientBrand = Brand.nominal<Type>()
+
+/** Effect Schema for encoding/decoding client sequence numbers. */
+export const Schema = S.fromBrand(ClientBrand)(S.Int)
+
+/**
+ * Creates a branded client sequence number from a plain number.
+ *
+ * @example
+ * ```ts
+ * const clientSeq = EventSequenceNumber.Client.make(1)
+ * ```
+ */
+export const make = ClientBrand
+
+/**
+ * Default client sequence number (0). Used for confirmed/synced events.
+ *
+ * @example
+ * ```ts
+ * const defaultSeq = EventSequenceNumber.Client.DEFAULT // 0
+ * ```
+ */
+export const DEFAULT = make(0)
+
+/** Default rebase generation (0). Increments each time the client rebases unconfirmed events. */
+export const REBASE_GENERATION_DEFAULT = 0
+
+/**
+ * Composite event sequence number consisting of global + client + rebaseGeneration.
+ * Used for client-side event tracking with support for unconfirmed local events.
+ *
+ * For event notation documentation, see: contributor-docs/events-notation.md
+ */
+export type Composite = {
+  global: Global
+  client: Type
+  /**
+   * Generation integer that is incremented whenever the client rebased.
+   * Remains constant for all subsequent events until another rebase occurs.
+   */
+  rebaseGeneration: number
+}
+
+/** Input type for creating a Composite sequence number. Allows omitting rebaseGeneration (defaults to 0). */
+export type CompositeInput =
+  | Composite
+  | (Omit<typeof CompositeSchema.Encoded, 'rebaseGeneration'> & { rebaseGeneration?: number })
+
+/** A pair of sequence numbers representing an event and its parent. */
+export type CompositePair = { seqNum: Composite; parentSeqNum: Composite }
+
+/**
+ * Compare two composite sequence numbers.
+ * Comparison hierarchy: global > client > rebaseGeneration
+ */
+export const compare = (a: Composite, b: Composite) => {
+  if (a.global !== b.global) {
+    return a.global - b.global
+  }
+  if (a.client !== b.client) {
+    return a.client - b.client
+  }
+  return a.rebaseGeneration - b.rebaseGeneration
+}
+
+/**
+ * Convert a composite sequence number to a string representation.
+ *
+ * For notation documentation, see: contributor-docs/events-notation.md
+ */
+export const toString = (seqNum: Composite) => {
+  const rebaseGenerationStr = seqNum.rebaseGeneration > 0 ? `r${seqNum.rebaseGeneration}` : ''
+  return seqNum.client === 0
+    ? `e${seqNum.global}${rebaseGenerationStr}`
+    : `e${seqNum.global}.${seqNum.client}${rebaseGenerationStr}`
+}
+
+/**
+ * Convert a string representation of a sequence number to a Composite.
+ * Parses strings in the format: e{global}[.{client}][r{rebaseGeneration}]
+ * Examples: "e0", "e0r1", "e0.1", "e0.1r1"
+ *
+ * For full notation documentation, see: contributor-docs/events-notation.md
+ */
+export const fromString = (str: string): Composite => {
+  if (str.startsWith('e') === false) {
+    throw new Error('Invalid event sequence number string: must start with "e"')
+  }
+
+  // Remove the 'e' prefix
+  const remaining = str.slice(1)
+
+  // Parse rebase generation if present
+  let rebaseGeneration = REBASE_GENERATION_DEFAULT
+  let withoutRebase = remaining
+  const rebaseMatch = remaining.match(/r(\d+)$/)
+  if (rebaseMatch !== null) {
+    rebaseGeneration = Number.parseInt(rebaseMatch[1]!, 10)
+    withoutRebase = remaining.slice(0, -rebaseMatch[0].length)
+  }
+
+  // Parse global and client parts
+  const parts = withoutRebase.split('.')
+
+  // Validate that parts contain only digits (and possibly empty for client)
+  if (parts[0] === '' || /^\d+$/.test(parts[0]!) === false) {
+    throw new Error('Invalid event sequence number string: invalid number format')
+  }
+
+  if (parts.length > 1 && parts[1] !== undefined && (parts[1] === '' || /^\d+$/.test(parts[1]) === false)) {
+    throw new Error('Invalid event sequence number string: invalid number format')
+  }
+
+  const global = Number.parseInt(parts[0]!, 10)
+  const client = parts.length > 1 && parts[1] !== undefined ? Number.parseInt(parts[1], 10) : 0
+
+  if (Number.isNaN(global) === true || Number.isNaN(client) === true || Number.isNaN(rebaseGeneration) === true) {
+    throw new TypeError('Invalid event sequence number string: invalid number format')
+  }
+
+  return {
+    global: makeGlobal(global),
+    client: make(client),
+    rebaseGeneration,
+  }
+}
+
+/** Creates a Composite sequence number from a global sequence number (client=0, rebaseGeneration=0). */
+export const fromGlobal = (seqNum: Global): Composite => ({
+  global: seqNum,
+  client: DEFAULT,
+  rebaseGeneration: REBASE_GENERATION_DEFAULT,
+})
+
+/** Returns true if two Composite sequence numbers are structurally equal. */
+export const isEqual = (a: Composite, b: Composite) =>
+  a.global === b.global && a.client === b.client && a.rebaseGeneration === b.rebaseGeneration
+
+/** Returns true if `a` is strictly greater than `b` (compares global, then client). */
+export const isGreaterThan = (a: Composite, b: Composite) => {
+  return a.global > b.global || (a.global === b.global && a.client > b.client)
+}
+
+/** Returns true if `a` is greater than or equal to `b` (compares global, then client). */
+export const isGreaterThanOrEqual = (a: Composite, b: Composite) => {
+  return a.global > b.global || (a.global === b.global && a.client >= b.client)
+}
+
+/** Returns the larger of two Composite sequence numbers. */
+export const max = (a: Composite, b: Composite) => {
+  return a.global > b.global || (a.global === b.global && a.client > b.client) ? a : b
+}
+
+/** Returns the difference between two Composite sequence numbers (a - b) for global and client components. */
+export const diff = (a: Composite, b: Composite) => {
+  return {
+    global: a.global - b.global,
+    client: a.client - b.client,
+  }
+}
+
+/**
+ * Schema for the composite event sequence number.
+ * NOTE: Client mutation events with a non-0 client id won't be synced to the sync backend.
+ */
+const CompositeSchema = S.Struct({
+  global: GlobalSchema,
+  /** Only increments for client-local events */
+  client: Schema,
+  // Client only
+  rebaseGeneration: S.Int,
+}).annotations({
+  title: 'EventSequenceNumber.Composite',
+  pretty: () => (seqNum) => toString(seqNum),
+})
+
+/**
+ * Creates a validated Composite sequence number from input.
+ * If rebaseGeneration is omitted, defaults to REBASE_GENERATION_DEFAULT (0).
+ */
+const makeComposite = (seqNum: CompositeInput): Composite => {
+  return S.is(CompositeSchema)(seqNum) === true
+    ? seqNum
+    : S.decodeSync(CompositeSchema)({
+        ...seqNum,
+        rebaseGeneration: seqNum.rebaseGeneration ?? REBASE_GENERATION_DEFAULT,
+      })
+}
+
+/**
+ * Effect Schema for the composite event sequence number (global + client + rebaseGeneration).
+ * Also includes a `make` helper for creating validated Composite values.
+ *
+ * @example
+ * ```ts
+ * const seqNum: EventSequenceNumber.Client.Composite = {
+ *   global: EventSequenceNumber.Global.make(5),
+ *   client: EventSequenceNumber.Client.DEFAULT,
+ *   rebaseGeneration: 0
+ * }
+ *
+ * const validated = EventSequenceNumber.Client.Composite.make({ global: 5, client: 0, rebaseGeneration: 0 })
+ * ```
+ */
+export const Composite = Object.assign(CompositeSchema, { make: makeComposite })
+
+/** The root sequence number (global=0, client=0, rebaseGeneration=0). Parent of the first event. */
+export const ROOT = {
+  global: makeGlobal(0),
+  client: DEFAULT,
+  rebaseGeneration: REBASE_GENERATION_DEFAULT,
+} satisfies Composite
+
+/**
+ * Computes the next sequence number and its parent based on the current position.
+ *
+ * For client-local events (isClient=true): increments the client component, keeps global.
+ * For global events (isClient=false): increments global, resets client to 0.
+ */
+export const nextPair = ({
+  seqNum,
+  isClient,
+  rebaseGeneration,
+}: {
+  seqNum: Composite
+  isClient: boolean
+  rebaseGeneration?: number
+}): CompositePair => {
+  if (isClient === true) {
+    return {
+      seqNum: {
+        global: seqNum.global,
+        client: make(seqNum.client + 1),
+        rebaseGeneration: rebaseGeneration ?? seqNum.rebaseGeneration,
+      },
+      parentSeqNum: seqNum,
+    }
+  }
+
+  return {
+    seqNum: {
+      global: makeGlobal(seqNum.global + 1),
+      client: DEFAULT,
+      rebaseGeneration: rebaseGeneration ?? seqNum.rebaseGeneration,
+    },
+    // NOTE we always point to `client: 0` for non-client-local events
+    parentSeqNum: { global: seqNum.global, client: DEFAULT, rebaseGeneration: seqNum.rebaseGeneration },
+  }
+}