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

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,256 @@
+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('ClientEventSequenceNumber', 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,
+})
+  .annotate({ title: 'EventSequenceNumber.Composite' })
+  .pipe(S.overrideToFormatter(() => (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-only events (isClientOnly=true): increments the client component, keeps global.
+ * For global events (isClientOnly=false): increments global, resets client to 0.
+ */
+export const nextPair = ({
+  seqNum,
+  isClientOnly,
+  rebaseGeneration,
+}: {
+  seqNum: Composite
+  isClientOnly: boolean
+  rebaseGeneration?: number
+}): CompositePair => {
+  if (isClientOnly === 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 },
+  }
+}

package/src/schema/EventSequenceNumber/global.ts

@@ -0,0 +1,19 @@
+import { Brand, Schema as S } from '@livestore/utils/effect'
+
+/** Branded integer type for global sequence numbers assigned by the sync backend. */
+export type Type = Brand.Branded<number, 'GlobalEventSequenceNumber'>
+
+const GlobalBrand = Brand.nominal<Type>()
+
+/** Effect Schema for encoding/decoding global sequence numbers. */
+export const Schema = S.fromBrand('GlobalEventSequenceNumber', GlobalBrand)(S.Int)
+
+/**
+ * Creates a branded global sequence number from a plain number.
+ *
+ * @example
+ * ```ts
+ * const seqNum = EventSequenceNumber.Global.make(5)
+ * ```
+ */
+export const make = GlobalBrand

package/src/schema/EventSequenceNumber/mod.ts

@@ -0,0 +1,37 @@
+/**
+ * Client sequence numbers track events created locally before sync confirmation.
+ * Also contains the Composite type combining global and client sequence numbers with a rebase
+ * generation to fully identify an event's position in the eventlog.
+ *
+ * For event notation documentation, see: contributor-docs/events-notation.md
+ *
+ * @example
+ * ```ts
+ * import { EventSequenceNumber } from '@livestore/common'
+ *
+ * // Client sequence number
+ * const clientSeq = EventSequenceNumber.Client.make(1)
+ *
+ * // Composite sequence number
+ * const composite: EventSequenceNumber.Client.Composite = {
+ *   global: EventSequenceNumber.Global.make(5),
+ *   client: EventSequenceNumber.Client.DEFAULT,
+ *   rebaseGeneration: 0,
+ * }
+ * ```
+ */
+export * as Client from './client.ts'
+
+/**
+ * Global sequence numbers are assigned by the sync backend and represent
+ * the canonical ordering of events across all clients. They are monotonically
+ * increasing integers that establish the authoritative event timeline.
+ *
+ * @example
+ * ```ts
+ * import { EventSequenceNumber } from '@livestore/common'
+ *
+ * const globalSeq = EventSequenceNumber.Global.make(5)
+ * ```
+ */
+export * as Global from './global.ts'