@livestore/common 0.4.0-dev.2 → 0.4.0-dev.21

package/src/schema/EventSequenceNumber/client.ts

@@ -0,0 +1,257 @@
+import { Brand, Schema as S } from '@livestore/utils/effect'
+
+import { type Type as Global, Schema as GlobalSchema, make as makeGlobal } from './global.ts'
+
+/** Branded integer type for client-local sequence numbers. */
+export type Type = Brand.Branded<number, 'ClientEventSequenceNumber'>
+
+const ClientBrand = Brand.nominal<Type>()
+
+/** Effect Schema for encoding/decoding client sequence numbers. */
+export const Schema = S.fromBrand(ClientBrand)(S.Int)
+
+/**
+ * Creates a branded client sequence number from a plain number.
+ *
+ * @example
+ * ```ts
+ * const clientSeq = EventSequenceNumber.Client.make(1)
+ * ```
+ */
+export const make = ClientBrand
+
+/**
+ * Default client sequence number (0). Used for confirmed/synced events.
+ *
+ * @example
+ * ```ts
+ * const defaultSeq = EventSequenceNumber.Client.DEFAULT // 0
+ * ```
+ */
+export const DEFAULT = 0 as any as Type
+
+/** Default rebase generation (0). Increments each time the client rebases unconfirmed events. */
+export const REBASE_GENERATION_DEFAULT = 0
+
+/**
+ * Composite event sequence number consisting of global + client + rebaseGeneration.
+ * Used for client-side event tracking with support for unconfirmed local events.
+ *
+ * For event notation documentation, see: contributor-docs/events-notation.md
+ */
+export type Composite = {
+  global: Global
+  client: Type
+  /**
+   * Generation integer that is incremented whenever the client rebased.
+   * Remains constant for all subsequent events until another rebase occurs.
+   */
+  rebaseGeneration: number
+}
+
+/** Input type for creating a Composite sequence number. Allows omitting rebaseGeneration (defaults to 0). */
+export type CompositeInput =
+  | Composite
+  | (Omit<typeof CompositeSchema.Encoded, 'rebaseGeneration'> & { rebaseGeneration?: number })
+
+/** A pair of sequence numbers representing an event and its parent. */
+export type CompositePair = { seqNum: Composite; parentSeqNum: Composite }
+
+/**
+ * Compare two composite sequence numbers.
+ * Comparison hierarchy: global > client > rebaseGeneration
+ */
+export const compare = (a: Composite, b: Composite) => {
+  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 a composite sequence number to a string representation.
+ *
+ * For notation documentation, see: contributor-docs/events-notation.md
+ */
+export const toString = (seqNum: Composite) => {
+  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 a sequence number to a Composite.
+ * 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): Composite => {
+  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 = REBASE_GENERATION_DEFAULT
+  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 Global,
+    client: client as any as Type,
+    rebaseGeneration,
+  }
+}
+
+/** Creates a Composite sequence number from a global sequence number (client=0, rebaseGeneration=0). */
+export const fromGlobal = (seqNum: Global): Composite => ({
+  global: seqNum,
+  client: DEFAULT,
+  rebaseGeneration: REBASE_GENERATION_DEFAULT,
+})
+
+/** Returns true if two Composite sequence numbers are structurally equal. */
+export const isEqual = (a: Composite, b: Composite) =>
+  a.global === b.global && a.client === b.client && a.rebaseGeneration === b.rebaseGeneration
+
+/** Returns true if `a` is strictly greater than `b` (compares global, then client). */
+export const isGreaterThan = (a: Composite, b: Composite) => {
+  return a.global > b.global || (a.global === b.global && a.client > b.client)
+}
+
+/** Returns true if `a` is greater than or equal to `b` (compares global, then client). */
+export const isGreaterThanOrEqual = (a: Composite, b: Composite) => {
+  return a.global > b.global || (a.global === b.global && a.client >= b.client)
+}
+
+/** Returns the larger of two Composite sequence numbers. */
+export const max = (a: Composite, b: Composite) => {
+  return a.global > b.global || (a.global === b.global && a.client > b.client) ? a : b
+}
+
+/** Returns the difference between two Composite sequence numbers (a - b) for global and client components. */
+export const diff = (a: Composite, b: Composite) => {
+  return {
+    global: a.global - b.global,
+    client: a.client - b.client,
+  }
+}
+
+/**
+ * Schema for the composite event sequence number.
+ * NOTE: Client mutation events with a non-0 client id won't be synced to the sync backend.
+ */
+const CompositeSchema = S.Struct({
+  global: GlobalSchema,
+  /** Only increments for client-local events */
+  client: Schema,
+  // Client only
+  rebaseGeneration: S.Int,
+}).annotations({
+  title: 'EventSequenceNumber.Composite',
+  pretty: () => (seqNum) => toString(seqNum),
+})
+
+/**
+ * Creates a validated Composite sequence number from input.
+ * If rebaseGeneration is omitted, defaults to REBASE_GENERATION_DEFAULT (0).
+ */
+const makeComposite = (seqNum: CompositeInput): Composite => {
+  return S.is(CompositeSchema)(seqNum)
+    ? seqNum
+    : S.decodeSync(CompositeSchema)({
+        ...seqNum,
+        rebaseGeneration: seqNum.rebaseGeneration ?? REBASE_GENERATION_DEFAULT,
+      })
+}
+
+/**
+ * Effect Schema for the composite event sequence number (global + client + rebaseGeneration).
+ * Also includes a `make` helper for creating validated Composite values.
+ *
+ * @example
+ * ```ts
+ * const seqNum: EventSequenceNumber.Client.Composite = {
+ *   global: EventSequenceNumber.Global.make(5),
+ *   client: EventSequenceNumber.Client.DEFAULT,
+ *   rebaseGeneration: 0
+ * }
+ *
+ * const validated = EventSequenceNumber.Client.Composite.make({ global: 5, client: 0, rebaseGeneration: 0 })
+ * ```
+ */
+export const Composite = Object.assign(CompositeSchema, { make: makeComposite })
+
+/** The root sequence number (global=0, client=0, rebaseGeneration=0). Parent of the first event. */
+export const ROOT = {
+  global: makeGlobal(0),
+  client: DEFAULT,
+  rebaseGeneration: REBASE_GENERATION_DEFAULT,
+} satisfies Composite
+
+/**
+ * Computes the next sequence number and its parent based on the current position.
+ *
+ * For client-local events (isClient=true): increments the client component, keeps global.
+ * For global events (isClient=false): increments global, resets client to 0.
+ */
+export const nextPair = ({
+  seqNum,
+  isClient,
+  rebaseGeneration,
+}: {
+  seqNum: Composite
+  isClient: boolean
+  rebaseGeneration?: number
+}): CompositePair => {
+  if (isClient) {
+    return {
+      seqNum: {
+        global: seqNum.global,
+        client: (seqNum.client + 1) as any as Type,
+        rebaseGeneration: rebaseGeneration ?? seqNum.rebaseGeneration,
+      },
+      parentSeqNum: seqNum,
+    }
+  }
+
+  return {
+    seqNum: {
+      global: (seqNum.global + 1) as any as Global,
+      client: DEFAULT,
+      rebaseGeneration: rebaseGeneration ?? seqNum.rebaseGeneration,
+    },
+    // NOTE we always point to `client: 0` for non-client-local events
+    parentSeqNum: { global: seqNum.global, client: DEFAULT, rebaseGeneration: seqNum.rebaseGeneration },
+  }
+}

package/src/schema/EventSequenceNumber/global.ts

@@ -0,0 +1,19 @@
+import { Brand, Schema as S } from '@livestore/utils/effect'
+
+/** Branded integer type for global sequence numbers assigned by the sync backend. */
+export type Type = Brand.Branded<number, 'GlobalEventSequenceNumber'>
+
+const GlobalBrand = Brand.nominal<Type>()
+
+/** Effect Schema for encoding/decoding global sequence numbers. */
+export const Schema = S.fromBrand(GlobalBrand)(S.Int)
+
+/**
+ * Creates a branded global sequence number from a plain number.
+ *
+ * @example
+ * ```ts
+ * const seqNum = EventSequenceNumber.Global.make(5)
+ * ```
+ */
+export const make = GlobalBrand

package/src/schema/EventSequenceNumber/mod.ts

@@ -0,0 +1,37 @@
+/**
+ * Client sequence numbers track events created locally before sync confirmation.
+ * Also contains the Composite type combining global and client sequence numbers with a rebase
+ * generation to fully identify an event's position in the eventlog.
+ *
+ * For event notation documentation, see: contributor-docs/events-notation.md
+ *
+ * @example
+ * ```ts
+ * import { EventSequenceNumber } from '@livestore/common'
+ *
+ * // Client sequence number
+ * const clientSeq = EventSequenceNumber.Client.make(1)
+ *
+ * // Composite sequence number
+ * const composite: EventSequenceNumber.Client.Composite = {
+ *   global: EventSequenceNumber.Global.make(5),
+ *   client: EventSequenceNumber.Client.DEFAULT,
+ *   rebaseGeneration: 0,
+ * }
+ * ```
+ */
+export * as Client from './client.ts'
+
+/**
+ * Global sequence numbers are assigned by the sync backend and represent
+ * the canonical ordering of events across all clients. They are monotonically
+ * increasing integers that establish the authoritative event timeline.
+ *
+ * @example
+ * ```ts
+ * import { EventSequenceNumber } from '@livestore/common'
+ *
+ * const globalSeq = EventSequenceNumber.Global.make(5)
+ * ```
+ */
+export * as Global from './global.ts'

package/src/schema/EventSequenceNumber.test.ts

@@ -5,13 +5,13 @@ import { EventSequenceNumber } from './mod.ts'
 
 Vitest.describe('EventSequenceNumber', () => {
   Vitest.test('nextPair (no rebase)', () => {
-    const e_0_0 = EventSequenceNumber.make({ global: 0, client: 0 })
-    expect(EventSequenceNumber.nextPair({ seqNum: e_0_0, isClient: false }).seqNum).toStrictEqual({
+    const e_0_0 = EventSequenceNumber.Client.Composite.make({ global: 0, client: 0 })
+    expect(EventSequenceNumber.Client.nextPair({ seqNum: e_0_0, isClient: false }).seqNum).toStrictEqual({
       global: 1,
       client: 0,
       rebaseGeneration: 0,
     })
-    expect(EventSequenceNumber.nextPair({ seqNum: e_0_0, isClient: true }).seqNum).toStrictEqual({
+    expect(EventSequenceNumber.Client.nextPair({ seqNum: e_0_0, isClient: true }).seqNum).toStrictEqual({
       global: 0,
       client: 1,
       rebaseGeneration: 0,
@@ -19,65 +19,83 @@ Vitest.describe('EventSequenceNumber', () => {
   })
 
   Vitest.test('nextPair (rebase)', () => {
-    const e_0_0 = EventSequenceNumber.make({ global: 0, client: 0 })
-    expect(EventSequenceNumber.nextPair({ seqNum: e_0_0, isClient: false, rebaseGeneration: 1 }).seqNum).toStrictEqual({
+    const e_0_0 = EventSequenceNumber.Client.Composite.make({ global: 0, client: 0 })
+    expect(
+      EventSequenceNumber.Client.nextPair({ seqNum: e_0_0, isClient: false, rebaseGeneration: 1 }).seqNum,
+    ).toStrictEqual({
       global: 1,
       client: 0,
-      rebaseGeneration: 0,
+      rebaseGeneration: 1,
     })
-    expect(EventSequenceNumber.nextPair({ seqNum: e_0_0, isClient: true, rebaseGeneration: 1 }).seqNum).toStrictEqual({
+    expect(
+      EventSequenceNumber.Client.nextPair({ seqNum: e_0_0, isClient: true, rebaseGeneration: 1 }).seqNum,
+    ).toStrictEqual({
       global: 0,
       client: 1,
       rebaseGeneration: 1,
     })
 
-    const e_0_0_g1 = EventSequenceNumber.make({ global: 0, client: 0, rebaseGeneration: 2 })
-    expect(EventSequenceNumber.nextPair({ seqNum: e_0_0_g1, isClient: false }).seqNum).toStrictEqual({
+    const e_0_0_g1 = EventSequenceNumber.Client.Composite.make({ global: 0, client: 0, rebaseGeneration: 2 })
+    expect(EventSequenceNumber.Client.nextPair({ seqNum: e_0_0_g1, isClient: false }).seqNum).toStrictEqual({
       global: 1,
       client: 0,
-      rebaseGeneration: 0,
+      rebaseGeneration: 2,
     })
   })
 
   Vitest.test('toString', () => {
-    expect(EventSequenceNumber.toString(EventSequenceNumber.make({ global: 0, client: 0 }))).toBe('e0')
-    expect(EventSequenceNumber.toString(EventSequenceNumber.make({ global: 0, client: 0, rebaseGeneration: 1 }))).toBe(
-      'e0r1',
-    )
-    expect(EventSequenceNumber.toString(EventSequenceNumber.make({ global: 0, client: 1 }))).toBe('e0+1')
-    expect(EventSequenceNumber.toString(EventSequenceNumber.make({ global: 0, client: 1, rebaseGeneration: 1 }))).toBe(
-      'e0+1r1',
-    )
-    expect(EventSequenceNumber.toString(EventSequenceNumber.make({ global: 5, client: 3, rebaseGeneration: 2 }))).toBe(
-      'e5+3r2',
-    )
+    expect(
+      EventSequenceNumber.Client.toString(EventSequenceNumber.Client.Composite.make({ global: 0, client: 0 })),
+    ).toBe('e0')
+    expect(
+      EventSequenceNumber.Client.toString(
+        EventSequenceNumber.Client.Composite.make({ global: 0, client: 0, rebaseGeneration: 1 }),
+      ),
+    ).toBe('e0r1')
+    expect(
+      EventSequenceNumber.Client.toString(EventSequenceNumber.Client.Composite.make({ global: 0, client: 1 })),
+    ).toBe('e0.1')
+    expect(
+      EventSequenceNumber.Client.toString(
+        EventSequenceNumber.Client.Composite.make({ global: 0, client: 1, rebaseGeneration: 1 }),
+      ),
+    ).toBe('e0.1r1')
+    expect(
+      EventSequenceNumber.Client.toString(
+        EventSequenceNumber.Client.Composite.make({ global: 5, client: 3, rebaseGeneration: 2 }),
+      ),
+    ).toBe('e5.3r2')
   })
 
   Vitest.test('fromString', () => {
     // Basic cases
-    expect(EventSequenceNumber.fromString('e0')).toStrictEqual(EventSequenceNumber.make({ global: 0, client: 0 }))
-    expect(EventSequenceNumber.fromString('e0r1')).toStrictEqual(
-      EventSequenceNumber.make({ global: 0, client: 0, rebaseGeneration: 1 }),
+    expect(EventSequenceNumber.Client.fromString('e0')).toStrictEqual(
+      EventSequenceNumber.Client.Composite.make({ global: 0, client: 0 }),
+    )
+    expect(EventSequenceNumber.Client.fromString('e0r1')).toStrictEqual(
+      EventSequenceNumber.Client.Composite.make({ global: 0, client: 0, rebaseGeneration: 1 }),
+    )
+    expect(EventSequenceNumber.Client.fromString('e0.1')).toStrictEqual(
+      EventSequenceNumber.Client.Composite.make({ global: 0, client: 1 }),
     )
-    expect(EventSequenceNumber.fromString('e0+1')).toStrictEqual(EventSequenceNumber.make({ global: 0, client: 1 }))
-    expect(EventSequenceNumber.fromString('e0+1r1')).toStrictEqual(
-      EventSequenceNumber.make({ global: 0, client: 1, rebaseGeneration: 1 }),
+    expect(EventSequenceNumber.Client.fromString('e0.1r1')).toStrictEqual(
+      EventSequenceNumber.Client.Composite.make({ global: 0, client: 1, rebaseGeneration: 1 }),
     )
-    expect(EventSequenceNumber.fromString('e5+3r2')).toStrictEqual(
-      EventSequenceNumber.make({ global: 5, client: 3, rebaseGeneration: 2 }),
+    expect(EventSequenceNumber.Client.fromString('e5.3r2')).toStrictEqual(
+      EventSequenceNumber.Client.Composite.make({ global: 5, client: 3, rebaseGeneration: 2 }),
     )
 
     // Error cases
-    expect(() => EventSequenceNumber.fromString('0')).toThrow(
+    expect(() => EventSequenceNumber.Client.fromString('0')).toThrow(
       'Invalid event sequence number string: must start with "e"',
     )
-    expect(() => EventSequenceNumber.fromString('eabc')).toThrow(
+    expect(() => EventSequenceNumber.Client.fromString('eabc')).toThrow(
       'Invalid event sequence number string: invalid number format',
     )
-    expect(() => EventSequenceNumber.fromString('e0+abc')).toThrow(
+    expect(() => EventSequenceNumber.Client.fromString('e0.abc')).toThrow(
       'Invalid event sequence number string: invalid number format',
     )
-    expect(() => EventSequenceNumber.fromString('e0rabc')).toThrow(
+    expect(() => EventSequenceNumber.Client.fromString('e0rabc')).toThrow(
       'Invalid event sequence number string: invalid number format',
     )
   })
@@ -93,37 +111,37 @@ Vitest.describe('EventSequenceNumber', () => {
     ]
 
     for (const testCase of testCases) {
-      const original = EventSequenceNumber.make(testCase)
-      const str = EventSequenceNumber.toString(original)
-      const parsed = EventSequenceNumber.fromString(str)
+      const original = EventSequenceNumber.Client.Composite.make(testCase)
+      const str = EventSequenceNumber.Client.toString(original)
+      const parsed = EventSequenceNumber.Client.fromString(str)
       expect(parsed).toStrictEqual(original)
     }
   })
 
   Vitest.test('compare', () => {
-    const e_0_0_r0 = EventSequenceNumber.make({ global: 0, client: 0, rebaseGeneration: 0 })
-    const e_0_0_r1 = EventSequenceNumber.make({ global: 0, client: 0, rebaseGeneration: 1 })
-    const e_0_1_r0 = EventSequenceNumber.make({ global: 0, client: 1, rebaseGeneration: 0 })
-    const e_0_1_r1 = EventSequenceNumber.make({ global: 0, client: 1, rebaseGeneration: 1 })
-    const e_1_0_r0 = EventSequenceNumber.make({ global: 1, client: 0, rebaseGeneration: 0 })
-    const e_1_1_r0 = EventSequenceNumber.make({ global: 1, client: 1, rebaseGeneration: 0 })
+    const e_0_0_r0 = EventSequenceNumber.Client.Composite.make({ global: 0, client: 0, rebaseGeneration: 0 })
+    const e_0_0_r1 = EventSequenceNumber.Client.Composite.make({ global: 0, client: 0, rebaseGeneration: 1 })
+    const e_0_1_r0 = EventSequenceNumber.Client.Composite.make({ global: 0, client: 1, rebaseGeneration: 0 })
+    const e_0_1_r1 = EventSequenceNumber.Client.Composite.make({ global: 0, client: 1, rebaseGeneration: 1 })
+    const e_1_0_r0 = EventSequenceNumber.Client.Composite.make({ global: 1, client: 0, rebaseGeneration: 0 })
+    const e_1_1_r0 = EventSequenceNumber.Client.Composite.make({ global: 1, client: 1, rebaseGeneration: 0 })
 
     // Global comparison (strongest level)
-    expect(EventSequenceNumber.compare(e_0_0_r0, e_1_0_r0)).toBeLessThan(0)
-    expect(EventSequenceNumber.compare(e_1_0_r0, e_0_0_r0)).toBeGreaterThan(0)
-    expect(EventSequenceNumber.compare(e_0_1_r1, e_1_0_r0)).toBeLessThan(0) // global overrides client and rebase
+    expect(EventSequenceNumber.Client.compare(e_0_0_r0, e_1_0_r0)).toBeLessThan(0)
+    expect(EventSequenceNumber.Client.compare(e_1_0_r0, e_0_0_r0)).toBeGreaterThan(0)
+    expect(EventSequenceNumber.Client.compare(e_0_1_r1, e_1_0_r0)).toBeLessThan(0) // global overrides client and rebase
 
     // Client comparison (second level)
-    expect(EventSequenceNumber.compare(e_0_0_r0, e_0_1_r0)).toBeLessThan(0)
-    expect(EventSequenceNumber.compare(e_0_1_r0, e_0_0_r0)).toBeGreaterThan(0)
-    expect(EventSequenceNumber.compare(e_0_0_r1, e_0_1_r0)).toBeLessThan(0) // client overrides rebase
+    expect(EventSequenceNumber.Client.compare(e_0_0_r0, e_0_1_r0)).toBeLessThan(0)
+    expect(EventSequenceNumber.Client.compare(e_0_1_r0, e_0_0_r0)).toBeGreaterThan(0)
+    expect(EventSequenceNumber.Client.compare(e_0_0_r1, e_0_1_r0)).toBeLessThan(0) // client overrides rebase
 
     // Rebase generation comparison (weakest level)
-    expect(EventSequenceNumber.compare(e_0_0_r0, e_0_0_r1)).toBeLessThan(0)
-    expect(EventSequenceNumber.compare(e_0_0_r1, e_0_0_r0)).toBeGreaterThan(0)
+    expect(EventSequenceNumber.Client.compare(e_0_0_r0, e_0_0_r1)).toBeLessThan(0)
+    expect(EventSequenceNumber.Client.compare(e_0_0_r1, e_0_0_r0)).toBeGreaterThan(0)
 
     // Equal comparison
-    expect(EventSequenceNumber.compare(e_0_0_r0, e_0_0_r0)).toBe(0)
-    expect(EventSequenceNumber.compare(e_1_1_r0, e_1_1_r0)).toBe(0)
+    expect(EventSequenceNumber.Client.compare(e_0_0_r0, e_0_0_r0)).toBe(0)
+    expect(EventSequenceNumber.Client.compare(e_1_1_r0, e_1_1_r0)).toBe(0)
   })
 })