@clickhouse/client 1.22.0 → 1.23.0-head.287977a.1

package/skills/clickhouse-js-node-rowbinary-parser/src/reader.ts

@@ -0,0 +1,68 @@
+/**
+ * Barrel re-export of the RowBinary reader, split by type family into the
+ * sibling modules. Import from here for everything in one place, or from a
+ * specific module (e.g. `./integers.js`, `./strings.js`) to pull in only the
+ * sub-parsers a given result actually needs — the latter is what a generated
+ * parser should do, copying just the modules its column types require.
+ *
+ * - core      — Cursor, Reader<T>, advance, NeedMoreData
+ * - varint    — readUVarint
+ * - integers  — readUInt8..readUInt256, readInt8..readInt256
+ * - bool / enums / floats
+ * - decimals  — DecimalValue, formatDecimal, readDecimal32..256
+ * - strings   — readString, readFixedString, readFixedStringBytes
+ * - uuid      — readUUID(+BigInt/HiLo), formatUUID(+Table)
+ * - ip        — readIPv4/6, formatIPv4/6
+ * - datetime / time / interval
+ * - composite — readArray/Map/Tuple/TupleNamed/Nullable/Variant/QBit
+ * - rows      — readRows
+ * - geo       — Point, readPoint/Ring/LineString/Polygon/MultiLineString/MultiPolygon/Geometry
+ * - dynamic   — readDynamic, readDynamicType
+ * - json      — readJSON
+ * - stream    — streamRowBatches, coalesceChunks
+ * - transparent / special wrappers (mostly documentation; see each file):
+ *   lowCardinality (readLowCardinality), simpleAggregateFunction
+ *   (readSimpleAggregateFunction), nested (readNested), nothing (readNothing),
+ *   aggregateFunction (readAggregateFunction)
+ *
+ * Runtime schema path — compile a reader from the type STRINGS rather than
+ * hand-/code-generating one. Use this when the column types are not known until
+ * the response arrives (or you just want a generic decoder); for a fixed,
+ * known schema the specialized straight-line reader is faster.
+ * - header   — readHeader: the RowBinaryWithNamesAndTypes preamble (column
+ *              names + type strings) off the cursor
+ * - compile  — astToReader: fold one parsed type AST (from
+ *              `@clickhouse/datatype-parser`) into a value Reader. AST in,
+ *              reader out — the type-to-combinator mapping, nothing else
+ * - rowBinaryWithNamesAndTypes — typeStringToReader (parse a type string +
+ *              fold) and compileRowBinaryWithNamesAndTypes (read the header,
+ *              compile every column, return a `readRows` driver for the rest of
+ *              the stream): the end-to-end runtime entry point
+ */
+export * from "./core.js";
+export * from "./varint.js";
+export * from "./integers.js";
+export * from "./bool.js";
+export * from "./enums.js";
+export * from "./floats.js";
+export * from "./decimals.js";
+export * from "./strings.js";
+export * from "./uuid.js";
+export * from "./ip.js";
+export * from "./datetime.js";
+export * from "./time.js";
+export * from "./interval.js";
+export * from "./composite.js";
+export * from "./rows.js";
+export * from "./geo.js";
+export * from "./dynamic.js";
+export * from "./json.js";
+export * from "./stream.js";
+export * from "./lowCardinality.js";
+export * from "./simpleAggregateFunction.js";
+export * from "./nested.js";
+export * from "./nothing.js";
+export * from "./aggregateFunction.js";
+export * from "./header.js";
+export * from "./compile.js";
+export * from "./rowBinaryWithNamesAndTypes.js";

package/skills/clickhouse-js-node-rowbinary-parser/src/rowBinaryWithNamesAndTypes.ts

@@ -0,0 +1,155 @@
+/**
+ * The `RowBinaryWithNamesAndTypes` entry point: read the header off a cursor,
+ * compile each column's type string into a reader, and hand back a driver that
+ * decodes the rest of the stream.
+ *
+ * This ties together the pieces: {@link readHeader} (wire), the parser
+ * (`@clickhouse/datatype-parser`), and {@link astToReader} (the AST → reader
+ * fold in `compile.ts`), then assembles a named-tuple row reader over the
+ * columns and a {@link readRows} driver for the row data.
+ */
+
+import { parseDataType } from "@clickhouse/datatype-parser";
+
+import type { Reader, Cursor } from "./core.js";
+import { readHeader } from "./header.js";
+import { readRows } from "./rows.js";
+import { astToReader, RowBinaryTypeError } from "./compile.js";
+
+/** One decoded row, keyed by column name. */
+export type Row = Record<string, unknown>;
+
+/**
+ * The product of compiling a `RowBinaryWithNamesAndTypes` header: the column
+ * metadata, the per-column readers, and — the headline — `readRows`, the
+ * {@link Reader} that decodes every remaining row of the stream.
+ */
+export interface CompiledStream {
+  /** Column names, in stream order (from the header). */
+  names: string[];
+  /** Column type strings, in stream order (from the header). */
+  types: string[];
+  /** One folded reader per column, in stream order. */
+  columnReaders: Reader<unknown>[];
+  /** Reads exactly one row into a `{ [name]: value }` object. */
+  readRow: Reader<Row>;
+  /**
+   * Reads the REST of the stream (all rows after the header) into an array.
+   * Streaming-aware via {@link readRows}: on a partial trailing row it rewinds
+   * to the last complete row and returns what it has.
+   */
+  readRows: Reader<Row[]>;
+}
+
+/**
+ * Parse one ClickHouse type string and fold it into a {@link Reader}. Throws a
+ * {@link RowBinaryTypeError} if the parser rejects the string (e.g. the
+ * deliberately unsupported `AggregateFunction` / `SimpleAggregateFunction`) —
+ * carrying the `typeString` and the parse `position`.
+ */
+export function typeStringToReader(typeStr: string): Reader<unknown> {
+  const result = parseDataType(typeStr);
+  if (!result.ok()) {
+    const err = result.error!;
+    throw new RowBinaryTypeError(
+      `cannot compile type ${JSON.stringify(typeStr)}: ${err.message}`,
+      { typeString: typeStr, position: err.position },
+    );
+  }
+  return astToReader(result.ast!);
+}
+
+/** Resolves a ClickHouse type string to a reader — `typeStringToReader` or a cache wrapping it. */
+export type TypeReaderResolver = (typeStr: string) => Reader<unknown>;
+
+/**
+ * Build an LRU-cached {@link typeStringToReader}. The full ClickHouse type
+ * STRING is a perfect cache key: two columns of the same type compile to the
+ * same reader, and a reader is stateless (it only ever touches the cursor it is
+ * handed), so one instance is safe to share across columns and across streams —
+ * a cache hit skips the parse + AST fold entirely.
+ *
+ * Worth it when you decode many `RowBinaryWithNamesAndTypes` responses whose
+ * schemas overlap (e.g. the same query run repeatedly): keep one cache and pass
+ * it to {@link compileRowBinaryWithNamesAndTypes}, so a recurring type is
+ * compiled once rather than once per response. A single response rarely repeats
+ * a type across its own columns, so the win is across calls, not within one.
+ *
+ * Classic Map-based LRU: a `Map` iterates in insertion order, so on a HIT we
+ * delete + re-set the entry to move it to the most-recently-used end, and on
+ * overflow we evict the oldest key (the first the `Map` yields). `maxSize` caps
+ * memory. A parse FAILURE is never cached — {@link typeStringToReader} throws
+ * before anything is stored — so fixing a bad type is not shadowed by a cached
+ * error.
+ */
+export function createTypeReaderCache(maxSize = 256): TypeReaderResolver {
+  const cache = new Map<string, Reader<unknown>>();
+  return (typeStr) => {
+    const cached = cache.get(typeStr);
+    if (cached !== undefined) {
+      // Touch on hit. A Map iterates in INSERTION order, not usage order — so on
+      // its own `keys().next()` would give the oldest-added key, not the
+      // least-recently-USED one. Deleting and re-inserting moves this key to the
+      // tail, which is what turns insertion order INTO recency order: every
+      // access (hit here, or miss below) lands the key at the tail, leaving the
+      // head as the genuine least-recently-used entry.
+      cache.delete(typeStr);
+      cache.set(typeStr, cached);
+      return cached;
+    }
+    const reader = typeStringToReader(typeStr); // may throw — then nothing is cached
+    cache.set(typeStr, reader);
+    if (cache.size > maxSize) {
+      // The head is the least-recently-used key (see touch-on-hit above), so it
+      // is the correct one to evict.
+      const lru = cache.keys().next().value;
+      if (lru !== undefined) cache.delete(lru);
+    }
+    return reader;
+  };
+}
+
+/**
+ * The headline entry point. Reads the `RowBinaryWithNamesAndTypes` header off
+ * `state`, compiles each column type into a combinator reader, and returns the
+ * column metadata plus the readers — including `readRows`, the reader for the
+ * REST of the stream. After this call the cursor sits at the first row, so:
+ *
+ *   const s = new Cursor(buf);
+ *   const { names, readRows } = compileRowBinaryWithNamesAndTypes(s);
+ *   const rows = readRows(s);   // decode every remaining row
+ *
+ * Pass `resolveType` to reuse readers across calls — e.g. a shared
+ * {@link createTypeReaderCache}. It defaults to {@link typeStringToReader}
+ * (compile every column afresh).
+ */
+export function compileRowBinaryWithNamesAndTypes(
+  state: Cursor,
+  resolveType: TypeReaderResolver = typeStringToReader,
+): CompiledStream {
+  const { names, types } = readHeader(state);
+  const columnReaders = types.map((t) => resolveType(t));
+
+  // Build the row reader POSITIONALLY — by column index, NOT by keying the
+  // readers on column name and handing them to `readTupleNamed`. The header is
+  // an ordered list and RowBinary has no row delimiter, so every row MUST read
+  // exactly these readers, in exactly this order. Keying readers by name first
+  // would corrupt the stream on legal-but-awkward headers:
+  //   - duplicate column names (e.g. two `SELECT 1 AS x, 2 AS x`) collapse to a
+  //     single entry in a `Record`, so fewer readers run than there are columns;
+  //   - integer-like names (`0`, `1`, …) are reordered ahead of string keys by
+  //     `Object.keys()`, so the readers would run out of header order.
+  // Either desyncs the cursor and misreads every subsequent row. Reading by
+  // index sidesteps both. The row OBJECT is still keyed by name; on a duplicate
+  // name the last column with that name wins in the object, but every column is
+  // still consumed off the wire in order, so the cursor stays in sync.
+  const readRow: Reader<Row> = (s) => {
+    const row: Row = {};
+    for (let i = 0; i < columnReaders.length; i++) {
+      row[names[i]!] = columnReaders[i]!(s);
+    }
+    return row;
+  };
+
+  return { names, types, columnReaders, readRow, readRows: readRows(readRow) };
+}

package/skills/clickhouse-js-node-rowbinary-parser/src/rows.ts

@@ -0,0 +1,58 @@
+import { NeedMoreData, type Reader } from "./core.js";
+
+/**
+ * Drive `readRow` over every row of a plain `RowBinary` result into an array.
+ * Curried: `readRows(readRow)` returns a `Reader<T[]>`. Rows are concatenated on
+ * the wire with no count, length prefix, or delimiter, so the result is exhausted
+ * only when the cursor reaches the buffer end.
+ *
+ * `readRow` must consume EXACTLY one row's bytes — a byte short or long compounds
+ * across rows and the cursor overshoots or never lands on `buf.length`. Returns
+ * `[]` for an empty buffer. When generating code, inline the per-column reads
+ * into the loop body:
+ *
+ *   function readRowsUser(s) {
+ *     const out = [];
+ *     while (s.pos < s.buf.length) {
+ *       out.push({ id: readUInt64(s), name: readString(s) });
+ *     }
+ *     return out;
+ *   }
+ *
+ * STREAMING (partial trailing row): a chunk of a still-arriving response may end
+ * mid-row. `pos` is committed only AFTER a row reads cleanly, so when a row
+ * starves and `readRow` throws {@link NeedMoreData}, this catches it, rewinds
+ * `pos` to the last complete row boundary, and returns the rows so far — never a
+ * half-built row. The cursor is left at the straddling row, a commit point the
+ * driver carries forward:
+ *
+ *   const drive = readRows(readRow);
+ *   let committed = 0;
+ *   for (const chunk of chunks) {              // chunk = growing prefix
+ *     const s = new Cursor(chunk);
+ *     s.pos = committed;
+ *     emit(drive(s));                          // complete rows in this chunk
+ *     committed = s.pos;                        // start of the straddling row
+ *   }
+ *
+ * On a complete buffer no read starves, so the catch never runs. Errors other
+ * than {@link NeedMoreData} are real decode faults and propagate. See also
+ * `streamRowBatches`, the async driver built on this.
+ */
+export function readRows<T>(readRow: Reader<T>): Reader<T[]> {
+  return (state) => {
+    const out: T[] = [];
+    let committed = state.pos;
+    try {
+      while (state.pos < state.buf.length) {
+        const row = readRow(state);
+        committed = state.pos; // row read cleanly — advance the commit point
+        out.push(row);
+      }
+    } catch (e) {
+      if (e !== NeedMoreData) throw e;
+      state.pos = committed; // drop the partial trailing row; resume next chunk
+    }
+    return out;
+  };
+}

package/skills/clickhouse-js-node-rowbinary-parser/src/simpleAggregateFunction.ts

@@ -0,0 +1,20 @@
+import { type Reader } from "./core.js";
+
+/**
+ * `SimpleAggregateFunction(func, T)` is TRANSPARENT in RowBinary: the column
+ * already holds a finished value of the underlying type `T` (the partial
+ * aggregate of a "simple" function — sum / min / max / groupArrayArray / … — is
+ * just a value of `T`), so it is encoded byte-for-byte the same as `T`. Decode
+ * the inner `T` directly.
+ *
+ * Do NOT confuse it with `AggregateFunction(func, T)`, whose value is an opaque
+ * serialized aggregation STATE with a function-specific binary layout — see
+ * `./aggregateFunction.js`.
+ *
+ * Identity combinator, documentation only:
+ *
+ *   readSimpleAggregateFunction(readUInt64) === readUInt64
+ */
+export const readSimpleAggregateFunction = <T>(
+  readValue: Reader<T>,
+): Reader<T> => readValue;

package/skills/clickhouse-js-node-rowbinary-parser/src/stream.ts

@@ -0,0 +1,276 @@
+import { type Reader, Cursor } from "./core.js";
+import { readRows } from "./rows.js";
+
+/** Empty buffer reused as the "no carry" sentinel between chunks. */
+const EMPTY_CHUNK = Buffer.alloc(0);
+
+/** Stats captured at the moment the small-chunk warning fires. */
+export interface SmallChunkStats {
+  /** Chunks consumed so far. */
+  chunks: number;
+  /** Rows decoded so far. */
+  rows: number;
+  /** `rows / chunks` — the ratio that tripped the threshold. */
+  rowsPerChunk: number;
+}
+
+/**
+ * Tuning for {@link streamRowBatches}'s small-chunk warning. Pass `false` to
+ * disable it, `true` / omit for the defaults, or an object to tune.
+ */
+export type WarnOnSmallChunks =
+  | boolean
+  | {
+      /**
+       * Warn when the running `rows / chunks` average drops below this. Default
+       * `2`: throw + restart re-decodes the partial trailing row on EVERY chunk,
+       * so once a chunk barely covers a row or two the re-scan dominates — the
+       * regime where `streamingRow.bench.ts` shows throw+restart losing to a lean
+       * generator. Keep it low so the warning only fires when chunks are
+       * genuinely too small, never on a healthy hundreds-of-rows-per-chunk stream.
+       */
+      minRowsPerChunk?: number;
+      /**
+       * Don't evaluate until this many chunks have been seen. Default `16`:
+       * lets the average settle and suppresses the warning on small results,
+       * where the gotcha doesn't bite (it only matters at megabytes / millions
+       * of rows). A stream that ends before this never warns.
+       */
+      warmupChunks?: number;
+      /** Where the warning goes. Default `console.warn`. */
+      warn?: (message: string, stats: SmallChunkStats) => void;
+    };
+
+/** Options for {@link streamRowBatches}. */
+export interface StreamRowBatchesOptions {
+  /**
+   * Diagnostic that catches a silent throughput killer: chunks so small that the
+   * throw+restart streaming strategy spends most of its time re-decoding the
+   * partial trailing row instead of making progress. Fires AT MOST ONCE per
+   * stream. On by default; see {@link WarnOnSmallChunks} to tune or disable.
+   *
+   * The fix it points at is usually upstream — raise the HTTP response's read
+   * size (Node sets the socket/stream `highWaterMark`; a fetch `Response.body`
+   * reader delivers larger chunks than a hand-rolled tiny read) into the
+   * tens–hundreds of KB range — or, when chunk size isn't yours to control,
+   * compose {@link coalesceChunks} in front to merge small chunks first.
+   */
+  warnOnSmallChunks?: WarnOnSmallChunks;
+}
+
+/**
+ * Stream a chunked `RowBinary` response into batches of decoded rows. This is
+ * the async front door built on {@link readRows}: feed it the byte chunks of an
+ * HTTP response (anything async-iterable — a Node `Readable`, `response.body`,
+ * etc.) and a per-row `Reader`, and `for await` the batches.
+ *
+ * One batch is yielded per incoming chunk — exactly the rows that completed
+ * within it — so batch size tracks chunk size, which the caller controls. A
+ * chunk that doesn't complete a new row yields nothing; its bytes are carried
+ * into the next chunk. Empty batches are never yielded.
+ *
+ * How it works (the carry-buffer driver):
+ *  - Join the leftover `carry` from the previous chunk to the new chunk, build a
+ *    state over the join, and run `readRows`. It decodes whole rows, stops cleanly
+ *    on the partial trailing row (catching `NeedMoreData`), and leaves `pos` at
+ *    that row's start.
+ *  - The unread tail `pos..end` becomes the next `carry` as a `subarray` VIEW,
+ *    NOT a copy. The joined buffer is owned entirely by this generator — it is
+ *    never yielded to the caller — so there is no aliasing hazard in keeping a
+ *    view into it, and we skip a per-chunk copy of the tail. The view is also
+ *    short-lived: the next chunk's `Buffer.concat` copies these bytes into a
+ *    fresh buffer, after which the old one is released.
+ *  - When the stream ends, any non-empty carry means the response was truncated
+ *    mid-row — a malformed stream — so it throws rather than silently dropping
+ *    bytes.
+ *
+ * `readRow` is a `Reader<T>` — write it as `(s) => ({ id: readUInt64(s),
+ * name: readString(s) })`. Build any configured/combinator readers ONCE (e.g.
+ * `const readRow = readTupleNamed({...})`) and reuse, rather than rebuilding them
+ * per chunk.
+ *
+ * ZERO-COPY NOTE: raw-bytes readers (`readUUID`/`readIPv6`/`readFixedStringBytes`
+ * and binary `String`) return views into the current chunk's joined buffer. Those
+ * stay valid as long as you hold the row objects, but are NOT views into one
+ * stable buffer across batches. If you retain them long-term, copy in `readRow`.
+ *
+ * BACKPRESSURE: this is a pull stream — the next chunk is only requested when the
+ * consumer asks for the next batch, so a slow consumer naturally throttles reading.
+ *
+ * The per-chunk bookkeeping for the small-chunk warning (two integer adds and a
+ * compare) runs once per CHUNK, not per row, so it is off every hot path; the
+ * default-on warning is documented in {@link StreamRowBatchesOptions}.
+ */
+export async function* streamRowBatches<T>(
+  chunks: AsyncIterable<Uint8Array>,
+  readRow: Reader<T>,
+  options?: StreamRowBatchesOptions,
+): AsyncGenerator<T[], void, undefined> {
+  const drive = readRows(readRow);
+  let carry: Buffer<ArrayBufferLike> = EMPTY_CHUNK;
+
+  // Resolve the warning config once, outside the loop.
+  const warnCfg = options?.warnOnSmallChunks;
+  const warnEnabled = warnCfg !== false;
+  const warnObj = typeof warnCfg === "object" ? warnCfg : undefined;
+  const minRowsPerChunk = warnObj?.minRowsPerChunk ?? 2;
+  const warmupChunks = warnObj?.warmupChunks ?? 16;
+  const warn = warnObj?.warn ?? ((message: string) => console.warn(message));
+  let chunkCount = 0;
+  let rowCount = 0;
+  let warned = false;
+
+  for await (const chunk of chunks) {
+    // Normalize to a Buffer without copying (a Uint8Array shares its ArrayBuffer).
+    const incoming = Buffer.isBuffer(chunk)
+      ? chunk
+      : Buffer.from(chunk.buffer, chunk.byteOffset, chunk.byteLength);
+    const work =
+      carry.length === 0 ? incoming : Buffer.concat([carry, incoming]);
+
+    const state = new Cursor(work);
+    const rows = drive(state);
+    if (rows.length > 0) yield rows;
+
+    // Carry the unread tail (the partial trailing row, if any) to the next
+    // chunk. A view, not a copy: we own `work` and never expose it, so keeping a
+    // subarray into it is safe; the next concat copies these bytes out.
+    carry = state.pos < work.length ? work.subarray(state.pos) : EMPTY_CHUNK;
+
+    if (warnEnabled && !warned) {
+      chunkCount++;
+      rowCount += rows.length;
+      const rowsPerChunk = rowCount / chunkCount;
+      if (chunkCount >= warmupChunks && rowsPerChunk < minRowsPerChunk) {
+        warned = true;
+        warn(
+          `RowBinary stream: chunks look too small — ${rowsPerChunk.toFixed(2)} rows/chunk over ${chunkCount} chunks. ` +
+            `Streaming throws + restarts the partial trailing row on every chunk, so tiny chunks spend most of their ` +
+            `time re-decoding instead of advancing. Increase the upstream read/highWaterMark to tens–hundreds of KB, ` +
+            `or compose coalesceChunks() in front of this stream to merge small chunks first.`,
+          { chunks: chunkCount, rows: rowCount, rowsPerChunk },
+        );
+      }
+    }
+  }
+  if (carry.length > 0) {
+    throw new Error(
+      `RowBinary stream ended mid-row: ${carry.length} trailing byte(s) left undecoded`,
+    );
+  }
+}
+
+/** A timeout result distinct from any `IteratorResult`. */
+const TIMED_OUT = Symbol("coalesceChunks.timeout");
+
+/**
+ * Coalesce (debounce) a chunk stream so each emitted chunk is at least `minSize`
+ * bytes — a filter you compose IN FRONT of {@link streamRowBatches} when the
+ * source delivers chunks too small to stream efficiently and you can't enlarge
+ * them upstream:
+ *
+ *   streamRowBatches(coalesceChunks(httpChunks, { minSize: 64 * 1024, timeoutMs: 50 }), readRow)
+ *
+ * WHY: the throw+restart streaming strategy re-decodes the partial trailing row
+ * on every chunk boundary, so the smaller the chunks the more time is wasted
+ * re-scanning (see `streamingRow.bench.ts`). Merging small chunks up front cuts
+ * the number of boundaries — and the backtracking with it.
+ *
+ * THE TRADE-OFF (latency vs. reallocation vs. backtracking): merging holds bytes
+ * back until enough accumulate, so it ADDS up to `timeoutMs` of latency to data
+ * that arrives in a trickle, and it COPIES via `Buffer.concat` to join the parts
+ * (one extra allocation per emitted chunk). In return the downstream parser
+ * backtracks far less. Tune `minSize` to the downstream sweet spot (tens–hundreds
+ * of KB) and `timeoutMs` to the latency you can spare.
+ *
+ * SEMANTICS:
+ *  - Accumulates incoming chunks until their total reaches `minSize`, then emits
+ *    the join immediately.
+ *  - A batch below `minSize` is flushed early when `timeoutMs` elapses from the
+ *    moment its FIRST byte arrived (the deadline is anchored, not reset per
+ *    chunk — a steady trickle of tiny chunks can't defer the flush forever).
+ *  - While nothing is buffered it blocks indefinitely for the next chunk: an idle
+ *    or finished stream is never charged the timeout.
+ *  - End of stream flushes whatever remains (possibly below `minSize`); a single
+ *    already-large-enough chunk passes straight through with no copy.
+ *
+ * It keeps exactly ONE outstanding pull on the source at a time (never calls
+ * `next()` while a prior result is still in flight), reads one chunk ahead so it
+ * can race arrival against the timer, and releases the source via `return()` if
+ * the consumer abandons it early.
+ */
+export async function* coalesceChunks(
+  source: AsyncIterable<Uint8Array>,
+  { minSize, timeoutMs }: { minSize: number; timeoutMs: number },
+): AsyncGenerator<Buffer, void, undefined> {
+  const it = source[Symbol.asyncIterator]();
+  // The single in-flight pull. Read one ahead so we always have a promise to
+  // race the timer against; never start a second next() before this resolves.
+  let pull = it.next();
+  let parts: Buffer[] = [];
+  let buffered = 0;
+  let deadline = 0; // ms timestamp; armed when the first byte enters an empty batch
+
+  const asBuffer = (u8: Uint8Array): Buffer =>
+    Buffer.isBuffer(u8)
+      ? u8
+      : Buffer.from(u8.buffer, u8.byteOffset, u8.byteLength);
+
+  const flush = (): Buffer => {
+    // One part: hand it back as-is (no concat, no copy). Many: join them.
+    const out = parts.length === 1 ? parts[0]! : Buffer.concat(parts, buffered);
+    parts = [];
+    buffered = 0;
+    return out;
+  };
+
+  const take = (u8: Uint8Array): void => {
+    const b = asBuffer(u8);
+    parts.push(b);
+    buffered += b.length;
+  };
+
+  try {
+    while (true) {
+      if (buffered === 0) {
+        // Nothing buffered: block for the next chunk with no timeout.
+        const r = await pull;
+        if (r.done) return;
+        take(r.value);
+        deadline = Date.now() + timeoutMs;
+        pull = it.next();
+        if (buffered >= minSize) yield flush();
+        continue;
+      }
+
+      // Below minSize with bytes in hand: race the next chunk against the time
+      // left on this batch's anchored deadline.
+      const remaining = deadline - Date.now();
+      if (remaining <= 0) {
+        yield flush();
+        continue;
+      }
+      let timer: ReturnType<typeof setTimeout> | undefined;
+      const timeout = new Promise<typeof TIMED_OUT>((resolve) => {
+        timer = setTimeout(() => resolve(TIMED_OUT), remaining);
+      });
+      const r = await Promise.race([pull, timeout]);
+      clearTimeout(timer); // no-op if it already fired; frees the loop otherwise
+      if (r === TIMED_OUT) {
+        // pull is STILL outstanding — keep it; just flush what we have so far.
+        yield flush();
+        continue;
+      }
+      if (r.done) {
+        yield flush(); // emit the tail; stream is over
+        return;
+      }
+      take(r.value);
+      pull = it.next();
+      if (buffered >= minSize) yield flush();
+    }
+  } finally {
+    // Consumer broke out early (break/throw): let the source clean up.
+    if (typeof it.return === "function") await it.return();
+  }
+}

package/skills/clickhouse-js-node-rowbinary-parser/src/strings.ts

@@ -0,0 +1,55 @@
+import { type Reader, Cursor, advance } from "./core.js";
+import { readUVarint } from "./varint.js";
+
+/**
+ * Read a `String`: a varint byte-length prefix followed by that many bytes,
+ * decoded as UTF-8.
+ *
+ * NOTE: ClickHouse `String` is arbitrary bytes, not guaranteed UTF-8. For binary
+ * columns, read `state.buf.subarray(start, start + len)` and skip the decode to
+ * keep the raw bytes.
+ */
+export function readString(state: Cursor): string {
+  const len = readUVarint(state);
+  const start = advance(state, len);
+  return state.buf.toString("utf8", start, start + len);
+}
+
+/**
+ * Read a `FixedString(N)`: exactly `size` raw bytes, decoded as UTF-8. Curried:
+ * `readFixedString(N)` returns the reader.
+ *
+ * The value is right-padded with NUL bytes to `size`; those trailing `\x00` are
+ * part of the stored value and are preserved here. Trim them
+ * (`.replace(/\x00+$/, "")`) only if your column holds NUL-terminated text.
+ *
+ * ClickHouse server returns `FixedString`s in JSON with the trailing NULs,
+ * therefore this reader preserves them as well.
+ */
+export function readFixedString(size: number): Reader<string> {
+  return (state) => {
+    const start = advance(state, size);
+    return state.buf.toString("utf8", start, start + size);
+  };
+}
+
+/**
+ * Read a `FixedString(N)` as raw bytes (no UTF-8 decode) — for binary columns.
+ * Curried: `readFixedStringBytes(N)` returns the reader. Returns a zero-copy
+ * view: no allocation, but the slice shares memory with the response, so
+ * retaining any one slice pins the entire chunk buffer in memory.
+ *
+ * SAFE TO TOGGLE — if the bytes outlive the row/response, return an independent
+ * copy instead so the chunk can be freed:
+ *
+ *   // return Buffer.from(state.buf.subarray(start, start + size));
+ *
+ * Make an educated tradeoff: view (default) when consumed immediately, a copy
+ * when retained.
+ */
+export function readFixedStringBytes(size: number): Reader<Buffer> {
+  return (state) => {
+    const start = advance(state, size);
+    return state.buf.subarray(start, start + size);
+  };
+}