@kyneta/changefeed 1.3.0

package/src/callable.ts

@@ -0,0 +1,82 @@
+// callable — the createCallable combinator.
+//
+// Wraps a Changefeed<S, C> in a callable function-object so that
+// `feed()` returns `feed.current`. The callable preserves the full
+// changefeed contract: [CHANGEFEED], .current, .subscribe().
+//
+// This is the same function-object pattern used by LocalRef in
+// @kyneta/cast — a function with properties attached.
+
+import type { ChangeBase } from "./change.js"
+import type { Changefeed, ChangefeedProtocol, Changeset } from "./changefeed.js"
+import { CHANGEFEED } from "./changefeed.js"
+
+// ---------------------------------------------------------------------------
+// Type
+// ---------------------------------------------------------------------------
+
+/**
+ * A changefeed that is also callable — `feed()` returns `feed.current`.
+ *
+ * This is the intersection of `Changefeed<S, C>` and `() => S`.
+ * The call signature provides ergonomic read access without `.current`.
+ */
+export type CallableChangefeed<
+  S,
+  C extends ChangeBase = ChangeBase,
+> = Changefeed<S, C> & (() => S)
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Wrap a `Changefeed<S, C>` in a callable function-object.
+ *
+ * The returned object:
+ * - `feed()` → `feed.current` (callable)
+ * - `feed.current` → delegated getter
+ * - `feed.subscribe(cb)` → delegated
+ * - `feed[CHANGEFEED]` → delegated protocol
+ * - `hasChangefeed(feed)` → `true`
+ *
+ * ```ts
+ * const [source, emit] = createChangefeed(() => count)
+ * const feed = createCallable(source)
+ * feed()              // read current value
+ * feed.current        // same as feed()
+ * feed.subscribe(cb)  // subscribe to changes
+ * ```
+ */
+export function createCallable<S, C extends ChangeBase>(
+  feed: Changefeed<S, C>,
+): CallableChangefeed<S, C> {
+  const callable: any = () => feed.current
+
+  // [CHANGEFEED] — non-enumerable getter delegating to source
+  Object.defineProperty(callable, CHANGEFEED, {
+    get(): ChangefeedProtocol<S, C> {
+      return feed[CHANGEFEED]
+    },
+    enumerable: false,
+    configurable: false,
+  })
+
+  // .current — getter delegating to source
+  Object.defineProperty(callable, "current", {
+    get(): S {
+      return feed.current
+    },
+    enumerable: true,
+    configurable: false,
+  })
+
+  // .subscribe — delegating to source
+  callable.subscribe = (
+    callback: (changeset: Changeset<C>) => void,
+  ): (() => void) => {
+    return feed.subscribe(callback)
+  }
+
+  return callable as CallableChangefeed<S, C>
+}

package/src/change.ts

@@ -0,0 +1,28 @@
+// ChangeBase — the universal base type for all changes.
+//
+// A change describes a delta to a reactive value. The same change
+// structure flows in both directions:
+//   - Going in (producer → consumer): the change describes what happened
+//   - Coming out (consumer → subscriber): the change describes the delta
+//
+// Changes are an open protocol identified by a string discriminant.
+// Built-in change types (TextChange, SequenceChange, etc.) live in
+// @kyneta/schema — they are schema vocabulary, not contract primitives.
+// Third-party producers extend ChangeBase with their own types.
+
+// ---------------------------------------------------------------------------
+// Base protocol
+// ---------------------------------------------------------------------------
+
+/**
+ * All changes carry a string `type` discriminant. Built-in change types
+ * use well-known strings ("text", "sequence", "map", "replace", "tree").
+ * Third-party producers extend this with their own types.
+ *
+ * Provenance metadata (e.g. "local", "sync") is carried at the batch
+ * level on `Changeset.origin`, not on individual changes. See
+ * `Changeset` in `changefeed.ts`.
+ */
+export interface ChangeBase {
+  readonly type: string
+}

package/src/changefeed.ts

@@ -0,0 +1,250 @@
+// Changefeed — the universal reactive contract.
+//
+// A changefeed is a reactive value with a current state and a stream
+// of future changes. You read `current` to see what's there now;
+// you subscribe to learn what changes next.
+//
+// The changefeed protocol is expressed through a single symbol: CHANGEFEED.
+//
+// Changes are delivered as `Changeset<C>` — a batch of one or more
+// changes with optional provenance metadata. Auto-commit wraps a
+// single change in a degenerate changeset of one; transactions and
+// `applyChanges` deliver multi-change batches. The subscriber API
+// is uniform regardless of batch size.
+//
+// This module is the canonical home of the reactive contract. It has
+// zero dependencies — no schema, no paths, no interpreters.
+
+import type { ChangeBase } from "./change.js"
+
+// ---------------------------------------------------------------------------
+// Symbol
+// ---------------------------------------------------------------------------
+
+/**
+ * The single symbol that marks a value as a changefeed. Accessing
+ * `obj[CHANGEFEED]` yields a `ChangefeedProtocol<S, C>` — the current
+ * value and a stream of future changes.
+ *
+ * Uses `Symbol.for` so that multiple copies of this module (e.g. in
+ * different bundle chunks) share the same symbol identity.
+ */
+export const CHANGEFEED: unique symbol = Symbol.for("kyneta:changefeed") as any
+
+// ---------------------------------------------------------------------------
+// Changeset — the unit of batch delivery
+// ---------------------------------------------------------------------------
+
+/**
+ * A changeset is the unit of delivery through the changefeed protocol.
+ * It wraps one or more changes with optional batch-level metadata.
+ *
+ * - Auto-commit produces a degenerate changeset of one change.
+ * - Transactions and `applyChanges` produce multi-change batches.
+ * - `origin` carries provenance for the entire batch (e.g. "sync",
+ *   "undo", "local"). Individual changes do not carry provenance —
+ *   the batch does.
+ *
+ * The subscriber API always receives a `Changeset`, making it uniform
+ * regardless of how the changes were produced.
+ */
+export interface Changeset<C = ChangeBase> {
+  /** The individual changes in this batch. */
+  readonly changes: readonly C[]
+  /** Provenance of the batch (e.g. "sync", "undo", "local"). */
+  readonly origin?: string
+}
+
+// ---------------------------------------------------------------------------
+// Core interfaces — protocol layer
+// ---------------------------------------------------------------------------
+
+/**
+ * The protocol object that sits behind the `[CHANGEFEED]` symbol.
+ *
+ * A coalgebra: `current` gives the live state, `subscribe` gives the
+ * stream of future changes. In automata-theory terms this is a Moore
+ * machine with a push-based transition stream.
+ *
+ * Properties:
+ * - `current` is a getter — always returns the live current value
+ * - `subscribe` returns an unsubscribe function
+ * - Subscribers receive a `Changeset<C>` — a batch of changes with
+ *   optional provenance. For auto-commit (single mutation), the
+ *   changeset contains exactly one change.
+ * - Static (non-reactive) sources return a protocol whose tail never emits:
+ *   `{ current: value, subscribe: () => () => {} }`
+ *
+ * This is internal plumbing — developers interact with `Changefeed<S, C>`
+ * (the developer-facing type that includes `[CHANGEFEED]`, `.current`,
+ * and `.subscribe()` in one interface).
+ */
+export interface ChangefeedProtocol<S, C extends ChangeBase = ChangeBase> {
+  /** The current value, always live (a getter). */
+  readonly current: S
+  /** Subscribe to future changes. Returns an unsubscribe function. */
+  subscribe(callback: (changeset: Changeset<C>) => void): () => void
+}
+
+// ---------------------------------------------------------------------------
+// Core interfaces — developer-facing type
+// ---------------------------------------------------------------------------
+
+/**
+ * The developer-facing changefeed type: a reactive value with direct
+ * access to `.current`, `.subscribe()`, and the `[CHANGEFEED]` marker.
+ *
+ * Developers write `readonly peers: Changefeed<PeerMap, PeerChange>` —
+ * no `Has` prefix, no separate protocol object, no triple declaration.
+ *
+ * A `Changefeed<S, C>` is the intersection of:
+ * - The `[CHANGEFEED]` marker (for compiler detection and runtime protocol)
+ * - Direct `.current` and `.subscribe()` access (for developer ergonomics)
+ *
+ * Use `changefeed(source)` to project any `HasChangefeed` into a
+ * `Changefeed`, or `createChangefeed()` to build one from scratch.
+ */
+export interface Changefeed<S, C extends ChangeBase = ChangeBase> {
+  /** The protocol object behind the symbol. */
+  readonly [CHANGEFEED]: ChangefeedProtocol<S, C>
+  /** The current value, always live (a getter). */
+  readonly current: S
+  /** Subscribe to future changes. Returns an unsubscribe function. */
+  subscribe(callback: (changeset: Changeset<C>) => void): () => void
+}
+
+/**
+ * An object that carries a changefeed protocol under the `[CHANGEFEED]`
+ * symbol.
+ *
+ * Any ref, interpreted node, or enriched value can implement this
+ * interface to participate in the reactive protocol.
+ */
+export interface HasChangefeed<S = unknown, A extends ChangeBase = ChangeBase> {
+  readonly [CHANGEFEED]: ChangefeedProtocol<S, A>
+}
+
+// ---------------------------------------------------------------------------
+// Type guard
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns `true` if `value` has a `[CHANGEFEED]` property, i.e. it
+ * implements the `HasChangefeed` interface.
+ */
+export function hasChangefeed<S = unknown, A extends ChangeBase = ChangeBase>(
+  value: unknown,
+): value is HasChangefeed<S, A> {
+  return (
+    value !== null &&
+    value !== undefined &&
+    (typeof value === "object" || typeof value === "function") &&
+    CHANGEFEED in (value as object)
+  )
+}
+
+// ---------------------------------------------------------------------------
+// Static feed helper
+// ---------------------------------------------------------------------------
+
+/**
+ * Creates a changefeed protocol that never emits changes — useful for
+ * static/non-reactive data sources that still need to participate in
+ * the changefeed protocol.
+ */
+export function staticChangefeed<S>(head: S): ChangefeedProtocol<S, never> {
+  return {
+    get current() {
+      return head
+    },
+    subscribe() {
+      return () => {}
+    },
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Projector — lift HasChangefeed to Changefeed
+// ---------------------------------------------------------------------------
+
+/**
+ * Project any object with `[CHANGEFEED]` into a developer-facing
+ * `Changefeed<S, C>` — lifting the hidden protocol surface to direct
+ * `.current` and `.subscribe()` accessibility.
+ *
+ * ```ts
+ * const feed = changefeed(doc.title)
+ * feed.current          // live value
+ * feed.subscribe(cb)    // subscribe to changes
+ * feed[CHANGEFEED]      // the protocol object (same as doc.title[CHANGEFEED])
+ * ```
+ */
+export function changefeed<S, C extends ChangeBase>(
+  source: HasChangefeed<S, C>,
+): Changefeed<S, C> {
+  const protocol = source[CHANGEFEED]
+  return {
+    [CHANGEFEED]: protocol,
+    get current(): S {
+      return protocol.current
+    },
+    subscribe(callback: (changeset: Changeset<C>) => void): () => void {
+      return protocol.subscribe(callback)
+    },
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Factory — create standalone Changefeed values
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a standalone `Changefeed<S, C>` with push semantics.
+ *
+ * Returns a tuple of the feed and an emit function. The feed's
+ * `[CHANGEFEED]` returns the protocol view of itself. Manages its
+ * own subscriber set internally.
+ *
+ * ```ts
+ * const [feed, emit] = createChangefeed(() => count)
+ * feed.current                       // read live value
+ * feed.subscribe(cs => { ... })      // subscribe
+ * hasChangefeed(feed)                 // true
+ * emit({ changes: [{ type: "replace", value: 42 }] })  // push
+ * ```
+ */
+export function createChangefeed<S, C extends ChangeBase = ChangeBase>(
+  getCurrent: () => S,
+): [feed: Changefeed<S, C>, emit: (changeset: Changeset<C>) => void] {
+  const subscribers = new Set<(changeset: Changeset<C>) => void>()
+
+  const protocol: ChangefeedProtocol<S, C> = {
+    get current(): S {
+      return getCurrent()
+    },
+    subscribe(callback: (changeset: Changeset<C>) => void): () => void {
+      subscribers.add(callback)
+      return () => {
+        subscribers.delete(callback)
+      }
+    },
+  }
+
+  const feed: Changefeed<S, C> = {
+    [CHANGEFEED]: protocol,
+    get current(): S {
+      return getCurrent()
+    },
+    subscribe(callback: (changeset: Changeset<C>) => void): () => void {
+      return protocol.subscribe(callback)
+    },
+  }
+
+  const emit = (changeset: Changeset<C>): void => {
+    for (const cb of subscribers) {
+      cb(changeset)
+    }
+  }
+
+  return [feed, emit]
+}

package/src/index.ts

@@ -0,0 +1,27 @@
+// @kyneta/changefeed — the universal reactive contract.
+//
+// This barrel re-exports everything from the three source modules
+// that make up the changefeed contract package.
+
+// Callable — the createCallable combinator
+export type { CallableChangefeed } from "./callable.js"
+export { createCallable } from "./callable.js"
+// ChangeBase — the universal base type for all changes
+export type { ChangeBase } from "./change.js"
+// Changefeed — symbol, types, type guards, factories, projector
+export type {
+  Changefeed,
+  ChangefeedProtocol,
+  Changeset,
+  HasChangefeed,
+} from "./changefeed.js"
+export {
+  CHANGEFEED,
+  changefeed,
+  createChangefeed,
+  hasChangefeed,
+  staticChangefeed,
+} from "./changefeed.js"
+// ReactiveMap — callable changefeed over a mutable Map
+export type { ReactiveMap, ReactiveMapHandle } from "./reactive-map.js"
+export { createReactiveMap } from "./reactive-map.js"

package/src/reactive-map.ts

@@ -0,0 +1,162 @@
+// reactive-map — a callable changefeed over a mutable Map.
+//
+// ReactiveMap<K, V, C> is a CallableChangefeed<ReadonlyMap<K, V>, C>
+// with lifted collection accessors (.get, .has, .keys, .size, iteration).
+// The handle provides raw map mutations (set, delete, clear) without
+// automatic emission — the consumer decides when and what to emit.
+//
+// This extracts the recurring pattern of "callable changefeed over a
+// ReadonlyMap with convenience accessors" (used by exchange.peers,
+// Catalog, and future reactive collections) into a single combinator.
+
+import type { CallableChangefeed } from "./callable.js"
+import type { ChangeBase } from "./change.js"
+import type { ChangefeedProtocol, Changeset } from "./changefeed.js"
+import { CHANGEFEED, createChangefeed } from "./changefeed.js"
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/**
+ * A callable changefeed over a `ReadonlyMap<K, V>` with lifted
+ * collection accessors.
+ *
+ * `reactiveMap()` returns the current `ReadonlyMap<K, V>`.
+ * `.get()`, `.has()`, `.keys()`, `.size`, and `[Symbol.iterator]()`
+ * delegate to the internal map — no need to unwrap `.current` first.
+ *
+ * Extends `CallableChangefeed` — assignable anywhere a
+ * `CallableChangefeed<ReadonlyMap<K, V>, C>` or `Changefeed` is expected.
+ */
+export interface ReactiveMap<K, V, C extends ChangeBase = ChangeBase>
+  extends CallableChangefeed<ReadonlyMap<K, V>, C> {
+  /** Get the value for a key, or `undefined` if absent. */
+  get(key: K): V | undefined
+  /** Whether the map contains a key. */
+  has(key: K): boolean
+  /** An iterator over all keys. */
+  keys(): IterableIterator<K>
+  /** The number of entries. */
+  readonly size: number
+  /** Iterate over `[key, value]` pairs. */
+  [Symbol.iterator](): IterableIterator<[K, V]>
+}
+
+/**
+ * The producer-side handle for a `ReactiveMap`.
+ *
+ * Provides raw map mutations (`set`, `delete`, `clear`) that modify
+ * the internal map **without** emitting changes. Call `emit()` with
+ * the appropriate changeset after mutations are complete.
+ *
+ * This separation lets the consumer batch mutations and emit a single
+ * changeset — e.g. `clear()` → N × `set()` → one `emit()`.
+ */
+export interface ReactiveMapHandle<K, V, C extends ChangeBase> {
+  /** Insert or overwrite an entry. Does NOT emit. */
+  set(key: K, value: V): void
+  /** Remove an entry. Returns `true` if the key was present. Does NOT emit. */
+  delete(key: K): boolean
+  /** Remove all entries. Does NOT emit. */
+  clear(): void
+  /** Push a changeset to all subscribers. */
+  emit(changeset: Changeset<C>): void
+}
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a `ReactiveMap<K, V, C>` and its producer-side handle.
+ *
+ * The reactive map owns its internal `Map<K, V>`. Consumers read via
+ * the `ReactiveMap` surface (call signature, `.get()`, `.has()`, etc.).
+ * Producers mutate via the `ReactiveMapHandle` (`set`, `delete`,
+ * `clear`) and push notifications via `emit`.
+ *
+ * ```ts
+ * const [peers, handle] = createReactiveMap<PeerId, PeerInfo, PeerChange>()
+ *
+ * handle.set("alice", aliceInfo)
+ * handle.emit({ changes: [{ type: "peer-joined", peer: aliceInfo }] })
+ *
+ * peers()          // ReadonlyMap with one entry
+ * peers.get("alice")  // aliceInfo
+ * peers.size       // 1
+ * ```
+ */
+export function createReactiveMap<K, V, C extends ChangeBase = ChangeBase>(): [
+  ReactiveMap<K, V, C>,
+  ReactiveMapHandle<K, V, C>,
+] {
+  const map = new Map<K, V>()
+
+  // Create the base changefeed + emit pair.
+  // The thunk reads the same Map instance — never reassigned.
+  const [feed, emit] = createChangefeed<ReadonlyMap<K, V>, C>(() => map)
+
+  // Build the callable function-object.
+  // We construct it manually (rather than using createCallable) so we
+  // can attach the collection accessors in one pass.
+  const callable: any = () => map as ReadonlyMap<K, V>
+
+  // ── Changefeed protocol ──
+
+  Object.defineProperty(callable, CHANGEFEED, {
+    get(): ChangefeedProtocol<ReadonlyMap<K, V>, C> {
+      return feed[CHANGEFEED]
+    },
+    enumerable: false,
+    configurable: false,
+  })
+
+  Object.defineProperty(callable, "current", {
+    get(): ReadonlyMap<K, V> {
+      return map
+    },
+    enumerable: true,
+    configurable: false,
+  })
+
+  callable.subscribe = (
+    callback: (changeset: Changeset<C>) => void,
+  ): (() => void) => {
+    return feed.subscribe(callback)
+  }
+
+  // ── Lifted collection accessors ──
+
+  callable.get = (key: K): V | undefined => map.get(key)
+  callable.has = (key: K): boolean => map.has(key)
+  callable.keys = (): IterableIterator<K> => map.keys()
+
+  Object.defineProperty(callable, "size", {
+    get(): number {
+      return map.size
+    },
+    enumerable: true,
+    configurable: false,
+  })
+
+  callable[Symbol.iterator] = (): IterableIterator<[K, V]> =>
+    map[Symbol.iterator]()
+
+  // ── Handle (producer side) ──
+
+  const handle: ReactiveMapHandle<K, V, C> = {
+    set(key: K, value: V): void {
+      map.set(key, value)
+    },
+    delete(key: K): boolean {
+      return map.delete(key)
+    },
+    clear(): void {
+      map.clear()
+    },
+    emit,
+  }
+
+  return [callable as ReactiveMap<K, V, C>, handle]
+}