@kyneta/changefeed 1.3.0

package/src/__tests__/changefeed.test.ts

@@ -0,0 +1,347 @@
+import { describe, expect, it, vi } from "vitest"
+import { createCallable } from "../callable.js"
+import type { ChangeBase } from "../change.js"
+import {
+  CHANGEFEED,
+  type Changeset,
+  changefeed,
+  createChangefeed,
+  hasChangefeed,
+  staticChangefeed,
+} from "../changefeed.js"
+
+// ---------------------------------------------------------------------------
+// hasChangefeed
+// ---------------------------------------------------------------------------
+
+describe("hasChangefeed", () => {
+  it("returns false for nullish values and primitives", () => {
+    expect(hasChangefeed(null)).toBe(false)
+    expect(hasChangefeed(undefined)).toBe(false)
+    expect(hasChangefeed(42)).toBe(false)
+    expect(hasChangefeed("hello")).toBe(false)
+    expect(hasChangefeed(true)).toBe(false)
+  })
+
+  it("returns false for a plain object", () => {
+    expect(hasChangefeed({ foo: 1 })).toBe(false)
+  })
+
+  it("returns true for an object with [CHANGEFEED]", () => {
+    const obj = {
+      [CHANGEFEED]: {
+        get current() {
+          return 0
+        },
+        subscribe: () => () => {},
+      },
+    }
+    expect(hasChangefeed(obj)).toBe(true)
+  })
+
+  it("returns true for a function with [CHANGEFEED]", () => {
+    const fn: any = () => 0
+    fn[CHANGEFEED] = {
+      get current() {
+        return 0
+      },
+      subscribe: () => () => {},
+    }
+    expect(hasChangefeed(fn)).toBe(true)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Symbol identity
+// ---------------------------------------------------------------------------
+
+describe("CHANGEFEED symbol identity", () => {
+  it("matches Symbol.for('kyneta:changefeed') — cross-package detection works", () => {
+    // This is the critical invariant of the package extraction:
+    // any object created with Symbol.for("kyneta:changefeed") (e.g. by
+    // @kyneta/schema's withChangefeed interpreter) must be detectable
+    // by hasChangefeed from @kyneta/changefeed.
+    const externalSymbol = Symbol.for("kyneta:changefeed")
+    const obj: Record<symbol, unknown> = {}
+    Object.defineProperty(obj, externalSymbol, {
+      value: { current: 0, subscribe: () => () => {} },
+      enumerable: false,
+    })
+    expect(hasChangefeed(obj)).toBe(true)
+    expect((obj as any)[CHANGEFEED]).toBe((obj as any)[externalSymbol])
+  })
+})
+
+// ---------------------------------------------------------------------------
+// createChangefeed
+// ---------------------------------------------------------------------------
+
+describe("createChangefeed", () => {
+  it(".current reads the live value", () => {
+    let value = "hello"
+    const [feed] = createChangefeed(() => value)
+    expect(feed.current).toBe("hello")
+
+    value = "world"
+    expect(feed.current).toBe("world")
+  })
+
+  it(".subscribe() receives emitted changesets with origin", () => {
+    let value = 0
+    const [feed, emit] = createChangefeed<number, ChangeBase>(() => value)
+
+    const received: Changeset<ChangeBase>[] = []
+    feed.subscribe(cs => {
+      received.push(cs)
+    })
+
+    value = 1
+    emit({ changes: [{ type: "replace" }] })
+
+    value = 2
+    emit({ changes: [{ type: "replace" }], origin: "sync" })
+
+    expect(received).toHaveLength(2)
+    expect(received[0]?.changes).toEqual([{ type: "replace" }])
+    expect(received[0]?.origin).toBeUndefined()
+    expect(received[1]?.origin).toBe("sync")
+  })
+
+  it("hasChangefeed() returns true for the feed", () => {
+    const [feed] = createChangefeed(() => 0)
+    expect(hasChangefeed(feed)).toBe(true)
+  })
+
+  it("[CHANGEFEED] protocol object has live .current", () => {
+    let value = 10
+    const [feed] = createChangefeed(() => value)
+    expect(feed[CHANGEFEED].current).toBe(10)
+
+    value = 20
+    expect(feed[CHANGEFEED].current).toBe(20)
+  })
+
+  it("unsubscribe stops delivery", () => {
+    const value = 0
+    const [feed, emit] = createChangefeed<number, ChangeBase>(() => value)
+
+    const received: Changeset<ChangeBase>[] = []
+    const unsub = feed.subscribe(cs => {
+      received.push(cs)
+    })
+
+    emit({ changes: [{ type: "replace" }] })
+    expect(received).toHaveLength(1)
+
+    unsub()
+    emit({ changes: [{ type: "replace" }] })
+    expect(received).toHaveLength(1)
+  })
+
+  it("multiple subscribers all receive changesets", () => {
+    const [feed, emit] = createChangefeed<number, ChangeBase>(() => 0)
+
+    const a: Changeset<ChangeBase>[] = []
+    const b: Changeset<ChangeBase>[] = []
+    feed.subscribe(cs => a.push(cs))
+    feed.subscribe(cs => b.push(cs))
+
+    emit({ changes: [{ type: "replace" }] })
+    expect(a).toHaveLength(1)
+    expect(b).toHaveLength(1)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// changefeed() projector
+// ---------------------------------------------------------------------------
+
+describe("changefeed() projector", () => {
+  it("delegates .current to source protocol", () => {
+    let value = "initial"
+    const source = {
+      [CHANGEFEED]: {
+        get current() {
+          return value
+        },
+        subscribe: () => () => {},
+      },
+    }
+
+    const feed = changefeed(source)
+    expect(feed.current).toBe("initial")
+
+    value = "updated"
+    expect(feed.current).toBe("updated")
+  })
+
+  it("delegates .subscribe() to source protocol", () => {
+    const cb = vi.fn()
+    const box: { cb: ((cs: Changeset) => void) | null } = { cb: null }
+
+    const source = {
+      [CHANGEFEED]: {
+        get current() {
+          return 0
+        },
+        subscribe: (callback: (cs: Changeset) => void) => {
+          box.cb = callback
+          return () => {
+            box.cb = null
+          }
+        },
+      },
+    }
+
+    const feed = changefeed(source)
+    const unsub = feed.subscribe(cb)
+
+    expect(box.cb).not.toBeNull()
+    if (box.cb) box.cb({ changes: [{ type: "replace" }] })
+    expect(cb).toHaveBeenCalledTimes(1)
+
+    unsub()
+    expect(box.cb).toBeNull()
+  })
+
+  it("[CHANGEFEED] on projected feed is the source protocol", () => {
+    const protocol = {
+      get current() {
+        return 42
+      },
+      subscribe: () => () => {},
+    }
+
+    const source = { [CHANGEFEED]: protocol }
+    const feed = changefeed(source)
+    expect(feed[CHANGEFEED]).toBe(protocol)
+  })
+
+  it("hasChangefeed() returns true for projected feed", () => {
+    const source = {
+      [CHANGEFEED]: {
+        get current() {
+          return 0
+        },
+        subscribe: () => () => {},
+      },
+    }
+    expect(hasChangefeed(changefeed(source))).toBe(true)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// staticChangefeed
+// ---------------------------------------------------------------------------
+
+describe("staticChangefeed", () => {
+  it(".current returns the value and subscribe never fires", () => {
+    const cf = staticChangefeed("hello")
+    expect(cf.current).toBe("hello")
+
+    const cb = vi.fn()
+    const unsub = cf.subscribe(cb)
+    expect(cb).not.toHaveBeenCalled()
+    unsub()
+    expect(cb).not.toHaveBeenCalled()
+  })
+})
+
+// ---------------------------------------------------------------------------
+// createCallable
+// ---------------------------------------------------------------------------
+
+describe("createCallable", () => {
+  it("calling the feed returns current value", () => {
+    let value = 5
+    const [source] = createChangefeed(() => value)
+    const feed = createCallable(source)
+
+    expect(feed()).toBe(5)
+
+    value = 10
+    expect(feed()).toBe(10)
+  })
+
+  it(".current returns the current value", () => {
+    let value = "a"
+    const [source] = createChangefeed(() => value)
+    const feed = createCallable(source)
+
+    expect(feed.current).toBe("a")
+
+    value = "b"
+    expect(feed.current).toBe("b")
+  })
+
+  it(".subscribe() delegates to source subscribe", () => {
+    let value = 0
+    const [source, emit] = createChangefeed<number, ChangeBase>(() => value)
+    const feed = createCallable(source)
+
+    const received: Changeset<ChangeBase>[] = []
+    feed.subscribe(cs => {
+      received.push(cs)
+    })
+
+    value = 1
+    emit({ changes: [{ type: "replace" }] })
+    expect(received).toHaveLength(1)
+  })
+
+  it("hasChangefeed() returns true", () => {
+    const [source] = createChangefeed(() => 0)
+    const feed = createCallable(source)
+    expect(hasChangefeed(feed)).toBe(true)
+  })
+
+  it("[CHANGEFEED] protocol delegates to source", () => {
+    let value = 100
+    const [source] = createChangefeed(() => value)
+    const feed = createCallable(source)
+
+    expect(feed[CHANGEFEED].current).toBe(100)
+
+    value = 200
+    expect(feed[CHANGEFEED].current).toBe(200)
+  })
+
+  it("feed() reflects source value changes", () => {
+    let value = 0
+    const [source, _emit] = createChangefeed<number, ChangeBase>(() => value)
+    const feed = createCallable(source)
+
+    expect(feed()).toBe(0)
+
+    // Value changes are reflected through the getter delegation,
+    // independent of emit (which only notifies subscribers).
+    value = 42
+    expect(feed()).toBe(42)
+    expect(feed.current).toBe(42)
+  })
+
+  it("unsubscribe stops delivery", () => {
+    const [source, emit] = createChangefeed<number, ChangeBase>(() => 0)
+    const feed = createCallable(source)
+
+    const received: Changeset<ChangeBase>[] = []
+    const unsub = feed.subscribe(cs => {
+      received.push(cs)
+    })
+
+    emit({ changes: [{ type: "replace" }] })
+    expect(received).toHaveLength(1)
+
+    unsub()
+    emit({ changes: [{ type: "replace" }] })
+    expect(received).toHaveLength(1)
+  })
+
+  it("[CHANGEFEED] is non-enumerable but discoverable via getOwnPropertySymbols", () => {
+    const [source] = createChangefeed(() => 0)
+    const feed = createCallable(source)
+    expect(Object.keys(feed)).not.toContain(CHANGEFEED.toString())
+    const symbols = Object.getOwnPropertySymbols(feed)
+    expect(symbols).toContain(CHANGEFEED)
+  })
+})

package/src/__tests__/reactive-map.test.ts

@@ -0,0 +1,324 @@
+// ReactiveMap — unit tests for the reactive map combinator.
+
+import { describe, expect, it, vi } from "vitest"
+import {
+  type CallableChangefeed,
+  type ChangeBase,
+  type Changeset,
+  createReactiveMap,
+  hasChangefeed,
+} from "../index.js"
+
+// ---------------------------------------------------------------------------
+// Test change type
+// ---------------------------------------------------------------------------
+
+interface TestChange extends ChangeBase {
+  readonly type: "set" | "delete"
+  readonly key: string
+}
+
+// ---------------------------------------------------------------------------
+// Construction
+// ---------------------------------------------------------------------------
+
+describe("createReactiveMap", () => {
+  it("returns a tuple of [ReactiveMap, ReactiveMapHandle]", () => {
+    const [map, handle] = createReactiveMap<string, number, TestChange>()
+    expect(typeof map).toBe("function")
+    expect(handle).toBeDefined()
+    expect(typeof handle.set).toBe("function")
+    expect(typeof handle.delete).toBe("function")
+    expect(typeof handle.clear).toBe("function")
+    expect(typeof handle.emit).toBe("function")
+  })
+
+  it("starts empty", () => {
+    const [map] = createReactiveMap<string, number, TestChange>()
+    expect(map.size).toBe(0)
+    expect([...map]).toEqual([])
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Call signature
+// ---------------------------------------------------------------------------
+
+describe("call signature", () => {
+  it("calling the map returns a ReadonlyMap snapshot", () => {
+    const [map, handle] = createReactiveMap<string, number, TestChange>()
+    handle.set("a", 1)
+    const snapshot = map()
+    expect(snapshot).toBeInstanceOf(Map)
+    expect(snapshot.get("a")).toBe(1)
+  })
+
+  it(".current returns the same map as calling", () => {
+    const [map, handle] = createReactiveMap<string, number, TestChange>()
+    handle.set("x", 42)
+    expect(map.current).toBe(map())
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Lifted collection accessors
+// ---------------------------------------------------------------------------
+
+describe("collection accessors", () => {
+  it(".get() delegates to the internal map", () => {
+    const [map, handle] = createReactiveMap<string, number, TestChange>()
+    expect(map.get("missing")).toBeUndefined()
+    handle.set("a", 1)
+    expect(map.get("a")).toBe(1)
+  })
+
+  it(".has() delegates to the internal map", () => {
+    const [map, handle] = createReactiveMap<string, number, TestChange>()
+    expect(map.has("a")).toBe(false)
+    handle.set("a", 1)
+    expect(map.has("a")).toBe(true)
+  })
+
+  it(".keys() yields all keys", () => {
+    const [map, handle] = createReactiveMap<string, number, TestChange>()
+    handle.set("a", 1)
+    handle.set("b", 2)
+    expect([...map.keys()]).toEqual(["a", "b"])
+  })
+
+  it(".size reflects the number of entries", () => {
+    const [map, handle] = createReactiveMap<string, number, TestChange>()
+    expect(map.size).toBe(0)
+    handle.set("a", 1)
+    expect(map.size).toBe(1)
+    handle.set("b", 2)
+    expect(map.size).toBe(2)
+    handle.delete("a")
+    expect(map.size).toBe(1)
+  })
+
+  it("[Symbol.iterator] yields [key, value] pairs", () => {
+    const [map, handle] = createReactiveMap<string, number, TestChange>()
+    handle.set("x", 10)
+    handle.set("y", 20)
+    const entries = [...map]
+    expect(entries).toEqual([
+      ["x", 10],
+      ["y", 20],
+    ])
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Handle mutations
+// ---------------------------------------------------------------------------
+
+describe("ReactiveMapHandle", () => {
+  it("set() inserts entries visible via the map", () => {
+    const [map, handle] = createReactiveMap<string, number, TestChange>()
+    handle.set("a", 1)
+    handle.set("b", 2)
+    expect(map.get("a")).toBe(1)
+    expect(map.get("b")).toBe(2)
+  })
+
+  it("set() overwrites existing entries", () => {
+    const [map, handle] = createReactiveMap<string, number, TestChange>()
+    handle.set("a", 1)
+    handle.set("a", 99)
+    expect(map.get("a")).toBe(99)
+    expect(map.size).toBe(1)
+  })
+
+  it("delete() removes an entry and returns true", () => {
+    const [map, handle] = createReactiveMap<string, number, TestChange>()
+    handle.set("a", 1)
+    const result = handle.delete("a")
+    expect(result).toBe(true)
+    expect(map.has("a")).toBe(false)
+    expect(map.size).toBe(0)
+  })
+
+  it("delete() returns false for missing key", () => {
+    const [, handle] = createReactiveMap<string, number, TestChange>()
+    expect(handle.delete("nope")).toBe(false)
+  })
+
+  it("clear() removes all entries", () => {
+    const [map, handle] = createReactiveMap<string, number, TestChange>()
+    handle.set("a", 1)
+    handle.set("b", 2)
+    handle.set("c", 3)
+    handle.clear()
+    expect(map.size).toBe(0)
+    expect([...map]).toEqual([])
+  })
+
+  it("mutations do NOT automatically emit", () => {
+    const [map, handle] = createReactiveMap<string, number, TestChange>()
+    const cb = vi.fn()
+    map.subscribe(cb)
+
+    handle.set("a", 1)
+    handle.delete("a")
+    handle.clear()
+
+    expect(cb).not.toHaveBeenCalled()
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Changefeed protocol — subscribe / emit
+// ---------------------------------------------------------------------------
+
+describe("changefeed protocol", () => {
+  it("emit() delivers changeset to subscribers", () => {
+    const [map, handle] = createReactiveMap<string, number, TestChange>()
+    const received: Changeset<TestChange>[] = []
+    map.subscribe(cs => received.push(cs))
+
+    handle.set("a", 1)
+    handle.emit({ changes: [{ type: "set", key: "a" }] })
+
+    expect(received).toHaveLength(1)
+    expect(received[0].changes).toEqual([{ type: "set", key: "a" }])
+  })
+
+  it("multiple subscribers all receive the changeset", () => {
+    const [map, handle] = createReactiveMap<string, number, TestChange>()
+    const cb1 = vi.fn()
+    const cb2 = vi.fn()
+    map.subscribe(cb1)
+    map.subscribe(cb2)
+
+    handle.emit({ changes: [{ type: "set", key: "x" }] })
+
+    expect(cb1).toHaveBeenCalledTimes(1)
+    expect(cb2).toHaveBeenCalledTimes(1)
+  })
+
+  it("unsubscribe stops delivery", () => {
+    const [map, handle] = createReactiveMap<string, number, TestChange>()
+    const cb = vi.fn()
+    const unsub = map.subscribe(cb)
+
+    handle.emit({ changes: [{ type: "set", key: "a" }] })
+    expect(cb).toHaveBeenCalledTimes(1)
+
+    unsub()
+
+    handle.emit({ changes: [{ type: "set", key: "b" }] })
+    expect(cb).toHaveBeenCalledTimes(1)
+  })
+
+  it("changeset preserves origin", () => {
+    const [map, handle] = createReactiveMap<string, number, TestChange>()
+    const received: Changeset<TestChange>[] = []
+    map.subscribe(cs => received.push(cs))
+
+    handle.emit({
+      changes: [{ type: "set", key: "a" }],
+      origin: "sync",
+    })
+
+    expect(received[0].origin).toBe("sync")
+  })
+
+  it("subscriber sees current state at time of emit", () => {
+    const [map, handle] = createReactiveMap<string, number, TestChange>()
+    let snapshotSize = -1
+    map.subscribe(() => {
+      snapshotSize = map.size
+    })
+
+    handle.set("a", 1)
+    handle.set("b", 2)
+    handle.emit({
+      changes: [
+        { type: "set", key: "a" },
+        { type: "set", key: "b" },
+      ],
+    })
+
+    expect(snapshotSize).toBe(2)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// hasChangefeed type guard
+// ---------------------------------------------------------------------------
+
+describe("hasChangefeed", () => {
+  it("returns true for a ReactiveMap", () => {
+    const [map] = createReactiveMap<string, number, TestChange>()
+    expect(hasChangefeed(map)).toBe(true)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Backward compatibility — assignable to CallableChangefeed
+// ---------------------------------------------------------------------------
+
+describe("backward compatibility", () => {
+  it("ReactiveMap is assignable to CallableChangefeed", () => {
+    const [map] = createReactiveMap<string, number, TestChange>()
+
+    // Type-level test: assign to CallableChangefeed
+    const callable: CallableChangefeed<
+      ReadonlyMap<string, number>,
+      TestChange
+    > = map
+
+    // Runtime: callable still works
+    expect(callable()).toBeInstanceOf(Map)
+    expect(callable.current).toBeInstanceOf(Map)
+    expect(typeof callable.subscribe).toBe("function")
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Wholesale rebuild pattern (exchange.peers use case)
+// ---------------------------------------------------------------------------
+
+describe("wholesale rebuild pattern", () => {
+  it("clear → set × N → emit rebuilds and notifies", () => {
+    const [map, handle] = createReactiveMap<string, number, TestChange>()
+
+    // Initial state
+    handle.set("a", 1)
+    handle.set("b", 2)
+    handle.emit({
+      changes: [
+        { type: "set", key: "a" },
+        { type: "set", key: "b" },
+      ],
+    })
+
+    const received: Changeset<TestChange>[] = []
+    map.subscribe(cs => received.push(cs))
+
+    // Wholesale rebuild
+    handle.clear()
+    handle.set("c", 3)
+    handle.set("d", 4)
+    handle.emit({
+      changes: [
+        { type: "delete", key: "a" },
+        { type: "delete", key: "b" },
+        { type: "set", key: "c" },
+        { type: "set", key: "d" },
+      ],
+    })
+
+    // One changeset with all changes
+    expect(received).toHaveLength(1)
+    expect(received[0].changes).toHaveLength(4)
+
+    // Map reflects new state
+    expect(map.size).toBe(2)
+    expect(map.has("a")).toBe(false)
+    expect(map.has("b")).toBe(false)
+    expect(map.get("c")).toBe(3)
+    expect(map.get("d")).toBe(4)
+  })
+})