@langchain/langgraph/dist/stream/mux.d.ts

LangGraph

import { InterruptPayload, Namespace, ProtocolEvent, StreamTransformer } from "./types.js";
import { StreamChannel } from "./stream-channel.js";
import { STREAM_EVENTS_V3_MODES } from "./convert.js";

//#region src/stream/mux.d.ts
/**
 * Symbol key used by {@link StreamMux} to resolve the values promise on a
 * stream handle. Using a symbol keeps this off the public autocomplete surface.
 */
declare const RESOLVE_VALUES: unique symbol;
/**
 * Symbol key used by {@link StreamMux} to reject the values promise on a
 * stream handle. Using a symbol keeps this off the public autocomplete surface.
 */
declare const REJECT_VALUES: unique symbol;
/**
 * Minimal interface that {@link StreamMux} requires from stream handles
 * for lifecycle resolution. This avoids a direct dependency on
 * `GraphRunStream` / `SubgraphRunStream`.
 */
interface StreamHandle {
  [RESOLVE_VALUES](values: unknown): void;
  [REJECT_VALUES](err: unknown): void;
}
/**
 * A discovered subgraph namespace paired with its run stream handle.
 */
type SubgraphDiscovery = {
  ns: Namespace;
  stream: StreamHandle;
};
/**
 * Central event dispatcher that routes {@link ProtocolEvent}s through a
 * pipeline of {@link StreamTransformer}s, manages namespace discovery for
 * subgraph streams, and exposes async iteration over filtered event
 * sequences.
 *
 * One `StreamMux` instance exists per top-level
 * `streamEvents(..., { version: "v3" })` invocation.
 */
declare class StreamMux {
  #private;
  /** @internal All protocol events in arrival order (after reducer pipeline). */
  readonly _events: StreamChannel<ProtocolEvent>;
  /** @internal New-namespace discovery notifications. */
  readonly _discoveries: StreamChannel<SubgraphDiscovery>;
  /**
   * Associates a pre-existing stream handle with a namespace so that
   * {@link close} can resolve its values promise later.
   *
   * @param path - The namespace path to register.
   * @param stream - The run stream handle for that namespace.
   */
  register(path: Namespace, stream: StreamHandle): void;
  /**
   * Registers a transformer and replays all buffered events through it so
   * it catches up with events already processed by the mux.  When the event
   * log is empty (typical at construction time) the replay is a no-op.
   *
   * The transformer must already have been initialised (i.e. `init()` called
   * and any projection wired).  The sequence is:
   *
   *   1. Snapshot the current event log length.
   *   2. Append the transformer so future {@link push} calls reach it.
   *   3. Replay events `[0, snapshot)` through `process()`.
   *   4. If the mux is already closed, call `finalize()` (or `fail()`)
   *      immediately so the transformer's log/channel terminates cleanly.
   *
   * @param transformer - An already-initialised transformer to register.
   */
  addTransformer(transformer: StreamTransformer<unknown>): void;
  /**
   * Scans a transformer projection for streaming and final-value primitives.
   * Remote stream channels are wired to auto-forward to the protocol event
   * stream; local stream channels are tracked for lifecycle only.
   *
   * Two projection shapes are recognised:
   *
   *   - {@link StreamChannel} values — named channels forward each `push()`
   *     immediately as a `custom:<channelName>` protocol event. Unnamed
   *     channels remain in-process-only.
   *
   *   - `PromiseLike<unknown>` values — tracked as final-value
   *     projections and flushed on {@link close} as a single
   *     `custom:<key>` event, where `<key>` is the projection key.
   *     This mirrors the in-process `await run.extensions.<key>`
   *     ergonomics on remote clients via
   *     `await thread.extensions.<key>`.
   *
   * Plain values that are neither are ignored — they remain in-process-only,
   * matching prior behaviour.
   *
   * @param projection - The object returned by `transformer.init()`.
   */
  wireChannels(projection: Record<string, unknown>): void;
  /**
   * Distributes an event through the transformer pipeline, then appends it to
   * the main event log.
   *
   * Subgraph discovery (materializing a {@link StreamHandle} for each
   * newly observed top-level namespace) is handled by the
   * {@link createSubgraphDiscoveryTransformer} when installed, not here.
   *
   * @param ns - The namespace path that produced the event.
   * @param event - The protocol event to process and store.
   */
  push(ns: Namespace, event: ProtocolEvent): void;
  /**
   * Gracefully ends the stream: resolves values promises on all known
   * streams, finalizes every transformer, auto-closes streaming
   * channels, flushes any final-value projections as `custom:<name>`
   * events, and closes both event logs.
   *
   * When final-value projections are present, `_events.close()` is
   * deferred until every tracked projection promise has settled so
   * remote consumers observe the flushed values before their event
   * stream ends. Callers do not need to await — `close()` returns
   * synchronously and any downstream consumer iterating
   * {@link _events} naturally waits for the final events.
   */
  close(): void;
  /**
   * Propagates a failure to all transformers, channels, event logs, and
   * stream handles.
   *
   * @param err - The error that caused the run to fail.
   */
  fail(err: unknown): void;
  /**
   * Records that the run was interrupted, appending the supplied payloads
   * for later retrieval.
   *
   * @param interrupts - The interrupt payloads to store.
   */
  markInterrupted(interrupts: InterruptPayload[]): void;
  /**
   * Whether the run ended due to an interrupt.
   *
   * @returns `true` if {@link markInterrupted} was called.
   */
  get interrupted(): boolean;
  /**
   * All interrupt payloads collected during the run.
   *
   * @returns A readonly view of the accumulated interrupt payloads.
   */
  get interrupts(): readonly InterruptPayload[];
  /**
   * Returns an async iterator that yields only events whose namespace
   * starts with {@link path}.
   *
   * @param path - Namespace prefix to filter on.
   * @param startAt - Zero-based index into the event log to begin from.
   * @returns An async iterator over matching {@link ProtocolEvent}s.
   */
  subscribeEvents(path: Namespace, startAt?: number): AsyncIterator<ProtocolEvent>;
}
//#endregion
export { REJECT_VALUES, RESOLVE_VALUES, StreamHandle, StreamMux, SubgraphDiscovery };
//# sourceMappingURL=mux.d.ts.map