@livestore/common 0.3.0-dev.3 → 0.3.0-dev.31

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.test.ts

@@ -0,0 +1,12 @@
+import { Vitest } from '@livestore/utils/node-vitest'
+import { expect } from 'vitest'
+
+import { EventId } from './mod.js'
+
+Vitest.describe('EventId', () => {
+  Vitest.test('nextPair', () => {
+    const e_0_0 = EventId.make({ global: 0, client: 0 })
+    expect(EventId.nextPair(e_0_0, false).id).toStrictEqual({ global: 1, client: 0 })
+    expect(EventId.nextPair(e_0_0, true).id).toStrictEqual({ global: 0, client: 1 })
+  })
+})

package/src/schema/EventId.ts

@@ -1,16 +1,41 @@
-import { Schema } from '@livestore/utils/effect'
+import { Brand, Schema } from '@livestore/utils/effect'
+
+export type ClientEventId = Brand.Branded<number, 'ClientEventId'>
+export const localEventId = Brand.nominal<ClientEventId>()
+export const ClientEventId = Schema.fromBrand(localEventId)(Schema.Int)
+
+export type GlobalEventId = Brand.Branded<number, 'GlobalEventId'>
+export const globalEventId = Brand.nominal<GlobalEventId>()
+export const GlobalEventId = Schema.fromBrand(globalEventId)(Schema.Int)
+
+export const clientDefault = 0 as any as ClientEventId
 
 /**
  * LiveStore event id value consisting of a globally unique event sequence number
- * and a local sequence number.
+ * and a client sequence number.
  *
- * The local sequence number is only used for localOnly 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: number; local: 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: Schema.Number,
-  local: Schema.Number,
+  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' })
 
 /**
@@ -20,27 +45,62 @@ export const compare = (a: EventId, b: EventId) => {
   if (a.global !== b.global) {
     return a.global - b.global
   }
-  return a.local - b.local
+  return a.client - b.client
+}
+
+/**
+ * Convert an event id to a string representation.
+ */
+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.
+ */
+export const fromString = (str: string): EventId => {
+  const [global, client] = str.slice(1, -1).split(',').map(Number)
+  if (global === undefined || client === undefined) {
+    throw new Error('Invalid event id string')
+  }
+  return { global, client } as EventId
 }
 
-export const isEqual = (a: EventId, b: EventId) => a.global === b.global && a.local === b.local
+export const isEqual = (a: EventId, b: EventId) => a.global === b.global && a.client === b.client
 
 export type EventIdPair = { id: EventId; parentId: EventId }
 
-export const ROOT = { global: -1, local: 0 } 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.local > b.local)
+  return a.global > b.global || (a.global === b.global && a.client > b.client)
+}
+
+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)
 }
 
-export const nextPair = (id: EventId, isLocal: boolean) => {
+export const nextPair = (id: EventId, isLocal: boolean): EventIdPair => {
   if (isLocal) {
-    return { id: { global: id.global, local: id.local + 1 }, parentId: id }
+    return { id: { global: id.global, client: (id.client + 1) as any as ClientEventId }, parentId: id }
   }
 
   return {
-    id: { global: id.global + 1, local: 0 },
-    // NOTE we always point to `local: 0` for non-localOnly mutations
-    parentId: { global: id.global, local: 0 },
+    id: { global: (id.global + 1) as any as GlobalEventId, client: clientDefault },
+    // 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)