@livestore/common 0.0.0-snapshot-2b8a9de3ec1a701aca891ebc2c98eb328274ae9e → 0.0.0-snapshot-2c861249e50661661613204300b1fc0d902c2e46

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 { makeApplyMutation } from './leader-thread/apply-mutation.js'
-import type { LiveStoreSchema, MutationDef, MutationEvent, MutationLogMetaRow } from './schema/mod.js'
-import { EventId, getMutationDef, MUTATION_LOG_META_TABLE } 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 = ({
-  logDb,
+export const rehydrateFromEventlog = ({
+  dbEventlog,
   // TODO re-use this db when bringing back the boot in-memory db implementation
   // db,
   schema,
   migrationOptions,
   onProgress,
+  applyEvent,
 }: {
-  logDb: SqliteDb
-  db: SqliteDb
+  dbEventlog: SqliteDb
+  // db: SqliteDb
   schema: LiveStoreSchema
-  migrationOptions: MigrationOptionsFromMutationLog
+  migrationOptions: MigrationOptionsFromEventlog
   onProgress: (_: { done: number; total: number }) => Effect.Effect<void>
+  applyEvent: ApplyEvent
 }) =>
   Effect.gen(function* () {
-    const mutationsCount = logDb.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 applyMutation = yield* makeApplyMutation
-
-    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 = {
+        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,
-        } satisfies MutationEvent.AnyEncoded
+        })
 
-        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 = logDb.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,13 +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 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' })
 
 /**
@@ -36,7 +51,7 @@ export const compare = (a: EventId, b: EventId) => {
 /**
  * Convert an event id to a string representation.
  */
-export const toString = (id: EventId) => `(${id.global},${id.client})`
+export const toString = (id: EventId) => (id.client === 0 ? `e${id.global}` : `e${id.global}+${id.client}`)
 
 /**
  * Convert a string representation of an event id to an event id.
@@ -53,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)
@@ -63,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)
 }
@@ -74,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 },
   }
 }

package/src/schema/LiveStoreEvent.ts

@@ -0,0 +1,239 @@
+import { memoizeByRef } from '@livestore/utils'
+import { Option, Schema } from '@livestore/utils/effect'
+
+import type { EventDef, EventDefRecord } from './EventDef.js'
+import * as EventId from './EventId.js'
+import type { LiveStoreSchema } from './schema.js'
+
+export type EventDefPartial<TEventDef extends EventDef.Any> = {
+  name: TEventDef['name']
+  args: Schema.Schema.Type<TEventDef['schema']>
+}
+
+export type PartialEncoded<TEventDef extends EventDef.Any> = {
+  name: TEventDef['name']
+  args: Schema.Schema.Encoded<TEventDef['schema']>
+}
+
+export type ForEventDef<TEventDef extends EventDef.Any> = {
+  name: TEventDef['name']
+  args: Schema.Schema.Type<TEventDef['schema']>
+  id: EventId.EventId
+  parentId: EventId.EventId
+  clientId: string
+  sessionId: string
+}
+
+export type EventDefEncoded<TEventDef extends EventDef.Any> = {
+  name: TEventDef['name']
+  args: Schema.Schema.Encoded<TEventDef['schema']>
+  id: EventId.EventId
+  parentId: EventId.EventId
+  clientId: string
+  sessionId: string
+}
+
+export type AnyDecoded = ForEventDef<EventDef.Any>
+export const AnyDecoded = Schema.Struct({
+  name: Schema.String,
+  args: Schema.Any,
+  id: EventId.EventId,
+  parentId: EventId.EventId,
+  clientId: Schema.String,
+  sessionId: Schema.String,
+}).annotations({ title: 'LiveStoreEvent.AnyDecoded' })
+
+export type AnyEncoded = EventDefEncoded<EventDef.Any>
+export const AnyEncoded = Schema.Struct({
+  name: Schema.String,
+  args: Schema.Any,
+  id: EventId.EventId,
+  parentId: EventId.EventId,
+  clientId: Schema.String,
+  sessionId: Schema.String,
+}).annotations({ title: 'LiveStoreEvent.AnyEncoded' })
+
+export const AnyEncodedGlobal = Schema.Struct({
+  name: Schema.String,
+  args: Schema.Any,
+  id: EventId.GlobalEventId,
+  parentId: EventId.GlobalEventId,
+  clientId: Schema.String,
+  sessionId: Schema.String,
+}).annotations({ title: 'LiveStoreEvent.AnyEncodedGlobal' })
+export type AnyEncodedGlobal = typeof AnyEncodedGlobal.Type
+
+export type PartialAnyDecoded = EventDefPartial<EventDef.Any>
+export type PartialAnyEncoded = PartialEncoded<EventDef.Any>
+
+export const PartialAnyEncoded = Schema.Struct({
+  name: Schema.String,
+  args: Schema.Any,
+})
+
+export type PartialForSchema<TSchema extends LiveStoreSchema> = {
+  [K in keyof TSchema['_EventDefMapType']]: EventDefPartial<TSchema['_EventDefMapType'][K]>
+}[keyof TSchema['_EventDefMapType']]
+
+export type ForSchema<TSchema extends LiveStoreSchema> = {
+  [K in keyof TSchema['_EventDefMapType']]: ForEventDef<TSchema['_EventDefMapType'][K]>
+}[keyof TSchema['_EventDefMapType']]
+
+export const isPartialEventDef = (event: AnyDecoded | PartialAnyDecoded): event is PartialAnyDecoded =>
+  'id' in event === false && 'parentId' in event === false
+
+export type ForEventDefRecord<TEventDefRecord extends EventDefRecord> = Schema.Schema<
+  {
+    [K in keyof TEventDefRecord]: {
+      name: K
+      args: Schema.Schema.Type<TEventDefRecord[K]['schema']>
+      id: EventId.EventId
+      parentId: EventId.EventId
+      clientId: string
+      sessionId: string
+    }
+  }[keyof TEventDefRecord],
+  {
+    [K in keyof TEventDefRecord]: {
+      name: K
+      args: Schema.Schema.Encoded<TEventDefRecord[K]['schema']>
+      id: EventId.EventId
+      parentId: EventId.EventId
+      clientId: string
+      sessionId: string
+    }
+  }[keyof TEventDefRecord]
+>
+
+export type EventDefPartialSchema<TEventDefRecord extends EventDefRecord> = Schema.Schema<
+  {
+    [K in keyof TEventDefRecord]: {
+      name: K
+      args: Schema.Schema.Type<TEventDefRecord[K]['schema']>
+    }
+  }[keyof TEventDefRecord],
+  {
+    [K in keyof TEventDefRecord]: {
+      name: K
+      args: Schema.Schema.Encoded<TEventDefRecord[K]['schema']>
+    }
+  }[keyof TEventDefRecord]
+>
+
+export const makeEventDefSchema = <TSchema extends LiveStoreSchema>(
+  schema: TSchema,
+): ForEventDefRecord<TSchema['_EventDefMapType']> =>
+  Schema.Union(
+    ...[...schema.eventsDefsMap.values()].map((def) =>
+      Schema.Struct({
+        name: Schema.Literal(def.name),
+        args: def.schema,
+        id: EventId.EventId,
+        parentId: EventId.EventId,
+        clientId: Schema.String,
+        sessionId: Schema.String,
+      }),
+    ),
+  ).annotations({ title: 'EventDef' }) as any
+
+export const makeEventDefPartialSchema = <TSchema extends LiveStoreSchema>(
+  schema: TSchema,
+): EventDefPartialSchema<TSchema['_EventDefMapType']> =>
+  Schema.Union(
+    ...[...schema.eventsDefsMap.values()].map((def) =>
+      Schema.Struct({
+        name: Schema.Literal(def.name),
+        args: def.schema,
+      }),
+    ),
+  ).annotations({ title: 'EventDefPartial' }) as any
+
+export const makeEventDefSchemaMemo = memoizeByRef(makeEventDefSchema)
+
+/** Equivalent to AnyEncoded but with a meta field and some convenience methods */
+export class EncodedWithMeta extends Schema.Class<EncodedWithMeta>('LiveStoreEvent.EncodedWithMeta')({
+  name: Schema.String,
+  args: Schema.Any,
+  // TODO rename to `.num` / `.parentNum`
+  id: EventId.EventId,
+  parentId: EventId.EventId,
+  clientId: Schema.String,
+  sessionId: Schema.String,
+  // TODO get rid of `meta` again by cleaning up the usage implementations
+  meta: Schema.Struct({
+    sessionChangeset: Schema.Union(
+      Schema.TaggedStruct('sessionChangeset', {
+        data: Schema.Uint8Array,
+        debug: Schema.Any.pipe(Schema.optional),
+      }),
+      Schema.TaggedStruct('no-op', {}),
+      Schema.TaggedStruct('unset', {}),
+    ),
+    syncMetadata: Schema.Option(Schema.JsonValue),
+  }).pipe(
+    Schema.mutable,
+    Schema.optional,
+    Schema.withDefaults({
+      constructor: () => ({ sessionChangeset: { _tag: 'unset' as const }, syncMetadata: Option.none() }),
+      decoding: () => ({ sessionChangeset: { _tag: 'unset' as const }, syncMetadata: Option.none() }),
+    }),
+  ),
+}) {
+  toJSON = (): any => {
+    // Only used for logging/debugging
+    // - More readable way to print the id + parentId
+    // - not including `meta`, `clientId`, `sessionId`
+    return {
+      id: `${EventId.toString(this.id)} → ${EventId.toString(this.parentId)} (${this.clientId}, ${this.sessionId})`,
+      name: this.name,
+      args: this.args,
+    }
+  }
+
+  /**
+   * Example: (global event)
+   * For event id e2 → e1 which should be rebased on event id e3 → e2
+   * the resulting event id will be e4 → e3
+   *
+   * Example: (client event)
+   * For event id e2+1 → e2 which should be rebased on event id e3 → e2
+   * the resulting event id will be e3+1 → e3
+   *
+   * Syntax: e2+2 → e2+1
+   *          ^ ^    ^ ^
+   *          | |    | +- client parent id
+   *          | |    +--- global parent id
+   *          | +-- client id
+   *          +---- global id
+   * Client id is ommitted for global events
+   */
+  rebase = (parentId: EventId.EventId, isClient: boolean) =>
+    new EncodedWithMeta({
+      ...this,
+      ...EventId.nextPair(parentId, isClient),
+    })
+
+  static fromGlobal = (event: AnyEncodedGlobal, syncMetadata: Option.Option<Schema.JsonValue>) =>
+    new EncodedWithMeta({
+      ...event,
+      id: { global: event.id, client: EventId.clientDefault },
+      parentId: { global: event.parentId, client: EventId.clientDefault },
+      meta: { sessionChangeset: { _tag: 'unset' as const }, syncMetadata },
+    })
+
+  toGlobal = (): AnyEncodedGlobal => ({
+    ...this,
+    id: this.id.global,
+    parentId: this.parentId.global,
+  })
+}
+
+/** NOTE `meta` is not considered for equality */
+export const isEqualEncoded = (a: AnyEncoded, b: AnyEncoded) =>
+  a.id.global === b.id.global &&
+  a.id.client === b.id.client &&
+  a.name === b.name &&
+  a.clientId === b.clientId &&
+  a.sessionId === b.sessionId &&
+  // TODO use schema equality here
+  JSON.stringify(a.args) === JSON.stringify(b.args)