Events

Event definitions

There are two types of events:

• synced: Events that are synced across clients
• clientOnly: Events that are only processed locally on the client (but still synced across client sessions e.g. across browser tabs/windows)

An event definition consists of a unique name of the event and a schema for the event arguments. It’s recommended to version event definitions to make it easier to evolve them over time.

Events will be synced across clients and materialized into state (i.e. SQLite tables) via materializers.

Example

livestore-schema.ts

// livestore/schema.ts
import { Events, Schema } from '@livestore/livestore'

export const events = {
  todoCreated: Events.synced({
    name: 'v1.TodoCreated',
    schema: Schema.Struct({ id: Schema.String, text: Schema.String }),
  }),
  todoCompleted: Events.synced({
    name: 'v1.TodoCompleted',
    schema: Schema.Struct({ id: Schema.String }),
  }),
} as const

Best Practices

• It’s strongly recommended to use past-tense event names (e.g. todoCreated/createdTodo instead of todoCreate/createTodo) to indicate something already occurred.
• When generating IDs for events (e.g. for the todo in the example above), it’s recommended to use a globally unique ID generator (e.g. UUID, nanoid, etc.) to avoid conflicts. For convenience, @livestore/livestore re-exports the nanoid function.
• TODO: write down more best practices
• TODO: mention AI linting (either manually or via a CI step)
  • core idea: feed list of best practices to AI and check if events adhere to them + get suggestions if not
• It’s recommended to avoid DELETE events and instead use soft-deletes (e.g. add a deleted date/boolean column with a default value of null). This helps avoid some common concurrency issues.

Unknown events

Older clients might receive events that were introduced in newer app versions. Configure the behaviour centrally via unknownEventHandling when constructing the schema:

const schema = makeSchema({
  events,
  state,
  unknownEventHandling: {
    strategy: 'callback',
    onUnknownEvent: (event, error) => {
      console.warn('LiveStore saw an unknown event', { event, reason: error.reason })
    },
  },
})

Pick 'warn' (default) to log every occurrence, 'ignore' to silently drop new events until the client updates, 'fail' to halt immediately, or 'callback' to delegate to custom logging/telemetry while continuing to process the log.

Schema evolution

• Event definitions can’t be removed after they were added to your app.
• Event schema definitions can be evolved as long as the changes are forward-compatible.
  • That means data encoded with the old schema can be decoded with the new schema.
  • In practice, this means …
    • for structs …
      • you can add new fields if they have default values or are optional
      • you can remove fields

Commiting events

commit.ts livestore-schema.ts

// somewhere in your app
import type { Store } from '@livestore/livestore'

import { events } from './livestore-schema.ts'

declare const store: Store

store.commit(events.todoCreated({ id: '1', text: 'Buy milk' }))

// livestore/schema.ts
import { Events, Schema } from '@livestore/livestore'

export const events = {
  todoCreated: Events.synced({
    name: 'v1.TodoCreated',
    schema: Schema.Struct({ id: Schema.String, text: Schema.String }),
  }),
  todoCompleted: Events.synced({
    name: 'v1.TodoCompleted',
    schema: Schema.Struct({ id: Schema.String }),
  }),
} as const

Eventlog

The history of all events that have been committed is stored forms the “eventlog”. It is persisted in the client as well as in the sync backend.

Example eventlog.db: