Add KVStorageComposite, IndexedDB storage and SSE change streams

- Every KV storage emits change events (base class owns writeMany/removeMany/
  writeIfAbsent; implementations provide protected apply* methods)
- KVStorageHttpServer streams changes over SSE (GET /events) with a resumable
  history; KVStorageHttp.watch() subscribes and resumes via Last-Event-ID
- KVStorageIndexedDB for local persistence
- KVStorageComposite keeps replicas of a source in sync: local reads, resume
  instead of full sync, offline outbox replayed in order, echo tracking
- Values may contain bigint/Uint8Array (Extended JSON over the network)
- Vendor sse-session, event-emitter and extended-json (no runtime deps)
- Freeze child nodes so shadowed state on children fails loudly
- CI on Node 22, 24 and 26

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017Qxbkp4tA7G5SCWjzWuxmE

src/kv-storage/kv-storage-indexeddb.ts

@@ -0,0 +1,129 @@
+import type { AnySpec, Spec } from '../utils/schema.js'
+import { BaseKVStorage, type ScanOptions } from './base-kv-storage.js'
+
+export interface KVStorageIndexedDBOptions {
+  /** Database name. */
+  name: string
+  /** Object store name. Default `kv`. */
+  storeName?: string
+  /** IndexedDB factory. Default `globalThis.indexedDB`. */
+  indexedDB?: IDBFactory
+  /** Entries read per transaction while scanning. Default 256. */
+  scanBatchSize?: number
+}
+
+/**
+ * KV storage in the browser's IndexedDB (one object store, string keys). Values are stored with the
+ * structured clone algorithm, so `bigint` and `Uint8Array` survive. IndexedDB orders string keys by
+ * UTF-16 code unit, like JavaScript string comparison.
+ */
+export class KVStorageIndexedDB<S extends Spec = AnySpec> extends BaseKVStorage<S> {
+  private readonly storeName: string
+  private readonly scanBatchSize: number
+  private readonly db: Promise<IDBDatabase>
+
+  constructor(options: KVStorageIndexedDBOptions) {
+    super()
+    this.storeName = options.storeName ?? 'kv'
+    this.scanBatchSize = options.scanBatchSize ?? 256
+    const factory = options.indexedDB ?? globalThis.indexedDB
+    const open = factory.open(options.name, 1)
+    open.onupgradeneeded = () => open.result.createObjectStore(this.storeName)
+    this.db = KVStorageIndexedDB.done(open)
+  }
+
+  async readMany(keys: string[]): Promise<unknown[]> {
+    const store = await this.store('readonly')
+    return Promise.all(keys.map((key) => KVStorageIndexedDB.done(store.get(key))))
+  }
+
+  async *scan(options: ScanOptions = {}): AsyncGenerator<[string, unknown]> {
+    let remaining = options.limit ?? Infinity
+    let last: string | undefined
+    while (remaining > 0) {
+      const batch = await this.readBatch(options, last, Math.min(remaining, this.scanBatchSize))
+      for (const entry of batch) {
+        yield entry
+        remaining--
+      }
+      if (batch.length < this.scanBatchSize) return
+      last = batch.at(-1)![0]
+    }
+  }
+
+  /** Closes the database connection. */
+  async close(): Promise<void> {
+    ;(await this.db).close()
+  }
+
+  protected async applyWrite(entries: [string, unknown][]): Promise<void> {
+    const store = await this.store('readwrite')
+    for (const [key, value] of entries) store.put(value, key)
+    await KVStorageIndexedDB.committed(store.transaction)
+  }
+
+  protected async applyRemove(keys: string[]): Promise<void> {
+    const store = await this.store('readwrite')
+    for (const key of keys) store.delete(key)
+    await KVStorageIndexedDB.committed(store.transaction)
+  }
+
+  protected async applyWriteIfAbsent(entries: [string, unknown][]): Promise<boolean[]> {
+    // One readwrite transaction: checks and writes can't interleave with other writers.
+    const store = await this.store('readwrite')
+    const written = await Promise.all(
+      entries.map(async ([key, value]) => {
+        if ((await KVStorageIndexedDB.done(store.getKey(key))) !== undefined) return false
+        store.add(value, key)
+        return true
+      }),
+    )
+    await KVStorageIndexedDB.committed(store.transaction)
+    return written
+  }
+
+  /** Up to `count` entries after `last` (exclusive), in scan order, within one transaction. */
+  private async readBatch(options: ScanOptions, last: string | undefined, count: number): Promise<[string, unknown][]> {
+    const reverse = options.reverse ?? false
+    // The upper bound is always exclusive (`lt`, or the last key seen in reverse); the lower bound
+    // is exclusive only when resuming forwards after `last`.
+    const lower = reverse ? options.gte : (last ?? options.gte)
+    const upper = reverse ? (last ?? options.lt) : options.lt
+    const lowerOpen = !reverse && last !== undefined
+    if (lower !== undefined && upper !== undefined && lower >= upper) return []
+    let range: IDBKeyRange | undefined
+    if (lower !== undefined && upper !== undefined) range = IDBKeyRange.bound(lower, upper, lowerOpen, true)
+    else if (lower !== undefined) range = IDBKeyRange.lowerBound(lower, lowerOpen)
+    else if (upper !== undefined) range = IDBKeyRange.upperBound(upper, true)
+    const store = await this.store('readonly')
+    const out: [string, unknown][] = []
+    const request = options.values ? store.openCursor(range, reverse ? 'prev' : 'next') : store.openKeyCursor(range, reverse ? 'prev' : 'next')
+    return new Promise((resolve, reject) => {
+      request.onerror = () => reject(request.error)
+      request.onsuccess = () => {
+        const cursor = request.result
+        if (!cursor || out.length >= count) return resolve(out)
+        out.push([cursor.key as string, options.values ? (cursor as IDBCursorWithValue).value : undefined])
+        cursor.continue()
+      }
+    })
+  }
+
+  private async store(mode: IDBTransactionMode): Promise<IDBObjectStore> {
+    return (await this.db).transaction(this.storeName, mode).objectStore(this.storeName)
+  }
+
+  private static done<T>(request: IDBRequest<T>): Promise<T> {
+    return new Promise((resolve, reject) => {
+      request.onsuccess = () => resolve(request.result)
+      request.onerror = () => reject(request.error)
+    })
+  }
+
+  private static committed(transaction: IDBTransaction): Promise<void> {
+    return new Promise((resolve, reject) => {
+      transaction.oncomplete = () => resolve()
+      transaction.onerror = transaction.onabort = () => reject(transaction.error)
+    })
+  }
+}