@hanzo/base 0.2.0

package/src/core/realtime.ts

@@ -0,0 +1,303 @@
+/**
+ * RealtimeService -- SSE-based subscription manager.
+ *
+ * Features:
+ * - Query deduplication via hash(collection+topic) with reference counting
+ * - Auto-reconnect with exponential backoff
+ * - Max observed timestamp tracking
+ * - Connection state notifications
+ */
+
+import type { BaseRecord } from './state.js'
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type ConnectionState = 'disconnected' | 'connecting' | 'connected'
+
+export interface RealtimeEvent {
+  action: 'create' | 'update' | 'delete'
+  record: BaseRecord
+}
+
+export type RealtimeCallback = (event: RealtimeEvent) => void
+export type ConnectionCallback = (state: ConnectionState) => void
+
+interface Subscription {
+  collection: string
+  topic: string
+  callbacks: Set<RealtimeCallback>
+}
+
+// ---------------------------------------------------------------------------
+// RealtimeService
+// ---------------------------------------------------------------------------
+
+export class RealtimeService {
+  private readonly _baseUrl: string
+  private readonly _getToken: () => string
+
+  private _eventSource: EventSource | null = null
+  private _state: ConnectionState = 'disconnected'
+  private _connectionListeners = new Set<ConnectionCallback>()
+
+  /** Dedup map: hash -> Subscription. */
+  private _subscriptions = new Map<string, Subscription>()
+
+  /** SSE client id assigned by the server on connect. */
+  private _clientId: string | null = null
+
+  /** Reconnect state. */
+  private _reconnectAttempts = 0
+  private _reconnectTimer: ReturnType<typeof setTimeout> | null = null
+  private _maxReconnectDelay = 30_000
+  private _baseReconnectDelay = 500
+
+  /** High-water mark of observed server timestamps. */
+  private _maxTimestamp = 0n
+
+  /** Set to true when disconnect() is called explicitly. */
+  private _intentionalDisconnect = false
+
+  constructor(baseUrl: string, getToken: () => string) {
+    this._baseUrl = baseUrl.replace(/\/$/, '')
+    this._getToken = getToken
+  }
+
+  // ---- Public API ---------------------------------------------------------
+
+  get state(): ConnectionState {
+    return this._state
+  }
+
+  get maxTimestamp(): bigint {
+    return this._maxTimestamp
+  }
+
+  /**
+   * Subscribe to realtime events for a collection topic.
+   *
+   * Topic is usually "*" (all changes) or a record id.
+   * Returns an unsubscribe function.
+   */
+  subscribe(
+    collection: string,
+    topic: string,
+    callback: RealtimeCallback,
+  ): () => void {
+    const hash = this._hash(collection, topic)
+    let sub = this._subscriptions.get(hash)
+
+    if (!sub) {
+      sub = { collection, topic, callbacks: new Set() }
+      this._subscriptions.set(hash, sub)
+    }
+    sub.callbacks.add(callback)
+
+    // If this is the first subscription, connect.
+    if (this._subscriptions.size === 1 && !this._eventSource) {
+      this._connect()
+    } else if (this._clientId) {
+      // Already connected -- submit this subscription to the server.
+      this._submitSubscriptions()
+    }
+
+    return () => {
+      sub!.callbacks.delete(callback)
+      if (sub!.callbacks.size === 0) {
+        this._subscriptions.delete(hash)
+        if (this._clientId) {
+          this._submitSubscriptions()
+        }
+      }
+      // If no subscriptions remain, disconnect.
+      if (this._subscriptions.size === 0) {
+        this.disconnect()
+      }
+    }
+  }
+
+  /** Remove all subscribers for a topic, or all topics if none specified. */
+  unsubscribe(topic?: string): void {
+    if (topic) {
+      this._subscriptions.delete(topic)
+    } else {
+      this._subscriptions.clear()
+    }
+    if (this._subscriptions.size === 0) {
+      this.disconnect()
+    }
+  }
+
+  /** Register a connection-state listener. Returns unsubscribe. */
+  onConnectionChange(callback: ConnectionCallback): () => void {
+    this._connectionListeners.add(callback)
+    return () => {
+      this._connectionListeners.delete(callback)
+    }
+  }
+
+  /** Explicitly disconnect. */
+  disconnect(): void {
+    this._intentionalDisconnect = true
+    this._clearReconnect()
+    if (this._eventSource) {
+      this._eventSource.close()
+      this._eventSource = null
+    }
+    this._clientId = null
+    this._setState('disconnected')
+  }
+
+  // ---- Connection ---------------------------------------------------------
+
+  private _connect(): void {
+    if (this._eventSource) return
+    this._intentionalDisconnect = false
+    this._setState('connecting')
+
+    const url = `${this._baseUrl}/api/realtime`
+    this._eventSource = new EventSource(url)
+
+    this._eventSource.addEventListener('PB_CONNECT', (e: MessageEvent) => {
+      try {
+        const data = JSON.parse(e.data) as { clientId: string }
+        this._clientId = data.clientId
+        this._reconnectAttempts = 0
+        this._setState('connected')
+        this._submitSubscriptions()
+      } catch {
+        // malformed connect event
+      }
+    })
+
+    // Listen for all SSE events. The server sends events named after
+    // the collection, e.g. event: "posts".
+    this._eventSource.onmessage = (e: MessageEvent) => {
+      this._handleMessage(e)
+    }
+
+    // The server sends named events for each collection.
+    // We use the generic handler plus specific ones registered dynamically.
+    this._eventSource.onerror = () => {
+      this._eventSource?.close()
+      this._eventSource = null
+      this._clientId = null
+      this._setState('disconnected')
+
+      if (!this._intentionalDisconnect) {
+        this._scheduleReconnect()
+      }
+    }
+  }
+
+  private _handleMessage(e: MessageEvent): void {
+    let payload: { action: string; record: BaseRecord }
+    try {
+      payload = JSON.parse(e.data)
+    } catch {
+      return
+    }
+
+    const action = payload.action as RealtimeEvent['action']
+    const record = payload.record
+    if (!record?.id) return
+
+    // Track timestamp high-water mark.
+    const ts = record.updated ?? record.created
+    if (ts) {
+      const n = BigInt(new Date(ts).getTime()) * 1000n
+      if (n > this._maxTimestamp) {
+        this._maxTimestamp = n
+      }
+    }
+
+    // Fan out to matching subscriptions.
+    const collectionName = record.collectionName ?? ''
+    for (const sub of this._subscriptions.values()) {
+      if (sub.collection !== collectionName) continue
+      if (sub.topic !== '*' && sub.topic !== record.id) continue
+      const event: RealtimeEvent = { action, record }
+      for (const cb of sub.callbacks) {
+        try {
+          cb(event)
+        } catch {
+          // subscriber errors must not break fanout
+        }
+      }
+    }
+  }
+
+  /** Submit current subscription set to the server via POST. */
+  private async _submitSubscriptions(): Promise<void> {
+    if (!this._clientId) return
+
+    const topics: string[] = []
+    for (const sub of this._subscriptions.values()) {
+      topics.push(`${sub.collection}/${sub.topic}`)
+    }
+
+    const token = this._getToken()
+    try {
+      await fetch(`${this._baseUrl}/api/realtime`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          ...(token ? { Authorization: token } : {}),
+        },
+        body: JSON.stringify({
+          clientId: this._clientId,
+          subscriptions: topics,
+        }),
+      })
+    } catch {
+      // will retry on next reconnect
+    }
+  }
+
+  // ---- Reconnect ----------------------------------------------------------
+
+  private _scheduleReconnect(): void {
+    this._clearReconnect()
+    const delay = Math.min(
+      this._baseReconnectDelay * Math.pow(2, this._reconnectAttempts),
+      this._maxReconnectDelay,
+    )
+    // Add jitter: +/- 25%
+    const jitter = delay * (0.75 + Math.random() * 0.5)
+    this._reconnectAttempts++
+
+    this._reconnectTimer = setTimeout(() => {
+      this._reconnectTimer = null
+      this._connect()
+    }, jitter)
+  }
+
+  private _clearReconnect(): void {
+    if (this._reconnectTimer !== null) {
+      clearTimeout(this._reconnectTimer)
+      this._reconnectTimer = null
+    }
+  }
+
+  // ---- State --------------------------------------------------------------
+
+  private _setState(state: ConnectionState): void {
+    if (this._state === state) return
+    this._state = state
+    for (const cb of this._connectionListeners) {
+      try {
+        cb(state)
+      } catch {
+        // listener errors must not break notification
+      }
+    }
+  }
+
+  // ---- Helpers ------------------------------------------------------------
+
+  private _hash(collection: string, topic: string): string {
+    return `${collection}::${topic}`
+  }
+}

package/src/core/state.ts

@@ -0,0 +1,112 @@
+/**
+ * State version tracking (Convex-inspired).
+ *
+ * Each query result is tagged with a StateVersion so the client can
+ * detect ordering, replay transitions, and drive optimistic rollbacks.
+ */
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface StateVersion {
+  /** Monotonically increasing counter bumped on every query-set change. */
+  querySet: number
+  /** Server timestamp (microseconds since epoch) of the latest known event. */
+  ts: bigint
+  /** Identity hash -- changes when the authenticated user changes. */
+  identity: number
+}
+
+export type Modification =
+  | { type: 'QueryUpdated'; collection: string; record: BaseRecord }
+  | { type: 'QueryRemoved'; collection: string; id: string }
+  | { type: 'QueryFailed'; collection: string; error: string }
+
+export interface Transition {
+  startVersion: StateVersion
+  endVersion: StateVersion
+  modifications: Modification[]
+}
+
+/** Minimal record shape that every Base record satisfies. */
+export interface BaseRecord {
+  id: string
+  collectionId?: string
+  collectionName?: string
+  created?: string
+  updated?: string
+  [key: string]: unknown
+}
+
+// ---------------------------------------------------------------------------
+// VersionTracker
+// ---------------------------------------------------------------------------
+
+export class VersionTracker {
+  private _version: StateVersion
+  private _history: Transition[] = []
+  private readonly _maxHistory: number
+
+  constructor(maxHistory = 128) {
+    this._version = { querySet: 0, ts: 0n, identity: 0 }
+    this._maxHistory = maxHistory
+  }
+
+  get current(): Readonly<StateVersion> {
+    return { ...this._version }
+  }
+
+  get history(): readonly Transition[] {
+    return this._history
+  }
+
+  /**
+   * Advance the version and record a transition.
+   * Returns the new version.
+   */
+  advance(modifications: Modification[], serverTs?: bigint): StateVersion {
+    const start = { ...this._version }
+
+    this._version = {
+      querySet: this._version.querySet + 1,
+      ts: serverTs ?? this._version.ts,
+      identity: this._version.identity,
+    }
+
+    const transition: Transition = {
+      startVersion: start,
+      endVersion: { ...this._version },
+      modifications,
+    }
+
+    this._history.push(transition)
+    if (this._history.length > this._maxHistory) {
+      this._history.shift()
+    }
+
+    return { ...this._version }
+  }
+
+  /** Update identity hash (e.g. on auth change). */
+  setIdentity(identity: number): void {
+    this._version = { ...this._version, identity }
+  }
+
+  /** Update the high-water timestamp without bumping querySet. */
+  updateTimestamp(ts: bigint): void {
+    if (ts > this._version.ts) {
+      this._version = { ...this._version, ts }
+    }
+  }
+
+  /** Simple FNV-1a-like hash for identity derivation. */
+  static hashIdentity(token: string): number {
+    let h = 0x811c9dc5
+    for (let i = 0; i < token.length; i++) {
+      h ^= token.charCodeAt(i)
+      h = Math.imul(h, 0x01000193)
+    }
+    return h >>> 0
+  }
+}

package/src/core/store.ts

@@ -0,0 +1,241 @@
+/**
+ * QueryStore -- manages server state + optimistic overlay.
+ *
+ * Subscribers are notified whenever the effective (server + optimistic)
+ * state for their query changes.  Optimistic mutations are tracked by
+ * mutationId so they can be rolled back individually.
+ */
+
+import type { BaseRecord, Modification } from './state.js'
+import { VersionTracker } from './state.js'
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface QueryKey {
+  collection: string
+  filter: string
+}
+
+export type StoreCallback = (records: BaseRecord[]) => void
+
+interface OptimisticEntry {
+  mutationId: string
+  collection: string
+  /** null means "delete this id" */
+  record: BaseRecord | null
+  deletedId?: string
+  createdAt: number
+}
+
+interface QuerySlot {
+  key: QueryKey
+  serverRecords: BaseRecord[]
+  listeners: Set<StoreCallback>
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function queryHash(collection: string, filter: string): string {
+  return `${collection}::${filter}`
+}
+
+function mergeOptimistic(
+  server: BaseRecord[],
+  optimistic: OptimisticEntry[],
+  collection: string,
+): BaseRecord[] {
+  // Start with a mutable copy keyed by id.
+  const map = new Map<string, BaseRecord>()
+  for (const r of server) {
+    map.set(r.id, r)
+  }
+
+  for (const entry of optimistic) {
+    if (entry.collection !== collection) continue
+    if (entry.record === null && entry.deletedId) {
+      map.delete(entry.deletedId)
+    } else if (entry.record) {
+      map.set(entry.record.id, entry.record)
+    }
+  }
+
+  return Array.from(map.values())
+}
+
+// ---------------------------------------------------------------------------
+// QueryStore
+// ---------------------------------------------------------------------------
+
+export class QueryStore {
+  private readonly _slots = new Map<string, QuerySlot>()
+  private readonly _optimistic: OptimisticEntry[] = []
+  private readonly _version = new VersionTracker()
+
+  get version() {
+    return this._version.current
+  }
+
+  // ---- Query cache --------------------------------------------------------
+
+  /** Return cached effective (server+optimistic) result or undefined. */
+  getQuery(collection: string, filter = ''): BaseRecord[] | undefined {
+    const slot = this._slots.get(queryHash(collection, filter))
+    if (!slot) return undefined
+    return mergeOptimistic(slot.serverRecords, this._optimistic, collection)
+  }
+
+  /** Overwrite the server-truth cache for a query and notify. */
+  setQuery(collection: string, filter: string, data: BaseRecord[]): void {
+    const hash = queryHash(collection, filter)
+    let slot = this._slots.get(hash)
+    if (!slot) {
+      slot = { key: { collection, filter }, serverRecords: [], listeners: new Set() }
+      this._slots.set(hash, slot)
+    }
+    slot.serverRecords = data
+
+    this._version.advance(
+      data.map((r) => ({ type: 'QueryUpdated' as const, collection, record: r })),
+    )
+
+    this._notify(slot)
+  }
+
+  // ---- Optimistic mutations -----------------------------------------------
+
+  /** Apply an optimistic create/update. Returns a mutationId for rollback. */
+  optimisticSet(collection: string, record: BaseRecord): string {
+    const mutationId = `opt_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`
+    this._optimistic.push({
+      mutationId,
+      collection,
+      record,
+      createdAt: Date.now(),
+    })
+    this._notifyCollection(collection)
+    return mutationId
+  }
+
+  /** Apply an optimistic delete. */
+  optimisticDelete(collection: string, id: string): string {
+    const mutationId = `opt_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`
+    this._optimistic.push({
+      mutationId,
+      collection,
+      record: null,
+      deletedId: id,
+      createdAt: Date.now(),
+    })
+    this._notifyCollection(collection)
+    return mutationId
+  }
+
+  /** Remove a single optimistic mutation and re-derive. */
+  rollbackOptimistic(mutationId: string): void {
+    const idx = this._optimistic.findIndex((e) => e.mutationId === mutationId)
+    if (idx === -1) return
+    const entry = this._optimistic[idx]
+    this._optimistic.splice(idx, 1)
+    this._notifyCollection(entry.collection)
+  }
+
+  /** Drop all optimistic entries for a collection. */
+  clearOptimistic(collection: string): void {
+    for (let i = this._optimistic.length - 1; i >= 0; i--) {
+      if (this._optimistic[i].collection === collection) {
+        this._optimistic.splice(i, 1)
+      }
+    }
+    this._notifyCollection(collection)
+  }
+
+  // ---- Server event ingestion ---------------------------------------------
+
+  /**
+   * Apply a realtime SSE event from the server.
+   * `action` is one of "create", "update", "delete".
+   */
+  applyServerUpdate(
+    collection: string,
+    action: 'create' | 'update' | 'delete',
+    record: BaseRecord,
+  ): void {
+    const mods: Modification[] = []
+
+    for (const slot of this._slots.values()) {
+      if (slot.key.collection !== collection) continue
+
+      if (action === 'delete') {
+        const before = slot.serverRecords.length
+        slot.serverRecords = slot.serverRecords.filter((r) => r.id !== record.id)
+        if (slot.serverRecords.length !== before) {
+          mods.push({ type: 'QueryRemoved', collection, id: record.id })
+        }
+      } else {
+        // create or update -- upsert
+        const idx = slot.serverRecords.findIndex((r) => r.id === record.id)
+        if (idx >= 0) {
+          slot.serverRecords[idx] = record
+        } else {
+          slot.serverRecords.push(record)
+        }
+        mods.push({ type: 'QueryUpdated', collection, record })
+      }
+    }
+
+    if (mods.length > 0) {
+      const ts = record.updated
+        ? BigInt(new Date(record.updated).getTime()) * 1000n
+        : undefined
+      this._version.advance(mods, ts)
+    }
+
+    this._notifyCollection(collection)
+  }
+
+  // ---- Subscriptions ------------------------------------------------------
+
+  /** Subscribe to effective-state changes for a query. Returns unsubscribe. */
+  subscribe(collection: string, filter: string, callback: StoreCallback): () => void {
+    const hash = queryHash(collection, filter)
+    let slot = this._slots.get(hash)
+    if (!slot) {
+      slot = { key: { collection, filter }, serverRecords: [], listeners: new Set() }
+      this._slots.set(hash, slot)
+    }
+    slot.listeners.add(callback)
+    return () => {
+      slot!.listeners.delete(callback)
+      // GC empty slots
+      if (slot!.listeners.size === 0 && slot!.serverRecords.length === 0) {
+        this._slots.delete(hash)
+      }
+    }
+  }
+
+  // ---- Internal -----------------------------------------------------------
+
+  private _notify(slot: QuerySlot): void {
+    if (slot.listeners.size === 0) return
+    const effective = mergeOptimistic(slot.serverRecords, this._optimistic, slot.key.collection)
+    for (const cb of slot.listeners) {
+      try {
+        cb(effective)
+      } catch {
+        // listener errors must not break the store
+      }
+    }
+  }
+
+  private _notifyCollection(collection: string): void {
+    for (const slot of this._slots.values()) {
+      if (slot.key.collection === collection) {
+        this._notify(slot)
+      }
+    }
+  }
+}