@livestore/common 0.0.0-snapshot-2ef046b02334f52613d31dbe06af53487685edc0 → 0.0.0-snapshot-8115ad48d5a57244358c943ecc92bb0a30274b87

package/src/{rehydrate-from-mutationlog.ts → rehydrate-from-eventlog.ts}

@@ -1,88 +1,85 @@
 import { memoizeByRef } from '@livestore/utils'
 import { Chunk, Effect, Option, Schema, Stream } from '@livestore/utils/effect'
 
-import { type MigrationOptionsFromMutationLog, type SqliteDb, UnexpectedError } from './adapter-types.js'
-import type { ApplyMutation } from './leader-thread/mod.js'
-import type { LiveStoreSchema, MutationDef, MutationLogMetaRow } from './schema/mod.js'
-import { EventId, getMutationDef, MUTATION_LOG_META_TABLE, MutationEvent } from './schema/mod.js'
+import { type MigrationOptionsFromEventlog, type SqliteDb, UnexpectedError } from './adapter-types.js'
+import type { ApplyEvent } from './leader-thread/mod.js'
+import type { EventDef, EventlogMetaRow, LiveStoreSchema } from './schema/mod.js'
+import { EventId, EVENTLOG_META_TABLE, getEventDef, LiveStoreEvent } from './schema/mod.js'
 import type { PreparedBindValues } from './util.js'
 import { sql } from './util.js'
 
-export const rehydrateFromMutationLog = ({
-  dbMutationLog,
+export const rehydrateFromEventlog = ({
+  dbEventlog,
   // TODO re-use this db when bringing back the boot in-memory db implementation
   // db,
   schema,
   migrationOptions,
   onProgress,
-  applyMutation,
+  applyEvent,
 }: {
-  dbMutationLog: SqliteDb
+  dbEventlog: SqliteDb
   // db: SqliteDb
   schema: LiveStoreSchema
-  migrationOptions: MigrationOptionsFromMutationLog
+  migrationOptions: MigrationOptionsFromEventlog
   onProgress: (_: { done: number; total: number }) => Effect.Effect<void>
-  applyMutation: ApplyMutation
+  applyEvent: ApplyEvent
 }) =>
   Effect.gen(function* () {
-    const mutationsCount = dbMutationLog.select<{ count: number }>(
-      `SELECT COUNT(*) AS count FROM ${MUTATION_LOG_META_TABLE}`,
-    )[0]!.count
+    const eventsCount = dbEventlog.select<{ count: number }>(`SELECT COUNT(*) AS count FROM ${EVENTLOG_META_TABLE}`)[0]!
+      .count
 
-    const hashMutation = memoizeByRef((mutation: MutationDef.Any) => Schema.hash(mutation.schema))
+    const hashEvent = memoizeByRef((event: EventDef.AnyWithoutFn) => Schema.hash(event.schema))
 
-    const processMutation = (row: MutationLogMetaRow) =>
+    const processEvent = (row: EventlogMetaRow) =>
       Effect.gen(function* () {
-        const mutationDef = getMutationDef(schema, row.mutation)
+        const eventDef = getEventDef(schema, row.name)
 
-        if (migrationOptions.excludeMutations?.has(row.mutation) === true) return
+        if (migrationOptions.excludeEvents?.has(row.name) === true) return
 
-        if (hashMutation(mutationDef) !== row.schemaHash) {
-          yield* Effect.logWarning(
-            `Schema hash mismatch for mutation ${row.mutation}. Trying to apply mutation anyway.`,
-          )
+        if (hashEvent(eventDef.eventDef) !== row.schemaHash) {
+          yield* Effect.logWarning(`Schema hash mismatch for mutation ${row.name}. Trying to apply mutation anyway.`)
         }
 
         const args = JSON.parse(row.argsJson)
 
         // Checking whether the schema has changed in an incompatible way
-        yield* Schema.decodeUnknown(mutationDef.schema)(args).pipe(
+        yield* Schema.decodeUnknown(eventDef.eventDef.schema)(args).pipe(
           Effect.mapError((cause) =>
             UnexpectedError.make({
               cause,
               note: `\
-There was an error during rehydrating from the mutation log while decoding
-the persisted mutation event args for mutation "${row.mutation}".
+There was an error during rehydrating from the eventlog while decoding
+the persisted mutation event args for mutation "${row.name}".
 This likely means the schema has changed in an incompatible way.
 `,
             }),
           ),
         )
 
-        const mutationEventEncoded = MutationEvent.EncodedWithMeta.make({
+        const eventEncoded = LiveStoreEvent.EncodedWithMeta.make({
           id: { global: row.idGlobal, client: row.idClient },
           parentId: { global: row.parentIdGlobal, client: row.parentIdClient },
-          mutation: row.mutation,
+          name: row.name,
           args,
           clientId: row.clientId,
           sessionId: row.sessionId,
         })
 
-        yield* applyMutation(mutationEventEncoded, { skipMutationLog: true })
-      }).pipe(Effect.withSpan(`@livestore/common:rehydrateFromMutationLog:processMutation`))
+        yield* applyEvent(eventEncoded, { skipEventlog: true })
+      }).pipe(Effect.withSpan(`@livestore/common:rehydrateFromEventlog:processEvent`))
 
     const CHUNK_SIZE = 100
 
-    const stmt = dbMutationLog.prepare(sql`\
-SELECT * FROM ${MUTATION_LOG_META_TABLE} 
+    const stmt = dbEventlog.prepare(sql`\
+SELECT * FROM ${EVENTLOG_META_TABLE} 
 WHERE idGlobal > $idGlobal OR (idGlobal = $idGlobal AND idClient > $idClient)
 ORDER BY idGlobal ASC, idClient ASC
 LIMIT ${CHUNK_SIZE}
 `)
 
-    let processedMutations = 0
+    let processedEvents = 0
 
-    yield* Stream.unfoldChunk<Chunk.Chunk<MutationLogMetaRow> | { _tag: 'Initial ' }, MutationLogMetaRow>(
+    yield* Stream.unfoldChunk<Chunk.Chunk<EventlogMetaRow> | { _tag: 'Initial ' }, EventlogMetaRow>(
       { _tag: 'Initial ' },
       (item) => {
         // End stream if no more rows
@@ -95,7 +92,7 @@ LIMIT ${CHUNK_SIZE}
             )
           : EventId.ROOT
         const nextItem = Chunk.fromIterable(
-          stmt.select<MutationLogMetaRow>({
+          stmt.select<EventlogMetaRow>({
             $idGlobal: lastId?.global,
             $idClient: lastId?.client,
           } as any as PreparedBindValues),
@@ -107,15 +104,15 @@ LIMIT ${CHUNK_SIZE}
       Stream.bufferChunks({ capacity: 2 }),
       Stream.tap((row) =>
         Effect.gen(function* () {
-          yield* processMutation(row)
+          yield* processEvent(row)
 
-          processedMutations++
-          yield* onProgress({ done: processedMutations, total: mutationsCount })
+          processedEvents++
+          yield* onProgress({ done: processedEvents, total: eventsCount })
         }),
       ),
       Stream.runDrain,
     )
   }).pipe(
-    Effect.withPerformanceMeasure('@livestore/common:rehydrateFromMutationLog'),
-    Effect.withSpan('@livestore/common:rehydrateFromMutationLog'),
+    Effect.withPerformanceMeasure('@livestore/common:rehydrateFromEventlog'),
+    Effect.withSpan('@livestore/common:rehydrateFromEventlog'),
   )

package/src/schema/EventDef.ts

@@ -0,0 +1,216 @@
+import type { SingleOrReadonlyArray } from '@livestore/utils'
+import { shouldNeverHappen } from '@livestore/utils'
+import { Schema } from '@livestore/utils/effect'
+
+import type { QueryBuilder } from '../query-builder/mod.js'
+import type { BindValues } from '../sql-queries/sql-queries.js'
+
+export type EventDefMap = {
+  map: Map<string | 'livestore.RawSql', EventDef.Any>
+}
+export type EventDefRecord = {
+  'livestore.RawSql': RawSqlEvent
+  [name: string]: EventDef.Any
+}
+
+export type EventDef<TName extends string, TType, TEncoded = TType, TDerived extends boolean = false> = {
+  name: TName
+  schema: Schema.Schema<TType, TEncoded>
+  options: {
+    /**
+     * When set to true, the mutation won't be synced across clients but
+     */
+    clientOnly: boolean
+    /** Warning: This feature is not fully implemented yet */
+    facts: FactsCallback<TType> | undefined
+    derived: TDerived
+  }
+
+  /** Helper function to construct a partial mutation event */
+  (args: TType): {
+    name: TName
+    args: TType
+  }
+
+  readonly Event: {
+    name: TName
+    args: TType
+  }
+}
+
+export type FactsCallback<TTo> = (
+  args: TTo,
+  currentFacts: EventDefFacts,
+) => {
+  modify: {
+    set: Iterable<EventDefFactInput>
+    unset: Iterable<EventDefFactInput>
+  }
+  require: Iterable<EventDefFactInput>
+}
+
+export namespace EventDef {
+  export type Any = EventDef<string, any, any, boolean>
+
+  export type AnyWithoutFn = Pick<Any, 'name' | 'schema' | 'options'>
+}
+
+export type EventDefKey = string
+export type EventDefFact = string
+export type EventDefFacts = ReadonlyMap<string, any>
+
+export type EventDefFactsGroup = {
+  modifySet: EventDefFacts
+  modifyUnset: EventDefFacts
+
+  /**
+   * Events on independent "dependency" branches are commutative which can facilitate more prioritized syncing
+   */
+  depRequire: EventDefFacts
+  depRead: EventDefFacts
+}
+
+export type EventDefFactsSnapshot = Map<string, any>
+
+export type EventDefFactInput = string | readonly [string, any]
+
+export const defineFacts = <
+  TRecord extends Record<string, EventDefFactInput | ((...args: any[]) => EventDefFactInput)>,
+>(
+  record: TRecord,
+): TRecord => record
+
+export type DefineEventOptions<TTo, TDerived extends boolean = false> = {
+  // TODO actually implement this
+  // onError?: (error: any) => void
+  /** Warning: This feature is not fully implemented yet */
+  facts?: (
+    args: TTo,
+    currentFacts: EventDefFacts,
+  ) => {
+    modify?: {
+      set?: Iterable<EventDefFactInput>
+      unset?: Iterable<EventDefFactInput>
+    }
+    /**
+     * Two purposes: constrain history and constrain compaction
+     */
+    require?: Iterable<EventDefFactInput>
+  }
+  /**
+   * When set to true, the event won't be synced over the network
+   */
+  clientOnly?: boolean
+  derived?: TDerived
+}
+
+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, '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>
+}
+
+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 })
+
+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 })
+
+export type MaterializerResult =
+  | {
+      sql: string
+      bindValues: BindValues
+      writeTables?: ReadonlySet<string>
+    }
+  | QueryBuilder.Any
+  | string
+
+export type Materializer<TEventDef extends EventDef.AnyWithoutFn = EventDef.AnyWithoutFn> = (
+  event: TEventDef['schema']['Type'],
+  context: { currentFacts: EventDefFacts; clientOnly: boolean },
+) => SingleOrReadonlyArray<MaterializerResult>
+
+export const defineMaterializer = <TEventDef extends EventDef.AnyWithoutFn>(
+  eventDef: TEventDef,
+  materializer: Materializer<TEventDef>,
+): Materializer<TEventDef> => {
+  return materializer
+}
+
+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 }>>
+    // [K in TInputRecord[keyof TInputRecord]['name']]: Materializer<
+    //   Extract<TInputRecord[keyof TInputRecord], { name: K }>
+    // >
+  },
+) => {
+  return handlers
+}
+
+export const rawSqlEvent = defineEvent({
+  name: 'livestore.RawSql',
+  schema: Schema.Struct({
+    sql: Schema.String,
+    bindValues: Schema.optional(Schema.Record({ key: Schema.String, value: Schema.Any })),
+    writeTables: Schema.optional(Schema.ReadonlySet(Schema.String)),
+  }),
+  clientOnly: true,
+  derived: true,
+})
+
+export const rawSqlMaterializer = defineMaterializer(rawSqlEvent, ({ sql, bindValues, writeTables }) => ({
+  sql,
+  bindValues: bindValues ?? {},
+  writeTables,
+}))
+
+export type RawSqlEvent = typeof rawSqlEvent

package/src/schema/EventId.ts

@@ -14,20 +14,28 @@ export const clientDefault = 0 as any as ClientEventId
  * LiveStore event id value consisting of a globally unique event sequence number
  * and a client sequence number.
  *
- * The client sequence number is only used for clientOnly mutations and starts from 0 for each global sequence number.
+ * The client sequence number is only used for clientOnly events and starts from 0 for each global sequence number.
  */
 export type EventId = { global: GlobalEventId; client: ClientEventId }
 
 // export const EventSequenceNumber = Schema.Struct({})
 // export const EventNumber = Schema.Struct({})
+// export const ClientEventNumber = Schema.Struct({})
+// export const GlobalEventNumber = Schema.Struct({})
 
 /**
  * NOTE: Client mutation events with a non-0 client id, won't be synced to the sync backend.
  */
 export const EventId = Schema.Struct({
   global: GlobalEventId,
-  /** Only increments for clientOnly mutations */
+  /** Only increments for clientOnly events */
   client: ClientEventId,
+
+  // TODO also provide a way to see "confirmation level" of event (e.g. confirmed by leader/sync backend)
+
+  // TODO: actually add this field
+  // Client only
+  // generation: Schema.Number.pipe(Schema.optional),
 }).annotations({ title: 'LiveStore.EventId' })
 
 /**
@@ -60,7 +68,7 @@ export const isEqual = (a: EventId, b: EventId) => a.global === b.global && a.cl
 
 export type EventIdPair = { id: EventId; parentId: EventId }
 
-export const ROOT = { global: -1 as any as GlobalEventId, client: clientDefault } satisfies EventId
+export const ROOT = { global: 0 as any as GlobalEventId, client: clientDefault } satisfies EventId
 
 export const isGreaterThan = (a: EventId, b: EventId) => {
   return a.global > b.global || (a.global === b.global && a.client > b.client)
@@ -70,6 +78,17 @@ export const isGreaterThanOrEqual = (a: EventId, b: EventId) => {
   return a.global > b.global || (a.global === b.global && a.client >= b.client)
 }
 
+export const max = (a: EventId, b: EventId) => {
+  return a.global > b.global || (a.global === b.global && a.client > b.client) ? a : b
+}
+
+export const diff = (a: EventId, b: EventId) => {
+  return {
+    global: a.global - b.global,
+    client: a.client - b.client,
+  }
+}
+
 export const make = (id: EventId | typeof EventId.Encoded): EventId => {
   return Schema.is(EventId)(id) ? id : Schema.decodeSync(EventId)(id)
 }
@@ -81,7 +100,7 @@ export const nextPair = (id: EventId, isLocal: boolean): EventIdPair => {
 
   return {
     id: { global: (id.global + 1) as any as GlobalEventId, client: clientDefault },
-    // NOTE we always point to `client: 0` for non-clientOnly mutations
+    // NOTE we always point to `client: 0` for non-clientOnly events
     parentId: { global: id.global, client: clientDefault },
   }
 }