@graphrefly/graphrefly 0.45.0 → 0.46.0

package/dist/base/io/index.d.cts

@@ -0,0 +1,2245 @@
+import { Message, Node, NodeOptions } from '@graphrefly/pure-ts/core';
+import { SnapshotStorageTier } from '@graphrefly/pure-ts/extra/storage';
+import { GraphCheckpointRecord } from '@graphrefly/pure-ts/graph';
+import { E as EmitTriad, b as ExternalRegister } from '../../external-register-CWyroXb_.cjs';
+import { B as BackoffStrategy, a as BackoffPreset } from '../../backoff-Bnb9OoPh.cjs';
+import { AsyncSourceOpts } from '@graphrefly/pure-ts/extra';
+import { W as WithStatusBundle } from '../../status-U-rUI79b.cjs';
+import { r as retry } from '../../retry-DWuhjvsA.cjs';
+import '../../_internal-B23BagFd.cjs';
+
+/**
+ * {@link reactiveSink} — canonical sink factory for Wave 5 adapters.
+ *
+ * Every `to*` adapter in {@link ./adapters.ts} can be expressed as a thin
+ * config wrapper around this one factory. It centralizes:
+ *
+ * - **Transport boundary** — the sole place in the sink layer where a raw
+ *   Promise / `.then` / `.catch` sits (§5.10 boundary documented here).
+ * - **Retry** — delegates to {@link BackoffStrategy} from `backoff.ts`.
+ * - **Buffering** — `batchSize` / `flushIntervalMs` with tier-3 flush-on-
+ *   terminal per spec §5.11. Buffered mode activates when `sendBatch` is
+ *   supplied or a batching knob is set.
+ * - **Backpressure** — bounded internal queue with `drop-oldest` /
+ *   `drop-newest` / `error` strategies. The `"wait"` strategy is deferred
+ *   to external composition (`source | valve(...) | reactiveSink(...)`).
+ * - **Companions** — `sent` / `failed` / `inFlight` / `errors` (+ `buffered`
+ *   / `paused` when buffering or backpressure is active). These surface
+ *   every transport outcome as reactive nodes so downstream operators can
+ *   build retry fallbacks, dead-letter queues, or SLO gauges without
+ *   touching callback soup.
+ */
+
+/**
+ * Structured transport-failure record. Every sink routes both recoverable
+ * (pre-retry) and terminal (post-exhaustion) failures through this shape.
+ *
+ * @category extra
+ */
+type SinkTransportError = {
+    /**
+     * Failure stage. Known values: `"serialize"`, `"send"`, `"close"`,
+     * `"routing_key"`, `"ack"`, `"retry_exhausted"`. Open to extension for
+     * protocol-specific stages.
+     */
+    stage: string;
+    /** The error. */
+    error: Error;
+    /** Unwrapped DATA value (present for per-record failures). */
+    value: unknown;
+    /** Full message tuple (present for non-DATA stages like `"close"`). */
+    message?: Message;
+    /** Attempt number when `retry` is active — `1` = initial send. */
+    attempt?: number;
+};
+/**
+ * Terminal failure record delivered on the `failed` companion after retries
+ * are exhausted (or `shouldRetry` returned `false`).
+ *
+ * @category extra
+ */
+type SinkFailure<T> = {
+    value: T;
+    error: Error;
+    /** Total attempts made, including the initial send. */
+    attempts: number;
+};
+/**
+ * Handle returned by every Wave 5 sink.
+ *
+ * @category extra
+ */
+type ReactiveSinkHandle<T> = {
+    /** Unsubscribe from source, cancel timers, fire `TEARDOWN` on companions. */
+    dispose(): void;
+    /** Drain buffer + await in-flight sends (buffered mode only). */
+    flush?(): Promise<void>;
+    /** DATA values that successfully reached the transport. */
+    sent: Node<T>;
+    /** Values that permanently failed (after any retries). */
+    failed: Node<SinkFailure<T> | null>;
+    /** Number of pending transport operations. */
+    inFlight: Node<number>;
+    /** Every transient transport error (pre-retry). Latest-only. */
+    errors: Node<SinkTransportError | null>;
+    /** Items currently buffered (buffered mode / backpressure only). */
+    buffered?: Node<number>;
+    /** `true` when a backpressure strategy has dropped / rejected items. */
+    paused?: Node<boolean>;
+};
+/**
+ * Retry configuration for {@link reactiveSink}.
+ *
+ * @category extra
+ */
+type ReactiveSinkRetryOptions = {
+    /** Total attempts including the initial send. Default: `1` (no retry). */
+    maxAttempts?: number;
+    /** Backoff strategy (ns) or preset name. Default: `"exponential"` when `maxAttempts > 1`. */
+    backoff?: BackoffStrategy | BackoffPreset;
+    /** Predicate — return `false` to short-circuit retry for a given error. */
+    shouldRetry?: (err: Error, attempt: number) => boolean;
+};
+/**
+ * Backpressure configuration for {@link reactiveSink}. When omitted, the
+ * sink has no internal buffer cap beyond the natural `batchSize` /
+ * `flushIntervalMs` limits.
+ *
+ * @category extra
+ */
+type ReactiveSinkBackpressureOptions = {
+    /** Hard cap on buffered items; further items trigger `strategy`. Default: `Infinity`. */
+    maxBuffer?: number;
+    /** Policy when the buffer is full. Default: `"drop-oldest"`. */
+    strategy?: "drop-oldest" | "drop-newest" | "error";
+};
+/**
+ * Base options shared by every sink built on {@link reactiveSink}.
+ *
+ * @category extra
+ */
+type ReactiveSinkOptions<T> = {
+    /** Optional name used for companion node naming. */
+    name?: string;
+    /** Invoked synchronously for every transient transport error. */
+    onTransportError?: (err: SinkTransportError) => void;
+    /** Retry configuration. */
+    retry?: ReactiveSinkRetryOptions;
+    /** Backpressure configuration. */
+    backpressure?: ReactiveSinkBackpressureOptions;
+    /** Batch size before auto-flush (buffered mode). */
+    batchSize?: number;
+    /** Flush interval in ms; `0` = write-through (buffered mode). */
+    flushIntervalMs?: number;
+    /** Optional transform applied before `send` / `sendBatch`. */
+    serialize?: (value: T) => unknown;
+    /**
+     * Reactive stop signal — when this node emits any DATA or terminal, the
+     * sink tears down. Gives callers a reactive alternative to the imperative
+     * `handle.dispose()` call so teardown can be wired through the graph.
+     */
+    stopOn?: Node<unknown>;
+    /**
+     * Optional hook invoked for each upstream non-DATA message (COMPLETE /
+     * ERROR / etc.) observed by the sink. Used by adapters like
+     * {@link toWebSocket} to close the underlying resource when the source
+     * terminates, without the caller having to subscribe twice.
+     */
+    onUpstreamMessage?: (msg: Message) => void;
+    /**
+     * Invoked once during `dispose()` after the sink's own cleanup (unsub,
+     * final drain, TEARDOWN on companions). Adapters wrap external resources
+     * (socket listeners, file handles) by passing their cleanup here —
+     * avoids hand-rolling a wrapper around `handle.dispose`.
+     */
+    onDispose?: () => void;
+    /**
+     * Ignored — reserved for future parity with `source.pipe(...)` style.
+     *
+     * @internal
+     */
+    _reserved?: never;
+};
+/**
+ * Full config accepted by {@link reactiveSink}. One of `send` / `sendBatch`
+ * is required.
+ *
+ * @category extra
+ */
+type ReactiveSinkConfig<T, Ctx = unknown> = ReactiveSinkOptions<T> & {
+    /** Per-record transport call. */
+    send?: (value: T, ctx: Ctx) => Promise<void> | void;
+    /** Batched transport call. When supplied, buffering activates automatically. */
+    sendBatch?: (batch: T[], ctx: Ctx) => Promise<void> | void;
+    /** Context object threaded into every `send` / `sendBatch` call. */
+    ctx?: Ctx;
+};
+/**
+ * Build a reactive sink with retry / buffering / backpressure / observability
+ * companions. Every Wave 5 `to*` adapter is a thin config wrapper around
+ * this factory.
+ *
+ * **Modes:**
+ * - `send` only, no batching knobs → **per-record write-through**
+ * - `send` + `batchSize` or `flushIntervalMs` → **per-record buffered**
+ *   (buffer drains via repeated `send` calls — one-by-one in order)
+ * - `sendBatch` → **batched** (whole chunks handed to the transport)
+ *
+ * @category extra
+ */
+declare function reactiveSink<T, Ctx = unknown>(source: Node<T>, config: ReactiveSinkConfig<T, Ctx>): ReactiveSinkHandle<T>;
+
+/**
+ * Internal helpers shared by IO sub-files.
+ *
+ * - `ExtraOpts` / `sourceOpts` — common opts + the `describeKind: "producer"`
+ *   wrapper used by every producer-shaped IO source.
+ * - `SinkHandle` / `BufferedSinkHandle` — public sink handle shapes shared by
+ *   per-record and buffered sinks across multiple protocols.
+ * - `AdapterHandlers` / `AckableMessage` — alias of `EmitTriad` and the
+ *   manual-ack envelope used by Pulsar / RabbitMQ ingest sub-files.
+ * - `AttachStorageGraphLike` — duck-typed graph shape used by
+ *   `checkpointToS3` / `checkpointToRedis`.
+ */
+
+type ExtraOpts = Omit<NodeOptions, "describeKind">;
+/** Handle returned by per-record and buffered sinks. */
+type SinkHandle = {
+    /** Stop the sink (unsubscribe from source). */
+    dispose: () => void;
+    /** Reactive node that emits the latest transport error (or `null`). */
+    errors: Node<SinkTransportError | null>;
+    /** Manually drain the internal buffer (buffered sinks only). */
+    flush?: () => Promise<void>;
+};
+/** Handle returned by buffered sinks. `flush()` drains remaining buffer. */
+type BufferedSinkHandle = SinkHandle & {
+    /** Manually drain the internal buffer. */
+    flush: () => Promise<void>;
+};
+/** Standard handler triple for adapters that accept injected registrations. Alias of {@link EmitTriad}. */
+type AdapterHandlers<T> = EmitTriad<T>;
+/**
+ * Message envelope emitted by queue consumers when `autoAck: false`. The
+ * caller is responsible for calling `ack()` after successful processing or
+ * `nack()` to re-queue / dead-letter. Pairs cleanly with reactive pipelines:
+ *
+ * ```ts
+ * const messages$ = fromPulsar(consumer, { autoAck: false });
+ * effect([messages$], ([m]) => {
+ *   try {
+ *     process(m.value);
+ *     m.ack();
+ *   } catch (err) {
+ *     m.nack({ requeue: true });
+ *   }
+ * });
+ * ```
+ *
+ * Ack/nack are imperative callbacks (§5.10 boundary) because the underlying
+ * SDKs expose them as such. Reactive-all-the-way ack flows can be built by
+ * piping `msg.ack` calls into a `reactiveSink` if desired.
+ *
+ * **Caller contract — must settle every emitted message.** The envelope holds
+ * a closure reference to the raw SDK message; unsettled envelopes keep the
+ * broker's in-flight window full and leak memory proportional to consumer
+ * throughput. Patterns that drop messages (filter, take-first, switchMap
+ * discard) must explicitly `nack({ requeue: true })` the discarded ones, or
+ * wrap the source to force-settle on teardown.
+ *
+ * **Ack/nack transport failures.** Both methods route exceptions through
+ * the source's `onAckError` option (when provided) — SDK rejections from
+ * `acknowledge()`/`negativeAcknowledge()` don't escape as unhandled
+ * rejections. Default (no `onAckError`): swallow. The broker handles
+ * redelivery on its own timeline.
+ *
+ * @category extra
+ */
+type AckableMessage<T> = {
+    /** The wrapped message body. */
+    value: T;
+    /** Acknowledge successful processing. Safe to call more than once — idempotent. */
+    ack(): void;
+    /**
+     * Negative-acknowledge — signals the broker the message was not processed
+     * successfully. `requeue: true` asks the broker to redeliver; `requeue: false`
+     * may route to a dead-letter queue (SDK-specific). Omit `requeue` to
+     * defer to the SDK's own default.
+     */
+    nack(opts?: {
+        requeue?: boolean;
+    }): void;
+};
+/** Duck-typed graph shape consumed by `checkpointToS3` / `checkpointToRedis`. */
+type AttachStorageGraphLike = {
+    attachSnapshotStorage: (pairs: readonly {
+        snapshot: SnapshotStorageTier<GraphCheckpointRecord>;
+    }[], opts?: unknown) => {
+        dispose(): void;
+    };
+    name: string;
+};
+
+/**
+ * S3 object-storage sink IO — `toS3` buffers upstream `DATA` values and
+ * uploads them as NDJSON or JSON objects via the duck-typed
+ * {@link S3ClientLike}.
+ *
+ * `S3ClientLike` is also used by `checkpointToS3` (in `./checkpoint.ts`).
+ */
+
+/** Duck-typed S3 client (compatible with AWS SDK v3 `S3Client.send(PutObjectCommand(...))`). */
+type S3ClientLike = {
+    putObject(params: {
+        Bucket: string;
+        Key: string;
+        Body: string | Uint8Array;
+        ContentType?: string;
+    }): Promise<unknown>;
+};
+/** Options for {@link toS3}. */
+type ToS3Options<T> = ExtraOpts & {
+    /** Output format. Default: `"ndjson"`. */
+    format?: "ndjson" | "json";
+    /** Generate the S3 key for each batch. Receives `(seq, wallClockNs)`. Default: ISO timestamp + sequence. */
+    keyGenerator?: (seq: number, timestampNs: number) => string;
+    /** Batch size before auto-flush. Default: `1000`. */
+    batchSize?: number;
+    /** Flush interval in ms. Default: `10000`. */
+    flushIntervalMs?: number;
+    /** Transform value before serialization. Default: identity. */
+    transform?: (value: T) => unknown;
+    onTransportError?: (err: SinkTransportError) => void;
+};
+/**
+ * S3 object storage sink — buffers values and uploads as NDJSON or JSON objects.
+ *
+ * @param source - Upstream node.
+ * @param client - S3-compatible client with `putObject()`.
+ * @param bucket - S3 bucket name.
+ * @param opts - Format, key generation, batching options.
+ * @returns `BufferedSinkHandle`.
+ *
+ * @category extra
+ */
+declare function toS3<T>(source: Node<T>, client: S3ClientLike, bucket: string, opts?: ToS3Options<T>): ReactiveSinkHandle<T>;
+
+/**
+ * Graph checkpoint sinks — `checkpointToS3` and `checkpointToRedis` wire a
+ * graph's `attachSnapshotStorage` with an S3- or Redis-backed
+ * {@link SnapshotStorageTier}.
+ */
+
+/** Options for {@link checkpointToS3}. */
+type CheckpointToS3Options = {
+    /** S3 key prefix. Default: `"checkpoints/"`. */
+    prefix?: string;
+    /** Debounce ms on the S3 tier. Default: `500`. */
+    debounceMs?: number;
+    /** Full snapshot compaction interval. Default: `10`. */
+    compactEvery?: number;
+    onError?: (error: unknown) => void;
+};
+/**
+ * Wires `graph.attachSnapshotStorage()` with an S3-backed tier.
+ *
+ * @param graph - Graph instance to checkpoint.
+ * @param client - S3-compatible client with `putObject()`.
+ * @param bucket - S3 bucket name.
+ * @param opts - Key prefix, debounce, and compaction options.
+ * @returns Dispose handle.
+ *
+ * @category extra
+ */
+declare function checkpointToS3(graph: AttachStorageGraphLike, client: S3ClientLike, bucket: string, opts?: CheckpointToS3Options): {
+    dispose(): void;
+};
+/** Duck-typed Redis client for checkpoint storage. */
+type RedisCheckpointClientLike = {
+    set(key: string, value: string): Promise<unknown>;
+    get(key: string): Promise<string | null>;
+};
+/** Options for {@link checkpointToRedis}. */
+type CheckpointToRedisOptions = {
+    /** Key prefix. Default: `"graphrefly:checkpoint:"`. */
+    prefix?: string;
+    /** Debounce ms on the Redis tier. Default: `500`. */
+    debounceMs?: number;
+    /** Full snapshot compaction interval. Default: `10`. */
+    compactEvery?: number;
+    onError?: (error: unknown) => void;
+};
+/**
+ * Wires `graph.attachSnapshotStorage()` with a Redis-backed tier.
+ *
+ * @param graph - Graph instance to checkpoint.
+ * @param client - Redis client with `set()`/`get()`.
+ * @param opts - Key prefix, debounce, and compaction options.
+ * @returns Dispose handle.
+ *
+ * @category extra
+ */
+declare function checkpointToRedis(graph: AttachStorageGraphLike, client: RedisCheckpointClientLike, opts?: CheckpointToRedisOptions): {
+    dispose(): void;
+};
+
+/**
+ * ClickHouse live materialized view IO — `fromClickHouseWatch` polls a query
+ * via `fromTimer + switchMap` (reactive timer, switch semantics cancel
+ * in-flight queries) and emits one `DATA` per result row per scrape.
+ */
+
+/** Structured ClickHouse query result row. */
+type ClickHouseRow = Record<string, unknown>;
+/** Duck-typed ClickHouse client. */
+type ClickHouseClientLike = {
+    query(opts: {
+        query: string;
+        format?: string;
+    }): Promise<{
+        json<T = unknown>(): Promise<T[]>;
+    }>;
+};
+/** Options for {@link fromClickHouseWatch}. */
+type FromClickHouseWatchOptions = AsyncSourceOpts & {
+    /** Polling interval in nanoseconds. Default: `5 * NS_PER_SEC` (5s). */
+    intervalNs?: number;
+    /** JSON format to request. Default: `"JSONEachRow"`. */
+    format?: string;
+    /**
+     * Maximum consecutive query errors before terminating the source. Prevents
+     * error storms when the database is unavailable. Default: `5`. Set to
+     * `Infinity` to keep retrying indefinitely.
+     */
+    maxConsecutiveErrors?: number;
+};
+/**
+ * ClickHouse live materialized view as a reactive source.
+ *
+ * Polls a ClickHouse query on a reactive timer interval and emits new/changed rows.
+ * Uses a timer-driven approach (not busy-wait polling).
+ *
+ * @param client - ClickHouse client instance (caller owns connection).
+ * @param query - SQL query to execute on each interval.
+ * @param opts - Polling interval and format options.
+ * @returns `Node<ClickHouseRow>` — one `DATA` per result row per scrape.
+ *
+ * @example
+ * ```ts
+ * import { createClient } from "@clickhouse/client";
+ * import { fromClickHouseWatch } from "@graphrefly/graphrefly-ts";
+ *
+ * const client = createClient({ url: "http://localhost:8123" });
+ * const rows$ = fromClickHouseWatch(client, "SELECT * FROM errors_mv ORDER BY timestamp DESC LIMIT 100");
+ * ```
+ *
+ * @category extra
+ */
+declare function fromClickHouseWatch(client: ClickHouseClientLike, query: string, opts?: FromClickHouseWatchOptions): Node<ClickHouseRow>;
+
+/**
+ * CSV ingest IO — `fromCSV` reads an `AsyncIterable<string>` of CSV chunks
+ * (one node per row), and `csvRows` is the stateful operator variant for
+ * existing reactive `Node<string>` upstreams. Both share the local
+ * `parseCSVLine` helper so quoted fields and embedded delimiters are handled
+ * uniformly.
+ */
+
+/** Parsed CSV row. */
+type CSVRow = Record<string, string>;
+/** Options for {@link fromCSV}. */
+type FromCSVOptions = ExtraOpts & {
+    /** Column delimiter. Default: `","`. */
+    delimiter?: string;
+    /** Whether the first row is a header. Default: `true`. */
+    hasHeader?: boolean;
+    /** Explicit column names (overrides header row). */
+    columns?: string[];
+    /** Custom line parser (e.g. wrapping a library like `csv-parse`). Overrides built-in parser + delimiter. */
+    parseLine?: (line: string) => string[];
+};
+/**
+ * CSV file/stream ingest for batch replay.
+ *
+ * Reads a CSV from a `ReadableStream<string>` or an `AsyncIterable<string>` of lines,
+ * emitting one `DATA` per row. `COMPLETE` after all rows are emitted.
+ *
+ * @param source - Async iterable of CSV text chunks (lines or multi-line chunks).
+ * @param opts - Delimiter, header, and column options.
+ * @returns `Node<CSVRow>` — one `DATA` per parsed row.
+ *
+ * @example
+ * ```ts
+ * import { createReadStream } from "node:fs";
+ * import { fromCSV } from "@graphrefly/graphrefly-ts";
+ *
+ * const csv$ = fromCSV(createReadStream("data.csv", "utf-8"));
+ * ```
+ *
+ * @category extra
+ */
+declare function fromCSV(source: AsyncIterable<string>, opts?: FromCSVOptions): Node<CSVRow>;
+/**
+ * Stateful CSV parser operator — takes a `Node<string>` emitting raw text
+ * chunks (from any source: {@link fromAsyncIter}, {@link fromHTTPStream},
+ * WebSocket, file watcher, etc.) and emits one `DATA` per parsed row.
+ *
+ * Buffers incomplete lines across chunks. Mirrors {@link fromCSV}'s parsing
+ * logic without committing to an async-iterable-only input.
+ *
+ * @example
+ * ```ts
+ * import { fromHTTPStream, csvRows } from "@graphrefly/graphrefly-ts";
+ * const bytes$ = fromHTTPStream("https://example.com/data.csv");
+ * const text$ = decodeText(bytes$);   // caller-provided byte→string decoder
+ * const rows$ = csvRows(text$, { columns: ["name", "age"] });
+ * ```
+ *
+ * @category extra
+ */
+declare function csvRows(source: Node<string>, opts?: FromCSVOptions): Node<CSVRow>;
+
+/**
+ * Drizzle adapter (5.2b) — `fromDrizzle` runs `query.execute()` and emits one
+ * `DATA` containing the full mapped row array, then `COMPLETE`.
+ */
+
+/**
+ * Duck-typed Drizzle query builder result.
+ *
+ * Drizzle query builders (e.g. `db.select().from(users)`) expose `.execute()`
+ * which returns `Promise<T[]>`. This interface captures that contract without
+ * depending on `drizzle-orm`.
+ */
+type DrizzleQueryLike<T = unknown> = {
+    execute(): Promise<T[]>;
+};
+/** Options for {@link fromDrizzle}. */
+type FromDrizzleOptions<T, U = T> = ExtraOpts & {
+    /** Map each row to the desired shape. Default: identity cast. */
+    mapRow?: (row: T) => U;
+};
+/**
+ * One-shot Drizzle query as a reactive source.
+ *
+ * Calls `query.execute()`, emits one `DATA` per result row, then `COMPLETE`.
+ * Compose with `switchMap` + `fromTimer` for periodic re-query.
+ *
+ * @param query - Drizzle query builder (e.g. `db.select().from(users).where(...)`).
+ * @param opts - Row mapper and node options.
+ * @returns `Node<U>` — one `DATA` per row, then `COMPLETE`.
+ *
+ * @example
+ * ```ts
+ * import { drizzle } from "drizzle-orm/node-postgres";
+ * import { fromDrizzle } from "@graphrefly/graphrefly-ts";
+ *
+ * const db = drizzle(pool);
+ * const rows$ = fromDrizzle(db.select().from(users).where(eq(users.active, true)));
+ * ```
+ *
+ * @category extra
+ */
+declare function fromDrizzle<T = unknown, U = T>(query: DrizzleQueryLike<T>, opts?: FromDrizzleOptions<T, U>): Node<U[]>;
+
+/**
+ * HTTP IO — `fromHTTP` (one-shot fetch with `withStatus` companion bundle),
+ * `toHTTP` (per-record / buffered sink with retry support), `fromHTTPStream`
+ * (raw `Uint8Array` byte stream), `fromHTTPPoll` (interval-driven re-fetch).
+ *
+ * Uses the platform `fetch` API (Node 18+, browsers, Deno, Bun). Timeouts use
+ * `AbortController` driven by `setTimeout` per spec §5.10's resilience-operator
+ * carve-out.
+ */
+
+/**
+ * Options for {@link fromHTTP}.
+ *
+ * @category extra
+ */
+interface FromHTTPOptions extends AsyncSourceOpts {
+    /** HTTP method. Default: `"GET"`. */
+    method?: string;
+    /** Request headers. */
+    headers?: Record<string, string>;
+    /** Request body (for POST/PUT/PATCH). */
+    body?: any;
+    /** Transform the Response before emitting. Default: `response.json()`. */
+    transform?: (response: Response) => any | Promise<any>;
+    /** Request timeout in **nanoseconds**. Default: `30s` (30 * NS_PER_SEC). */
+    timeoutNs?: number;
+    /**
+     * When `true`, emit `COMPLETE` after the first successful fetch. Useful for
+     * one-shot semantics where downstream wants to know "no more values ever."
+     * Default: `false` — the node stays live and replays cached DATA to late
+     * subscribers via push-on-subscribe (spec §2.2).
+     */
+    completeAfterFetch?: boolean;
+    /**
+     * When `true`, trigger a fresh fetch on each new subscriber instead of
+     * sharing one cached result. Default: `false` — one shared fetch whose
+     * result is cached and replayed to every subscriber.
+     */
+    refetchOnSubscribe?: boolean;
+}
+/**
+ * Result of {@link fromHTTP}: main source plus status, error, and fetch count companions.
+ *
+ * @category extra
+ */
+type HTTPBundle<T> = WithStatusBundle<T> & {
+    /** Number of successful fetches. */
+    fetchCount: Node<number>;
+    /** Nanosecond wall-clock timestamp of the last successful fetch. */
+    lastUpdated: Node<number>;
+    /**
+     * `true` after at least one successful fetch; stays `true` across
+     * resubscribes. Orthogonal to {@link withStatus}'s `active`/`completed`
+     * lifecycle — use this as the "fetch done" signal under the default
+     * (cached, stays-live) behavior where `withStatus` never transitions to
+     * `"completed"` unless `completeAfterFetch: true` is set.
+     */
+    fetched: Node<boolean>;
+};
+/**
+ * Creates a one-shot fetch-based HTTP source with lifecycle tracking.
+ *
+ * @category extra
+ */
+declare function fromHTTP<T = any>(url: string, opts?: FromHTTPOptions): HTTPBundle<T>;
+/** Options for {@link toHTTP}. */
+type ToHTTPOptions<T> = ExtraOpts & {
+    /** HTTP method. Default: `"POST"`. */
+    method?: string;
+    /** Request headers applied to every call. Caller sets Content-Type. */
+    headers?: Record<string, string>;
+    /** Serialize a value to a request body. Default: `JSON.stringify`. */
+    serialize?: (value: T) => string | Uint8Array;
+    /** Optional request timeout in nanoseconds. */
+    timeoutNs?: number;
+    /**
+     * Format used when `batchSize` / `flushIntervalMs` is set:
+     * - `"json-array"` — body is `JSON.stringify(batch)`
+     * - `"ndjson"` — body is newline-delimited JSON.
+     * Default: `"json-array"`.
+     */
+    batchFormat?: "json-array" | "ndjson";
+    /** Batch size before auto-flush (buffered mode). */
+    batchSize?: number;
+    /** Flush interval in ms (buffered mode). */
+    flushIntervalMs?: number;
+    /** Retry configuration — same shape as {@link ReactiveSinkRetryOptions}. */
+    retry?: Parameters<typeof reactiveSink<T>>[1]["retry"];
+    onTransportError?: (err: SinkTransportError) => void;
+};
+/**
+ * HTTP sink — forwards upstream `DATA` values as HTTP requests.
+ *
+ * Per-record mode (default, no batching knobs): one request per DATA.
+ * Buffered mode (`batchSize` / `flushIntervalMs`): one request per chunk,
+ * body is JSON-array or NDJSON depending on `batchFormat`.
+ *
+ * @param source - Upstream node.
+ * @param url - Request URL.
+ * @param opts - Serialization, batching, retry options.
+ * @returns {@link ReactiveSinkHandle}.
+ *
+ * @category extra
+ */
+declare function toHTTP<T>(source: Node<T>, url: string, opts?: ToHTTPOptions<T>): ReactiveSinkHandle<T>;
+/** Options for {@link fromHTTPStream}. */
+type FromHTTPStreamOptions = ExtraOpts & {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: unknown;
+    signal?: AbortSignal;
+};
+/**
+ * Streaming HTTP source — emits each chunk from the response body as a
+ * `Uint8Array` `DATA`. `COMPLETE` when the stream ends; `ERROR` on non-ok
+ * response or fetch failure.
+ *
+ * Useful for ingesting server-push APIs (LLM streaming, SSE endpoints — pair
+ * with {@link fromSSE}, NDJSON endpoints — pair with {@link fromNDJSON}).
+ *
+ * @category extra
+ */
+declare function fromHTTPStream(url: string, opts?: FromHTTPStreamOptions): Node<Uint8Array>;
+/** Options for {@link fromHTTPPoll}. */
+type FromHTTPPollOptions = FromHTTPOptions & {
+    /** Poll interval in milliseconds. Default: `5000`. */
+    intervalMs?: number;
+};
+/**
+ * Repeatedly-fetching HTTP source — a reactive composition of
+ * {@link fromTimer} + {@link switchMap} + {@link fromHTTP} that fetches on an
+ * interval and emits the latest response. Previous in-flight fetches are
+ * cancelled when a new tick arrives (switch semantics).
+ *
+ * @example
+ * ```ts
+ * import { fromHTTPPoll } from "@graphrefly/graphrefly-ts";
+ * const health$ = fromHTTPPoll<{ ok: boolean }>("https://example.com/health", { intervalMs: 10_000 });
+ * ```
+ *
+ * @category extra
+ */
+declare function fromHTTPPoll<T = unknown>(url: string, opts?: FromHTTPPollOptions): Node<T>;
+
+/**
+ * Kafka IO — `fromKafka` (KafkaJS-compatible consumer source) and
+ * `toKafka` (producer sink). Compatible with Pulsar via KoP (Kafka-on-Pulsar).
+ */
+
+/** Duck-typed Kafka consumer (compatible with kafkajs, confluent-kafka, Pulsar KoP). */
+type KafkaConsumerLike = {
+    subscribe(opts: {
+        topic: string;
+        fromBeginning?: boolean;
+    }): Promise<void>;
+    run(opts: {
+        eachMessage: (payload: {
+            topic: string;
+            partition: number;
+            message: {
+                key: Buffer | null;
+                value: Buffer | null;
+                headers?: Record<string, Buffer | string | undefined>;
+                offset: string;
+                timestamp: string;
+            };
+        }) => Promise<void>;
+    }): Promise<void>;
+    disconnect(): Promise<void>;
+};
+/** Duck-typed Kafka producer. */
+type KafkaProducerLike = {
+    send(record: {
+        topic: string;
+        messages: Array<{
+            key?: string | Buffer | null;
+            value: string | Buffer | null;
+            headers?: Record<string, string | Buffer>;
+        }>;
+    }): Promise<void>;
+    disconnect(): Promise<void>;
+};
+/** Structured Kafka message. */
+type KafkaMessage<T = unknown> = {
+    topic: string;
+    partition: number;
+    key: string | null;
+    value: T;
+    headers: Record<string, string>;
+    offset: string;
+    timestamp: string;
+    timestampNs: number;
+};
+/** Options for {@link fromKafka}. */
+type FromKafkaOptions = ExtraOpts & {
+    /** Start from beginning of topic. Default: `false`. */
+    fromBeginning?: boolean;
+    /** Deserialize message value. Default: `JSON.parse(buffer.toString())`. */
+    deserialize?: (value: Buffer | null) => unknown;
+};
+/**
+ * Kafka consumer as a reactive source.
+ *
+ * Wraps a KafkaJS-compatible consumer. Each message becomes a `DATA` emission.
+ * Compatible with Pulsar via KoP (Kafka-on-Pulsar).
+ *
+ * @param consumer - KafkaJS-compatible consumer instance (caller owns connect/disconnect lifecycle).
+ * @param topic - Topic to consume from.
+ * @param opts - Deserialization and source options.
+ * @returns `Node<KafkaMessage<T>>` — one `DATA` per Kafka message.
+ *
+ * @example
+ * ```ts
+ * import { Kafka } from "kafkajs";
+ * import { fromKafka } from "@graphrefly/graphrefly-ts";
+ *
+ * const kafka = new Kafka({ brokers: ["localhost:9092"] });
+ * const consumer = kafka.consumer({ groupId: "my-group" });
+ * await consumer.connect();
+ *
+ * const events$ = fromKafka(consumer, "events", { deserialize: (buf) => JSON.parse(buf!.toString()) });
+ * ```
+ *
+ * @category extra
+ */
+declare function fromKafka<T = unknown>(consumer: KafkaConsumerLike, topic: string, opts?: FromKafkaOptions): Node<KafkaMessage<T>>;
+/** Options for {@link toKafka}. */
+type ToKafkaOptions<T> = ExtraOpts & {
+    /** Serialize value for Kafka. Default: `JSON.stringify`. */
+    serialize?: (value: T) => string | Buffer;
+    /** Extract message key from value. Default: `null` (no key). */
+    keyExtractor?: (value: T) => string | null;
+    /** Called on serialization or send failures. */
+    onTransportError?: (err: SinkTransportError) => void;
+};
+/**
+ * Kafka producer sink — forwards upstream `DATA` to a Kafka topic.
+ *
+ * @param source - Upstream node to forward.
+ * @param kafkaProducer - KafkaJS-compatible producer instance.
+ * @param topic - Target topic.
+ * @param opts - Serialization and key extraction options.
+ * @returns Unsubscribe function.
+ *
+ * @category extra
+ */
+declare function toKafka<T>(source: Node<T>, kafkaProducer: KafkaProducerLike, topic: string, opts?: ToKafkaOptions<T>): ReactiveSinkHandle<T>;
+
+/**
+ * Kysely adapter (5.2b) — `fromKysely` runs `query.execute()` and emits one
+ * `DATA` containing the full mapped row array, then `COMPLETE`.
+ */
+
+/**
+ * Duck-typed Kysely query builder result.
+ *
+ * Kysely query builders expose `.execute()` which returns `Promise<T[]>`.
+ * This interface captures that contract without depending on `kysely`.
+ */
+type KyselyQueryLike<T = unknown> = {
+    execute(): Promise<T[]>;
+};
+/** Options for {@link fromKysely}. */
+type FromKyselyOptions<T, U = T> = ExtraOpts & {
+    /** Map each row to the desired shape. Default: identity cast. */
+    mapRow?: (row: T) => U;
+};
+/**
+ * One-shot Kysely query as a reactive source.
+ *
+ * Calls `query.execute()`, emits one `DATA` per result row, then `COMPLETE`.
+ * Compose with `switchMap` + `fromTimer` for periodic re-query.
+ *
+ * @param query - Kysely query builder (e.g. `db.selectFrom("users").selectAll()`).
+ * @param opts - Row mapper and node options.
+ * @returns `Node<U>` — one `DATA` per row, then `COMPLETE`.
+ *
+ * @example
+ * ```ts
+ * import { Kysely, PostgresDialect } from "kysely";
+ * import { fromKysely } from "@graphrefly/graphrefly-ts";
+ *
+ * const db = new Kysely<DB>({ dialect: new PostgresDialect({ pool }) });
+ * const rows$ = fromKysely(db.selectFrom("users").selectAll().where("active", "=", true));
+ * ```
+ *
+ * @category extra
+ */
+declare function fromKysely<T = unknown, U = T>(query: KyselyQueryLike<T>, opts?: FromKyselyOptions<T, U>): Node<U[]>;
+
+/**
+ * MCP (Model Context Protocol) IO — `fromMCP` wraps an MCP client's
+ * notification surface as a reactive source via `externalProducer`.
+ */
+
+/**
+ * Duck-typed MCP (Model Context Protocol) client — only the notification
+ * registration surface is required so callers are not coupled to a specific SDK.
+ */
+type MCPClientLike = {
+    setNotificationHandler(method: string, handler: (notification: unknown) => void): void;
+};
+/** Options for {@link fromMCP}. */
+type FromMCPOptions = ExtraOpts & {
+    /** MCP notification method to subscribe to. Default `"notifications/message"`. */
+    method?: string;
+    onDisconnect?: (cb: (err?: unknown) => void) => void;
+};
+/**
+ * Wraps an MCP client's server-push notifications as a reactive source.
+ *
+ * @category extra
+ */
+declare function fromMCP<T = unknown>(client: MCPClientLike, opts?: FromMCPOptions): Node<T>;
+
+/**
+ * NATS IO — `fromNATS` (subject-subscription consumer source) and `toNATS`
+ * (publish sink). Compatible with `nats.js`-style clients.
+ */
+
+/** Duck-typed NATS subscription (compatible with nats.js). */
+type NATSSubscriptionLike = AsyncIterable<{
+    subject: string;
+    data: Uint8Array;
+    headers?: {
+        get(key: string): string;
+        keys(): string[];
+    };
+    reply?: string;
+    sid: number;
+}>;
+/** Duck-typed NATS client (compatible with nats.js). */
+type NATSClientLike = {
+    subscribe(subject: string, opts?: {
+        queue?: string;
+    }): NATSSubscriptionLike;
+    publish(subject: string, data?: Uint8Array, opts?: {
+        headers?: unknown;
+        reply?: string;
+    }): void;
+    drain(): Promise<void>;
+};
+/** Structured NATS message. */
+type NATSMessage<T = unknown> = {
+    subject: string;
+    data: T;
+    headers: Record<string, string>;
+    reply: string | undefined;
+    sid: number;
+    timestampNs: number;
+};
+/** Options for {@link fromNATS}. */
+type FromNATSOptions = ExtraOpts & {
+    /** Queue group name for load balancing. */
+    queue?: string;
+    /** Deserialize message data. Default: `JSON.parse(textDecoder.decode(data))`. */
+    deserialize?: (data: Uint8Array) => unknown;
+};
+/**
+ * NATS consumer as a reactive source.
+ *
+ * Wraps a `nats.js`-compatible client subscription. Each message becomes a `DATA` emission.
+ *
+ * @param client - NATS client instance (caller owns connect/drain lifecycle).
+ * @param subject - Subject to subscribe to (supports wildcards).
+ * @param opts - Queue group, deserialization, and source options.
+ * @returns `Node<NATSMessage<T>>` — one `DATA` per NATS message.
+ *
+ * @remarks
+ * Teardown sets an internal flag but cannot break the async iterator. The loop
+ * exits on the next message or when the subscription is drained/unsubscribed
+ * externally. Call `client.drain()` after unsubscribing for prompt cleanup.
+ *
+ * @example
+ * ```ts
+ * import { connect } from "nats";
+ * import { fromNATS } from "@graphrefly/graphrefly-ts";
+ *
+ * const nc = await connect({ servers: "localhost:4222" });
+ * const events$ = fromNATS(nc, "events.>");
+ * ```
+ *
+ * @category extra
+ */
+declare function fromNATS<T = unknown>(client: NATSClientLike, subject: string, opts?: FromNATSOptions): Node<NATSMessage<T>>;
+/** Options for {@link toNATS}. */
+type ToNATSOptions<T> = ExtraOpts & {
+    /** Serialize value for NATS. Default: `JSON.stringify` → Uint8Array. */
+    serialize?: (value: T) => Uint8Array;
+    /** Called on serialization failures. */
+    onTransportError?: (err: SinkTransportError) => void;
+};
+/**
+ * NATS publisher sink — forwards upstream `DATA` to a NATS subject.
+ *
+ * @param source - Upstream node to forward.
+ * @param client - NATS client instance.
+ * @param subject - Target subject.
+ * @param opts - Serialization options.
+ * @returns Unsubscribe function.
+ *
+ * @category extra
+ */
+declare function toNATS<T>(source: Node<T>, client: NATSClientLike, subject: string, opts?: ToNATSOptions<T>): ReactiveSinkHandle<T>;
+
+/**
+ * NDJSON (newline-delimited JSON) IO — `fromNDJSON` reads an
+ * `AsyncIterable<string>` of NDJSON chunks (one node per line) and
+ * `ndjsonRows` is the stateful operator variant for existing reactive
+ * `Node<string>` upstreams.
+ */
+
+/**
+ * Stateful NDJSON parser operator — takes a `Node<string>` of raw text chunks
+ * and emits one `DATA` per parsed JSON object. Buffers partial lines across
+ * chunks.
+ *
+ * @category extra
+ */
+declare function ndjsonRows<T = unknown>(source: Node<string>, opts?: ExtraOpts): Node<T>;
+/** Options for {@link fromNDJSON}. */
+type FromNDJSONOptions = ExtraOpts & {};
+/**
+ * Newline-delimited JSON stream ingest for batch replay.
+ *
+ * Reads an async iterable of text chunks, splits by newline, parses each line
+ * as JSON, and emits one `DATA` per parsed object. `COMPLETE` after stream ends.
+ *
+ * @param source - Async iterable of NDJSON text chunks.
+ * @param opts - Optional producer options.
+ * @returns `Node<T>` — one `DATA` per JSON line.
+ *
+ * @example
+ * ```ts
+ * import { createReadStream } from "node:fs";
+ * import { fromNDJSON } from "@graphrefly/graphrefly-ts";
+ *
+ * const logs$ = fromNDJSON(createReadStream("logs.ndjson", "utf-8"));
+ * ```
+ *
+ * @category extra
+ */
+declare function fromNDJSON<T = unknown>(source: AsyncIterable<string>, opts?: FromNDJSONOptions): Node<T>;
+
+/**
+ * OpenTelemetry (OTLP/HTTP) IO — `fromOTel` exposes traces/metrics/logs as
+ * three reactive nodes via `externalBundle`. The caller owns the HTTP server
+ * and wires the registrar callback to OTLP routes.
+ */
+
+/** Structured OTel span. */
+type OTelSpan = {
+    traceId: string;
+    spanId: string;
+    operationName: string;
+    serviceName: string;
+    startTimeNs: number;
+    endTimeNs: number;
+    status: "OK" | "ERROR" | "UNSET";
+    attributes: Record<string, unknown>;
+    events: Array<{
+        name: string;
+        timestampNs: number;
+        attributes?: Record<string, unknown>;
+    }>;
+};
+/** Structured OTel metric data point. */
+type OTelMetric = {
+    name: string;
+    description?: string;
+    unit?: string;
+    type: "gauge" | "sum" | "histogram" | "summary";
+    value: number;
+    attributes: Record<string, unknown>;
+    timestampNs: number;
+};
+/** Structured OTel log record. */
+type OTelLog = {
+    timestampNs: number;
+    severityNumber?: number;
+    severityText?: string;
+    body: unknown;
+    attributes: Record<string, unknown>;
+    traceId?: string;
+    spanId?: string;
+};
+/** Registration callback for the OTLP/HTTP receiver. */
+type OTelRegister = (handlers: {
+    onTraces: (spans: OTelSpan[]) => void;
+    onMetrics: (metrics: OTelMetric[]) => void;
+    onLogs: (logs: OTelLog[]) => void;
+    onError: (err: unknown) => void;
+}) => (() => void) | undefined;
+/** Options for {@link fromOTel}. */
+type FromOTelOptions = ExtraOpts & {};
+/** Bundle returned by {@link fromOTel}. */
+type OTelBundle = {
+    traces: Node<OTelSpan>;
+    metrics: Node<OTelMetric>;
+    logs: Node<OTelLog>;
+    /** Unconditional teardown — calls the registrar's cleanup and fires COMPLETE on every channel. */
+    dispose(): void;
+};
+/**
+ * OTLP/HTTP receiver — accepts traces, metrics, and logs as separate reactive nodes.
+ *
+ * The caller owns the HTTP server. `fromOTel` receives a `register` callback that
+ * wires OTLP POST endpoints to the three signal handlers. Each signal type gets
+ * its own `Node` so downstream can subscribe selectively.
+ *
+ * @param register - Wires OTLP HTTP routes to `onTraces`, `onMetrics`, `onLogs` handlers.
+ * @param opts - Optional producer options.
+ * @returns {@link OTelBundle} — `{ traces, metrics, logs }` nodes.
+ *
+ * @example
+ * ```ts
+ * import express from "express";
+ * import { fromOTel } from "@graphrefly/graphrefly-ts";
+ *
+ * const app = express();
+ * app.use(express.json());
+ *
+ * const otel = fromOTel(({ onTraces, onMetrics, onLogs }) => {
+ *   app.post("/v1/traces", (req, res) => { onTraces(req.body.resourceSpans ?? []); res.sendStatus(200); });
+ *   app.post("/v1/metrics", (req, res) => { onMetrics(req.body.resourceMetrics ?? []); res.sendStatus(200); });
+ *   app.post("/v1/logs", (req, res) => { onLogs(req.body.resourceLogs ?? []); res.sendStatus(200); });
+ *   return () => {};
+ * });
+ * ```
+ *
+ * @category extra
+ */
+declare function fromOTel(register: OTelRegister, opts?: FromOTelOptions): OTelBundle;
+
+/**
+ * Prisma adapter (5.2b) — `fromPrisma` runs `model.findMany(args)` and emits
+ * one `DATA` containing the full mapped row array, then `COMPLETE`.
+ */
+
+/**
+ * Duck-typed Prisma model delegate.
+ *
+ * Compatible with any Prisma model's `findMany` method (e.g. `prisma.user`).
+ * The consumer passes the model delegate directly — no dependency on `@prisma/client`.
+ */
+type PrismaModelLike<T = unknown> = {
+    findMany(args?: unknown): Promise<T[]>;
+};
+/** Options for {@link fromPrisma}. */
+type FromPrismaOptions<T, U = T> = ExtraOpts & {
+    /** Prisma `findMany` args (where, orderBy, select, include, take, skip, etc.). */
+    args?: unknown;
+    /** Map each row to the desired shape. Default: identity cast. */
+    mapRow?: (row: T) => U;
+};
+/**
+ * One-shot Prisma query as a reactive source.
+ *
+ * Calls `model.findMany(args)`, emits one `DATA` per result row, then `COMPLETE`.
+ * Compose with `switchMap` + `fromTimer` for periodic re-query.
+ *
+ * @param model - Prisma model delegate (e.g. `prisma.user`).
+ * @param opts - `findMany` args, row mapper, and node options.
+ * @returns `Node<U>` — one `DATA` per row, then `COMPLETE`.
+ *
+ * @example
+ * ```ts
+ * import { PrismaClient } from "@prisma/client";
+ * import { fromPrisma } from "@graphrefly/graphrefly-ts";
+ *
+ * const prisma = new PrismaClient();
+ * const activeUsers = fromPrisma(prisma.user, {
+ *   args: { where: { active: true } },
+ * });
+ * ```
+ *
+ * @category extra
+ */
+declare function fromPrisma<T = unknown, U = T>(model: PrismaModelLike<T>, opts?: FromPrismaOptions<T, U>): Node<U[]>;
+
+/**
+ * Prometheus scrape IO — `fromPrometheus` polls a `/metrics` endpoint via
+ * `fromTimer + switchMap` (reactive timer, not bare `setInterval`) and emits
+ * one `DATA` per parsed metric per scrape. `parsePrometheusText` exposes the
+ * exposition-format parser as a pure helper.
+ */
+
+/** Parsed Prometheus metric. */
+type PrometheusMetric = {
+    name: string;
+    labels: Record<string, string>;
+    value: number;
+    timestampMs?: number;
+    type?: "counter" | "gauge" | "histogram" | "summary" | "untyped";
+    help?: string;
+    timestampNs: number;
+};
+/** Options for {@link fromPrometheus}. */
+type FromPrometheusOptions = AsyncSourceOpts & {
+    /** Scrape interval in nanoseconds. Default `15 * NS_PER_SEC` (15s). */
+    intervalNs?: number;
+    /** Request headers for the scrape. */
+    headers?: Record<string, string>;
+    /** Request timeout in nanoseconds. Default `10 * NS_PER_SEC` (10s). */
+    timeoutNs?: number;
+    /**
+     * Maximum consecutive scrape errors before terminating the source. Prevents
+     * error storms when the endpoint is down. Default: `1` (terminate on first error — preserves pre-switchMap back-compat). Raise it (or set `Infinity`)
+     * to keep retrying indefinitely.
+     */
+    maxConsecutiveErrors?: number;
+};
+/**
+ * Scrapes a Prometheus `/metrics` endpoint on a reactive timer interval.
+ *
+ * Each scrape parses the exposition format and emits one `DATA` per metric line.
+ * Uses `fromTimer` semantics internally (reactive timer source, not polling).
+ *
+ * @param endpoint - URL of the Prometheus metrics endpoint.
+ * @param opts - Scrape interval, headers, timeout.
+ * @returns `Node<PrometheusMetric>` — one `DATA` per metric per scrape.
+ *
+ * @example
+ * ```ts
+ * import { fromPrometheus } from "@graphrefly/graphrefly-ts";
+ *
+ * const prom$ = fromPrometheus("http://localhost:9090/metrics", { intervalNs: 30 * NS_PER_SEC });
+ * ```
+ *
+ * @category extra
+ */
+declare function fromPrometheus(endpoint: string, opts?: FromPrometheusOptions): Node<PrometheusMetric>;
+/**
+ * Parses Prometheus exposition format text into structured metrics.
+ *
+ * @category extra
+ */
+declare function parsePrometheusText(text: string): PrometheusMetric[];
+
+/**
+ * Apache Pulsar IO — `fromPulsar` (native-client consumer source with optional
+ * manual ack via {@link AckableMessage} envelopes) and `toPulsar` (producer
+ * sink). For Kafka-on-Pulsar (KoP), use the Kafka adapter instead.
+ */
+
+/** Duck-typed Pulsar consumer (compatible with pulsar-client). */
+type PulsarConsumerLike = {
+    receive(): Promise<{
+        getData(): Buffer;
+        getMessageId(): {
+            toString(): string;
+        };
+        getPartitionKey(): string;
+        getProperties(): Record<string, string>;
+        getPublishTimestamp(): number;
+        getEventTimestamp(): number;
+        getTopicName(): string;
+    }>;
+    acknowledge(msg: unknown): Promise<void>;
+    close(): Promise<void>;
+};
+/** Duck-typed Pulsar producer. */
+type PulsarProducerLike = {
+    send(msg: {
+        data: Buffer;
+        partitionKey?: string;
+        properties?: Record<string, string>;
+    }): Promise<void>;
+    close(): Promise<void>;
+};
+/** Structured Pulsar message. */
+type PulsarMessage<T = unknown> = {
+    topic: string;
+    messageId: string;
+    key: string;
+    value: T;
+    properties: Record<string, string>;
+    publishTime: number;
+    eventTime: number;
+    timestampNs: number;
+};
+/** Options for {@link fromPulsar}. */
+type FromPulsarOptions = ExtraOpts & {
+    /** Deserialize message data. Default: `JSON.parse(buffer.toString())`. */
+    deserialize?: (data: Buffer) => unknown;
+    /** Acknowledge messages automatically. Default: `true`. */
+    autoAck?: boolean;
+    /**
+     * Routes ack/nack transport failures to the caller. Covers:
+     * - `autoAck: true` — post-emit `acknowledge()` promise rejections.
+     * - `autoAck: false` — envelope `ack()` / `nack()` promise rejections.
+     * Default: swallow (SDK handles redelivery on its own).
+     */
+    onAckError?: (err: Error) => void;
+};
+/**
+ * Apache Pulsar consumer as a reactive source (native client).
+ *
+ * Wraps a `pulsar-client`-compatible consumer. Each message becomes a `DATA` emission.
+ * For Kafka-on-Pulsar (KoP), use {@link fromKafka} instead.
+ *
+ * @param consumer - Pulsar consumer instance (caller owns create/close lifecycle).
+ * @param opts - Deserialization and source options.
+ * @returns `Node<PulsarMessage<T>>` — one `DATA` per Pulsar message.
+ *
+ * @remarks
+ * Teardown sets an internal flag but cannot interrupt a pending `consumer.receive()`.
+ * The loop exits on the next message or when the consumer is closed externally.
+ * Callers should call `consumer.close()` after unsubscribing for prompt cleanup.
+ *
+ * @example
+ * ```ts
+ * import Pulsar from "pulsar-client";
+ * import { fromPulsar } from "@graphrefly/graphrefly-ts";
+ *
+ * const client = new Pulsar.Client({ serviceUrl: "pulsar://localhost:6650" });
+ * const consumer = await client.subscribe({ topic: "events", subscription: "my-sub" });
+ * const events$ = fromPulsar(consumer);
+ * ```
+ *
+ * @category extra
+ */
+declare function fromPulsar<T = unknown>(consumer: PulsarConsumerLike, opts?: FromPulsarOptions & {
+    autoAck?: true;
+}): Node<PulsarMessage<T>>;
+declare function fromPulsar<T = unknown>(consumer: PulsarConsumerLike, opts: FromPulsarOptions & {
+    autoAck: false;
+}): Node<AckableMessage<PulsarMessage<T>>>;
+/** Options for {@link toPulsar}. */
+type ToPulsarOptions<T> = ExtraOpts & {
+    /** Serialize value for Pulsar. Default: `JSON.stringify` → Buffer. */
+    serialize?: (value: T) => Buffer;
+    /** Extract partition key from value. Default: none. */
+    keyExtractor?: (value: T) => string | undefined;
+    /** Extract properties from value. */
+    propertiesExtractor?: (value: T) => Record<string, string> | undefined;
+    /** Called on serialization or send failures. */
+    onTransportError?: (err: SinkTransportError) => void;
+};
+/**
+ * Pulsar producer sink — forwards upstream `DATA` to a Pulsar topic.
+ *
+ * @param source - Upstream node to forward.
+ * @param pulsarProducer - Pulsar producer instance (caller owns lifecycle).
+ * @param opts - Serialization options.
+ * @returns Unsubscribe function.
+ *
+ * @category extra
+ */
+declare function toPulsar<T>(source: Node<T>, pulsarProducer: PulsarProducerLike, opts?: ToPulsarOptions<T>): ReactiveSinkHandle<T>;
+
+/**
+ * RabbitMQ IO — `fromRabbitMQ` (queue-consumer source with optional manual
+ * ack via {@link AckableMessage} envelopes) and `toRabbitMQ` (publisher
+ * sink). Compatible with `amqplib`-style channels.
+ */
+
+/** Duck-typed RabbitMQ channel (compatible with amqplib). */
+type RabbitMQChannelLike = {
+    consume(queue: string, onMessage: (msg: {
+        content: Buffer;
+        fields: {
+            routingKey: string;
+            exchange: string;
+            deliveryTag: number;
+            redelivered: boolean;
+        };
+        properties: Record<string, unknown>;
+    } | null) => void, opts?: {
+        noAck?: boolean;
+    }): Promise<{
+        consumerTag: string;
+    }>;
+    cancel(consumerTag: string): Promise<void>;
+    ack(msg: unknown): void;
+    publish(exchange: string, routingKey: string, content: Buffer, opts?: Record<string, unknown>): boolean;
+    sendToQueue(queue: string, content: Buffer, opts?: Record<string, unknown>): boolean;
+};
+/** Structured RabbitMQ message. */
+type RabbitMQMessage<T = unknown> = {
+    queue: string;
+    routingKey: string;
+    exchange: string;
+    content: T;
+    properties: Record<string, unknown>;
+    deliveryTag: number;
+    redelivered: boolean;
+    timestampNs: number;
+};
+/** Options for {@link fromRabbitMQ}. */
+type FromRabbitMQOptions = ExtraOpts & {
+    /** Deserialize message content. Default: `JSON.parse(buffer.toString())`. */
+    deserialize?: (content: Buffer) => unknown;
+    /** Auto-acknowledge messages. Default: `true`. */
+    autoAck?: boolean;
+    /**
+     * Routes envelope ack/nack transport failures (including "SDK exposes no
+     * `nack` method") to the caller. Default: swallow.
+     */
+    onAckError?: (err: Error) => void;
+};
+/**
+ * RabbitMQ consumer as a reactive source.
+ *
+ * Wraps an `amqplib`-compatible channel. Each message becomes a `DATA` emission.
+ *
+ * @param channel - AMQP channel instance (caller owns connection/channel lifecycle).
+ * @param queue - Queue to consume from.
+ * @param opts - Deserialization and acknowledgment options.
+ * @returns `Node<RabbitMQMessage<T>>` — one `DATA` per RabbitMQ message.
+ *
+ * @remarks
+ * When `autoAck` is `false`, the adapter opens the channel with `noAck: false`
+ * (broker requires acks) but does not call `channel.ack()`. The caller must ack
+ * messages externally using the `deliveryTag` from the emitted {@link RabbitMQMessage}:
+ * ```ts
+ * channel.ack({ fields: { deliveryTag: msg.deliveryTag } } as any);
+ * ```
+ *
+ * @example
+ * ```ts
+ * import amqplib from "amqplib";
+ * import { fromRabbitMQ } from "@graphrefly/graphrefly-ts";
+ *
+ * const conn = await amqplib.connect("amqp://localhost");
+ * const ch = await conn.createChannel();
+ * await ch.assertQueue("events");
+ * const events$ = fromRabbitMQ(ch, "events");
+ * ```
+ *
+ * @category extra
+ */
+declare function fromRabbitMQ<T = unknown>(channel: RabbitMQChannelLike, queue: string, opts?: FromRabbitMQOptions & {
+    autoAck?: true;
+}): Node<RabbitMQMessage<T>>;
+declare function fromRabbitMQ<T = unknown>(channel: RabbitMQChannelLike, queue: string, opts: FromRabbitMQOptions & {
+    autoAck: false;
+}): Node<AckableMessage<RabbitMQMessage<T>>>;
+/** Options for {@link toRabbitMQ}. */
+type ToRabbitMQOptions<T> = ExtraOpts & {
+    /** Serialize value for RabbitMQ. Default: `Buffer.from(JSON.stringify(value))`. */
+    serialize?: (value: T) => Buffer;
+    /** Extract routing key from value. Default: `""`. */
+    routingKeyExtractor?: (value: T) => string;
+    /** Called on serialization or send failures. */
+    onTransportError?: (err: SinkTransportError) => void;
+};
+/**
+ * RabbitMQ producer sink — forwards upstream `DATA` to a RabbitMQ exchange/queue.
+ *
+ * @param source - Upstream node to forward.
+ * @param channel - AMQP channel instance.
+ * @param exchange - Target exchange (use `""` for default exchange + queue routing).
+ * @param opts - Serialization and routing options.
+ * @returns Unsubscribe function.
+ *
+ * @category extra
+ */
+declare function toRabbitMQ<T>(source: Node<T>, channel: RabbitMQChannelLike, exchange: string, opts?: ToRabbitMQOptions<T>): ReactiveSinkHandle<T>;
+
+/**
+ * Redis Streams IO — `fromRedisStream` (XREAD-BLOCK consumer source) and
+ * `toRedisStream` (XADD producer sink). Caller owns the Redis client
+ * lifecycle.
+ */
+
+/** Duck-typed Redis client (compatible with ioredis, redis). */
+type RedisClientLike = {
+    xadd(key: string, id: string, ...fieldsAndValues: string[]): Promise<string>;
+    xread(...args: Array<string | number>): Promise<Array<[string, Array<[string, string[]]>]> | null>;
+    disconnect(): void;
+};
+/** Structured Redis Stream entry. */
+type RedisStreamEntry<T = unknown> = {
+    id: string;
+    key: string;
+    data: T;
+    timestampNs: number;
+};
+/** Options for {@link fromRedisStream}. */
+type FromRedisStreamOptions = ExtraOpts & {
+    /** Block timeout in ms for XREAD. Default: `5000`. */
+    blockMs?: number;
+    /** Start ID. Default: `"$"` (new entries only). */
+    startId?: string;
+    /** Parse raw Redis hash fields to structured data. Default: parses `data` field as JSON. */
+    parse?: (fields: string[]) => unknown;
+};
+/**
+ * Redis Streams consumer as a reactive source.
+ *
+ * Uses XREAD with BLOCK to reactively consume stream entries.
+ *
+ * @param client - ioredis/redis-compatible client (caller owns connection).
+ * @param key - Redis stream key.
+ * @param opts - Block timeout, start ID, and parsing options.
+ * @returns `Node<RedisStreamEntry<T>>` — one `DATA` per stream entry.
+ *
+ * @remarks
+ * **COMPLETE:** This source never emits `COMPLETE` under normal operation — it
+ * is a long-lived stream consumer that runs until teardown or error, same as
+ * Kafka consumers. If you need a bounded read, wrap with `take()` or
+ * `takeUntil()`.
+ *
+ * **Client lifecycle:** The caller owns the Redis client connection. The adapter
+ * does not call `disconnect()` on teardown — the caller is responsible for
+ * closing the connection (same contract as `fromKafka`).
+ *
+ * @category extra
+ */
+declare function fromRedisStream<T = unknown>(client: RedisClientLike, key: string, opts?: FromRedisStreamOptions): Node<RedisStreamEntry<T>>;
+/** Options for {@link toRedisStream}. */
+type ToRedisStreamOptions<T> = ExtraOpts & {
+    /** Serialize value to Redis hash fields. Default: `["data", JSON.stringify(value)]`. */
+    serialize?: (value: T) => string[];
+    /** Max stream length (MAXLEN ~). Default: no trimming. */
+    maxLen?: number;
+    /** Called on serialization or send failures. */
+    onTransportError?: (err: SinkTransportError) => void;
+};
+/**
+ * Redis Streams producer sink — forwards upstream `DATA` to a Redis stream.
+ *
+ * @param source - Upstream node to forward.
+ * @param client - ioredis/redis-compatible client.
+ * @param key - Redis stream key.
+ * @param opts - Serialization options.
+ * @returns Unsubscribe function.
+ *
+ * @category extra
+ */
+declare function toRedisStream<T>(source: Node<T>, client: RedisClientLike, key: string, opts?: ToRedisStreamOptions<T>): ReactiveSinkHandle<T>;
+
+/**
+ * SQLite IO (roadmap §5.2b) — `fromSqlite` (one-shot synchronous query),
+ * `fromSqliteCursor` (row-by-row streaming via `iterate()`), and `toSqlite`
+ * (insert sink with optional transactional batching).
+ *
+ * Synchronous boundaries: SQLite drivers are typically synchronous
+ * (`better-sqlite3`, `node:sqlite`), so errors propagate immediately rather
+ * than via promise rejection. The duck-typed `SqliteDbLike.query` matches the
+ * project-wide `query(sql, params)` convention used by Postgres/ClickHouse.
+ */
+
+/**
+ * Duck-typed synchronous SQLite database.
+ *
+ * Compatible with `better-sqlite3` (`.prepare().all()` / `.prepare().run()`)
+ * and Node.js `node:sqlite` `DatabaseSync`. The user wraps their driver behind
+ * this uniform contract — method name `query` matches the project-wide
+ * convention (`PostgresClientLike.query`, `ClickHouseClientLike.query`).
+ */
+type SqliteDbLike = {
+    query(sql: string, params?: unknown[]): unknown[];
+};
+/** Options for {@link fromSqlite}. */
+type FromSqliteOptions<T> = ExtraOpts & {
+    /** Map a raw row object to the desired type. Default: identity cast. */
+    mapRow?: (row: unknown) => T;
+    /** Bind parameters for the query. */
+    params?: unknown[];
+};
+/**
+ * One-shot SQLite query as a reactive source.
+ *
+ * Executes `query` synchronously via `db.query()`, emits **one `DATA` containing
+ * the full result array**, then `COMPLETE`. Downstream flattens with
+ * `mergeAll` / a custom operator if per-row semantics are required — the
+ * array shape is the simpler default and matches how every SQL driver returns
+ * results natively. Use {@link fromSqliteCursor} for streaming row-by-row.
+ *
+ * @param db - SQLite database (caller owns connection).
+ * @param query - SQL string to execute.
+ * @param opts - Row mapper, params, and node options.
+ * @returns `Node<T[]>` — one `DATA` with the full row array, then `COMPLETE`.
+ *
+ * @example
+ * ```ts
+ * import Database from "better-sqlite3";
+ * import { fromSqlite } from "@graphrefly/graphrefly-ts";
+ *
+ * const raw = new Database("app.db");
+ * const db = { query: (sql, params) => raw.prepare(sql).all(...(params ?? [])) };
+ * const rows$ = fromSqlite(db, "SELECT * FROM users WHERE active = ?", { params: [1] });
+ * ```
+ *
+ * @category extra
+ */
+declare function fromSqlite<T = unknown>(db: SqliteDbLike, query: string, opts?: FromSqliteOptions<T>): Node<T[]>;
+/**
+ * Duck-typed iterable-capable SQLite database — `iterate(sql, params)` returns
+ * a synchronous iterator over rows, avoiding the "all-rows-in-memory" cost of
+ * `db.query`. Compatible with `better-sqlite3`'s `.prepare().iterate()`.
+ *
+ * @category extra
+ */
+type SqliteIterableDbLike = {
+    iterate(sql: string, params?: unknown[]): Iterable<unknown>;
+};
+/**
+ * Cursor-streaming SQLite query — emits one `DATA` per row from a synchronous
+ * row iterator, then `COMPLETE`. Use when result sets are too large to
+ * materialize fully into an array.
+ *
+ * @category extra
+ */
+declare function fromSqliteCursor<T = unknown>(db: SqliteIterableDbLike, query: string, opts?: FromSqliteOptions<T>): Node<T>;
+/** Options for {@link toSqlite}. */
+type ToSqliteOptions<T> = ExtraOpts & {
+    /** Build SQL + params for an insert. Default: JSON insert into `(data)` column. */
+    toSQL?: (value: T, table: string) => {
+        sql: string;
+        params: unknown[];
+    };
+    onTransportError?: (err: SinkTransportError) => void;
+    /**
+     * When `true`, buffer DATA values and execute all inserts inside a single
+     * `BEGIN`/`COMMIT` transaction when the batch drains.  This avoids per-row
+     * fsync overhead and dramatically reduces event-loop blocking for
+     * high-throughput sources.  The first insert error stops the batch and
+     * triggers a `ROLLBACK`; the error is reported via `onTransportError`.
+     */
+    batchInsert?: boolean;
+    /** Auto-flush when buffer reaches this size. Default: `1000`. Only applies when `batchInsert` is `true`. */
+    maxBatchSize?: number;
+    /** Periodic flush interval in ms. `0` = no timer (flush on terminal messages only). Default: `0`. Only applies when `batchInsert` is `true`. */
+    flushIntervalMs?: number;
+};
+/**
+ * SQLite sink — inserts each upstream `DATA` value as a row.
+ *
+ * Follows the same pattern as {@link toPostgres} / {@link toMongo}. Since SQLite
+ * is synchronous, errors propagate immediately (no `void promise.catch`).
+ *
+ * @param source - Upstream node.
+ * @param db - SQLite database (caller owns connection).
+ * @param table - Target table name.
+ * @param opts - SQL builder and error options.
+ * @returns Unsubscribe function.
+ *
+ * @example
+ * ```ts
+ * import Database from "better-sqlite3";
+ * import { toSqlite, state } from "@graphrefly/graphrefly-ts";
+ *
+ * const raw = new Database("app.db");
+ * const db = { query: (sql, params) => (raw.prepare(sql).run(...(params ?? [])), []) };
+ * const source = state({ name: "Alice", score: 42 });
+ * const unsub = toSqlite(source, db, "events");
+ * ```
+ *
+ * @category extra
+ */
+declare function toSqlite<T>(source: Node<T>, db: SqliteDbLike, table: string, opts?: ToSqliteOptions<T>): ReactiveSinkHandle<T>;
+
+/**
+ * Server-Sent Events IO — `toSSE` / `toSSEBytes` (encode any node into the
+ * `text/event-stream` wire format), `toReadableStream` (web-stream sink),
+ * `parseSSEStream` (async-iterator parser), `fromSSE` (line-delimited parser
+ * source).
+ */
+
+/** Options for {@link toSSE}. */
+type ToSSEOptions = {
+    /** Custom payload serializer for non-string payloads. Default: `JSON.stringify` fallback to `String(value)`. */
+    serialize?: (value: unknown) => string;
+    /** Event name for DATA tuples. Default: `"data"`. */
+    dataEvent?: string;
+    /** Event name for ERROR tuples. Default: `"error"`. */
+    errorEvent?: string;
+    /** Event name for COMPLETE tuples. Default: `"complete"`. */
+    completeEvent?: string;
+    /** Emit `event: resolved` when RESOLVED arrives. Default: `false`. */
+    includeResolved?: boolean;
+    /** Emit `event: dirty` when DIRTY arrives. Default: `false`. */
+    includeDirty?: boolean;
+    /** Add SSE comment keepalive frames (`: keepalive`) on an interval. Disabled when unset. */
+    keepAliveMs?: number;
+    /** Optional abort signal to terminate the stream early. */
+    signal?: AbortSignal;
+    /** Maps custom message types to SSE event names. */
+    eventNameResolver?: (type: symbol) => string;
+};
+/**
+ * Creates a standard Server-Sent Events stream from node messages.
+ *
+ * @category extra
+ */
+declare function toSSE<T>(source: Node<T>, opts?: ToSSEOptions): ReadableStream<Uint8Array>;
+/**
+ * Composable variant of {@link toSSE} — emits encoded SSE frames as
+ * `Uint8Array` through a reactive `Node`. Use this when you want to pipe SSE
+ * bytes through the reactive graph (persist to file, tee to multiple streams,
+ * etc.). Wrap with {@link toReadableStream} to expose a `ReadableStream` for
+ * `new Response(...)` use cases.
+ *
+ * @category extra
+ */
+declare function toSSEBytes<T>(source: Node<T>, opts?: ToSSEOptions): Node<Uint8Array>;
+/**
+ * Converts a `Node<Uint8Array>` into a WHATWG `ReadableStream<Uint8Array>`.
+ * Useful for composing with `new Response(...)` / `fetch` bodies.
+ *
+ * @category extra
+ */
+declare function toReadableStream(bytes: Node<Uint8Array>): ReadableStream<Uint8Array>;
+/** Parsed Server-Sent Event. */
+type SSEEvent<T = string> = {
+    event: string;
+    data: T;
+    id?: string;
+    retry?: number;
+};
+/** Options for {@link fromSSE}. */
+type FromSSEOptions<T = string> = ExtraOpts & {
+    /** Parse the raw `data:` payload. Default: identity (string). */
+    parse?: (raw: string) => T;
+};
+/** Options for {@link parseSSEStream}. */
+type ParseSSEStreamOptions<T = string> = {
+    /** Parse the raw `data:` payload. Default: identity (string). */
+    parse?: (raw: string) => T;
+    /**
+     * External abort signal. If aborted, the generator returns early after
+     * cancelling the underlying reader / iterator. Does not emit an error —
+     * the generator simply ends.
+     */
+    signal?: AbortSignal;
+};
+/**
+ * Parses a Server-Sent Events byte stream into an async-iterator of structured
+ * `{event, data, id, retry}` records. Pure async generator with no reactive
+ * dependency — safe to consume anywhere an `AsyncIterable<SSEEvent>` is
+ * expected (LLM provider adapters, tests, non-reactive transports).
+ *
+ * Handles:
+ * - Arbitrary chunk boundaries (internal text buffer + `TextDecoder` streaming).
+ * - `\n` and `\r\n` line endings.
+ * - `event:` / `data:` (multi-line via repeated fields) / `id:` / `retry:`.
+ * - Comments (`:` prefix).
+ * - Cancels the underlying reader / iterator on external abort or consumer
+ *   break, so a quiet stream doesn't leak pending `read()` calls.
+ *
+ * Used internally by {@link fromSSE} (reactive `Node<SSEEvent>`) — exposed as a
+ * pure helper so LLM provider adapters (Anthropic, OpenAI, Google) can parse
+ * their SSE streams without building a reactive node per call.
+ *
+ * @param source - SSE byte source (`ReadableStream`, `Response`, or `AsyncIterable<Uint8Array>`).
+ * @param opts - `{ parse?, signal? }`.
+ * @returns `AsyncGenerator<SSEEvent<T>>` — yields one event per SSE block; returns on stream end / abort.
+ *
+ * @category extra
+ */
+declare function parseSSEStream<T = string>(source: ReadableStream<Uint8Array> | Response | AsyncIterable<Uint8Array>, opts?: ParseSSEStreamOptions<T>): AsyncGenerator<SSEEvent<T>, void, unknown>;
+/**
+ * Parses a Server-Sent Events stream into structured `{event, data, id}` records.
+ *
+ * @param source - SSE byte source (`ReadableStream`, `Response`, or `AsyncIterable<Uint8Array>`).
+ * @param opts - Parse function and node options.
+ * @returns `Node<SSEEvent<T>>` — one `DATA` per SSE event; `COMPLETE` on stream end.
+ *
+ * @category extra
+ */
+declare function fromSSE<T = string>(source: ReadableStream<Uint8Array> | Response | AsyncIterable<Uint8Array>, opts?: FromSSEOptions<T>): Node<SSEEvent<T>>;
+
+/**
+ * StatsD / DogStatsD IO — `fromStatsD` registrar-based source plus
+ * `parseStatsD` helper for the line format. The caller owns the UDP socket;
+ * the adapter only wires the `emit` triad.
+ */
+
+/** Parsed StatsD metric. */
+type StatsDMetric = {
+    name: string;
+    value: number;
+    type: "counter" | "gauge" | "timer" | "histogram" | "set" | "distribution";
+    sampleRate?: number;
+    tags: Record<string, string>;
+    timestampNs: number;
+};
+/** Registration callback for StatsD receiver. Alias of {@link ExternalRegister} over {@link EmitTriad}. */
+type StatsDRegister = ExternalRegister<EmitTriad<StatsDMetric>>;
+/** Options for {@link fromStatsD}. */
+type FromStatsDOptions = ExtraOpts & {};
+/**
+ * StatsD/DogStatsD UDP receiver as a reactive source.
+ *
+ * The caller owns the UDP socket. `fromStatsD` receives a `register` callback
+ * that wires datagrams to the `emit` handler with parsed metrics.
+ *
+ * @param register - Wires socket to emit/error/complete handlers.
+ * @param opts - Optional producer options.
+ * @returns `Node<StatsDMetric>` — one `DATA` per metric line.
+ *
+ * @example
+ * ```ts
+ * import dgram from "node:dgram";
+ * import { fromStatsD, parseStatsD } from "@graphrefly/graphrefly-ts";
+ *
+ * const server = dgram.createSocket("udp4");
+ * const stats$ = fromStatsD(({ emit, error }) => {
+ *   server.on("message", (buf) => {
+ *     for (const line of buf.toString().split("\\n")) {
+ *       if (line.trim()) {
+ *         try { emit(parseStatsD(line)); }
+ *         catch (e) { error(e); }
+ *       }
+ *     }
+ *   });
+ *   server.bind(8125);
+ *   return () => server.close();
+ * });
+ * ```
+ *
+ * @category extra
+ */
+declare function fromStatsD(register: StatsDRegister, opts?: FromStatsDOptions): Node<StatsDMetric>;
+/**
+ * Parses a raw StatsD/DogStatsD line into a structured {@link StatsDMetric}.
+ *
+ * Format: `metric.name:value|type|@sampleRate|#tag1:val1,tag2:val2`
+ *
+ * @category extra
+ */
+declare function parseStatsD(line: string): StatsDMetric;
+
+/**
+ * Syslog (RFC 5424) IO — `fromSyslog` registrar-based source plus
+ * `parseSyslog` helper for the line format. The caller owns the UDP/TCP
+ * socket; the adapter only wires the `emit` triad.
+ */
+
+/** Parsed syslog message (RFC 5424). */
+type SyslogMessage = {
+    facility: number;
+    severity: number;
+    timestamp: string;
+    hostname: string;
+    appName: string;
+    procId: string;
+    msgId: string;
+    message: string;
+    timestampNs: number;
+};
+/** Registration callback for syslog receiver. Alias of {@link ExternalRegister} over {@link EmitTriad}. */
+type SyslogRegister = ExternalRegister<EmitTriad<SyslogMessage>>;
+/** Options for {@link fromSyslog}. */
+type FromSyslogOptions = ExtraOpts & {};
+/**
+ * RFC 5424 syslog receiver as a reactive source.
+ *
+ * The caller owns the UDP/TCP socket. `fromSyslog` receives a `register` callback
+ * that wires socket data events to the `emit` handler with parsed syslog messages.
+ *
+ * @param register - Wires socket to emit/error/complete handlers.
+ * @param opts - Optional producer options.
+ * @returns `Node<SyslogMessage>` — one `DATA` per syslog message.
+ *
+ * @example
+ * ```ts
+ * import dgram from "node:dgram";
+ * import { fromSyslog, parseSyslog } from "@graphrefly/graphrefly-ts";
+ *
+ * const server = dgram.createSocket("udp4");
+ * const syslog$ = fromSyslog(({ emit, error }) => {
+ *   server.on("message", (buf) => {
+ *     try { emit(parseSyslog(buf.toString())); }
+ *     catch (e) { error(e); }
+ *   });
+ *   server.bind(514);
+ *   return () => server.close();
+ * });
+ * ```
+ *
+ * @category extra
+ */
+declare function fromSyslog(register: SyslogRegister, opts?: FromSyslogOptions): Node<SyslogMessage>;
+/**
+ * Parses a raw RFC 5424 syslog line into a structured {@link SyslogMessage}.
+ *
+ * Format: `<PRI>VERSION TIMESTAMP HOSTNAME APP-NAME PROCID MSGID MSG`
+ *
+ * @category extra
+ */
+declare function parseSyslog(raw: string): SyslogMessage;
+
+/**
+ * ClickHouse insert sink IO — `toClickHouse` accumulates upstream `DATA`
+ * values and inserts them in batches via the duck-typed
+ * {@link ClickHouseInsertClientLike}.
+ */
+
+/** Duck-typed ClickHouse client for batch inserts. */
+type ClickHouseInsertClientLike = {
+    insert(params: {
+        table: string;
+        values: unknown[];
+        format?: string;
+    }): Promise<void>;
+};
+/** Options for {@link toClickHouse}. */
+type ToClickHouseOptions<T> = ExtraOpts & {
+    /** Batch size before auto-flush. Default: `1000`. */
+    batchSize?: number;
+    /** Flush interval in ms. Default: `5000`. */
+    flushIntervalMs?: number;
+    /** Insert format. Default: `"JSONEachRow"`. */
+    format?: string;
+    /** Transform value before insert. Default: identity. */
+    transform?: (value: T) => unknown;
+    onTransportError?: (err: SinkTransportError) => void;
+};
+/**
+ * ClickHouse buffered batch insert sink.
+ *
+ * Accumulates upstream `DATA` values and inserts in batches.
+ *
+ * @param source - Upstream node.
+ * @param client - ClickHouse client with `insert()`.
+ * @param table - Target table name.
+ * @param opts - Batch size, flush interval, and transform options.
+ * @returns `BufferedSinkHandle`.
+ *
+ * @category extra
+ */
+declare function toClickHouse<T>(source: Node<T>, client: ClickHouseInsertClientLike, table: string, opts?: ToClickHouseOptions<T>): ReactiveSinkHandle<T>;
+
+/**
+ * File-writer sink IO — `toFile` writes upstream `DATA` to any
+ * `FileWriterLike` (e.g. `fs.createWriteStream`). Buffered or write-through
+ * depending on `flushIntervalMs` / `batchSize`.
+ *
+ * Uses a duck-typed writable so the universal `extra/io` entry stays
+ * browser-safe — the caller injects the Node `fs` writer at the boundary.
+ */
+
+/** Duck-typed writable file handle (compatible with `fs.createWriteStream`). */
+type FileWriterLike = {
+    write(data: string | Uint8Array): boolean | undefined;
+    end(): void;
+};
+/** Options for {@link toFile}. */
+type ToFileOptions<T> = ExtraOpts & {
+    /** Serialize a value to a string line. Default: `JSON.stringify(v) + "\n"`. */
+    serialize?: (value: T) => string;
+    /** `"append"` (default) or `"overwrite"` — controls initial file behavior hint. */
+    mode?: "append" | "overwrite";
+    /** Flush interval in ms. `0` = write-through (no buffering). Default: `0`. */
+    flushIntervalMs?: number;
+    /** Buffer size (item count) before auto-flush. Default: `Infinity` (timer only). */
+    batchSize?: number;
+    onTransportError?: (err: SinkTransportError) => void;
+};
+/**
+ * File sink — writes upstream `DATA` values to a file-like writable.
+ *
+ * When `flushIntervalMs > 0` or `batchSize` is set, values are buffered and
+ * flushed in batches. Otherwise, each value is written immediately.
+ *
+ * @param source - Upstream node.
+ * @param writer - Writable file handle (e.g. `fs.createWriteStream(path, { flags: "a" })`).
+ * @param opts - Serialization, buffering, and mode options.
+ * @returns `BufferedSinkHandle` with `dispose()` and `flush()`.
+ *
+ * @category extra
+ */
+declare function toFile<T>(source: Node<T>, writer: FileWriterLike, opts?: ToFileOptions<T>): ReactiveSinkHandle<T>;
+
+/**
+ * CSV file sink IO — `toCSV` adds CSV row formatting on top of
+ * {@link toFile}. Uses the local `escapeCSVField` helper to quote cells that
+ * contain delimiters / quotes / newlines.
+ */
+
+/** Options for {@link toCSV}. */
+type ToCSVOptions<T> = ExtraOpts & {
+    /** Column names. Required — determines header row and field order. */
+    columns: string[];
+    /** Column delimiter. Default: `","`. */
+    delimiter?: string;
+    /** Whether to write a header row on first flush. Default: `true`. */
+    writeHeader?: boolean;
+    /** Extract a cell value from the row object. Default: `String(row[col] ?? "")`. */
+    cellExtractor?: (row: T, column: string) => string;
+    /** Flush interval in ms. Default: `0` (write-through). */
+    flushIntervalMs?: number;
+    /** Buffer size before auto-flush. Default: `Infinity`. */
+    batchSize?: number;
+    onTransportError?: (err: SinkTransportError) => void;
+};
+/**
+ * CSV file sink — writes upstream `DATA` as CSV rows.
+ *
+ * @param source - Upstream node.
+ * @param writer - Writable file handle.
+ * @param opts - Column definition, delimiter, and buffering options.
+ * @returns `BufferedSinkHandle`.
+ *
+ * @category extra
+ */
+declare function toCSV<T>(source: Node<T>, writer: FileWriterLike, opts: ToCSVOptions<T>): ReactiveSinkHandle<T>;
+
+/**
+ * Grafana Loki sink IO — `toLoki` pushes upstream `DATA` values as log
+ * entries via the duck-typed {@link LokiClientLike} `push()` surface.
+ */
+
+/** Loki log stream entry. */
+type LokiStream = {
+    stream: Record<string, string>;
+    values: [string, string][];
+};
+/** Duck-typed Loki push client (HTTP push API). */
+type LokiClientLike = {
+    push(streams: {
+        streams: LokiStream[];
+    }): Promise<unknown>;
+};
+/** Options for {@link toLoki}. */
+type ToLokiOptions<T> = ExtraOpts & {
+    /** Static labels applied to every log entry. */
+    labels?: Record<string, string>;
+    /** Extract the log line from a value. Default: `JSON.stringify(v)`. */
+    toLine?: (value: T) => string;
+    /** Extract additional labels from a value. Default: none. */
+    toLabels?: (value: T) => Record<string, string>;
+    onTransportError?: (err: SinkTransportError) => void;
+};
+/**
+ * Grafana Loki sink — pushes upstream `DATA` values as log entries.
+ *
+ * @param source - Upstream node.
+ * @param client - Loki-compatible client with `push()`.
+ * @param opts - Label, serialization, and error options.
+ * @returns Unsubscribe function.
+ *
+ * @category extra
+ */
+declare function toLoki<T>(source: Node<T>, client: LokiClientLike, opts?: ToLokiOptions<T>): ReactiveSinkHandle<T>;
+
+/**
+ * MongoDB insert sink IO — `toMongo` inserts each upstream `DATA` value via
+ * the duck-typed {@link MongoCollectionLike} `insertOne()`.
+ */
+
+/** Duck-typed MongoDB collection (compatible with `mongodb` driver). */
+type MongoCollectionLike = {
+    insertOne(doc: unknown): Promise<unknown>;
+};
+/** Options for {@link toMongo}. */
+type ToMongoOptions<T> = ExtraOpts & {
+    /** Transform value to a MongoDB document. Default: identity. */
+    toDocument?: (value: T) => unknown;
+    onTransportError?: (err: SinkTransportError) => void;
+};
+/**
+ * MongoDB sink — inserts each upstream `DATA` value as a document.
+ *
+ * @param source - Upstream node.
+ * @param collection - MongoDB collection with `insertOne()`.
+ * @param opts - Document transform and error options.
+ * @returns Unsubscribe function.
+ *
+ * @category extra
+ */
+declare function toMongo<T>(source: Node<T>, collection: MongoCollectionLike, opts?: ToMongoOptions<T>): ReactiveSinkHandle<T>;
+
+/**
+ * Postgres insert sink IO — `toPostgres` inserts each upstream `DATA` value
+ * via the duck-typed {@link PostgresClientLike} `query()` surface.
+ */
+
+/** Duck-typed Postgres client (compatible with `pg.Client` / `pg.Pool`). */
+type PostgresClientLike = {
+    query(sql: string, params?: unknown[]): Promise<unknown>;
+};
+/** Options for {@link toPostgres}. */
+type ToPostgresOptions<T> = ExtraOpts & {
+    /** Build the SQL + params for an insert. Default: JSON insert into `table`. */
+    toSQL?: (value: T, table: string) => {
+        sql: string;
+        params: unknown[];
+    };
+    onTransportError?: (err: SinkTransportError) => void;
+};
+/**
+ * PostgreSQL sink — inserts each upstream `DATA` value as a row.
+ *
+ * @param source - Upstream node.
+ * @param client - Postgres client with `query()`.
+ * @param table - Target table name.
+ * @param opts - SQL builder and error options.
+ * @returns Unsubscribe function.
+ *
+ * @category extra
+ */
+declare function toPostgres<T>(source: Node<T>, client: PostgresClientLike, table: string, opts?: ToPostgresOptions<T>): ReactiveSinkHandle<T>;
+
+/**
+ * Grafana Tempo sink IO — `toTempo` pushes upstream `DATA` values as trace
+ * spans (OTLP/HTTP shape) via the duck-typed {@link TempoClientLike}.
+ */
+
+/** Duck-typed Tempo span push client (OTLP/HTTP shape). */
+type TempoClientLike = {
+    push(payload: {
+        resourceSpans: unknown[];
+    }): Promise<unknown>;
+};
+/** Options for {@link toTempo}. */
+type ToTempoOptions<T> = ExtraOpts & {
+    /** Transform a value into OTLP resourceSpans entries. */
+    toResourceSpans?: (value: T) => unknown[];
+    onTransportError?: (err: SinkTransportError) => void;
+};
+/**
+ * Grafana Tempo sink — pushes upstream `DATA` values as trace spans.
+ *
+ * @param source - Upstream node.
+ * @param client - Tempo-compatible client with `push()`.
+ * @param opts - Span transform and error options.
+ * @returns Unsubscribe function.
+ *
+ * @category extra
+ */
+declare function toTempo<T>(source: Node<T>, client: TempoClientLike, opts?: ToTempoOptions<T>): ReactiveSinkHandle<T>;
+
+/**
+ * Webhook IO — `fromWebhook` is a thin wrapper over `externalProducer` that
+ * exposes the standard `EmitTriad` (`emit` / `error` / `complete`) callback
+ * shape to the caller's framework integration (Express, Fastify, Hono,
+ * Cloudflare Workers, etc.).
+ */
+
+/** Registration callback for {@link fromWebhook}. Alias of {@link ExternalRegister} over {@link EmitTriad}. */
+type WebhookRegister<T> = ExternalRegister<EmitTriad<T>>;
+/**
+ * Bridges HTTP webhook callbacks into a GraphReFly source.
+ *
+ * The `register` callback wires your runtime/framework callback to GraphReFly and may return a
+ * cleanup function. This keeps the adapter runtime-agnostic while following the same producer
+ * pattern as {@link fromEvent}.
+ *
+ * @param register - Registers webhook handlers (`emit`, `error`, `complete`) and optionally returns cleanup.
+ * @param opts - Optional producer options.
+ * @returns `Node<T>` — webhook payloads as `DATA`; teardown runs returned cleanup.
+ *
+ * @example
+ * ```ts
+ * import express from "express";
+ * import { fromWebhook } from "@graphrefly/graphrefly-ts";
+ *
+ * type HookPayload = { event: string; data: unknown };
+ * const app = express();
+ * app.use(express.json());
+ *
+ * const hook$ = fromWebhook<HookPayload>(({ emit, error }) => {
+ *   const handler = (req: express.Request, res: express.Response) => {
+ *     try {
+ *       emit(req.body as HookPayload);
+ *       res.status(200).send("ok");
+ *     } catch (e) {
+ *       error(e);
+ *       res.status(500).send("error");
+ *     }
+ *   };
+ *   app.post("/webhook", handler);
+ *   return () => {
+ *     // Express has no direct route-removal API in common use.
+ *   };
+ * });
+ * ```
+ *
+ * @example Fastify
+ * ```ts
+ * import Fastify from "fastify";
+ * import { fromWebhook } from "@graphrefly/graphrefly-ts";
+ *
+ * const fastify = Fastify();
+ * const hook$ = fromWebhook<any>(({ emit, error }) => {
+ *   const handler = async (req: any, reply: any) => {
+ *     try {
+ *       emit(req.body);
+ *       reply.code(200).send({ ok: true });
+ *     } catch (e) {
+ *       error(e);
+ *       reply.code(500).send({ ok: false });
+ *     }
+ *   };
+ *   fastify.post("/webhook", handler);
+ *   return () => {};
+ * });
+ * ```
+ *
+ * @category extra
+ */
+declare function fromWebhook<T = unknown>(register: WebhookRegister<T>, opts?: ExtraOpts): Node<T>;
+
+/**
+ * WebSocket IO — `fromWebSocket` (DOM-style `WebSocketLike` source / register
+ * variant), `toWebSocket` (sink with optional ack-tracking + retry),
+ * `fromWebSocketReconnect` (`fromWebSocket` wrapped in retry-on-disconnect with
+ * exponential backoff).
+ */
+
+/** WebSocket-like transport accepted by {@link fromWebSocket} / {@link toWebSocket}. */
+type WebSocketLike = {
+    send(data: string | ArrayBufferLike | Blob | ArrayBufferView): void;
+    close(code?: number, reason?: string): void;
+    addEventListener(type: "message" | "error" | "close", listener: (ev: unknown) => void): void;
+    removeEventListener(type: "message" | "error" | "close", listener: (ev: unknown) => void): void;
+};
+type WebSocketMessageEventLike = {
+    data: unknown;
+};
+type WebSocketRegister<T> = (emit: (payload: T) => void, error: (err: unknown) => void, complete: () => void) => () => void;
+/**
+ * Wraps a WebSocket as a GraphReFly producer source.
+ *
+ * Incoming socket messages are emitted as `DATA`; socket `error` emits `ERROR`; socket `close`
+ * emits `COMPLETE`. Teardown detaches listeners and optionally closes the socket.
+ *
+ * @category extra
+ */
+declare function fromWebSocket<T = unknown>(socket: WebSocketLike, opts?: ExtraOpts & {
+    parse?: (payload: unknown, event: unknown) => T;
+    closeOnTeardown?: boolean;
+}): Node<T>;
+declare function fromWebSocket<T = unknown>(register: WebSocketRegister<T>, opts?: ExtraOpts & {
+    parse?: (payload: unknown, event: unknown) => T;
+    closeOnTeardown?: boolean;
+}): Node<T>;
+/** Options for {@link toWebSocket}. */
+type ToWebSocketOptions<T> = {
+    /** Serialize DATA payloads before `socket.send(...)`. */
+    serialize?: (value: T) => string | ArrayBufferLike | Blob | ArrayBufferView;
+    /** Close socket when upstream emits COMPLETE. Default: `true`. */
+    closeOnComplete?: boolean;
+    /** Close socket when upstream emits ERROR. Default: `true`. */
+    closeOnError?: boolean;
+    /** Optional close code used when close is triggered by terminal tuples. */
+    closeCode?: number;
+    /** Optional close reason used when close is triggered by terminal tuples. */
+    closeReason?: string;
+    /** Structured callback — uses the unified {@link SinkTransportError} shape. */
+    onTransportError?: (event: SinkTransportError) => void;
+    /** Retry configuration — passed through to {@link reactiveSink}. */
+    retry?: ReactiveSinkHandle<T> extends infer _ ? Parameters<typeof reactiveSink<T>>[1]["retry"] : never;
+    /** Backpressure configuration — passed through to {@link reactiveSink}. */
+    backpressure?: Parameters<typeof reactiveSink<T>>[1]["backpressure"];
+    /** Reactive stop signal — when it emits any DATA / terminal, the sink tears down. */
+    stopOn?: Node<unknown>;
+};
+/**
+ * Forwards upstream `DATA` payloads to a WebSocket via `send`.
+ *
+ * Returns a {@link ReactiveSinkHandle} — every transport outcome (including
+ * socket `close` events) surfaces on the `errors` / `failed` / `sent` /
+ * `inFlight` companions.
+ *
+ * @category extra
+ */
+declare function toWebSocket<T>(source: Node<T>, socket: WebSocketLike, opts?: ToWebSocketOptions<T>): ReactiveSinkHandle<T>;
+/** Options for {@link fromWebSocketReconnect}. */
+type FromWebSocketReconnectOptions<T> = ExtraOpts & {
+    /** Optional parser applied to incoming messages. */
+    parse?: (payload: unknown, event: unknown) => T;
+    /** Max reconnect attempts. Default: `Infinity` (implied when `backoff` is set). */
+    maxRetries?: number;
+    /** Backoff strategy (ns) or preset name. Default: `"exponential"`. */
+    backoff?: Parameters<typeof retry>[1] extends infer O ? O extends {
+        backoff?: infer B;
+    } ? B : never : never;
+    /** Close the socket on teardown. Default: `true`. */
+    closeOnTeardown?: boolean;
+};
+/**
+ * Reconnecting WebSocket source — each connection attempt calls `factory` to
+ * obtain a fresh {@link WebSocketLike}; on `close` (treated as terminal
+ * `COMPLETE`), {@link retry} rebuilds the inner source and reconnects.
+ *
+ * For transient errors, {@link retry} retries with the configured
+ * backoff. On `maxRetries` exhaustion, terminal `ERROR` propagates.
+ *
+ * @param factory - Invoked per reconnect to create a fresh WebSocket.
+ * @param opts - Parse, retry, and close options.
+ *
+ * @example
+ * ```ts
+ * import { fromWebSocketReconnect } from "@graphrefly/graphrefly-ts";
+ * const ws$ = fromWebSocketReconnect(
+ *   () => new WebSocket("wss://example/stream"),
+ *   { backoff: "exponential", maxRetries: 10 },
+ * );
+ * ```
+ *
+ * @category extra
+ */
+declare function fromWebSocketReconnect<T = unknown>(factory: () => WebSocketLike, opts?: FromWebSocketReconnectOptions<T>): Node<T>;
+
+export { type AckableMessage, type AdapterHandlers, type BufferedSinkHandle, type CSVRow, type CheckpointToRedisOptions, type CheckpointToS3Options, type ClickHouseClientLike, type ClickHouseInsertClientLike, type ClickHouseRow, type DrizzleQueryLike, type FileWriterLike, type FromCSVOptions, type FromClickHouseWatchOptions, type FromDrizzleOptions, type FromHTTPOptions, type FromHTTPPollOptions, type FromHTTPStreamOptions, type FromKafkaOptions, type FromKyselyOptions, type FromMCPOptions, type FromNATSOptions, type FromNDJSONOptions, type FromOTelOptions, type FromPrismaOptions, type FromPrometheusOptions, type FromPulsarOptions, type FromRabbitMQOptions, type FromRedisStreamOptions, type FromSSEOptions, type FromSqliteOptions, type FromStatsDOptions, type FromSyslogOptions, type FromWebSocketReconnectOptions, type HTTPBundle, type KafkaConsumerLike, type KafkaMessage, type KafkaProducerLike, type KyselyQueryLike, type LokiClientLike, type LokiStream, type MCPClientLike, type MongoCollectionLike, type NATSClientLike, type NATSMessage, type NATSSubscriptionLike, type OTelBundle, type OTelLog, type OTelMetric, type OTelRegister, type OTelSpan, type ParseSSEStreamOptions, type PostgresClientLike, type PrismaModelLike, type PrometheusMetric, type PulsarConsumerLike, type PulsarMessage, type PulsarProducerLike, type RabbitMQChannelLike, type RabbitMQMessage, type RedisCheckpointClientLike, type RedisClientLike, type RedisStreamEntry, type S3ClientLike, type SSEEvent, type SinkHandle, type SinkTransportError, type SqliteDbLike, type SqliteIterableDbLike, type StatsDMetric, type StatsDRegister, type SyslogMessage, type SyslogRegister, type TempoClientLike, type ToCSVOptions, type ToClickHouseOptions, type ToFileOptions, type ToHTTPOptions, type ToKafkaOptions, type ToLokiOptions, type ToMongoOptions, type ToNATSOptions, type ToPostgresOptions, type ToPulsarOptions, type ToRabbitMQOptions, type ToRedisStreamOptions, type ToS3Options, type ToSSEOptions, type ToSqliteOptions, type ToTempoOptions, type ToWebSocketOptions, type WebSocketLike, type WebSocketMessageEventLike, type WebSocketRegister, type WebhookRegister, checkpointToRedis, checkpointToS3, csvRows, fromCSV, fromClickHouseWatch, fromDrizzle, fromHTTP, fromHTTPPoll, fromHTTPStream, fromKafka, fromKysely, fromMCP, fromNATS, fromNDJSON, fromOTel, fromPrisma, fromPrometheus, fromPulsar, fromRabbitMQ, fromRedisStream, fromSSE, fromSqlite, fromSqliteCursor, fromStatsD, fromSyslog, fromWebSocket, fromWebSocketReconnect, fromWebhook, ndjsonRows, parsePrometheusText, parseSSEStream, parseStatsD, parseSyslog, toCSV, toClickHouse, toFile, toHTTP, toKafka, toLoki, toMongo, toNATS, toPostgres, toPulsar, toRabbitMQ, toReadableStream, toRedisStream, toS3, toSSE, toSSEBytes, toSqlite, toTempo, toWebSocket };