@langchain/langgraph-sdk 1.8.9 → 1.9.0

package/dist/stream/assembled-to-message.js

@@ -0,0 +1,119 @@
+import { AIMessage, AIMessageChunk, HumanMessage, SystemMessage, ToolMessage } from "@langchain/core/messages";
+//#region src/stream/assembled-to-message.ts
+/**
+* Convert the protocol-native {@link AssembledMessage} (a namespace +
+* content-block bag) into a class instance from
+* `@langchain/core/messages`.
+*
+* The v2 messages channel carries `role` on the `message-start`
+* event, but `MessageAssembler` drops it by the time it produces an
+* `AssembledMessage`. The selector-side caller therefore captures the
+* role separately (via the assembler's per-update hook, see
+* `projections/messages.ts`) and passes it in.
+*
+* The conversion is intentionally lossless in the limit: when the
+* message finishes we emit the same BaseMessage shape that a
+* `values.messages` entry would round-trip to via
+* {@link tryCoerceMessageLikeToMessage}. Mid-stream, partial blocks
+* (e.g. tool_call_chunk) are folded into the same shape so the UI
+* can render an incrementally-completing message.
+*/
+/**
+* Produce a `BaseMessage` class instance from an in-progress or
+* finished assembled message. Safe to call repeatedly across deltas —
+* each call returns a new instance whose content reflects the
+* currently-observed blocks.
+*/
+function assembledToBaseMessage(input) {
+	const { id, role, blocks, toolCallId, usage } = input;
+	const content = extractContentString(blocks);
+	const toolCalls = extractToolCalls(blocks);
+	const toolCallChunks = extractToolCallChunks(blocks);
+	const additionalKwargs = usage != null ? { usage } : void 0;
+	switch (role) {
+		case "human": return new HumanMessage({
+			...id != null ? { id } : {},
+			content,
+			...additionalKwargs != null ? { additional_kwargs: additionalKwargs } : {}
+		});
+		case "system": return new SystemMessage({
+			...id != null ? { id } : {},
+			content,
+			...additionalKwargs != null ? { additional_kwargs: additionalKwargs } : {}
+		});
+		case "tool": return new ToolMessage({
+			...id != null ? { id } : {},
+			content,
+			tool_call_id: toolCallId ?? ""
+		});
+		default: {
+			const payload = {
+				...id != null ? { id } : {},
+				content,
+				...toolCalls.length > 0 ? { tool_calls: toolCalls } : {},
+				...toolCallChunks.length > 0 ? { tool_call_chunks: toolCallChunks } : {},
+				...additionalKwargs != null ? { additional_kwargs: additionalKwargs } : {}
+			};
+			return toolCallChunks.length > 0 ? new AIMessageChunk(payload) : new AIMessage(payload);
+		}
+	}
+}
+/**
+* Convenience: given the raw assembled message + the role captured
+* from `message-start`, produce a `BaseMessage` with the same id.
+*/
+function assembledMessageToBaseMessage(assembled, role, extras = {}) {
+	return assembledToBaseMessage({
+		id: assembled.id,
+		role,
+		blocks: assembled.blocks,
+		toolCallId: extras.toolCallId,
+		usage: assembled.usage
+	});
+}
+function extractContentString(blocks) {
+	let out = "";
+	for (const block of blocks) if (block.type === "text" && typeof block.text === "string") out += block.text;
+	return out;
+}
+function extractToolCalls(blocks) {
+	const out = [];
+	for (const block of blocks) {
+		if (block.type !== "tool_call" && block.type !== "tool_use") continue;
+		const tc = block;
+		out.push({
+			id: tc.id ?? "",
+			name: tc.name ?? "",
+			args: normalizeToolCallArgs(tc.args ?? tc.input),
+			type: "tool_call"
+		});
+	}
+	return out;
+}
+function extractToolCallChunks(blocks) {
+	const out = [];
+	for (const block of blocks) {
+		if (block.type !== "tool_call_chunk") continue;
+		const tc = block;
+		out.push({
+			id: tc.id,
+			name: tc.name,
+			args: tc.args,
+			index: tc.index,
+			type: "tool_call_chunk"
+		});
+	}
+	return out;
+}
+function normalizeToolCallArgs(value) {
+	if (value != null && typeof value === "object" && !Array.isArray(value)) return value;
+	if (typeof value === "string" && value.length > 0) try {
+		const parsed = JSON.parse(value);
+		if (parsed != null && typeof parsed === "object" && !Array.isArray(parsed)) return parsed;
+	} catch {}
+	return {};
+}
+//#endregion
+export { assembledMessageToBaseMessage, assembledToBaseMessage };
+
+//# sourceMappingURL=assembled-to-message.js.map

package/dist/stream/assembled-to-message.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assembled-to-message.js","names":[],"sources":["../../src/stream/assembled-to-message.ts"],"sourcesContent":["/**\n * Convert the protocol-native {@link AssembledMessage} (a namespace +\n * content-block bag) into a class instance from\n * `@langchain/core/messages`.\n *\n * The v2 messages channel carries `role` on the `message-start`\n * event, but `MessageAssembler` drops it by the time it produces an\n * `AssembledMessage`. The selector-side caller therefore captures the\n * role separately (via the assembler's per-update hook, see\n * `projections/messages.ts`) and passes it in.\n *\n * The conversion is intentionally lossless in the limit: when the\n * message finishes we emit the same BaseMessage shape that a\n * `values.messages` entry would round-trip to via\n * {@link tryCoerceMessageLikeToMessage}. Mid-stream, partial blocks\n * (e.g. tool_call_chunk) are folded into the same shape so the UI\n * can render an incrementally-completing message.\n */\nimport {\n  AIMessage,\n  AIMessageChunk,\n  HumanMessage,\n  SystemMessage,\n  ToolMessage,\n  type BaseMessage,\n} from \"@langchain/core/messages\";\nimport type { ContentBlock, MessageRole, UsageInfo } from \"@langchain/protocol\";\nimport type { AssembledMessage } from \"../client/stream/messages.js\";\n\nexport type ExtendedMessageRole = MessageRole | \"tool\";\n\nexport interface AssembledToMessageInput {\n  /** Stable message id (from `MessageStartData.id`). */\n  id?: string;\n  /** Author role captured from the `message-start` event. */\n  role: ExtendedMessageRole;\n  /** Content blocks assembled so far. */\n  blocks: ContentBlock[];\n  /** Tool-call id a `role: \"tool\"` message is responding to, if any. */\n  toolCallId?: string;\n  /** Final-token usage (populated on `message-finish`). */\n  usage?: UsageInfo;\n}\n\n/**\n * Produce a `BaseMessage` class instance from an in-progress or\n * finished assembled message. Safe to call repeatedly across deltas —\n * each call returns a new instance whose content reflects the\n * currently-observed blocks.\n */\nexport function assembledToBaseMessage(\n  input: AssembledToMessageInput\n): BaseMessage {\n  const { id, role, blocks, toolCallId, usage } = input;\n  const content = extractContentString(blocks);\n  const toolCalls = extractToolCalls(blocks);\n  const toolCallChunks = extractToolCallChunks(blocks);\n  const additionalKwargs =\n    usage != null ? ({ usage } as Record<string, unknown>) : undefined;\n\n  switch (role) {\n    case \"human\":\n      return new HumanMessage({\n        ...(id != null ? { id } : {}),\n        content,\n        ...(additionalKwargs != null\n          ? { additional_kwargs: additionalKwargs }\n          : {}),\n      });\n    case \"system\":\n      return new SystemMessage({\n        ...(id != null ? { id } : {}),\n        content,\n        ...(additionalKwargs != null\n          ? { additional_kwargs: additionalKwargs }\n          : {}),\n      });\n    case \"tool\":\n      return new ToolMessage({\n        ...(id != null ? { id } : {}),\n        content,\n        tool_call_id: toolCallId ?? \"\",\n      });\n    case \"ai\":\n    default: {\n      // Use `AIMessageChunk` whenever tool_call_chunks are present —\n      // the concrete `AIMessage` class silently DROPS the\n      // `tool_call_chunks` field, which would leave mid-stream tool\n      // calls invisible to the UI (it sees an AI message with empty\n      // content and no tool calls, rendering a blank bubble until\n      // `content-block-finish` finally promotes the chunks to\n      // finalized `tool_calls`). The chunk class is assignment-compatible\n      // with `BaseMessage` and round-trips through the merge logic.\n      const payload = {\n        ...(id != null ? { id } : {}),\n        content,\n        ...(toolCalls.length > 0 ? { tool_calls: toolCalls } : {}),\n        ...(toolCallChunks.length > 0\n          ? { tool_call_chunks: toolCallChunks }\n          : {}),\n        ...(additionalKwargs != null\n          ? { additional_kwargs: additionalKwargs }\n          : {}),\n      };\n      return toolCallChunks.length > 0\n        ? new AIMessageChunk(payload)\n        : new AIMessage(payload);\n    }\n  }\n}\n\n/**\n * Convenience: given the raw assembled message + the role captured\n * from `message-start`, produce a `BaseMessage` with the same id.\n */\nexport function assembledMessageToBaseMessage(\n  assembled: AssembledMessage,\n  role: ExtendedMessageRole,\n  extras: { toolCallId?: string } = {}\n): BaseMessage {\n  return assembledToBaseMessage({\n    id: assembled.id,\n    role,\n    blocks: assembled.blocks,\n    toolCallId: extras.toolCallId,\n    usage: assembled.usage,\n  });\n}\n\n// ---------- helpers ----------\n\nfunction extractContentString(blocks: ContentBlock[]): string {\n  let out = \"\";\n  for (const block of blocks) {\n    if (\n      block.type === \"text\" &&\n      typeof (block as { text?: unknown }).text === \"string\"\n    ) {\n      out += (block as { text: string }).text;\n    }\n  }\n  return out;\n}\n\ninterface LooseToolCall {\n  id: string;\n  name: string;\n  args: Record<string, unknown>;\n  type: \"tool_call\";\n}\n\nfunction extractToolCalls(blocks: ContentBlock[]): LooseToolCall[] {\n  const out: LooseToolCall[] = [];\n  for (const block of blocks) {\n    if (block.type !== \"tool_call\" && block.type !== \"tool_use\") continue;\n    const tc = block as ToolCallLikeBlock;\n    out.push({\n      id: tc.id ?? \"\",\n      name: tc.name ?? \"\",\n      args: normalizeToolCallArgs(tc.args ?? tc.input),\n      type: \"tool_call\",\n    });\n  }\n  return out;\n}\n\ninterface ToolCallLikeBlock {\n  id?: string;\n  name?: string;\n  args?: unknown;\n  input?: unknown;\n}\n\ninterface LooseToolCallChunk {\n  id?: string;\n  name?: string;\n  args?: string;\n  index?: number;\n  type: \"tool_call_chunk\";\n}\n\nfunction extractToolCallChunks(blocks: ContentBlock[]): LooseToolCallChunk[] {\n  const out: LooseToolCallChunk[] = [];\n  for (const block of blocks) {\n    if (block.type !== \"tool_call_chunk\") continue;\n    const tc = block as {\n      id?: string;\n      name?: string;\n      args?: string;\n      index?: number;\n    };\n    out.push({\n      id: tc.id,\n      name: tc.name,\n      args: tc.args,\n      index: tc.index,\n      type: \"tool_call_chunk\",\n    });\n  }\n  return out;\n}\n\nfunction normalizeToolCallArgs(value: unknown): Record<string, unknown> {\n  if (value != null && typeof value === \"object\" && !Array.isArray(value)) {\n    return value as Record<string, unknown>;\n  }\n  if (typeof value === \"string\" && value.length > 0) {\n    try {\n      const parsed = JSON.parse(value);\n      if (\n        parsed != null &&\n        typeof parsed === \"object\" &&\n        !Array.isArray(parsed)\n      ) {\n        return parsed as Record<string, unknown>;\n      }\n    } catch {\n      // Partial streaming input is represented via tool_call_chunks.\n    }\n  }\n  return {};\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;AAkDA,SAAgB,uBACd,OACa;CACb,MAAM,EAAE,IAAI,MAAM,QAAQ,YAAY,UAAU;CAChD,MAAM,UAAU,qBAAqB,OAAO;CAC5C,MAAM,YAAY,iBAAiB,OAAO;CAC1C,MAAM,iBAAiB,sBAAsB,OAAO;CACpD,MAAM,mBACJ,SAAS,OAAQ,EAAE,OAAO,GAA+B,KAAA;AAE3D,SAAQ,MAAR;EACE,KAAK,QACH,QAAO,IAAI,aAAa;GACtB,GAAI,MAAM,OAAO,EAAE,IAAI,GAAG,EAAE;GAC5B;GACA,GAAI,oBAAoB,OACpB,EAAE,mBAAmB,kBAAkB,GACvC,EAAE;GACP,CAAC;EACJ,KAAK,SACH,QAAO,IAAI,cAAc;GACvB,GAAI,MAAM,OAAO,EAAE,IAAI,GAAG,EAAE;GAC5B;GACA,GAAI,oBAAoB,OACpB,EAAE,mBAAmB,kBAAkB,GACvC,EAAE;GACP,CAAC;EACJ,KAAK,OACH,QAAO,IAAI,YAAY;GACrB,GAAI,MAAM,OAAO,EAAE,IAAI,GAAG,EAAE;GAC5B;GACA,cAAc,cAAc;GAC7B,CAAC;EAEJ,SAAS;GASP,MAAM,UAAU;IACd,GAAI,MAAM,OAAO,EAAE,IAAI,GAAG,EAAE;IAC5B;IACA,GAAI,UAAU,SAAS,IAAI,EAAE,YAAY,WAAW,GAAG,EAAE;IACzD,GAAI,eAAe,SAAS,IACxB,EAAE,kBAAkB,gBAAgB,GACpC,EAAE;IACN,GAAI,oBAAoB,OACpB,EAAE,mBAAmB,kBAAkB,GACvC,EAAE;IACP;AACD,UAAO,eAAe,SAAS,IAC3B,IAAI,eAAe,QAAQ,GAC3B,IAAI,UAAU,QAAQ;;;;;;;;AAShC,SAAgB,8BACd,WACA,MACA,SAAkC,EAAE,EACvB;AACb,QAAO,uBAAuB;EAC5B,IAAI,UAAU;EACd;EACA,QAAQ,UAAU;EAClB,YAAY,OAAO;EACnB,OAAO,UAAU;EAClB,CAAC;;AAKJ,SAAS,qBAAqB,QAAgC;CAC5D,IAAI,MAAM;AACV,MAAK,MAAM,SAAS,OAClB,KACE,MAAM,SAAS,UACf,OAAQ,MAA6B,SAAS,SAE9C,QAAQ,MAA2B;AAGvC,QAAO;;AAUT,SAAS,iBAAiB,QAAyC;CACjE,MAAM,MAAuB,EAAE;AAC/B,MAAK,MAAM,SAAS,QAAQ;AAC1B,MAAI,MAAM,SAAS,eAAe,MAAM,SAAS,WAAY;EAC7D,MAAM,KAAK;AACX,MAAI,KAAK;GACP,IAAI,GAAG,MAAM;GACb,MAAM,GAAG,QAAQ;GACjB,MAAM,sBAAsB,GAAG,QAAQ,GAAG,MAAM;GAChD,MAAM;GACP,CAAC;;AAEJ,QAAO;;AAkBT,SAAS,sBAAsB,QAA8C;CAC3E,MAAM,MAA4B,EAAE;AACpC,MAAK,MAAM,SAAS,QAAQ;AAC1B,MAAI,MAAM,SAAS,kBAAmB;EACtC,MAAM,KAAK;AAMX,MAAI,KAAK;GACP,IAAI,GAAG;GACP,MAAM,GAAG;GACT,MAAM,GAAG;GACT,OAAO,GAAG;GACV,MAAM;GACP,CAAC;;AAEJ,QAAO;;AAGT,SAAS,sBAAsB,OAAyC;AACtE,KAAI,SAAS,QAAQ,OAAO,UAAU,YAAY,CAAC,MAAM,QAAQ,MAAM,CACrE,QAAO;AAET,KAAI,OAAO,UAAU,YAAY,MAAM,SAAS,EAC9C,KAAI;EACF,MAAM,SAAS,KAAK,MAAM,MAAM;AAChC,MACE,UAAU,QACV,OAAO,WAAW,YAClB,CAAC,MAAM,QAAQ,OAAO,CAEtB,QAAO;SAEH;AAIV,QAAO,EAAE"}

package/dist/stream/channel-registry.cjs

@@ -0,0 +1,224 @@
+const require_store = require("./store.cjs");
+//#region src/stream/channel-registry.ts
+/**
+* Framework-agnostic ref-counted subscription cache.
+*
+* # What this module is
+*
+* Every framework binding (React, Vue, Svelte, Angular) owns one
+* {@link ChannelRegistry} per {@link StreamController}. The registry
+* is the single layer that:
+*
+*   1. Deduplicates server-side subscriptions across components — N
+*      hooks reading the same projection share one
+*      `thread.subscribe(...)` call and one {@link StreamStore}.
+*   2. Lazily opens / tears down subscriptions in step with mounting
+*      and unmounting consumers (ref counting on `spec.key`).
+*   3. Survives thread swaps — `controller.hydrate(newThreadId)`
+*      rebinds every live entry against the new thread without
+*      changing store identity, so React's
+*      `useSyncExternalStore` (and equivalents in other frameworks)
+*      keep working.
+*
+* # Why ref counting matters
+*
+* Most projections back at least one server subscription. Without
+* deduplication, every additional consumer of e.g. `useMessages(sub)`
+* would open its own SSE/WebSocket subscription, paying the same
+* payload N times. The registry guarantees we only ever pay once per
+* `spec.key`, regardless of how many consumers attach.
+*
+* # Why store identity is preserved on rebind
+*
+* Framework reactivity primitives subscribe to a store *instance* and
+* memoise their last seen snapshot. If we minted a new store on every
+* thread swap, every bound component would silently lose its
+* subscription. Instead, the registry keeps the same {@link StreamStore}
+* but resets its value to `spec.initial` and re-runs `spec.open()` —
+* consumers observe a clean slate without re-subscribing.
+*
+* @see ProjectionSpec - The contract every projection implements.
+* @see StreamStore - The observable store handed to consumers.
+*/
+/**
+* Ref-counted, thread-aware projection registry.
+*
+* Owns the `spec.key → (store, runtime)` mapping for one
+* {@link StreamController}. Lifecycle:
+*
+*   - `acquire(spec)`  → +1 ref, returns `{ store, release }`. The
+*      first acquire opens the projection's runtime; subsequent
+*      acquires for the same key share both the store and the
+*      runtime.
+*   - `release()`      → -1 ref. When the last consumer releases,
+*      the entry is removed and its runtime disposed.
+*   - `bind(thread)`   → swap or detach the underlying thread; every
+*      live entry's runtime is recreated against the new thread,
+*      keeping the same store identity.
+*   - `dispose()`      → tear everything down (idempotent). Safe to
+*      call multiple times.
+*
+* The registry is intentionally not generic over a state shape —
+* different consumers can hold projections producing different
+* snapshot types, so the registry keys everything as `unknown` and
+* lets {@link acquire} reapply the caller's `T` at the boundary.
+*/
+var ChannelRegistry = class {
+	/** Currently bound thread, or `undefined` while detached. */
+	#thread;
+	/** Read-only fan-out of the controller's root subscription. */
+	#rootBus;
+	/** All live entries, keyed by `spec.key`. */
+	#entries = /* @__PURE__ */ new Map();
+	/**
+	* Construct a registry bound to the controller's root event bus.
+	*
+	* The bus is forwarded to every projection's `open()` so root-scoped
+	* projections can avoid opening a second server subscription when
+	* their channel set is already covered by the root pump.
+	*
+	* @param rootBus - Read-only fan-out of the root subscription.
+	*/
+	constructor(rootBus) {
+		this.#rootBus = rootBus;
+	}
+	/**
+	* Rebind every live entry to a new {@link ThreadStream} (or detach
+	* when `thread == null`).
+	*
+	* Each live entry has its current runtime disposed (best-effort)
+	* and its store reset to `entry.initial` so consumers see a clean
+	* slate during the swap. When `thread != null`, a fresh runtime is
+	* opened against the new thread.
+	*
+	* Critically the {@link StreamStore} *instance* is preserved across
+	* the rebind: framework subscribers (e.g. React's
+	* `useSyncExternalStore`) keep observing the same store reference,
+	* so their subscriptions survive the swap.
+	*
+	* No-op when called with the currently bound thread.
+	*
+	* @param thread - The thread stream to bind, or `undefined` to detach.
+	*/
+	bind(thread) {
+		if (this.#thread === thread) return;
+		const previous = this.#thread;
+		this.#thread = thread;
+		for (const entry of this.#entries.values()) {
+			if (entry.runtime != null && previous != null) tryDispose(entry.runtime);
+			entry.runtime = void 0;
+			entry.store.setValue(entry.initial);
+			if (thread != null) entry.runtime = entry.open({
+				thread,
+				store: entry.store,
+				rootBus: this.#rootBus
+			});
+		}
+	}
+	/** Currently bound thread (may be `undefined` pre-mount). */
+	get thread() {
+		return this.#thread;
+	}
+	/**
+	* Acquire a ref-counted projection.
+	*
+	* If no entry exists for `spec.key`, one is created (allocating a
+	* {@link StreamStore} seeded with `spec.initial`) and — when a
+	* thread is currently bound — its runtime is opened immediately.
+	* If an entry already exists, its ref count is incremented and the
+	* existing store is returned.
+	*
+	* The returned `release()` is idempotent: calling it more than once
+	* is a no-op. When the ref count drops to zero, the entry is removed
+	* and its runtime disposed (best-effort, never throws into callers).
+	*
+	* Safe to call from any framework lifecycle hook. Subsequent calls
+	* for the same `spec.key` always return the same `store` reference
+	* for the lifetime of the controller, so consumers can rely on store
+	* identity.
+	*
+	* @typeParam T - Snapshot type produced by this projection.
+	* @param spec - Projection contract; the registry keys off `spec.key`.
+	* @returns A `{ store, release }` handle.
+	*/
+	acquire(spec) {
+		let entry = this.#entries.get(spec.key);
+		if (entry == null) {
+			const store = new require_store.StreamStore(spec.initial);
+			const newEntry = {
+				key: spec.key,
+				store,
+				initial: spec.initial,
+				open: spec.open,
+				refCount: 0,
+				runtime: void 0
+			};
+			if (this.#thread != null) newEntry.runtime = spec.open({
+				thread: this.#thread,
+				store,
+				rootBus: this.#rootBus
+			});
+			this.#entries.set(spec.key, newEntry);
+			entry = newEntry;
+		}
+		entry.refCount += 1;
+		let released = false;
+		return {
+			store: entry.store,
+			release: () => {
+				if (released) return;
+				released = true;
+				const current = this.#entries.get(spec.key);
+				if (current == null) return;
+				current.refCount -= 1;
+				if (current.refCount <= 0) {
+					this.#entries.delete(spec.key);
+					if (current.runtime != null) tryDispose(current.runtime);
+				}
+			}
+		};
+	}
+	/**
+	* Tear everything down.
+	*
+	* Detaches the bound thread (so no further `bind()` calls reopen
+	* runtimes) and disposes every live runtime in parallel. Safe to
+	* call multiple times — subsequent calls find an empty registry
+	* and resolve immediately.
+	*/
+	async dispose() {
+		this.#thread = void 0;
+		const entries = [...this.#entries.values()];
+		this.#entries.clear();
+		await Promise.all(entries.map(async (entry) => {
+			if (entry.runtime != null) await tryDispose(entry.runtime);
+		}));
+	}
+	/**
+	* Number of live entries. Diagnostic-only — callers should not
+	* branch on this value at runtime; it exists for tests asserting
+	* that consumers properly release their projections.
+	*/
+	get size() {
+		return this.#entries.size;
+	}
+};
+/**
+* Best-effort runtime disposal.
+*
+* `dispose()` should never throw, but a misbehaving projection should
+* not be able to wedge the entire registry. We swallow disposal
+* errors so the surrounding `bind()` / `release()` / `dispose()`
+* paths always make progress.
+*
+* @param runtime - Runtime returned by {@link ProjectionSpec.open}.
+*/
+async function tryDispose(runtime) {
+	try {
+		await runtime.dispose();
+	} catch {}
+}
+//#endregion
+exports.ChannelRegistry = ChannelRegistry;
+
+//# sourceMappingURL=channel-registry.cjs.map

package/dist/stream/channel-registry.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel-registry.cjs","names":["#rootBus","#entries","#thread","StreamStore"],"sources":["../../src/stream/channel-registry.ts"],"sourcesContent":["/**\n * Framework-agnostic ref-counted subscription cache.\n *\n * # What this module is\n *\n * Every framework binding (React, Vue, Svelte, Angular) owns one\n * {@link ChannelRegistry} per {@link StreamController}. The registry\n * is the single layer that:\n *\n *   1. Deduplicates server-side subscriptions across components — N\n *      hooks reading the same projection share one\n *      `thread.subscribe(...)` call and one {@link StreamStore}.\n *   2. Lazily opens / tears down subscriptions in step with mounting\n *      and unmounting consumers (ref counting on `spec.key`).\n *   3. Survives thread swaps — `controller.hydrate(newThreadId)`\n *      rebinds every live entry against the new thread without\n *      changing store identity, so React's\n *      `useSyncExternalStore` (and equivalents in other frameworks)\n *      keep working.\n *\n * # Why ref counting matters\n *\n * Most projections back at least one server subscription. Without\n * deduplication, every additional consumer of e.g. `useMessages(sub)`\n * would open its own SSE/WebSocket subscription, paying the same\n * payload N times. The registry guarantees we only ever pay once per\n * `spec.key`, regardless of how many consumers attach.\n *\n * # Why store identity is preserved on rebind\n *\n * Framework reactivity primitives subscribe to a store *instance* and\n * memoise their last seen snapshot. If we minted a new store on every\n * thread swap, every bound component would silently lose its\n * subscription. Instead, the registry keeps the same {@link StreamStore}\n * but resets its value to `spec.initial` and re-runs `spec.open()` —\n * consumers observe a clean slate without re-subscribing.\n *\n * @see ProjectionSpec - The contract every projection implements.\n * @see StreamStore - The observable store handed to consumers.\n */\nimport { StreamStore } from \"./store.js\";\nimport type {\n  AcquiredProjection,\n  ProjectionRuntime,\n  ProjectionSpec,\n  RootEventBus,\n  ThreadStream,\n} from \"./types.js\";\n\n/**\n * Internal record kept for each unique `spec.key` actively held by at\n * least one consumer.\n *\n * We intentionally store `initial` and `open` separately from `spec`\n * so the registry never depends on the spec object's identity — two\n * specs sharing the same `key` but produced from different factory\n * calls (e.g. fresh objects on each render) still collapse onto the\n * same entry.\n */\ninterface Entry {\n  /** Stable identity used for deduplication. */\n  readonly key: string;\n  /** Observable store handed back to every consumer of this key. */\n  readonly store: StreamStore<unknown>;\n  /** Initial snapshot reapplied on dispose / thread rebind. */\n  readonly initial: unknown;\n  /** Factory that opens the underlying subscription against a thread. */\n  readonly open: ProjectionSpec<unknown>[\"open\"];\n  /** Live consumers of this entry. Drops to 0 → entry is torn down. */\n  refCount: number;\n  /**\n   * Active runtime returned by `open()`. Undefined while detached\n   * (no thread bound yet, or a rebind is in progress).\n   */\n  runtime: ProjectionRuntime | undefined;\n}\n\n/**\n * Ref-counted, thread-aware projection registry.\n *\n * Owns the `spec.key → (store, runtime)` mapping for one\n * {@link StreamController}. Lifecycle:\n *\n *   - `acquire(spec)`  → +1 ref, returns `{ store, release }`. The\n *      first acquire opens the projection's runtime; subsequent\n *      acquires for the same key share both the store and the\n *      runtime.\n *   - `release()`      → -1 ref. When the last consumer releases,\n *      the entry is removed and its runtime disposed.\n *   - `bind(thread)`   → swap or detach the underlying thread; every\n *      live entry's runtime is recreated against the new thread,\n *      keeping the same store identity.\n *   - `dispose()`      → tear everything down (idempotent). Safe to\n *      call multiple times.\n *\n * The registry is intentionally not generic over a state shape —\n * different consumers can hold projections producing different\n * snapshot types, so the registry keys everything as `unknown` and\n * lets {@link acquire} reapply the caller's `T` at the boundary.\n */\nexport class ChannelRegistry {\n  /** Currently bound thread, or `undefined` while detached. */\n  #thread: ThreadStream | undefined;\n\n  /** Read-only fan-out of the controller's root subscription. */\n  readonly #rootBus: RootEventBus;\n\n  /** All live entries, keyed by `spec.key`. */\n  readonly #entries = new Map<string, Entry>();\n\n  /**\n   * Construct a registry bound to the controller's root event bus.\n   *\n   * The bus is forwarded to every projection's `open()` so root-scoped\n   * projections can avoid opening a second server subscription when\n   * their channel set is already covered by the root pump.\n   *\n   * @param rootBus - Read-only fan-out of the root subscription.\n   */\n  constructor(rootBus: RootEventBus) {\n    this.#rootBus = rootBus;\n  }\n\n  /**\n   * Rebind every live entry to a new {@link ThreadStream} (or detach\n   * when `thread == null`).\n   *\n   * Each live entry has its current runtime disposed (best-effort)\n   * and its store reset to `entry.initial` so consumers see a clean\n   * slate during the swap. When `thread != null`, a fresh runtime is\n   * opened against the new thread.\n   *\n   * Critically the {@link StreamStore} *instance* is preserved across\n   * the rebind: framework subscribers (e.g. React's\n   * `useSyncExternalStore`) keep observing the same store reference,\n   * so their subscriptions survive the swap.\n   *\n   * No-op when called with the currently bound thread.\n   *\n   * @param thread - The thread stream to bind, or `undefined` to detach.\n   */\n  bind(thread: ThreadStream | undefined): void {\n    if (this.#thread === thread) return;\n    const previous = this.#thread;\n    this.#thread = thread;\n    for (const entry of this.#entries.values()) {\n      // Tear down any active runtime from the previous thread.\n      if (entry.runtime != null && previous != null) {\n        void tryDispose(entry.runtime);\n      }\n      entry.runtime = undefined;\n      entry.store.setValue(entry.initial);\n      if (thread != null) {\n        entry.runtime = entry.open({\n          thread,\n          store: entry.store,\n          rootBus: this.#rootBus,\n        });\n      }\n    }\n  }\n\n  /** Currently bound thread (may be `undefined` pre-mount). */\n  get thread(): ThreadStream | undefined {\n    return this.#thread;\n  }\n\n  /**\n   * Acquire a ref-counted projection.\n   *\n   * If no entry exists for `spec.key`, one is created (allocating a\n   * {@link StreamStore} seeded with `spec.initial`) and — when a\n   * thread is currently bound — its runtime is opened immediately.\n   * If an entry already exists, its ref count is incremented and the\n   * existing store is returned.\n   *\n   * The returned `release()` is idempotent: calling it more than once\n   * is a no-op. When the ref count drops to zero, the entry is removed\n   * and its runtime disposed (best-effort, never throws into callers).\n   *\n   * Safe to call from any framework lifecycle hook. Subsequent calls\n   * for the same `spec.key` always return the same `store` reference\n   * for the lifetime of the controller, so consumers can rely on store\n   * identity.\n   *\n   * @typeParam T - Snapshot type produced by this projection.\n   * @param spec - Projection contract; the registry keys off `spec.key`.\n   * @returns A `{ store, release }` handle.\n   */\n  acquire<T>(spec: ProjectionSpec<T>): AcquiredProjection<T> {\n    let entry = this.#entries.get(spec.key);\n    if (entry == null) {\n      const store = new StreamStore<T>(spec.initial);\n      const newEntry: Entry = {\n        key: spec.key,\n        store: store as StreamStore<unknown>,\n        initial: spec.initial as unknown,\n        open: spec.open as ProjectionSpec<unknown>[\"open\"],\n        refCount: 0,\n        runtime: undefined,\n      };\n      // Open the runtime immediately when a thread is already bound.\n      // Otherwise it will be opened lazily by the next `bind()` call.\n      if (this.#thread != null) {\n        newEntry.runtime = spec.open({\n          thread: this.#thread,\n          store,\n          rootBus: this.#rootBus,\n        });\n      }\n      this.#entries.set(spec.key, newEntry);\n      entry = newEntry;\n    }\n    entry.refCount += 1;\n\n    let released = false;\n    return {\n      store: entry.store as StreamStore<T>,\n      release: () => {\n        if (released) return;\n        released = true;\n        const current = this.#entries.get(spec.key);\n        if (current == null) return;\n        current.refCount -= 1;\n        if (current.refCount <= 0) {\n          this.#entries.delete(spec.key);\n          if (current.runtime != null) void tryDispose(current.runtime);\n        }\n      },\n    };\n  }\n\n  /**\n   * Tear everything down.\n   *\n   * Detaches the bound thread (so no further `bind()` calls reopen\n   * runtimes) and disposes every live runtime in parallel. Safe to\n   * call multiple times — subsequent calls find an empty registry\n   * and resolve immediately.\n   */\n  async dispose(): Promise<void> {\n    this.#thread = undefined;\n    const entries = [...this.#entries.values()];\n    this.#entries.clear();\n    await Promise.all(\n      entries.map(async (entry) => {\n        if (entry.runtime != null) await tryDispose(entry.runtime);\n      })\n    );\n  }\n\n  /**\n   * Number of live entries. Diagnostic-only — callers should not\n   * branch on this value at runtime; it exists for tests asserting\n   * that consumers properly release their projections.\n   */\n  get size(): number {\n    return this.#entries.size;\n  }\n}\n\n/**\n * Best-effort runtime disposal.\n *\n * `dispose()` should never throw, but a misbehaving projection should\n * not be able to wedge the entire registry. We swallow disposal\n * errors so the surrounding `bind()` / `release()` / `dispose()`\n * paths always make progress.\n *\n * @param runtime - Runtime returned by {@link ProjectionSpec.open}.\n */\nasync function tryDispose(runtime: ProjectionRuntime): Promise<void> {\n  try {\n    await runtime.dispose();\n  } catch {\n    // Best-effort — dispose should never throw, but we don't want a\n    // bad projection to wedge the registry.\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoGA,IAAa,kBAAb,MAA6B;;CAE3B;;CAGA;;CAGA,2BAAoB,IAAI,KAAoB;;;;;;;;;;CAW5C,YAAY,SAAuB;AACjC,QAAA,UAAgB;;;;;;;;;;;;;;;;;;;;CAqBlB,KAAK,QAAwC;AAC3C,MAAI,MAAA,WAAiB,OAAQ;EAC7B,MAAM,WAAW,MAAA;AACjB,QAAA,SAAe;AACf,OAAK,MAAM,SAAS,MAAA,QAAc,QAAQ,EAAE;AAE1C,OAAI,MAAM,WAAW,QAAQ,YAAY,KAClC,YAAW,MAAM,QAAQ;AAEhC,SAAM,UAAU,KAAA;AAChB,SAAM,MAAM,SAAS,MAAM,QAAQ;AACnC,OAAI,UAAU,KACZ,OAAM,UAAU,MAAM,KAAK;IACzB;IACA,OAAO,MAAM;IACb,SAAS,MAAA;IACV,CAAC;;;;CAMR,IAAI,SAAmC;AACrC,SAAO,MAAA;;;;;;;;;;;;;;;;;;;;;;;;CAyBT,QAAW,MAAgD;EACzD,IAAI,QAAQ,MAAA,QAAc,IAAI,KAAK,IAAI;AACvC,MAAI,SAAS,MAAM;GACjB,MAAM,QAAQ,IAAIG,cAAAA,YAAe,KAAK,QAAQ;GAC9C,MAAM,WAAkB;IACtB,KAAK,KAAK;IACH;IACP,SAAS,KAAK;IACd,MAAM,KAAK;IACX,UAAU;IACV,SAAS,KAAA;IACV;AAGD,OAAI,MAAA,UAAgB,KAClB,UAAS,UAAU,KAAK,KAAK;IAC3B,QAAQ,MAAA;IACR;IACA,SAAS,MAAA;IACV,CAAC;AAEJ,SAAA,QAAc,IAAI,KAAK,KAAK,SAAS;AACrC,WAAQ;;AAEV,QAAM,YAAY;EAElB,IAAI,WAAW;AACf,SAAO;GACL,OAAO,MAAM;GACb,eAAe;AACb,QAAI,SAAU;AACd,eAAW;IACX,MAAM,UAAU,MAAA,QAAc,IAAI,KAAK,IAAI;AAC3C,QAAI,WAAW,KAAM;AACrB,YAAQ,YAAY;AACpB,QAAI,QAAQ,YAAY,GAAG;AACzB,WAAA,QAAc,OAAO,KAAK,IAAI;AAC9B,SAAI,QAAQ,WAAW,KAAW,YAAW,QAAQ,QAAQ;;;GAGlE;;;;;;;;;;CAWH,MAAM,UAAyB;AAC7B,QAAA,SAAe,KAAA;EACf,MAAM,UAAU,CAAC,GAAG,MAAA,QAAc,QAAQ,CAAC;AAC3C,QAAA,QAAc,OAAO;AACrB,QAAM,QAAQ,IACZ,QAAQ,IAAI,OAAO,UAAU;AAC3B,OAAI,MAAM,WAAW,KAAM,OAAM,WAAW,MAAM,QAAQ;IAC1D,CACH;;;;;;;CAQH,IAAI,OAAe;AACjB,SAAO,MAAA,QAAc;;;;;;;;;;;;;AAczB,eAAe,WAAW,SAA2C;AACnE,KAAI;AACF,QAAM,QAAQ,SAAS;SACjB"}

package/dist/stream/channel-registry.d.cts

@@ -0,0 +1,102 @@
+import { ThreadStream } from "../client/stream/index.cjs";
+import { AcquiredProjection, ProjectionSpec, RootEventBus } from "./types.cjs";
+
+//#region src/stream/channel-registry.d.ts
+/**
+ * Ref-counted, thread-aware projection registry.
+ *
+ * Owns the `spec.key → (store, runtime)` mapping for one
+ * {@link StreamController}. Lifecycle:
+ *
+ *   - `acquire(spec)`  → +1 ref, returns `{ store, release }`. The
+ *      first acquire opens the projection's runtime; subsequent
+ *      acquires for the same key share both the store and the
+ *      runtime.
+ *   - `release()`      → -1 ref. When the last consumer releases,
+ *      the entry is removed and its runtime disposed.
+ *   - `bind(thread)`   → swap or detach the underlying thread; every
+ *      live entry's runtime is recreated against the new thread,
+ *      keeping the same store identity.
+ *   - `dispose()`      → tear everything down (idempotent). Safe to
+ *      call multiple times.
+ *
+ * The registry is intentionally not generic over a state shape —
+ * different consumers can hold projections producing different
+ * snapshot types, so the registry keys everything as `unknown` and
+ * lets {@link acquire} reapply the caller's `T` at the boundary.
+ */
+declare class ChannelRegistry {
+  #private;
+  /**
+   * Construct a registry bound to the controller's root event bus.
+   *
+   * The bus is forwarded to every projection's `open()` so root-scoped
+   * projections can avoid opening a second server subscription when
+   * their channel set is already covered by the root pump.
+   *
+   * @param rootBus - Read-only fan-out of the root subscription.
+   */
+  constructor(rootBus: RootEventBus);
+  /**
+   * Rebind every live entry to a new {@link ThreadStream} (or detach
+   * when `thread == null`).
+   *
+   * Each live entry has its current runtime disposed (best-effort)
+   * and its store reset to `entry.initial` so consumers see a clean
+   * slate during the swap. When `thread != null`, a fresh runtime is
+   * opened against the new thread.
+   *
+   * Critically the {@link StreamStore} *instance* is preserved across
+   * the rebind: framework subscribers (e.g. React's
+   * `useSyncExternalStore`) keep observing the same store reference,
+   * so their subscriptions survive the swap.
+   *
+   * No-op when called with the currently bound thread.
+   *
+   * @param thread - The thread stream to bind, or `undefined` to detach.
+   */
+  bind(thread: ThreadStream | undefined): void;
+  /** Currently bound thread (may be `undefined` pre-mount). */
+  get thread(): ThreadStream | undefined;
+  /**
+   * Acquire a ref-counted projection.
+   *
+   * If no entry exists for `spec.key`, one is created (allocating a
+   * {@link StreamStore} seeded with `spec.initial`) and — when a
+   * thread is currently bound — its runtime is opened immediately.
+   * If an entry already exists, its ref count is incremented and the
+   * existing store is returned.
+   *
+   * The returned `release()` is idempotent: calling it more than once
+   * is a no-op. When the ref count drops to zero, the entry is removed
+   * and its runtime disposed (best-effort, never throws into callers).
+   *
+   * Safe to call from any framework lifecycle hook. Subsequent calls
+   * for the same `spec.key` always return the same `store` reference
+   * for the lifetime of the controller, so consumers can rely on store
+   * identity.
+   *
+   * @typeParam T - Snapshot type produced by this projection.
+   * @param spec - Projection contract; the registry keys off `spec.key`.
+   * @returns A `{ store, release }` handle.
+   */
+  acquire<T>(spec: ProjectionSpec<T>): AcquiredProjection<T>;
+  /**
+   * Tear everything down.
+   *
+   * Detaches the bound thread (so no further `bind()` calls reopen
+   * runtimes) and disposes every live runtime in parallel. Safe to
+   * call multiple times — subsequent calls find an empty registry
+   * and resolve immediately.
+   */
+  dispose(): Promise<void>;
+  /**
+   * Number of live entries. Diagnostic-only — callers should not
+   * branch on this value at runtime; it exists for tests asserting
+   * that consumers properly release their projections.
+   */
+  get size(): number;
+}
+//#endregion
+export { ChannelRegistry };
+//# sourceMappingURL=channel-registry.d.cts.map

package/dist/stream/channel-registry.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel-registry.d.cts","names":[],"sources":["../../src/stream/channel-registry.ts"],"mappings":";;;;;;;AAoGA;;;;;;;;;;;;;;;;;;;;cAAa,eAAA;EAAA;EAyFX;;;;;;;;;EAtEA,WAAA,CAAY,OAAA,EAAS,YAAA;EAyIb;;;;;;;;;;;;;;;;;;EAnHR,IAAA,CAAK,MAAA,EAAQ,YAAA;;MAsBT,MAAA,CAAA,GAAU,YAAA;;;;;;;;;;;;;;;;;;;;;;;EA0Bd,OAAA,GAAA,CAAW,IAAA,EAAM,cAAA,CAAe,CAAA,IAAK,kBAAA,CAAmB,CAAA;;;;;;;;;EAmDlD,OAAA,CAAA,GAAW,OAAA;;;;;;MAgBb,IAAA,CAAA;AAAA"}

package/dist/stream/channel-registry.d.ts

@@ -0,0 +1,102 @@
+import { ThreadStream } from "../client/stream/index.js";
+import { AcquiredProjection, ProjectionSpec, RootEventBus } from "./types.js";
+
+//#region src/stream/channel-registry.d.ts
+/**
+ * Ref-counted, thread-aware projection registry.
+ *
+ * Owns the `spec.key → (store, runtime)` mapping for one
+ * {@link StreamController}. Lifecycle:
+ *
+ *   - `acquire(spec)`  → +1 ref, returns `{ store, release }`. The
+ *      first acquire opens the projection's runtime; subsequent
+ *      acquires for the same key share both the store and the
+ *      runtime.
+ *   - `release()`      → -1 ref. When the last consumer releases,
+ *      the entry is removed and its runtime disposed.
+ *   - `bind(thread)`   → swap or detach the underlying thread; every
+ *      live entry's runtime is recreated against the new thread,
+ *      keeping the same store identity.
+ *   - `dispose()`      → tear everything down (idempotent). Safe to
+ *      call multiple times.
+ *
+ * The registry is intentionally not generic over a state shape —
+ * different consumers can hold projections producing different
+ * snapshot types, so the registry keys everything as `unknown` and
+ * lets {@link acquire} reapply the caller's `T` at the boundary.
+ */
+declare class ChannelRegistry {
+  #private;
+  /**
+   * Construct a registry bound to the controller's root event bus.
+   *
+   * The bus is forwarded to every projection's `open()` so root-scoped
+   * projections can avoid opening a second server subscription when
+   * their channel set is already covered by the root pump.
+   *
+   * @param rootBus - Read-only fan-out of the root subscription.
+   */
+  constructor(rootBus: RootEventBus);
+  /**
+   * Rebind every live entry to a new {@link ThreadStream} (or detach
+   * when `thread == null`).
+   *
+   * Each live entry has its current runtime disposed (best-effort)
+   * and its store reset to `entry.initial` so consumers see a clean
+   * slate during the swap. When `thread != null`, a fresh runtime is
+   * opened against the new thread.
+   *
+   * Critically the {@link StreamStore} *instance* is preserved across
+   * the rebind: framework subscribers (e.g. React's
+   * `useSyncExternalStore`) keep observing the same store reference,
+   * so their subscriptions survive the swap.
+   *
+   * No-op when called with the currently bound thread.
+   *
+   * @param thread - The thread stream to bind, or `undefined` to detach.
+   */
+  bind(thread: ThreadStream | undefined): void;
+  /** Currently bound thread (may be `undefined` pre-mount). */
+  get thread(): ThreadStream | undefined;
+  /**
+   * Acquire a ref-counted projection.
+   *
+   * If no entry exists for `spec.key`, one is created (allocating a
+   * {@link StreamStore} seeded with `spec.initial`) and — when a
+   * thread is currently bound — its runtime is opened immediately.
+   * If an entry already exists, its ref count is incremented and the
+   * existing store is returned.
+   *
+   * The returned `release()` is idempotent: calling it more than once
+   * is a no-op. When the ref count drops to zero, the entry is removed
+   * and its runtime disposed (best-effort, never throws into callers).
+   *
+   * Safe to call from any framework lifecycle hook. Subsequent calls
+   * for the same `spec.key` always return the same `store` reference
+   * for the lifetime of the controller, so consumers can rely on store
+   * identity.
+   *
+   * @typeParam T - Snapshot type produced by this projection.
+   * @param spec - Projection contract; the registry keys off `spec.key`.
+   * @returns A `{ store, release }` handle.
+   */
+  acquire<T>(spec: ProjectionSpec<T>): AcquiredProjection<T>;
+  /**
+   * Tear everything down.
+   *
+   * Detaches the bound thread (so no further `bind()` calls reopen
+   * runtimes) and disposes every live runtime in parallel. Safe to
+   * call multiple times — subsequent calls find an empty registry
+   * and resolve immediately.
+   */
+  dispose(): Promise<void>;
+  /**
+   * Number of live entries. Diagnostic-only — callers should not
+   * branch on this value at runtime; it exists for tests asserting
+   * that consumers properly release their projections.
+   */
+  get size(): number;
+}
+//#endregion
+export { ChannelRegistry };
+//# sourceMappingURL=channel-registry.d.ts.map

package/dist/stream/channel-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel-registry.d.ts","names":[],"sources":["../../src/stream/channel-registry.ts"],"mappings":";;;;;;;AAoGA;;;;;;;;;;;;;;;;;;;;cAAa,eAAA;EAAA;EAyFX;;;;;;;;;EAtEA,WAAA,CAAY,OAAA,EAAS,YAAA;EAyIb;;;;;;;;;;;;;;;;;;EAnHR,IAAA,CAAK,MAAA,EAAQ,YAAA;;MAsBT,MAAA,CAAA,GAAU,YAAA;;;;;;;;;;;;;;;;;;;;;;;EA0Bd,OAAA,GAAA,CAAW,IAAA,EAAM,cAAA,CAAe,CAAA,IAAK,kBAAA,CAAmB,CAAA;;;;;;;;;EAmDlD,OAAA,CAAA,GAAW,OAAA;;;;;;MAgBb,IAAA,CAAA;AAAA"}