@livestore/common 0.3.0-dev.28 → 0.3.0-dev.29

package/src/leader-thread/eventlog.ts

@@ -0,0 +1,199 @@
+import { LS_DEV, shouldNeverHappen } from '@livestore/utils'
+import { Effect, Option, Schema } from '@livestore/utils/effect'
+
+import type { SqliteDb } from '../adapter-types.js'
+import * as EventId from '../schema/EventId.js'
+import * as LiveStoreEvent from '../schema/LiveStoreEvent.js'
+import {
+  EVENTLOG_META_TABLE,
+  eventlogMetaTable,
+  sessionChangesetMetaTable,
+  SYNC_STATUS_TABLE,
+  syncStatusTable,
+} from '../schema/system-tables.js'
+import { migrateTable } from '../schema-management/migrations.js'
+import { insertRow, updateRows } from '../sql-queries/sql-queries.js'
+import type { PreparedBindValues } from '../util.js'
+import { prepareBindValues, sql } from '../util.js'
+import { execSql } from './connection.js'
+import type { InitialSyncInfo } from './types.js'
+import { LeaderThreadCtx } from './types.js'
+
+export const initEventlogDb = (dbEventlog: SqliteDb) =>
+  Effect.gen(function* () {
+    yield* migrateTable({
+      db: dbEventlog,
+      behaviour: 'create-if-not-exists',
+      tableAst: eventlogMetaTable.sqliteDef.ast,
+      skipMetaTable: true,
+    })
+
+    yield* migrateTable({
+      db: dbEventlog,
+      behaviour: 'create-if-not-exists',
+      tableAst: syncStatusTable.sqliteDef.ast,
+      skipMetaTable: true,
+    })
+
+    // Create sync status row if it doesn't exist
+    yield* execSql(
+      dbEventlog,
+      sql`INSERT INTO ${SYNC_STATUS_TABLE} (head)
+          SELECT ${EventId.ROOT.global}
+          WHERE NOT EXISTS (SELECT 1 FROM ${SYNC_STATUS_TABLE})`,
+      {},
+    )
+  })
+
+/** Exclusive of the "since event" */
+export const getEventsSince = (
+  since: EventId.EventId,
+): Effect.Effect<ReadonlyArray<LiveStoreEvent.EncodedWithMeta>, never, LeaderThreadCtx> =>
+  Effect.gen(function* () {
+    const { dbEventlog, dbReadModel } = yield* LeaderThreadCtx
+
+    const query = eventlogMetaTable.where('idGlobal', '>=', since.global).asSql()
+    const pendingEventsRaw = dbEventlog.select(query.query, prepareBindValues(query.bindValues, query.query))
+    const pendingEvents = Schema.decodeUnknownSync(eventlogMetaTable.rowSchema.pipe(Schema.Array))(pendingEventsRaw)
+
+    const sessionChangesetRows = sessionChangesetMetaTable.where('idGlobal', '>=', since.global).asSql()
+    const sessionChangesetRowsRaw = dbReadModel.select(
+      sessionChangesetRows.query,
+      prepareBindValues(sessionChangesetRows.bindValues, sessionChangesetRows.query),
+    )
+    const sessionChangesetRowsDecoded = Schema.decodeUnknownSync(
+      sessionChangesetMetaTable.rowSchema.pipe(Schema.Array),
+    )(sessionChangesetRowsRaw)
+
+    return pendingEvents
+      .map((eventlogEvent) => {
+        const sessionChangeset = sessionChangesetRowsDecoded.find(
+          (readModelEvent) =>
+            readModelEvent.idGlobal === eventlogEvent.idGlobal && readModelEvent.idClient === eventlogEvent.idClient,
+        )
+        return LiveStoreEvent.EncodedWithMeta.make({
+          name: eventlogEvent.name,
+          args: eventlogEvent.argsJson,
+          id: { global: eventlogEvent.idGlobal, client: eventlogEvent.idClient },
+          parentId: { global: eventlogEvent.parentIdGlobal, client: eventlogEvent.parentIdClient },
+          clientId: eventlogEvent.clientId,
+          sessionId: eventlogEvent.sessionId,
+          meta: {
+            sessionChangeset:
+              sessionChangeset && sessionChangeset.changeset !== null
+                ? {
+                    _tag: 'sessionChangeset' as const,
+                    data: sessionChangeset.changeset,
+                    debug: sessionChangeset.debug,
+                  }
+                : { _tag: 'unset' as const },
+            syncMetadata: eventlogEvent.syncMetadataJson,
+          },
+        })
+      })
+      .filter((_) => EventId.compare(_.id, since) > 0)
+      .sort((a, b) => EventId.compare(a.id, b.id))
+  })
+
+export const getClientHeadFromDb = (dbEventlog: SqliteDb): EventId.EventId => {
+  const res = dbEventlog.select<{ idGlobal: EventId.GlobalEventId; idClient: EventId.ClientEventId }>(
+    sql`select idGlobal, idClient from ${EVENTLOG_META_TABLE} order by idGlobal DESC, idClient DESC limit 1`,
+  )[0]
+
+  return res ? { global: res.idGlobal, client: res.idClient } : EventId.ROOT
+}
+
+export const getBackendHeadFromDb = (dbEventlog: SqliteDb): EventId.GlobalEventId =>
+  dbEventlog.select<{ head: EventId.GlobalEventId }>(sql`select head from ${SYNC_STATUS_TABLE}`)[0]?.head ??
+  EventId.ROOT.global
+
+// TODO use prepared statements
+export const updateBackendHead = (dbEventlog: SqliteDb, head: EventId.EventId) =>
+  dbEventlog.execute(sql`UPDATE ${SYNC_STATUS_TABLE} SET head = ${head.global}`)
+
+export const insertIntoEventlog = (
+  eventEncoded: LiveStoreEvent.EncodedWithMeta,
+  dbEventlog: SqliteDb,
+  eventDefSchemaHash: number,
+  clientId: string,
+  sessionId: string,
+) =>
+  Effect.gen(function* () {
+    // Check history consistency during LS_DEV
+    if (LS_DEV && eventEncoded.parentId.global !== EventId.ROOT.global) {
+      const parentEventExists =
+        dbEventlog.select<{ count: number }>(
+          `SELECT COUNT(*) as count FROM ${EVENTLOG_META_TABLE} WHERE idGlobal = ? AND idClient = ?`,
+          [eventEncoded.parentId.global, eventEncoded.parentId.client] as any as PreparedBindValues,
+        )[0]!.count === 1
+
+      if (parentEventExists === false) {
+        shouldNeverHappen(
+          `Parent mutation ${eventEncoded.parentId.global},${eventEncoded.parentId.client} does not exist`,
+        )
+      }
+    }
+
+    // TODO use prepared statements
+    yield* execSql(
+      dbEventlog,
+      ...insertRow({
+        tableName: EVENTLOG_META_TABLE,
+        columns: eventlogMetaTable.sqliteDef.columns,
+        values: {
+          idGlobal: eventEncoded.id.global,
+          idClient: eventEncoded.id.client,
+          parentIdGlobal: eventEncoded.parentId.global,
+          parentIdClient: eventEncoded.parentId.client,
+          name: eventEncoded.name,
+          argsJson: eventEncoded.args ?? {},
+          clientId,
+          sessionId,
+          schemaHash: eventDefSchemaHash,
+          syncMetadataJson: eventEncoded.meta.syncMetadata,
+        },
+      }),
+    )
+  })
+
+export const updateSyncMetadata = (items: ReadonlyArray<LiveStoreEvent.EncodedWithMeta>) =>
+  Effect.gen(function* () {
+    const { dbEventlog } = yield* LeaderThreadCtx
+
+    // TODO try to do this in a single query
+    for (let i = 0; i < items.length; i++) {
+      const event = items[i]!
+
+      yield* execSql(
+        dbEventlog,
+        ...updateRows({
+          tableName: EVENTLOG_META_TABLE,
+          columns: eventlogMetaTable.sqliteDef.columns,
+          where: { idGlobal: event.id.global, idClient: event.id.client },
+          updateValues: { syncMetadataJson: event.meta.syncMetadata },
+        }),
+      )
+    }
+  })
+
+export const getSyncBackendCursorInfo = (remoteHead: EventId.GlobalEventId) =>
+  Effect.gen(function* () {
+    const { dbEventlog } = yield* LeaderThreadCtx
+
+    if (remoteHead === EventId.ROOT.global) return Option.none()
+
+    const EventlogQuerySchema = Schema.Struct({
+      syncMetadataJson: Schema.parseJson(Schema.Option(Schema.JsonValue)),
+    }).pipe(Schema.pluck('syncMetadataJson'), Schema.Array, Schema.head)
+
+    const syncMetadataOption = yield* Effect.sync(() =>
+      dbEventlog.select<{ syncMetadataJson: string }>(
+        sql`SELECT syncMetadataJson FROM ${EVENTLOG_META_TABLE} WHERE idGlobal = ${remoteHead} ORDER BY idClient ASC LIMIT 1`,
+      ),
+    ).pipe(Effect.andThen(Schema.decode(EventlogQuerySchema)), Effect.map(Option.flatten), Effect.orDie)
+
+    return Option.some({
+      cursor: { global: remoteHead, client: EventId.clientDefault },
+      metadata: syncMetadataOption,
+    }) satisfies InitialSyncInfo
+  }).pipe(Effect.withSpan('@livestore/common:eventlog:getSyncBackendCursorInfo', { attributes: { remoteHead } }))

package/src/leader-thread/leader-worker-devtools.ts

@@ -2,7 +2,7 @@ import { Effect, FiberMap, Option, Stream, SubscriptionRef } from '@livestore/ut
 import { nanoid } from '@livestore/utils/nanoid'
 
 import { Devtools, IntentionalShutdownCause, liveStoreVersion, UnexpectedError } from '../index.js'
-import { MUTATION_LOG_META_TABLE, SCHEMA_META_TABLE, SCHEMA_MUTATIONS_META_TABLE } from '../schema/mod.js'
+import { EVENTLOG_META_TABLE, SCHEMA_EVENT_DEFS_META_TABLE, SCHEMA_META_TABLE } from '../schema/mod.js'
 import type { DevtoolsOptions, PersistenceInfoPair } from './types.js'
 import { LeaderThreadCtx } from './types.js'
 
@@ -63,7 +63,7 @@ const listenToDevtools = ({
       syncBackend,
       makeSqliteDb,
       dbReadModel,
-      dbMutationLog,
+      dbEventlog,
       shutdownStateSubRef,
       shutdownChannel,
       syncProcessor,
@@ -143,20 +143,20 @@ const listenToDevtools = ({
               }
 
               try {
-                if (tableNames.has(MUTATION_LOG_META_TABLE)) {
-                  // Is mutation log
+                if (tableNames.has(EVENTLOG_META_TABLE)) {
+                  // Is eventlog
                   yield* SubscriptionRef.set(shutdownStateSubRef, 'shutting-down')
 
-                  dbMutationLog.import(data)
+                  dbEventlog.import(data)
 
                   dbReadModel.destroy()
-                } else if (tableNames.has(SCHEMA_META_TABLE) && tableNames.has(SCHEMA_MUTATIONS_META_TABLE)) {
+                } else if (tableNames.has(SCHEMA_META_TABLE) && tableNames.has(SCHEMA_EVENT_DEFS_META_TABLE)) {
                   // Is read model
                   yield* SubscriptionRef.set(shutdownStateSubRef, 'shutting-down')
 
                   dbReadModel.import(data)
 
-                  dbMutationLog.destroy()
+                  dbEventlog.destroy()
                 } else {
                   yield* sendMessage(
                     Devtools.Leader.LoadDatabaseFile.Error.make({
@@ -190,7 +190,7 @@ const listenToDevtools = ({
               dbReadModel.destroy()
 
               if (mode === 'all-data') {
-                dbMutationLog.destroy()
+                dbEventlog.destroy()
               }
 
               yield* sendMessage(Devtools.Leader.ResetAllData.Success.make({ ...reqPayload }))
@@ -207,33 +207,33 @@ const listenToDevtools = ({
 
               const dbSizeQuery = `SELECT page_count * page_size as size FROM pragma_page_count(), pragma_page_size();`
               const dbFileSize = dbReadModel.select<{ size: number }>(dbSizeQuery, undefined)[0]!.size
-              const mutationLogFileSize = dbMutationLog.select<{ size: number }>(dbSizeQuery, undefined)[0]!.size
+              const eventlogFileSize = dbEventlog.select<{ size: number }>(dbSizeQuery, undefined)[0]!.size
 
               yield* sendMessage(
                 Devtools.Leader.DatabaseFileInfoRes.make({
                   readModel: { fileSize: dbFileSize, persistenceInfo: persistenceInfo.readModel },
-                  mutationLog: { fileSize: mutationLogFileSize, persistenceInfo: persistenceInfo.mutationLog },
+                  eventlog: { fileSize: eventlogFileSize, persistenceInfo: persistenceInfo.eventlog },
                   ...reqPayload,
                 }),
               )
 
               return
             }
-            case 'LSD.Leader.MutationLogReq': {
-              const mutationLog = dbMutationLog.export()
+            case 'LSD.Leader.EventlogReq': {
+              const eventlog = dbEventlog.export()
 
-              yield* sendMessage(Devtools.Leader.MutationLogRes.make({ mutationLog, ...reqPayload }))
+              yield* sendMessage(Devtools.Leader.EventlogRes.make({ eventlog, ...reqPayload }))
 
               return
             }
-            case 'LSD.Leader.RunMutationReq': {
+            case 'LSD.Leader.CommitEventReq': {
               yield* syncProcessor.pushPartial({
-                mutationEvent: decodedEvent.mutationEventEncoded,
+                event: decodedEvent.eventEncoded,
                 clientId: `devtools-${clientId}`,
                 sessionId: `devtools-${clientId}`,
               })
 
-              yield* sendMessage(Devtools.Leader.RunMutationRes.make({ ...reqPayload }))
+              yield* sendMessage(Devtools.Leader.CommitEventRes.make({ ...reqPayload }))
 
               return
             }
@@ -245,10 +245,10 @@ const listenToDevtools = ({
                 yield* syncBackend.pull(Option.none()).pipe(
                   Stream.map((_) => _.batch),
                   Stream.flattenIterables,
-                  Stream.tap(({ mutationEventEncoded, metadata }) =>
+                  Stream.tap(({ eventEncoded, metadata }) =>
                     sendMessage(
                       Devtools.Leader.SyncHistoryRes.make({
-                        mutationEventEncoded,
+                        eventEncoded,
                         metadata,
                         subscriptionId,
                         ...reqPayload,

package/src/leader-thread/make-leader-thread-layer.ts

@@ -5,13 +5,13 @@ import type { BootStatus, MakeSqliteDb, MigrationsReport, SqliteError } from '..
 import { UnexpectedError } from '../adapter-types.js'
 import type * as Devtools from '../devtools/mod.js'
 import type { LiveStoreSchema } from '../schema/mod.js'
-import { MutationEvent } from '../schema/mod.js'
+import { LiveStoreEvent } from '../schema/mod.js'
 import type { InvalidPullError, IsOfflineError, SyncOptions } from '../sync/sync.js'
 import { sql } from '../util.js'
-import { makeApplyMutation } from './apply-mutation.js'
+import { makeApplyEvent } from './apply-event.js'
+import * as Eventlog from './eventlog.js'
 import { bootDevtools } from './leader-worker-devtools.js'
 import { makeLeaderSyncProcessor } from './LeaderSyncProcessor.js'
-import * as Mutationlog from './mutationlog.js'
 import { recreateDb } from './recreate-db.js'
 import type { ShutdownChannel } from './shutdown-channel.js'
 import type {
@@ -31,7 +31,7 @@ export interface MakeLeaderThreadLayerParams {
   makeSqliteDb: MakeSqliteDb
   syncOptions: SyncOptions | undefined
   dbReadModel: LeaderSqliteDb
-  dbMutationLog: LeaderSqliteDb
+  dbEventlog: LeaderSqliteDb
   devtoolsOptions: DevtoolsOptions
   shutdownChannel: ShutdownChannel
   params?: {
@@ -55,7 +55,7 @@ export const makeLeaderThreadLayer = ({
   makeSqliteDb,
   syncOptions,
   dbReadModel,
-  dbMutationLog,
+  dbEventlog,
   devtoolsOptions,
   shutdownChannel,
   params,
@@ -66,8 +66,8 @@ export const makeLeaderThreadLayer = ({
 
     // TODO do more validation here than just checking the count of tables
     // Either happens on initial boot or if schema changes
-    const dbMutationLogMissing =
-      dbMutationLog.select<{ count: number }>(sql`select count(*) as count from sqlite_master`)[0]!.count === 0
+    const dbEventlogMissing =
+      dbEventlog.select<{ count: number }>(sql`select count(*) as count from sqlite_master`)[0]!.count === 0
 
     const dbReadModelMissing =
       dbReadModel.select<{ count: number }>(sql`select count(*) as count from sqlite_master`)[0]!.count === 0
@@ -89,8 +89,8 @@ export const makeLeaderThreadLayer = ({
 
     const syncProcessor = yield* makeLeaderSyncProcessor({
       schema,
-      dbMutationLogMissing,
-      dbMutationLog,
+      dbEventlogMissing,
+      dbEventlog,
       dbReadModel,
       dbReadModelMissing,
       initialBlockingSyncContext,
@@ -116,7 +116,7 @@ export const makeLeaderThreadLayer = ({
         }
       : { enabled: false as const }
 
-    const applyMutation = yield* makeApplyMutation({ schema, dbReadModel, dbMutationLog })
+    const applyEvent = yield* makeApplyEvent({ schema, dbReadModel, dbEventlog })
 
     const ctx = {
       schema,
@@ -124,14 +124,14 @@ export const makeLeaderThreadLayer = ({
       storeId,
       clientId,
       dbReadModel,
-      dbMutationLog,
+      dbEventlog,
       makeSqliteDb,
-      mutationEventSchema: MutationEvent.makeMutationEventSchema(schema),
+      eventSchema: LiveStoreEvent.makeEventDefSchema(schema),
       shutdownStateSubRef: yield* SubscriptionRef.make<ShutdownState>('running'),
       shutdownChannel,
       syncBackend,
       syncProcessor,
-      applyMutation,
+      applyEvent,
       extraIncomingMessagesQueue,
       devtools: devtoolsContext,
       // State will be set during `bootLeaderThread`
@@ -168,7 +168,7 @@ const makeInitialBlockingSyncContext = ({
   Effect.gen(function* () {
     const ctx = {
       isDone: false,
-      processedMutations: 0,
+      processedEvents: 0,
       total: -1,
     }
 
@@ -191,10 +191,10 @@ const makeInitialBlockingSyncContext = ({
             ctx.total = remaining + processed
           }
 
-          ctx.processedMutations += processed
+          ctx.processedEvents += processed
           yield* Queue.offer(bootStatusQueue, {
             stage: 'syncing',
-            progress: { done: ctx.processedMutations, total: ctx.total },
+            progress: { done: ctx.processedEvents, total: ctx.total },
           })
 
           if (remaining === 0 && blockingDeferred !== undefined) {
@@ -223,9 +223,9 @@ const bootLeaderThread = ({
   LeaderThreadCtx | Scope.Scope | HttpClient.HttpClient
 > =>
   Effect.gen(function* () {
-    const { dbMutationLog, bootStatusQueue, syncProcessor } = yield* LeaderThreadCtx
+    const { dbEventlog, bootStatusQueue, syncProcessor } = yield* LeaderThreadCtx
 
-    yield* Mutationlog.initMutationLogDb(dbMutationLog)
+    yield* Eventlog.initEventlogDb(dbEventlog)
 
     let migrationsReport: MigrationsReport
     if (dbReadModelMissing) {

package/src/leader-thread/mod.ts

@@ -3,4 +3,4 @@ export * from './types.js'
 export * as ShutdownChannel from './shutdown-channel.js'
 export * from './leader-worker-devtools.js'
 export * from './make-leader-thread-layer.js'
-export * as Mutationlog from './mutationlog.js'
+export * as Eventlog from './eventlog.js'

package/src/leader-thread/recreate-db.ts

@@ -3,7 +3,7 @@ import type { HttpClient } from '@livestore/utils/effect'
 import { Effect, Queue } from '@livestore/utils/effect'
 
 import type { InvalidPullError, IsOfflineError, MigrationHooks, MigrationsReport, SqliteError } from '../index.js'
-import { initializeSingletonTables, migrateDb, rehydrateFromMutationLog, UnexpectedError } from '../index.js'
+import { migrateDb, rehydrateFromEventlog, UnexpectedError } from '../index.js'
 import { configureConnection } from './connection.js'
 import { LeaderThreadCtx } from './types.js'
 
@@ -12,7 +12,7 @@ export const recreateDb: Effect.Effect<
   UnexpectedError | SqliteError | IsOfflineError | InvalidPullError,
   LeaderThreadCtx | HttpClient.HttpClient
 > = Effect.gen(function* () {
-  const { dbReadModel, dbMutationLog, schema, bootStatusQueue, applyMutation } = yield* LeaderThreadCtx
+  const { dbReadModel, dbEventlog, schema, bootStatusQueue, applyEvent } = yield* LeaderThreadCtx
 
   const migrationOptions = schema.migrationOptions
   let migrationsReport: MigrationsReport
@@ -41,26 +41,23 @@ export const recreateDb: Effect.Effect<
           Queue.offer(bootStatusQueue, { stage: 'migrating', progress: { done, total } }),
       })
 
-      initializeSingletonTables(schema, tmpDb)
-
       yield* Effect.tryAll(() => hooks?.pre?.(tmpDb)).pipe(UnexpectedError.mapToUnexpectedError)
 
       return { migrationsReport, tmpDb }
     })
 
   switch (migrationOptions.strategy) {
-    case 'from-mutation-log': {
+    case 'from-eventlog': {
       const hooks = migrationOptions.hooks
       const initResult = yield* initDb(hooks)
 
       migrationsReport = initResult.migrationsReport
 
-      yield* rehydrateFromMutationLog({
+      yield* rehydrateFromEventlog({
         // db: initResult.tmpDb,
-        dbMutationLog,
+        dbEventlog,
         schema,
-        migrationOptions,
-        applyMutation,
+        applyEvent,
         onProgress: ({ done, total }) =>
           Queue.offer(bootStatusQueue, { stage: 'rehydrating', progress: { done, total } }),
       })

package/src/leader-thread/types.ts

@@ -24,7 +24,7 @@ import type {
   SyncBackend,
   UnexpectedError,
 } from '../index.js'
-import type { EventId, LiveStoreSchema, MutationEvent } from '../schema/mod.js'
+import type { EventId, LiveStoreEvent, LiveStoreSchema } from '../schema/mod.js'
 import type * as SyncState from '../sync/syncstate.js'
 import type { ShutdownChannel } from './shutdown-channel.js'
 
@@ -52,7 +52,7 @@ export type InitialSyncInfo = Option.Option<{
 //   | { _tag: 'Reuse'; syncInfo: InitialSyncInfo }
 
 export type LeaderSqliteDb = SqliteDb<{ dbPointer: number; persistenceInfo: PersistenceInfo }>
-export type PersistenceInfoPair = { readModel: PersistenceInfo; mutationLog: PersistenceInfo }
+export type PersistenceInfoPair = { readModel: PersistenceInfo; eventlog: PersistenceInfo }
 
 export type DevtoolsOptions =
   | {
@@ -90,16 +90,16 @@ export class LeaderThreadCtx extends Context.Tag('LeaderThreadCtx')<
     clientId: string
     makeSqliteDb: MakeSqliteDb
     dbReadModel: LeaderSqliteDb
-    dbMutationLog: LeaderSqliteDb
+    dbEventlog: LeaderSqliteDb
     bootStatusQueue: Queue.Queue<BootStatus>
     // TODO we should find a more elegant way to handle cases which need this ref for their implementation
     shutdownStateSubRef: SubscriptionRef.SubscriptionRef<ShutdownState>
     shutdownChannel: ShutdownChannel
-    mutationEventSchema: MutationEvent.ForMutationDefRecord<any>
+    eventSchema: LiveStoreEvent.ForEventDefRecord<any>
     devtools: DevtoolsContext
     syncBackend: SyncBackend | undefined
     syncProcessor: LeaderSyncProcessor
-    applyMutation: ApplyMutation
+    applyEvent: ApplyEvent
     initialState: {
       leaderHead: EventId.EventId
       migrationsReport: MigrationsReport
@@ -113,11 +113,11 @@ export class LeaderThreadCtx extends Context.Tag('LeaderThreadCtx')<
   }
 >() {}
 
-export type ApplyMutation = (
-  mutationEventEncoded: MutationEvent.EncodedWithMeta,
+export type ApplyEvent = (
+  eventEncoded: LiveStoreEvent.EncodedWithMeta,
   options?: {
-    /** Needed for rehydrateFromMutationLog */
-    skipMutationLog?: boolean
+    /** Needed for rehydrateFromEventlog */
+    skipEventlog?: boolean
   },
 ) => Effect.Effect<
   { sessionChangeset: { _tag: 'sessionChangeset'; data: Uint8Array; debug: any } | { _tag: 'no-op' } },
@@ -143,10 +143,10 @@ export interface LeaderSyncProcessor {
     Scope.Scope
   >
 
-  /** Used by client sessions to push mutations to the leader thread */
+  /** Used by client sessions to push events to the leader thread */
   push: (
     /** `batch` needs to follow the same rules as `batch` in `SyncBackend.push` */
-    batch: ReadonlyArray<MutationEvent.EncodedWithMeta>,
+    batch: ReadonlyArray<LiveStoreEvent.EncodedWithMeta>,
     options?: {
       /**
        * If true, the effect will only finish when the local push has been processed (i.e. succeeded or was rejected).
@@ -158,7 +158,7 @@ export interface LeaderSyncProcessor {
 
   /** Currently only used by devtools which don't provide their own event numbers */
   pushPartial: (args: {
-    mutationEvent: MutationEvent.PartialAnyEncoded
+    event: LiveStoreEvent.PartialAnyEncoded
     clientId: string
     sessionId: string
   }) => Effect.Effect<void, UnexpectedError>

package/src/materializer-helper.ts

@@ -0,0 +1,110 @@
+import { isReadonlyArray } from '@livestore/utils'
+import { Schema } from '@livestore/utils/effect'
+
+import { SessionIdSymbol } from './adapter-types.js'
+import { isQueryBuilder } from './query-builder/api.js'
+import type { EventDef, Materializer, MaterializerResult } from './schema/EventDef.js'
+import type * as LiveStoreEvent from './schema/LiveStoreEvent.js'
+import type { BindValues } from './sql-queries/sql-queries.js'
+import type { PreparedBindValues } from './util.js'
+import { prepareBindValues } from './util.js'
+
+export const getExecArgsFromEvent = ({
+  eventDef: { eventDef, materializer },
+  event,
+}: {
+  eventDef: {
+    eventDef: EventDef.AnyWithoutFn
+    materializer: Materializer
+  }
+  /** Both encoded and decoded events are supported to reduce the number of times we need to decode/encode */
+  event:
+    | {
+        decoded: LiveStoreEvent.AnyDecoded | LiveStoreEvent.PartialAnyDecoded
+        encoded: undefined
+      }
+    | {
+        decoded: undefined
+        encoded: LiveStoreEvent.AnyEncoded | LiveStoreEvent.PartialAnyEncoded
+      }
+}): ReadonlyArray<{
+  statementSql: string
+  bindValues: PreparedBindValues
+  writeTables: ReadonlySet<string> | undefined
+}> => {
+  const eventArgsDecoded = event.decoded?.args ?? Schema.decodeUnknownSync(eventDef.schema)(event.encoded!.args)
+
+  const res = materializer(eventArgsDecoded, {
+    clientOnly: eventDef.options.clientOnly,
+    // TODO properly implement this
+    currentFacts: new Map(),
+  })
+
+  const statementRes = mapMaterializerResult(res)
+
+  return statementRes.map((statementRes) => {
+    const statementSql = statementRes.sql
+
+    const eventArgsEncoded = event.encoded?.args ?? Schema.encodeUnknownSync(eventDef.schema)(event.decoded!.args)
+    const bindValues = typeof statementRes === 'string' ? eventArgsEncoded : statementRes.bindValues
+
+    const writeTables = typeof statementRes === 'string' ? undefined : statementRes.writeTables
+
+    return { statementSql, bindValues: prepareBindValues(bindValues ?? {}, statementSql), writeTables }
+  })
+}
+
+const mapMaterializerResult = (
+  materializerResult: MaterializerResult | ReadonlyArray<MaterializerResult>,
+): ReadonlyArray<{
+  sql: string
+  bindValues: BindValues
+  writeTables: ReadonlySet<string> | undefined
+}> => {
+  if (isReadonlyArray(materializerResult)) {
+    return materializerResult.flatMap(mapMaterializerResult)
+  }
+  if (isQueryBuilder(materializerResult)) {
+    const { query, bindValues } = materializerResult.asSql()
+    return [{ sql: query, bindValues: bindValues as BindValues, writeTables: undefined }]
+  } else if (typeof materializerResult === 'string') {
+    return [{ sql: materializerResult, bindValues: {} as BindValues, writeTables: undefined }]
+  } else {
+    return [
+      {
+        sql: materializerResult.sql,
+        bindValues: materializerResult.bindValues,
+        writeTables: materializerResult.writeTables,
+      },
+    ]
+  }
+}
+
+// NOTE we should explore whether there is a more elegant solution
+// e.g. by leveraging the schema to replace the sessionIdSymbol
+export const replaceSessionIdSymbol = (
+  bindValues: Record<string, unknown> | ReadonlyArray<unknown>,
+  sessionId: string,
+) => {
+  deepReplaceValue(bindValues, SessionIdSymbol, sessionId)
+}
+
+const deepReplaceValue = <S, R>(input: any, searchValue: S, replaceValue: R): void => {
+  if (Array.isArray(input)) {
+    for (const i in input) {
+      if (input[i] === searchValue) {
+        input[i] = replaceValue
+      } else {
+        deepReplaceValue(input[i], searchValue, replaceValue)
+      }
+    }
+  } else if (typeof input === 'object' && input !== null) {
+    for (const key in input) {
+      if (input[key] === searchValue) {
+        input[key] = replaceValue
+      } else {
+        deepReplaceValue(input[key], searchValue, replaceValue)
+      }
+    }
+  }
+}