@livestore/common 0.4.0-dev.18 → 0.4.0-dev.19

package/src/schema/EventSequenceNumber.ts

@@ -1,208 +0,0 @@
-import { Brand, Schema } from '@livestore/utils/effect'
-
-export type ClientEventSequenceNumber = Brand.Branded<number, 'ClientEventSequenceNumber'>
-export const localEventSequenceNumber = Brand.nominal<ClientEventSequenceNumber>()
-export const ClientEventSequenceNumber = Schema.fromBrand(localEventSequenceNumber)(Schema.Int)
-
-export type GlobalEventSequenceNumber = Brand.Branded<number, 'GlobalEventSequenceNumber'>
-export const globalEventSequenceNumber = Brand.nominal<GlobalEventSequenceNumber>()
-export const GlobalEventSequenceNumber = Schema.fromBrand(globalEventSequenceNumber)(Schema.Int)
-
-export const clientDefault = 0 as any as ClientEventSequenceNumber
-
-export const rebaseGenerationDefault = 0
-
-/**
- * LiveStore event sequence number value consisting of a globally unique event sequence number
- * and a client sequence number.
- *
- * The client sequence number is only used for client-local events and starts from 0 for each global sequence number.
- *
- * For event notation documentation, see: contributor-docs/events-notation.md
- */
-export type EventSequenceNumber = {
-  global: GlobalEventSequenceNumber
-  client: ClientEventSequenceNumber
-  /**
-   * Generation integer that is incremented whenever the client rebased.
-   * Remains constant for all subsequent events until another rebase occurs.
-   */
-  rebaseGeneration: number
-}
-
-export type EventSequenceNumberInput =
-  | EventSequenceNumber
-  | (Omit<typeof EventSequenceNumber.Encoded, 'rebaseGeneration'> & { rebaseGeneration?: number })
-
-// TODO adjust name to `ClientEventSequenceNumber`
-/**
- * NOTE: Client mutation events with a non-0 client id, won't be synced to the sync backend.
- */
-export const EventSequenceNumber = Schema.Struct({
-  global: GlobalEventSequenceNumber,
-  /** Only increments for client-local events */
-  client: ClientEventSequenceNumber,
-
-  // TODO also provide a way to see "confirmation level" of event (e.g. confirmed by leader/sync backend)
-
-  // Client only
-  rebaseGeneration: Schema.Int,
-}).annotations({
-  title: 'LiveStore.EventSequenceNumber',
-  pretty: () => (seqNum) => toString(seqNum),
-})
-
-/**
- * Compare two event sequence numbers i.e. checks if the first event sequence number is less than the second.
- * Comparison hierarchy: global > client > rebaseGeneration
- */
-export const compare = (a: EventSequenceNumber, b: EventSequenceNumber) => {
-  if (a.global !== b.global) {
-    return a.global - b.global
-  }
-  if (a.client !== b.client) {
-    return a.client - b.client
-  }
-  return a.rebaseGeneration - b.rebaseGeneration
-}
-
-/**
- * Convert an event sequence number to a string representation.
- *
- * For notation documentation, see: contributor-docs/events-notation.md
- */
-export const toString = (seqNum: EventSequenceNumber) => {
-  const rebaseGenerationStr = seqNum.rebaseGeneration > 0 ? `r${seqNum.rebaseGeneration}` : ''
-  return seqNum.client === 0
-    ? `e${seqNum.global}${rebaseGenerationStr}`
-    : `e${seqNum.global}.${seqNum.client}${rebaseGenerationStr}`
-}
-
-/**
- * Convert a string representation of an event sequence number to an event sequence number.
- * Parses strings in the format: e{global}[.{client}][r{rebaseGeneration}]
- * Examples: "e0", "e0r1", "e0.1", "e0.1r1"
- *
- * For full notation documentation, see: contributor-docs/events-notation.md
- */
-export const fromString = (str: string): EventSequenceNumber => {
-  if (!str.startsWith('e')) {
-    throw new Error('Invalid event sequence number string: must start with "e"')
-  }
-
-  // Remove the 'e' prefix
-  const remaining = str.slice(1)
-
-  // Parse rebase generation if present
-  let rebaseGeneration = rebaseGenerationDefault
-  let withoutRebase = remaining
-  const rebaseMatch = remaining.match(/r(\d+)$/)
-  if (rebaseMatch !== null) {
-    rebaseGeneration = Number.parseInt(rebaseMatch[1]!, 10)
-    withoutRebase = remaining.slice(0, -rebaseMatch[0].length)
-  }
-
-  // Parse global and client parts
-  const parts = withoutRebase.split('.')
-
-  // Validate that parts contain only digits (and possibly empty for client)
-  if (parts[0] === '' || !/^\d+$/.test(parts[0]!)) {
-    throw new Error('Invalid event sequence number string: invalid number format')
-  }
-
-  if (parts.length > 1 && parts[1] !== undefined && (parts[1] === '' || !/^\d+$/.test(parts[1]))) {
-    throw new Error('Invalid event sequence number string: invalid number format')
-  }
-
-  const global = Number.parseInt(parts[0]!, 10)
-  const client = parts.length > 1 && parts[1] !== undefined ? Number.parseInt(parts[1], 10) : 0
-
-  if (Number.isNaN(global) || Number.isNaN(client) || Number.isNaN(rebaseGeneration)) {
-    throw new TypeError('Invalid event sequence number string: invalid number format')
-  }
-
-  return {
-    global: global as any as GlobalEventSequenceNumber,
-    client: client as any as ClientEventSequenceNumber,
-    rebaseGeneration,
-  }
-}
-
-export const fromGlobal = (seqNum: GlobalEventSequenceNumber) => ({
-  global: seqNum,
-  client: clientDefault,
-  rebaseGeneration: rebaseGenerationDefault,
-})
-
-export const isEqual = (a: EventSequenceNumber, b: EventSequenceNumber) =>
-  a.global === b.global && a.client === b.client && a.rebaseGeneration === b.rebaseGeneration
-
-export type EventSequenceNumberPair = { seqNum: EventSequenceNumber; parentSeqNum: EventSequenceNumber }
-
-export const ROOT = {
-  global: 0 as any as GlobalEventSequenceNumber,
-  client: clientDefault,
-  rebaseGeneration: rebaseGenerationDefault,
-} satisfies EventSequenceNumber
-
-export const isGreaterThan = (a: EventSequenceNumber, b: EventSequenceNumber) => {
-  return a.global > b.global || (a.global === b.global && a.client > b.client)
-}
-
-export const isGreaterThanOrEqual = (a: EventSequenceNumber, b: EventSequenceNumber) => {
-  return a.global > b.global || (a.global === b.global && a.client >= b.client)
-}
-
-export const max = (a: EventSequenceNumber, b: EventSequenceNumber) => {
-  return a.global > b.global || (a.global === b.global && a.client > b.client) ? a : b
-}
-
-export const diff = (a: EventSequenceNumber, b: EventSequenceNumber) => {
-  return {
-    global: a.global - b.global,
-    client: a.client - b.client,
-  }
-}
-
-export const make = (seqNum: EventSequenceNumberInput): EventSequenceNumber => {
-  return Schema.is(EventSequenceNumber)(seqNum)
-    ? seqNum
-    : Schema.decodeSync(EventSequenceNumber)({
-        ...seqNum,
-        rebaseGeneration: seqNum.rebaseGeneration ?? rebaseGenerationDefault,
-      })
-}
-
-/**
- * Computes the next event sequence/parent pair.
- */
-export const nextPair = ({
-  seqNum,
-  isClient,
-  rebaseGeneration,
-}: {
-  seqNum: EventSequenceNumber
-  isClient: boolean
-  rebaseGeneration?: number
-}): EventSequenceNumberPair => {
-  if (isClient) {
-    return {
-      seqNum: {
-        global: seqNum.global,
-        client: (seqNum.client + 1) as any as ClientEventSequenceNumber,
-        rebaseGeneration: rebaseGeneration ?? seqNum.rebaseGeneration,
-      },
-      parentSeqNum: seqNum,
-    }
-  }
-
-  return {
-    seqNum: {
-      global: (seqNum.global + 1) as any as GlobalEventSequenceNumber,
-      client: clientDefault,
-      rebaseGeneration: rebaseGeneration ?? seqNum.rebaseGeneration,
-    },
-    // NOTE we always point to `client: 0` for non-client-local events
-    parentSeqNum: { global: seqNum.global, client: clientDefault, rebaseGeneration: seqNum.rebaseGeneration },
-  }
-}

package/src/schema/LiveStoreEvent.ts

@@ -1,286 +0,0 @@
-import { memoizeByRef } from '@livestore/utils'
-import { Option, Schema } from '@livestore/utils/effect'
-
-import type { EventDef, EventDefRecord } from './EventDef.ts'
-import * as EventSequenceNumber from './EventSequenceNumber.ts'
-import type { LiveStoreSchema } from './schema.ts'
-
-export namespace ForEventDef {
-  export type PartialDecoded<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 Decoded<TEventDef extends EventDef.Any> = {
-    name: TEventDef['name']
-    args: Schema.Schema.Type<TEventDef['schema']>
-    seqNum: EventSequenceNumber.EventSequenceNumber
-    parentSeqNum: EventSequenceNumber.EventSequenceNumber
-    clientId: string
-    sessionId: string
-  }
-
-  export type Encoded<TEventDef extends EventDef.Any> = {
-    name: TEventDef['name']
-    args: Schema.Schema.Encoded<TEventDef['schema']>
-    seqNum: EventSequenceNumber.EventSequenceNumber
-    parentSeqNum: EventSequenceNumber.EventSequenceNumber
-    clientId: string
-    sessionId: string
-  }
-}
-
-export type AnyDecoded = ForEventDef.Decoded<EventDef.Any>
-export const AnyDecoded = Schema.Struct({
-  name: Schema.String,
-  args: Schema.Any,
-  seqNum: EventSequenceNumber.EventSequenceNumber,
-  parentSeqNum: EventSequenceNumber.EventSequenceNumber,
-  clientId: Schema.String,
-  sessionId: Schema.String,
-}).annotations({ title: 'LiveStoreEvent.AnyDecoded' })
-
-export type AnyEncoded = ForEventDef.Encoded<EventDef.Any>
-export const AnyEncoded = Schema.Struct({
-  name: Schema.String,
-  args: Schema.Any,
-  seqNum: EventSequenceNumber.EventSequenceNumber,
-  parentSeqNum: EventSequenceNumber.EventSequenceNumber,
-  clientId: Schema.String,
-  sessionId: Schema.String,
-}).annotations({ title: 'LiveStoreEvent.AnyEncoded' })
-
-export const AnyEncodedGlobal = Schema.Struct({
-  name: Schema.String,
-  args: Schema.Any,
-  seqNum: EventSequenceNumber.GlobalEventSequenceNumber,
-  parentSeqNum: EventSequenceNumber.GlobalEventSequenceNumber,
-  clientId: Schema.String,
-  sessionId: Schema.String,
-}).annotations({ title: 'LiveStoreEvent.AnyEncodedGlobal' })
-export type AnyEncodedGlobal = typeof AnyEncodedGlobal.Type
-
-export type PartialAnyDecoded = ForEventDef.PartialDecoded<EventDef.Any>
-export type PartialAnyEncoded = ForEventDef.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']]: ForEventDef.PartialDecoded<TSchema['_EventDefMapType'][K]>
-}[keyof TSchema['_EventDefMapType']]
-
-export type ForSchema<TSchema extends LiveStoreSchema> = {
-  [K in keyof TSchema['_EventDefMapType']]: ForEventDef.Decoded<TSchema['_EventDefMapType'][K]>
-}[keyof TSchema['_EventDefMapType']]
-
-export const isPartialEventDef = (event: AnyDecoded | PartialAnyDecoded): event is PartialAnyDecoded =>
-  'num' in event === false && 'parentSeqNum' in event === false
-
-export type ForEventDefRecord<TEventDefRecord extends EventDefRecord> = Schema.Schema<
-  {
-    [K in keyof TEventDefRecord]: {
-      name: K
-      args: Schema.Schema.Type<TEventDefRecord[K]['schema']>
-      seqNum: EventSequenceNumber.EventSequenceNumber
-      parentSeqNum: EventSequenceNumber.EventSequenceNumber
-      clientId: string
-      sessionId: string
-    }
-  }[keyof TEventDefRecord],
-  {
-    [K in keyof TEventDefRecord]: {
-      name: K
-      args: Schema.Schema.Encoded<TEventDefRecord[K]['schema']>
-      seqNum: EventSequenceNumber.EventSequenceNumber
-      parentSeqNum: EventSequenceNumber.EventSequenceNumber
-      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,
-        seqNum: EventSequenceNumber.EventSequenceNumber,
-        parentSeqNum: EventSequenceNumber.EventSequenceNumber,
-        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)
-
-export const encodedFromGlobal = (event: AnyEncodedGlobal): AnyEncoded => ({
-  ...event,
-  seqNum: EventSequenceNumber.fromGlobal(event.seqNum),
-  parentSeqNum: EventSequenceNumber.fromGlobal(event.parentSeqNum),
-})
-
-/** 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,
-  seqNum: EventSequenceNumber.EventSequenceNumber,
-  parentSeqNum: EventSequenceNumber.EventSequenceNumber,
-  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 as any as Schema.Schema<Uint8Array<ArrayBuffer>>,
-        debug: Schema.Any.pipe(Schema.optional),
-      }),
-      Schema.TaggedStruct('no-op', {}),
-      Schema.TaggedStruct('unset', {}),
-    ),
-    syncMetadata: Schema.Option(Schema.JsonValue),
-    /** Used to detect if the materializer is side effecting (during dev) */
-    materializerHashLeader: Schema.Option(Schema.Number),
-    materializerHashSession: Schema.Option(Schema.Number),
-  }).pipe(
-    Schema.mutable,
-    Schema.optional,
-    Schema.withDefaults({
-      constructor: () => ({
-        sessionChangeset: { _tag: 'unset' as const },
-        syncMetadata: Option.none(),
-        materializerHashLeader: Option.none(),
-        materializerHashSession: Option.none(),
-      }),
-      decoding: () => ({
-        sessionChangeset: { _tag: 'unset' as const },
-        syncMetadata: Option.none(),
-        materializerHashLeader: Option.none(),
-        materializerHashSession: Option.none(),
-      }),
-    }),
-  ),
-}) {
-  toJSON = (): any => {
-    // Only used for logging/debugging
-    // - More readable way to print the seqNum + parentSeqNum
-    // - not including `meta`, `clientId`, `sessionId`
-    return {
-      seqNum: `${EventSequenceNumber.toString(this.seqNum)} → ${EventSequenceNumber.toString(this.parentSeqNum)} (${this.clientId}, ${this.sessionId})`,
-      name: this.name,
-      args: this.args,
-    }
-  }
-
-  /**
-   * Example: (global event)
-   * For event e2 → e1 which should be rebased on event e3 → e2
-   * the resulting event num will be e4 → e3
-   *
-   * Example: (client event)
-   * For event e2.1 → e2 which should be rebased on event e3 → e2
-   * the resulting event num will be e3.1 → e3
-   *
-   * Syntax: e2.2 → e2.1
-   *          ^ ^    ^ ^
-   *          | |    | +- client parent number
-   *          | |    +--- global parent number
-   *          | +-- client number
-   *          +---- global number
-   * Client num is omitted for global events
-   */
-  rebase = ({
-    parentSeqNum,
-    isClient,
-    rebaseGeneration,
-  }: {
-    parentSeqNum: EventSequenceNumber.EventSequenceNumber
-    isClient: boolean
-    rebaseGeneration: number
-  }) =>
-    new EncodedWithMeta({
-      ...this,
-      ...EventSequenceNumber.nextPair({ seqNum: parentSeqNum, isClient, rebaseGeneration }),
-    })
-
-  static fromGlobal = (
-    event: AnyEncodedGlobal,
-    meta: {
-      syncMetadata: Option.Option<Schema.JsonValue>
-      materializerHashLeader: Option.Option<number>
-      materializerHashSession: Option.Option<number>
-    },
-  ) =>
-    new EncodedWithMeta({
-      ...event,
-      seqNum: {
-        global: event.seqNum,
-        client: EventSequenceNumber.clientDefault,
-        rebaseGeneration: EventSequenceNumber.rebaseGenerationDefault,
-      },
-      parentSeqNum: {
-        global: event.parentSeqNum,
-        client: EventSequenceNumber.clientDefault,
-        rebaseGeneration: EventSequenceNumber.rebaseGenerationDefault,
-      },
-      meta: {
-        sessionChangeset: { _tag: 'unset' as const },
-        syncMetadata: meta.syncMetadata,
-        materializerHashLeader: meta.materializerHashLeader,
-        materializerHashSession: meta.materializerHashSession,
-      },
-    })
-
-  toGlobal = (): AnyEncodedGlobal => ({
-    ...this,
-    seqNum: this.seqNum.global,
-    parentSeqNum: this.parentSeqNum.global,
-  })
-}
-
-/** NOTE `meta` is not considered for equality */
-export const isEqualEncoded = (a: AnyEncoded, b: AnyEncoded) =>
-  a.seqNum.global === b.seqNum.global &&
-  a.seqNum.client === b.seqNum.client &&
-  a.name === b.name &&
-  a.clientId === b.clientId &&
-  a.sessionId === b.sessionId &&
-  JSON.stringify(a.args) === JSON.stringify(b.args) // TODO use schema equality here