@kyneta/changefeed 1.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-present Duane Johnson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,135 @@
+# @kyneta/changefeed
+
+The universal reactive contract for Kyneta — a Moore machine identified by `[CHANGEFEED]`.
+
+## Overview
+
+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 protocol is expressed through a single well-known symbol: `CHANGEFEED` (`Symbol.for("kyneta:changefeed")`). Any object carrying this symbol participates in the reactive protocol — schema-interpreted refs, local state, peer lifecycle feeds, or anything else.
+
+This package contains the **contract only** — zero dependencies, no schema, no interpreters, no paths. Schema-specific extensions (`Op`, `ComposedChangefeedProtocol`, tree observation) live in `@kyneta/schema`, which depends on this package.
+
+## Install
+
+```sh
+pnpm add @kyneta/changefeed
+```
+
+## API
+
+### Types
+
+```ts
+// The universal base type for all changes — an open protocol identified by a string discriminant.
+interface ChangeBase {
+  readonly type: string
+}
+
+// A batch of changes with optional provenance.
+interface Changeset<C = ChangeBase> {
+  readonly changes: readonly C[]
+  readonly origin?: string
+}
+
+// The protocol object behind [CHANGEFEED] — a Moore machine coalgebra.
+interface ChangefeedProtocol<S, C extends ChangeBase = ChangeBase> {
+  readonly current: S
+  subscribe(callback: (changeset: Changeset<C>) => void): () => void
+}
+
+// Developer-facing type: [CHANGEFEED] marker + direct .current and .subscribe().
+interface Changefeed<S, C extends ChangeBase = ChangeBase> {
+  readonly [CHANGEFEED]: ChangefeedProtocol<S, C>
+  readonly current: S
+  subscribe(callback: (changeset: Changeset<C>) => void): () => void
+}
+
+// Marker interface — any object with [CHANGEFEED] participates in the protocol.
+interface HasChangefeed<S = unknown, A extends ChangeBase = ChangeBase> {
+  readonly [CHANGEFEED]: ChangefeedProtocol<S, A>
+}
+
+// A Changefeed that is also callable — feed() returns feed.current.
+type CallableChangefeed<S, C extends ChangeBase = ChangeBase> =
+  Changefeed<S, C> & (() => S)
+```
+
+### Functions
+
+#### `createChangefeed<S, C>(getCurrent: () => S): [Changefeed<S, C>, emit]`
+
+Create a standalone changefeed with push semantics. Returns a `[feed, emit]` tuple.
+
+```ts
+import { createChangefeed } from "@kyneta/changefeed"
+
+let count = 0
+const [feed, emit] = createChangefeed(() => count)
+
+feed.current              // 0
+feed.subscribe(cs => console.log(cs.changes))
+
+count = 1
+emit({ changes: [{ type: "increment", amount: 1 }] })
+// subscriber receives the changeset
+```
+
+#### `createCallable<S, C>(feed: Changefeed<S, C>): CallableChangefeed<S, C>`
+
+Wrap a changefeed in a callable function-object. `feed()` returns `feed.current`.
+
+```ts
+import { createChangefeed, createCallable } from "@kyneta/changefeed"
+
+let count = 0
+const [source, emit] = createChangefeed(() => count)
+const feed = createCallable(source)
+
+feed()          // 0 — callable
+feed.current    // 0 — getter
+feed.subscribe  // subscribe to changes
+```
+
+#### `changefeed<S, C>(source: HasChangefeed<S, C>): Changefeed<S, C>`
+
+Project any object with `[CHANGEFEED]` into a developer-facing `Changefeed` — lifting the hidden protocol surface to direct `.current` and `.subscribe()` accessibility.
+
+```ts
+import { changefeed } from "@kyneta/changefeed"
+
+const feed = changefeed(doc.title)
+feed.current          // live value
+feed.subscribe(cb)    // subscribe to changes
+```
+
+#### `hasChangefeed(value: unknown): value is HasChangefeed`
+
+Type guard — returns `true` if `value` has a `[CHANGEFEED]` property.
+
+#### `staticChangefeed<S>(head: S): ChangefeedProtocol<S, never>`
+
+Creates a protocol object that never emits changes — useful for static data sources that still need to participate in the protocol.
+
+## Relationship to `@kyneta/schema`
+
+`@kyneta/schema` depends on `@kyneta/changefeed` and extends the contract with tree-structured observation:
+
+| This package (`@kyneta/changefeed`) | `@kyneta/schema` |
+|---|---|
+| `ChangeBase` | `TextChange`, `MapChange`, `SequenceChange`, ... |
+| `Changeset<C>` | `Op<C>` (addressed delta with `Path`) |
+| `ChangefeedProtocol<S, C>` | `ComposedChangefeedProtocol<S, C>` (adds `subscribeTree`) |
+| `Changefeed<S, C>` | `HasComposedChangefeed<S, C>` |
+| `hasChangefeed()` | `hasComposedChangefeed()`, `getOrCreateChangefeed()` |
+| `createChangefeed()`, `createCallable()` | `expandMapOpsToLeaves()` |
+
+Consumers import the contract from `@kyneta/changefeed` directly — schema does **not** re-export contract symbols. The import path tells the truth about the dependency.
+
+## Relationship to `@kyneta/cast`
+
+The Kyneta compiler detects `[CHANGEFEED]` structurally on types for automatic reactive subscription. `HasChangefeed<S, C>` is the type-level marker the compiler looks for. The Cast runtime uses `hasChangefeed()` at runtime to discover reactive values and subscribe to their change streams.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,235 @@
+/**
+ * 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`.
+ */
+interface ChangeBase {
+    readonly type: string;
+}
+
+/**
+ * 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.
+ */
+declare const CHANGEFEED: unique symbol;
+/**
+ * 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.
+ */
+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;
+}
+/**
+ * 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).
+ */
+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;
+}
+/**
+ * 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.
+ */
+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.
+ */
+interface HasChangefeed<S = unknown, A extends ChangeBase = ChangeBase> {
+    readonly [CHANGEFEED]: ChangefeedProtocol<S, A>;
+}
+/**
+ * Returns `true` if `value` has a `[CHANGEFEED]` property, i.e. it
+ * implements the `HasChangefeed` interface.
+ */
+declare function hasChangefeed<S = unknown, A extends ChangeBase = ChangeBase>(value: unknown): value is HasChangefeed<S, A>;
+/**
+ * Creates a changefeed protocol that never emits changes — useful for
+ * static/non-reactive data sources that still need to participate in
+ * the changefeed protocol.
+ */
+declare function staticChangefeed<S>(head: S): ChangefeedProtocol<S, never>;
+/**
+ * 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])
+ * ```
+ */
+declare function changefeed<S, C extends ChangeBase>(source: HasChangefeed<S, C>): Changefeed<S, C>;
+/**
+ * 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
+ * ```
+ */
+declare function createChangefeed<S, C extends ChangeBase = ChangeBase>(getCurrent: () => S): [feed: Changefeed<S, C>, emit: (changeset: Changeset<C>) => void];
+
+/**
+ * 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`.
+ */
+type CallableChangefeed<S, C extends ChangeBase = ChangeBase> = Changefeed<S, C> & (() => S);
+/**
+ * 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
+ * ```
+ */
+declare function createCallable<S, C extends ChangeBase>(feed: Changefeed<S, C>): CallableChangefeed<S, C>;
+
+/**
+ * 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.
+ */
+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()`.
+ */
+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;
+}
+/**
+ * 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
+ * ```
+ */
+declare function createReactiveMap<K, V, C extends ChangeBase = ChangeBase>(): [
+    ReactiveMap<K, V, C>,
+    ReactiveMapHandle<K, V, C>
+];
+
+export { CHANGEFEED, type CallableChangefeed, type ChangeBase, type Changefeed, type ChangefeedProtocol, type Changeset, type HasChangefeed, type ReactiveMap, type ReactiveMapHandle, changefeed, createCallable, createChangefeed, createReactiveMap, hasChangefeed, staticChangefeed };

package/dist/index.js

@@ -0,0 +1,138 @@
+// src/changefeed.ts
+var CHANGEFEED = /* @__PURE__ */ Symbol.for("kyneta:changefeed");
+function hasChangefeed(value) {
+  return value !== null && value !== void 0 && (typeof value === "object" || typeof value === "function") && CHANGEFEED in value;
+}
+function staticChangefeed(head) {
+  return {
+    get current() {
+      return head;
+    },
+    subscribe() {
+      return () => {
+      };
+    }
+  };
+}
+function changefeed(source) {
+  const protocol = source[CHANGEFEED];
+  return {
+    [CHANGEFEED]: protocol,
+    get current() {
+      return protocol.current;
+    },
+    subscribe(callback) {
+      return protocol.subscribe(callback);
+    }
+  };
+}
+function createChangefeed(getCurrent) {
+  const subscribers = /* @__PURE__ */ new Set();
+  const protocol = {
+    get current() {
+      return getCurrent();
+    },
+    subscribe(callback) {
+      subscribers.add(callback);
+      return () => {
+        subscribers.delete(callback);
+      };
+    }
+  };
+  const feed = {
+    [CHANGEFEED]: protocol,
+    get current() {
+      return getCurrent();
+    },
+    subscribe(callback) {
+      return protocol.subscribe(callback);
+    }
+  };
+  const emit = (changeset) => {
+    for (const cb of subscribers) {
+      cb(changeset);
+    }
+  };
+  return [feed, emit];
+}
+
+// src/callable.ts
+function createCallable(feed) {
+  const callable = () => feed.current;
+  Object.defineProperty(callable, CHANGEFEED, {
+    get() {
+      return feed[CHANGEFEED];
+    },
+    enumerable: false,
+    configurable: false
+  });
+  Object.defineProperty(callable, "current", {
+    get() {
+      return feed.current;
+    },
+    enumerable: true,
+    configurable: false
+  });
+  callable.subscribe = (callback) => {
+    return feed.subscribe(callback);
+  };
+  return callable;
+}
+
+// src/reactive-map.ts
+function createReactiveMap() {
+  const map = /* @__PURE__ */ new Map();
+  const [feed, emit] = createChangefeed(() => map);
+  const callable = () => map;
+  Object.defineProperty(callable, CHANGEFEED, {
+    get() {
+      return feed[CHANGEFEED];
+    },
+    enumerable: false,
+    configurable: false
+  });
+  Object.defineProperty(callable, "current", {
+    get() {
+      return map;
+    },
+    enumerable: true,
+    configurable: false
+  });
+  callable.subscribe = (callback) => {
+    return feed.subscribe(callback);
+  };
+  callable.get = (key) => map.get(key);
+  callable.has = (key) => map.has(key);
+  callable.keys = () => map.keys();
+  Object.defineProperty(callable, "size", {
+    get() {
+      return map.size;
+    },
+    enumerable: true,
+    configurable: false
+  });
+  callable[Symbol.iterator] = () => map[Symbol.iterator]();
+  const handle = {
+    set(key, value) {
+      map.set(key, value);
+    },
+    delete(key) {
+      return map.delete(key);
+    },
+    clear() {
+      map.clear();
+    },
+    emit
+  };
+  return [callable, handle];
+}
+export {
+  CHANGEFEED,
+  changefeed,
+  createCallable,
+  createChangefeed,
+  createReactiveMap,
+  hasChangefeed,
+  staticChangefeed
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/changefeed.ts","../src/callable.ts","../src/reactive-map.ts"],"sourcesContent":["// Changefeed — the universal reactive contract.\n//\n// A changefeed is a reactive value with a current state and a stream\n// of future changes. You read `current` to see what's there now;\n// you subscribe to learn what changes next.\n//\n// The changefeed protocol is expressed through a single symbol: CHANGEFEED.\n//\n// Changes are delivered as `Changeset<C>` — a batch of one or more\n// changes with optional provenance metadata. Auto-commit wraps a\n// single change in a degenerate changeset of one; transactions and\n// `applyChanges` deliver multi-change batches. The subscriber API\n// is uniform regardless of batch size.\n//\n// This module is the canonical home of the reactive contract. It has\n// zero dependencies — no schema, no paths, no interpreters.\n\nimport type { ChangeBase } from \"./change.js\"\n\n// ---------------------------------------------------------------------------\n// Symbol\n// ---------------------------------------------------------------------------\n\n/**\n * The single symbol that marks a value as a changefeed. Accessing\n * `obj[CHANGEFEED]` yields a `ChangefeedProtocol<S, C>` — the current\n * value and a stream of future changes.\n *\n * Uses `Symbol.for` so that multiple copies of this module (e.g. in\n * different bundle chunks) share the same symbol identity.\n */\nexport const CHANGEFEED: unique symbol = Symbol.for(\"kyneta:changefeed\") as any\n\n// ---------------------------------------------------------------------------\n// Changeset — the unit of batch delivery\n// ---------------------------------------------------------------------------\n\n/**\n * A changeset is the unit of delivery through the changefeed protocol.\n * It wraps one or more changes with optional batch-level metadata.\n *\n * - Auto-commit produces a degenerate changeset of one change.\n * - Transactions and `applyChanges` produce multi-change batches.\n * - `origin` carries provenance for the entire batch (e.g. \"sync\",\n *   \"undo\", \"local\"). Individual changes do not carry provenance —\n *   the batch does.\n *\n * The subscriber API always receives a `Changeset`, making it uniform\n * regardless of how the changes were produced.\n */\nexport interface Changeset<C = ChangeBase> {\n  /** The individual changes in this batch. */\n  readonly changes: readonly C[]\n  /** Provenance of the batch (e.g. \"sync\", \"undo\", \"local\"). */\n  readonly origin?: string\n}\n\n// ---------------------------------------------------------------------------\n// Core interfaces — protocol layer\n// ---------------------------------------------------------------------------\n\n/**\n * The protocol object that sits behind the `[CHANGEFEED]` symbol.\n *\n * A coalgebra: `current` gives the live state, `subscribe` gives the\n * stream of future changes. In automata-theory terms this is a Moore\n * machine with a push-based transition stream.\n *\n * Properties:\n * - `current` is a getter — always returns the live current value\n * - `subscribe` returns an unsubscribe function\n * - Subscribers receive a `Changeset<C>` — a batch of changes with\n *   optional provenance. For auto-commit (single mutation), the\n *   changeset contains exactly one change.\n * - Static (non-reactive) sources return a protocol whose tail never emits:\n *   `{ current: value, subscribe: () => () => {} }`\n *\n * This is internal plumbing — developers interact with `Changefeed<S, C>`\n * (the developer-facing type that includes `[CHANGEFEED]`, `.current`,\n * and `.subscribe()` in one interface).\n */\nexport interface ChangefeedProtocol<S, C extends ChangeBase = ChangeBase> {\n  /** The current value, always live (a getter). */\n  readonly current: S\n  /** Subscribe to future changes. Returns an unsubscribe function. */\n  subscribe(callback: (changeset: Changeset<C>) => void): () => void\n}\n\n// ---------------------------------------------------------------------------\n// Core interfaces — developer-facing type\n// ---------------------------------------------------------------------------\n\n/**\n * The developer-facing changefeed type: a reactive value with direct\n * access to `.current`, `.subscribe()`, and the `[CHANGEFEED]` marker.\n *\n * Developers write `readonly peers: Changefeed<PeerMap, PeerChange>` —\n * no `Has` prefix, no separate protocol object, no triple declaration.\n *\n * A `Changefeed<S, C>` is the intersection of:\n * - The `[CHANGEFEED]` marker (for compiler detection and runtime protocol)\n * - Direct `.current` and `.subscribe()` access (for developer ergonomics)\n *\n * Use `changefeed(source)` to project any `HasChangefeed` into a\n * `Changefeed`, or `createChangefeed()` to build one from scratch.\n */\nexport interface Changefeed<S, C extends ChangeBase = ChangeBase> {\n  /** The protocol object behind the symbol. */\n  readonly [CHANGEFEED]: ChangefeedProtocol<S, C>\n  /** The current value, always live (a getter). */\n  readonly current: S\n  /** Subscribe to future changes. Returns an unsubscribe function. */\n  subscribe(callback: (changeset: Changeset<C>) => void): () => void\n}\n\n/**\n * An object that carries a changefeed protocol under the `[CHANGEFEED]`\n * symbol.\n *\n * Any ref, interpreted node, or enriched value can implement this\n * interface to participate in the reactive protocol.\n */\nexport interface HasChangefeed<S = unknown, A extends ChangeBase = ChangeBase> {\n  readonly [CHANGEFEED]: ChangefeedProtocol<S, A>\n}\n\n// ---------------------------------------------------------------------------\n// Type guard\n// ---------------------------------------------------------------------------\n\n/**\n * Returns `true` if `value` has a `[CHANGEFEED]` property, i.e. it\n * implements the `HasChangefeed` interface.\n */\nexport function hasChangefeed<S = unknown, A extends ChangeBase = ChangeBase>(\n  value: unknown,\n): value is HasChangefeed<S, A> {\n  return (\n    value !== null &&\n    value !== undefined &&\n    (typeof value === \"object\" || typeof value === \"function\") &&\n    CHANGEFEED in (value as object)\n  )\n}\n\n// ---------------------------------------------------------------------------\n// Static feed helper\n// ---------------------------------------------------------------------------\n\n/**\n * Creates a changefeed protocol that never emits changes — useful for\n * static/non-reactive data sources that still need to participate in\n * the changefeed protocol.\n */\nexport function staticChangefeed<S>(head: S): ChangefeedProtocol<S, never> {\n  return {\n    get current() {\n      return head\n    },\n    subscribe() {\n      return () => {}\n    },\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Projector — lift HasChangefeed to Changefeed\n// ---------------------------------------------------------------------------\n\n/**\n * Project any object with `[CHANGEFEED]` into a developer-facing\n * `Changefeed<S, C>` — lifting the hidden protocol surface to direct\n * `.current` and `.subscribe()` accessibility.\n *\n * ```ts\n * const feed = changefeed(doc.title)\n * feed.current          // live value\n * feed.subscribe(cb)    // subscribe to changes\n * feed[CHANGEFEED]      // the protocol object (same as doc.title[CHANGEFEED])\n * ```\n */\nexport function changefeed<S, C extends ChangeBase>(\n  source: HasChangefeed<S, C>,\n): Changefeed<S, C> {\n  const protocol = source[CHANGEFEED]\n  return {\n    [CHANGEFEED]: protocol,\n    get current(): S {\n      return protocol.current\n    },\n    subscribe(callback: (changeset: Changeset<C>) => void): () => void {\n      return protocol.subscribe(callback)\n    },\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Factory — create standalone Changefeed values\n// ---------------------------------------------------------------------------\n\n/**\n * Create a standalone `Changefeed<S, C>` with push semantics.\n *\n * Returns a tuple of the feed and an emit function. The feed's\n * `[CHANGEFEED]` returns the protocol view of itself. Manages its\n * own subscriber set internally.\n *\n * ```ts\n * const [feed, emit] = createChangefeed(() => count)\n * feed.current                       // read live value\n * feed.subscribe(cs => { ... })      // subscribe\n * hasChangefeed(feed)                 // true\n * emit({ changes: [{ type: \"replace\", value: 42 }] })  // push\n * ```\n */\nexport function createChangefeed<S, C extends ChangeBase = ChangeBase>(\n  getCurrent: () => S,\n): [feed: Changefeed<S, C>, emit: (changeset: Changeset<C>) => void] {\n  const subscribers = new Set<(changeset: Changeset<C>) => void>()\n\n  const protocol: ChangefeedProtocol<S, C> = {\n    get current(): S {\n      return getCurrent()\n    },\n    subscribe(callback: (changeset: Changeset<C>) => void): () => void {\n      subscribers.add(callback)\n      return () => {\n        subscribers.delete(callback)\n      }\n    },\n  }\n\n  const feed: Changefeed<S, C> = {\n    [CHANGEFEED]: protocol,\n    get current(): S {\n      return getCurrent()\n    },\n    subscribe(callback: (changeset: Changeset<C>) => void): () => void {\n      return protocol.subscribe(callback)\n    },\n  }\n\n  const emit = (changeset: Changeset<C>): void => {\n    for (const cb of subscribers) {\n      cb(changeset)\n    }\n  }\n\n  return [feed, emit]\n}\n","// callable — the createCallable combinator.\n//\n// Wraps a Changefeed<S, C> in a callable function-object so that\n// `feed()` returns `feed.current`. The callable preserves the full\n// changefeed contract: [CHANGEFEED], .current, .subscribe().\n//\n// This is the same function-object pattern used by LocalRef in\n// @kyneta/cast — a function with properties attached.\n\nimport type { ChangeBase } from \"./change.js\"\nimport type { Changefeed, ChangefeedProtocol, Changeset } from \"./changefeed.js\"\nimport { CHANGEFEED } from \"./changefeed.js\"\n\n// ---------------------------------------------------------------------------\n// Type\n// ---------------------------------------------------------------------------\n\n/**\n * A changefeed that is also callable — `feed()` returns `feed.current`.\n *\n * This is the intersection of `Changefeed<S, C>` and `() => S`.\n * The call signature provides ergonomic read access without `.current`.\n */\nexport type CallableChangefeed<\n  S,\n  C extends ChangeBase = ChangeBase,\n> = Changefeed<S, C> & (() => S)\n\n// ---------------------------------------------------------------------------\n// Factory\n// ---------------------------------------------------------------------------\n\n/**\n * Wrap a `Changefeed<S, C>` in a callable function-object.\n *\n * The returned object:\n * - `feed()` → `feed.current` (callable)\n * - `feed.current` → delegated getter\n * - `feed.subscribe(cb)` → delegated\n * - `feed[CHANGEFEED]` → delegated protocol\n * - `hasChangefeed(feed)` → `true`\n *\n * ```ts\n * const [source, emit] = createChangefeed(() => count)\n * const feed = createCallable(source)\n * feed()              // read current value\n * feed.current        // same as feed()\n * feed.subscribe(cb)  // subscribe to changes\n * ```\n */\nexport function createCallable<S, C extends ChangeBase>(\n  feed: Changefeed<S, C>,\n): CallableChangefeed<S, C> {\n  const callable: any = () => feed.current\n\n  // [CHANGEFEED] — non-enumerable getter delegating to source\n  Object.defineProperty(callable, CHANGEFEED, {\n    get(): ChangefeedProtocol<S, C> {\n      return feed[CHANGEFEED]\n    },\n    enumerable: false,\n    configurable: false,\n  })\n\n  // .current — getter delegating to source\n  Object.defineProperty(callable, \"current\", {\n    get(): S {\n      return feed.current\n    },\n    enumerable: true,\n    configurable: false,\n  })\n\n  // .subscribe — delegating to source\n  callable.subscribe = (\n    callback: (changeset: Changeset<C>) => void,\n  ): (() => void) => {\n    return feed.subscribe(callback)\n  }\n\n  return callable as CallableChangefeed<S, C>\n}\n","// reactive-map — a callable changefeed over a mutable Map.\n//\n// ReactiveMap<K, V, C> is a CallableChangefeed<ReadonlyMap<K, V>, C>\n// with lifted collection accessors (.get, .has, .keys, .size, iteration).\n// The handle provides raw map mutations (set, delete, clear) without\n// automatic emission — the consumer decides when and what to emit.\n//\n// This extracts the recurring pattern of \"callable changefeed over a\n// ReadonlyMap with convenience accessors\" (used by exchange.peers,\n// Catalog, and future reactive collections) into a single combinator.\n\nimport type { CallableChangefeed } from \"./callable.js\"\nimport type { ChangeBase } from \"./change.js\"\nimport type { ChangefeedProtocol, Changeset } from \"./changefeed.js\"\nimport { CHANGEFEED, createChangefeed } from \"./changefeed.js\"\n\n// ---------------------------------------------------------------------------\n// Types\n// ---------------------------------------------------------------------------\n\n/**\n * A callable changefeed over a `ReadonlyMap<K, V>` with lifted\n * collection accessors.\n *\n * `reactiveMap()` returns the current `ReadonlyMap<K, V>`.\n * `.get()`, `.has()`, `.keys()`, `.size`, and `[Symbol.iterator]()`\n * delegate to the internal map — no need to unwrap `.current` first.\n *\n * Extends `CallableChangefeed` — assignable anywhere a\n * `CallableChangefeed<ReadonlyMap<K, V>, C>` or `Changefeed` is expected.\n */\nexport interface ReactiveMap<K, V, C extends ChangeBase = ChangeBase>\n  extends CallableChangefeed<ReadonlyMap<K, V>, C> {\n  /** Get the value for a key, or `undefined` if absent. */\n  get(key: K): V | undefined\n  /** Whether the map contains a key. */\n  has(key: K): boolean\n  /** An iterator over all keys. */\n  keys(): IterableIterator<K>\n  /** The number of entries. */\n  readonly size: number\n  /** Iterate over `[key, value]` pairs. */\n  [Symbol.iterator](): IterableIterator<[K, V]>\n}\n\n/**\n * The producer-side handle for a `ReactiveMap`.\n *\n * Provides raw map mutations (`set`, `delete`, `clear`) that modify\n * the internal map **without** emitting changes. Call `emit()` with\n * the appropriate changeset after mutations are complete.\n *\n * This separation lets the consumer batch mutations and emit a single\n * changeset — e.g. `clear()` → N × `set()` → one `emit()`.\n */\nexport interface ReactiveMapHandle<K, V, C extends ChangeBase> {\n  /** Insert or overwrite an entry. Does NOT emit. */\n  set(key: K, value: V): void\n  /** Remove an entry. Returns `true` if the key was present. Does NOT emit. */\n  delete(key: K): boolean\n  /** Remove all entries. Does NOT emit. */\n  clear(): void\n  /** Push a changeset to all subscribers. */\n  emit(changeset: Changeset<C>): void\n}\n\n// ---------------------------------------------------------------------------\n// Factory\n// ---------------------------------------------------------------------------\n\n/**\n * Create a `ReactiveMap<K, V, C>` and its producer-side handle.\n *\n * The reactive map owns its internal `Map<K, V>`. Consumers read via\n * the `ReactiveMap` surface (call signature, `.get()`, `.has()`, etc.).\n * Producers mutate via the `ReactiveMapHandle` (`set`, `delete`,\n * `clear`) and push notifications via `emit`.\n *\n * ```ts\n * const [peers, handle] = createReactiveMap<PeerId, PeerInfo, PeerChange>()\n *\n * handle.set(\"alice\", aliceInfo)\n * handle.emit({ changes: [{ type: \"peer-joined\", peer: aliceInfo }] })\n *\n * peers()          // ReadonlyMap with one entry\n * peers.get(\"alice\")  // aliceInfo\n * peers.size       // 1\n * ```\n */\nexport function createReactiveMap<K, V, C extends ChangeBase = ChangeBase>(): [\n  ReactiveMap<K, V, C>,\n  ReactiveMapHandle<K, V, C>,\n] {\n  const map = new Map<K, V>()\n\n  // Create the base changefeed + emit pair.\n  // The thunk reads the same Map instance — never reassigned.\n  const [feed, emit] = createChangefeed<ReadonlyMap<K, V>, C>(() => map)\n\n  // Build the callable function-object.\n  // We construct it manually (rather than using createCallable) so we\n  // can attach the collection accessors in one pass.\n  const callable: any = () => map as ReadonlyMap<K, V>\n\n  // ── Changefeed protocol ──\n\n  Object.defineProperty(callable, CHANGEFEED, {\n    get(): ChangefeedProtocol<ReadonlyMap<K, V>, C> {\n      return feed[CHANGEFEED]\n    },\n    enumerable: false,\n    configurable: false,\n  })\n\n  Object.defineProperty(callable, \"current\", {\n    get(): ReadonlyMap<K, V> {\n      return map\n    },\n    enumerable: true,\n    configurable: false,\n  })\n\n  callable.subscribe = (\n    callback: (changeset: Changeset<C>) => void,\n  ): (() => void) => {\n    return feed.subscribe(callback)\n  }\n\n  // ── Lifted collection accessors ──\n\n  callable.get = (key: K): V | undefined => map.get(key)\n  callable.has = (key: K): boolean => map.has(key)\n  callable.keys = (): IterableIterator<K> => map.keys()\n\n  Object.defineProperty(callable, \"size\", {\n    get(): number {\n      return map.size\n    },\n    enumerable: true,\n    configurable: false,\n  })\n\n  callable[Symbol.iterator] = (): IterableIterator<[K, V]> =>\n    map[Symbol.iterator]()\n\n  // ── Handle (producer side) ──\n\n  const handle: ReactiveMapHandle<K, V, C> = {\n    set(key: K, value: V): void {\n      map.set(key, value)\n    },\n    delete(key: K): boolean {\n      return map.delete(key)\n    },\n    clear(): void {\n      map.clear()\n    },\n    emit,\n  }\n\n  return [callable as ReactiveMap<K, V, C>, handle]\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@kyneta/changefeed",
+  "version": "1.3.0",
+  "description": "Universal reactive contract — a Moore machine identified by [CHANGEFEED]",
+  "author": "Duane Johnson",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/halecraft/kyneta",
+    "directory": "packages/changefeed"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./src": "./src/index.ts",
+    "./src/*": "./src/*"
+  },
+  "devDependencies": {
+    "tsup": "^8.5.0",
+    "typescript": "^5.9.2",
+    "vitest": "^4.0.17"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "verify logic",
+    "verify": "verify"
+  }
+}