@hanzo/base 0.2.0

package/src/crdt/clock.ts

@@ -0,0 +1,78 @@
+/**
+ * Hybrid logical clock for CRDT operation ordering.
+ *
+ * Each operation is tagged with (timestamp, counter, siteId) to provide
+ * a total order across all sites. Compatible with the Go HLC implementation.
+ */
+
+export interface HLCTimestamp {
+  /** Wall-clock milliseconds since epoch. */
+  ts: number
+  /** Monotonic counter to break ties within the same ms. */
+  counter: number
+  /** Unique site identifier (usually client session id). */
+  siteId: string
+}
+
+export class HybridLogicalClock {
+  private _ts: number
+  private _counter: number
+  readonly siteId: string
+
+  constructor(siteId?: string) {
+    this.siteId = siteId ?? randomSiteId()
+    this._ts = Date.now()
+    this._counter = 0
+  }
+
+  /** Generate a new timestamp, guaranteed > any previous. */
+  now(): HLCTimestamp {
+    const wall = Date.now()
+    if (wall > this._ts) {
+      this._ts = wall
+      this._counter = 0
+    } else {
+      this._counter++
+    }
+    return { ts: this._ts, counter: this._counter, siteId: this.siteId }
+  }
+
+  /** Receive a remote timestamp and merge with local clock. */
+  receive(remote: HLCTimestamp): HLCTimestamp {
+    const wall = Date.now()
+    if (wall > this._ts && wall > remote.ts) {
+      this._ts = wall
+      this._counter = 0
+    } else if (remote.ts > this._ts) {
+      this._ts = remote.ts
+      this._counter = remote.counter + 1
+    } else if (this._ts > remote.ts) {
+      this._counter++
+    } else {
+      // Same ts -- take max counter + 1
+      this._counter = Math.max(this._counter, remote.counter) + 1
+    }
+    return { ts: this._ts, counter: this._counter, siteId: this.siteId }
+  }
+}
+
+/** Compare two HLC timestamps. Returns <0, 0, or >0. */
+export function compareHLC(a: HLCTimestamp, b: HLCTimestamp): number {
+  if (a.ts !== b.ts) return a.ts - b.ts
+  if (a.counter !== b.counter) return a.counter - b.counter
+  if (a.siteId < b.siteId) return -1
+  if (a.siteId > b.siteId) return 1
+  return 0
+}
+
+function randomSiteId(): string {
+  const buf = new Uint8Array(8)
+  if (typeof crypto !== 'undefined' && crypto.getRandomValues) {
+    crypto.getRandomValues(buf)
+  } else {
+    for (let i = 0; i < buf.length; i++) {
+      buf[i] = (Math.random() * 256) | 0
+    }
+  }
+  return Array.from(buf, (b) => b.toString(16).padStart(2, '0')).join('')
+}

package/src/crdt/counter.ts

@@ -0,0 +1,130 @@
+/**
+ * CRDTCounter -- PN-Counter (positive-negative counter).
+ *
+ * Each site tracks its own positive and negative totals.
+ * The value is sum(positives) - sum(negatives) across all sites.
+ * Merge is max() per-site per-direction.
+ */
+
+import { HybridLogicalClock } from './clock.js'
+import type { Operation, CounterIncrementPayload } from './operations.js'
+import { makeOpId } from './operations.js'
+
+export type CounterChangeCallback = (value: number) => void
+
+export class CRDTCounter {
+  /** Per-site positive accumulator. */
+  private _positive = new Map<string, number>()
+  /** Per-site negative accumulator. */
+  private _negative = new Map<string, number>()
+
+  private readonly _clock: HybridLogicalClock
+  private readonly _documentId: string
+  private readonly _field: string
+  private readonly _pendingOps: Operation[] = []
+  private _listeners = new Set<CounterChangeCallback>()
+
+  constructor(documentId: string, field: string, clock: HybridLogicalClock) {
+    this._documentId = documentId
+    this._field = field
+    this._clock = clock
+  }
+
+  // ---- Public API ---------------------------------------------------------
+
+  get value(): number {
+    let pos = 0
+    let neg = 0
+    for (const v of this._positive.values()) pos += v
+    for (const v of this._negative.values()) neg += v
+    return pos - neg
+  }
+
+  increment(amount = 1): Operation {
+    if (amount === 0) throw new Error('CRDTCounter: amount must be nonzero')
+
+    const siteId = this._clock.siteId
+    if (amount > 0) {
+      this._positive.set(siteId, (this._positive.get(siteId) ?? 0) + amount)
+    } else {
+      this._negative.set(siteId, (this._negative.get(siteId) ?? 0) + Math.abs(amount))
+    }
+
+    const hlc = this._clock.now()
+    const op: Operation = {
+      id: makeOpId(hlc),
+      documentId: this._documentId,
+      field: this._field,
+      hlc,
+      type: 'counter.increment',
+      payload: { delta: amount } satisfies CounterIncrementPayload,
+    }
+
+    this._pendingOps.push(op)
+    this._notifyChange()
+    return op
+  }
+
+  decrement(amount = 1): Operation {
+    return this.increment(-amount)
+  }
+
+  /** Apply a remote increment operation. */
+  applyRemote(op: Operation): void {
+    if (op.type !== 'counter.increment') return
+    this._clock.receive(op.hlc)
+
+    const payload = op.payload as CounterIncrementPayload
+    const siteId = op.hlc.siteId
+
+    if (payload.delta > 0) {
+      this._positive.set(siteId, (this._positive.get(siteId) ?? 0) + payload.delta)
+    } else {
+      this._negative.set(siteId, (this._negative.get(siteId) ?? 0) + Math.abs(payload.delta))
+    }
+
+    this._notifyChange()
+  }
+
+  /** Merge with a remote counter state (for full-state sync). */
+  mergeState(positives: Record<string, number>, negatives: Record<string, number>): void {
+    for (const [site, val] of Object.entries(positives)) {
+      this._positive.set(site, Math.max(this._positive.get(site) ?? 0, val))
+    }
+    for (const [site, val] of Object.entries(negatives)) {
+      this._negative.set(site, Math.max(this._negative.get(site) ?? 0, val))
+    }
+    this._notifyChange()
+  }
+
+  /** Export state for full-state sync. */
+  exportState(): { positive: Record<string, number>; negative: Record<string, number> } {
+    return {
+      positive: Object.fromEntries(this._positive),
+      negative: Object.fromEntries(this._negative),
+    }
+  }
+
+  drainOps(): Operation[] {
+    return this._pendingOps.splice(0, this._pendingOps.length)
+  }
+
+  onChange(callback: CounterChangeCallback): () => void {
+    this._listeners.add(callback)
+    return () => {
+      this._listeners.delete(callback)
+    }
+  }
+
+  private _notifyChange(): void {
+    if (this._listeners.size === 0) return
+    const val = this.value
+    for (const cb of this._listeners) {
+      try {
+        cb(val)
+      } catch {
+        // listener errors must not break notification
+      }
+    }
+  }
+}

package/src/crdt/document.ts

@@ -0,0 +1,194 @@
+/**
+ * CRDTDocument -- container for collaborative fields.
+ *
+ * A document holds named CRDT fields (text, counter, set, register) that
+ * share a single HLC clock and sync channel. Operations from all fields
+ * are collected and sent to the server together.
+ */
+
+import { HybridLogicalClock } from './clock.js'
+import { CRDTText } from './text.js'
+import { CRDTCounter } from './counter.js'
+import { CRDTSet } from './set.js'
+import { CRDTRegister } from './register.js'
+import type { Operation } from './operations.js'
+
+export type DocumentChangeCallback = (ops: Operation[]) => void
+
+export class CRDTDocument {
+  readonly id: string
+  readonly clock: HybridLogicalClock
+
+  private _texts = new Map<string, CRDTText>()
+  private _counters = new Map<string, CRDTCounter>()
+  private _sets = new Map<string, CRDTSet>()
+  private _registers = new Map<string, CRDTRegister>()
+  private _listeners = new Set<DocumentChangeCallback>()
+
+  /** Buffer for ops not yet synced. */
+  private _unsyncedOps: Operation[] = []
+
+  constructor(id: string, siteId?: string) {
+    this.id = id
+    this.clock = new HybridLogicalClock(siteId)
+  }
+
+  // ---- Field accessors ----------------------------------------------------
+
+  getText(field: string): CRDTText {
+    let t = this._texts.get(field)
+    if (!t) {
+      t = new CRDTText(this.id, field, this.clock)
+      this._texts.set(field, t)
+    }
+    return t
+  }
+
+  getCounter(field: string): CRDTCounter {
+    let c = this._counters.get(field)
+    if (!c) {
+      c = new CRDTCounter(this.id, field, this.clock)
+      this._counters.set(field, c)
+    }
+    return c
+  }
+
+  getSet<T = unknown>(field: string): CRDTSet<T> {
+    let s = this._sets.get(field)
+    if (!s) {
+      s = new CRDTSet(this.id, field, this.clock)
+      this._sets.set(field, s)
+    }
+    return s as CRDTSet<T>
+  }
+
+  getRegister<T = unknown>(field: string): CRDTRegister<T> {
+    let r = this._registers.get(field)
+    if (!r) {
+      r = new CRDTRegister(this.id, field, this.clock)
+      this._registers.set(field, r)
+    }
+    return r as CRDTRegister<T>
+  }
+
+  // ---- Operation collection -----------------------------------------------
+
+  /**
+   * Collect all pending local operations from all fields.
+   * Drains the per-field op buffers and returns them.
+   */
+  collectOps(): Operation[] {
+    const ops: Operation[] = []
+    for (const t of this._texts.values()) ops.push(...t.drainOps())
+    for (const c of this._counters.values()) ops.push(...c.drainOps())
+    for (const s of this._sets.values()) ops.push(...s.drainOps())
+    for (const r of this._registers.values()) ops.push(...r.drainOps())
+    this._unsyncedOps.push(...ops)
+    return ops
+  }
+
+  /**
+   * Acknowledge that operations up to and including `opId` have been
+   * persisted by the server. Removes them from the unsynced buffer.
+   */
+  acknowledge(opId: string): void {
+    const idx = this._unsyncedOps.findIndex((op) => op.id === opId)
+    if (idx >= 0) {
+      this._unsyncedOps.splice(0, idx + 1)
+    }
+  }
+
+  /** Get operations that have not been acknowledged by the server. */
+  getUnsyncedOps(): readonly Operation[] {
+    return this._unsyncedOps
+  }
+
+  // ---- Remote operation application ---------------------------------------
+
+  /**
+   * Apply a batch of remote operations to the appropriate CRDT fields.
+   */
+  applyRemoteOps(ops: Operation[]): void {
+    for (const op of ops) {
+      if (op.documentId !== this.id) continue
+      this._applyRemoteOp(op)
+    }
+  }
+
+  private _applyRemoteOp(op: Operation): void {
+    switch (op.type) {
+      case 'text.insert':
+      case 'text.delete': {
+        const t = this.getText(op.field)
+        t.applyRemote(op)
+        break
+      }
+      case 'counter.increment': {
+        const c = this.getCounter(op.field)
+        c.applyRemote(op)
+        break
+      }
+      case 'set.add':
+      case 'set.remove': {
+        const s = this.getSet(op.field)
+        s.applyRemote(op)
+        break
+      }
+      case 'register.set': {
+        const r = this.getRegister(op.field)
+        r.applyRemote(op)
+        break
+      }
+    }
+  }
+
+  // ---- Serialization ------------------------------------------------------
+
+  /**
+   * Encode all pending operations as a Uint8Array (JSON wire format).
+   * Used for WebSocket transmission.
+   */
+  encode(): Uint8Array {
+    const ops = this.collectOps()
+    const json = JSON.stringify({
+      documentId: this.id,
+      siteId: this.clock.siteId,
+      ops,
+    })
+    return new TextEncoder().encode(json)
+  }
+
+  /**
+   * Decode and apply a remote message (Uint8Array or string).
+   */
+  decode(data: Uint8Array | string): void {
+    const text = typeof data === 'string' ? data : new TextDecoder().decode(data)
+    const msg = JSON.parse(text) as { documentId: string; siteId: string; ops: Operation[] }
+
+    if (msg.documentId !== this.id) return
+    // Do not apply our own operations.
+    if (msg.siteId === this.clock.siteId) return
+
+    this.applyRemoteOps(msg.ops)
+    this._notifyChange(msg.ops)
+  }
+
+  // ---- Change notifications -----------------------------------------------
+
+  onChange(callback: DocumentChangeCallback): () => void {
+    this._listeners.add(callback)
+    return () => {
+      this._listeners.delete(callback)
+    }
+  }
+
+  private _notifyChange(ops: Operation[]): void {
+    for (const cb of this._listeners) {
+      try {
+        cb(ops)
+      } catch {
+        // listener errors must not break notification
+      }
+    }
+  }
+}

package/src/crdt/index.ts

@@ -0,0 +1,56 @@
+/**
+ * @hanzoai/base/crdt -- CRDT primitives for offline-first sync.
+ *
+ * Provides:
+ * - HybridLogicalClock for causal ordering
+ * - Operation types for wire format
+ * - CRDTText (RGA-based collaborative text)
+ * - CRDTCounter (PN-Counter)
+ * - CRDTSet (OR-Set with add-wins semantics)
+ * - CRDTRegister (LWW-Register)
+ * - CRDTDocument (container for collaborative fields)
+ */
+
+// Clock
+export { HybridLogicalClock, compareHLC } from './clock.js'
+export type { HLCTimestamp } from './clock.js'
+
+// Operations
+export { makeOpId, makePositionId } from './operations.js'
+export type {
+  OperationType,
+  Operation,
+  OperationPayload,
+  TextInsertPayload,
+  TextDeletePayload,
+  CounterIncrementPayload,
+  SetAddPayload,
+  SetRemovePayload,
+  RegisterSetPayload,
+} from './operations.js'
+
+// CRDT types
+export { CRDTText } from './text.js'
+export type { TextChangeCallback } from './text.js'
+
+export { CRDTCounter } from './counter.js'
+export type { CounterChangeCallback } from './counter.js'
+
+export { CRDTSet } from './set.js'
+export type { SetChangeCallback } from './set.js'
+
+export { CRDTRegister } from './register.js'
+export type { RegisterChangeCallback } from './register.js'
+
+export { CRDTDocument } from './document.js'
+export type { DocumentChangeCallback } from './document.js'
+
+// Sync
+export { CRDTSync } from './sync.js'
+export type {
+  SyncState,
+  PeerState,
+  SyncStateCallback,
+  PeerCallback,
+  RemoteChangeCallback,
+} from './sync.js'

package/src/crdt/operations.ts

@@ -0,0 +1,101 @@
+/**
+ * CRDT operation types -- wire format for sync between client and server.
+ *
+ * All operations are serializable to JSON and designed for
+ * eventual compatibility with a Go CRDT server.
+ */
+
+import type { HLCTimestamp } from './clock.js'
+
+// ---------------------------------------------------------------------------
+// Operation type tags
+// ---------------------------------------------------------------------------
+
+export type OperationType =
+  | 'text.insert'
+  | 'text.delete'
+  | 'counter.increment'
+  | 'set.add'
+  | 'set.remove'
+  | 'register.set'
+
+// ---------------------------------------------------------------------------
+// Base operation
+// ---------------------------------------------------------------------------
+
+export interface Operation {
+  /** Unique operation id: `{siteId}:{ts}:{counter}` */
+  id: string
+  /** The CRDT document id this operation belongs to. */
+  documentId: string
+  /** Which field within the document. */
+  field: string
+  /** HLC timestamp for causal ordering. */
+  hlc: HLCTimestamp
+  /** Operation type tag. */
+  type: OperationType
+  /** Type-specific payload. */
+  payload: OperationPayload
+}
+
+// ---------------------------------------------------------------------------
+// Payloads
+// ---------------------------------------------------------------------------
+
+export interface TextInsertPayload {
+  /** Position id of the character after which to insert (null = head). */
+  afterId: string | null
+  /** The text content to insert. Each character gets its own positional id. */
+  content: string
+  /** Assigned position ids for each character (same length as content). */
+  positionIds: string[]
+}
+
+export interface TextDeletePayload {
+  /** Position ids of the characters to tombstone. */
+  positionIds: string[]
+}
+
+export interface CounterIncrementPayload {
+  /** Delta (positive for increment, negative for decrement). */
+  delta: number
+}
+
+export interface SetAddPayload {
+  /** The value to add (JSON-serializable). */
+  value: unknown
+  /** Unique tag for this add operation (for OR-Set semantics). */
+  tag: string
+}
+
+export interface SetRemovePayload {
+  /** The value to remove. */
+  value: unknown
+  /** Tags being causally removed (observed tags at removal time). */
+  tags: string[]
+}
+
+export interface RegisterSetPayload {
+  /** The new value. */
+  value: unknown
+}
+
+export type OperationPayload =
+  | TextInsertPayload
+  | TextDeletePayload
+  | CounterIncrementPayload
+  | SetAddPayload
+  | SetRemovePayload
+  | RegisterSetPayload
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+export function makeOpId(hlc: HLCTimestamp): string {
+  return `${hlc.siteId}:${hlc.ts}:${hlc.counter}`
+}
+
+export function makePositionId(hlc: HLCTimestamp, charIndex: number): string {
+  return `${hlc.siteId}:${hlc.ts}:${hlc.counter}:${charIndex}`
+}

package/src/crdt/register.ts

@@ -0,0 +1,106 @@
+/**
+ * CRDTRegister<T> -- Last-Writer-Wins Register (LWW-Register).
+ *
+ * The value with the highest HLC timestamp wins.
+ * Ties are broken by site id comparison.
+ */
+
+import type { HLCTimestamp } from './clock.js'
+import { HybridLogicalClock, compareHLC } from './clock.js'
+import type { Operation, RegisterSetPayload } from './operations.js'
+import { makeOpId } from './operations.js'
+
+export type RegisterChangeCallback<T> = (value: T | undefined) => void
+
+export class CRDTRegister<T = unknown> {
+  private _value: T | undefined = undefined
+  private _hlc: HLCTimestamp | null = null
+
+  private readonly _clock: HybridLogicalClock
+  private readonly _documentId: string
+  private readonly _field: string
+  private readonly _pendingOps: Operation[] = []
+  private _listeners = new Set<RegisterChangeCallback<T>>()
+
+  constructor(documentId: string, field: string, clock: HybridLogicalClock) {
+    this._documentId = documentId
+    this._field = field
+    this._clock = clock
+  }
+
+  // ---- Public API ---------------------------------------------------------
+
+  get value(): T | undefined {
+    return this._value
+  }
+
+  set(value: T): Operation {
+    const hlc = this._clock.now()
+    this._value = value
+    this._hlc = hlc
+
+    const op: Operation = {
+      id: makeOpId(hlc),
+      documentId: this._documentId,
+      field: this._field,
+      hlc,
+      type: 'register.set',
+      payload: { value } satisfies RegisterSetPayload,
+    }
+
+    this._pendingOps.push(op)
+    this._notifyChange()
+    return op
+  }
+
+  /** Apply a remote set operation. LWW: only apply if remote HLC > current. */
+  applyRemote(op: Operation): void {
+    if (op.type !== 'register.set') return
+    this._clock.receive(op.hlc)
+
+    const payload = op.payload as RegisterSetPayload
+
+    if (this._hlc === null || compareHLC(op.hlc, this._hlc) > 0) {
+      this._value = payload.value as T
+      this._hlc = op.hlc
+      this._notifyChange()
+    }
+  }
+
+  /** Export current state for full-state sync. */
+  exportState(): { value: T | undefined; hlc: HLCTimestamp | null } {
+    return { value: this._value, hlc: this._hlc }
+  }
+
+  /** Import state from full-state sync. LWW merge. */
+  importState(value: T, hlc: HLCTimestamp): void {
+    if (this._hlc === null || compareHLC(hlc, this._hlc) > 0) {
+      this._value = value
+      this._hlc = hlc
+      this._notifyChange()
+    }
+  }
+
+  drainOps(): Operation[] {
+    return this._pendingOps.splice(0, this._pendingOps.length)
+  }
+
+  onChange(callback: RegisterChangeCallback<T>): () => void {
+    this._listeners.add(callback)
+    return () => {
+      this._listeners.delete(callback)
+    }
+  }
+
+  private _notifyChange(): void {
+    if (this._listeners.size === 0) return
+    const val = this._value
+    for (const cb of this._listeners) {
+      try {
+        cb(val)
+      } catch {
+        // listener errors must not break notification
+      }
+    }
+  }
+}