@clickhouse/client 1.22.0 → 1.23.0-head.c8dc8d8.1

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);
+  };
+}

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

@@ -0,0 +1,61 @@
+import { type Reader, Cursor } from "./core.js";
+import { readInt32, readInt64 } from "./integers.js";
+
+/** Semantic alias for `number` marking a seconds value (see {@link readTime}). */
+export type Seconds = number;
+
+/**
+ * A signed sub-second duration kept lossless as its raw parts: the value is
+ * `ticks / 10 ** precision` seconds. Used by `Time64` (a time-of-day duration,
+ * which has no natural JS type), carrying the precision so nothing is lost.
+ */
+export type ScaledTicks = readonly [ticks: bigint, precision: number];
+
+/**
+ * Read a `Time`: 4-byte signed `Int32` seconds-of-day (range ±999:59:59).
+ * Returns the raw seconds; pass it to {@link formatTime}.
+ */
+export function readTime(state: Cursor): Seconds {
+  return readInt32(state);
+}
+
+/**
+ * Read a `Time64(P)`: 8-byte signed `Int64` count of `10^-P`-second ticks.
+ * Curried: `readTime64(P)` returns the reader. Returns `[ticks, precision]` (a
+ * {@link ScaledTicks}); pass it to {@link formatTime64}.
+ */
+export function readTime64(precision: number): Reader<ScaledTicks> {
+  return (state) => [readInt64(state), precision];
+}
+
+/**
+ * Format a `Time` value (signed seconds-of-day) as "[-]HH:MM:SS". The hour
+ * field can exceed two digits (the range is ±999:59:59).
+ */
+export function formatTime(seconds: Seconds): string {
+  const sign = seconds < 0 ? "-" : "";
+  const s = Math.abs(seconds);
+  const hh = Math.floor(s / 3600);
+  const mm = Math.floor((s % 3600) / 60);
+  const ss = s % 60;
+  return `${sign}${String(hh).padStart(2, "0")}:${String(mm).padStart(2, "0")}:${String(ss).padStart(2, "0")}`;
+}
+
+/**
+ * Format a `Time64` [ticks, precision] (signed sub-second time-of-day) as
+ * "[-]HH:MM:SS[.fff]".
+ */
+export function formatTime64([ticks, precision]: ScaledTicks): string {
+  const sign = ticks < 0n ? "-" : "";
+  const t = ticks < 0n ? -ticks : ticks;
+  const scale = 10n ** BigInt(precision);
+  const totalSec = Number(t / scale);
+  const frac = t % scale;
+  const hh = Math.floor(totalSec / 3600);
+  const mm = Math.floor((totalSec % 3600) / 60);
+  const ss = totalSec % 60;
+  const base = `${sign}${String(hh).padStart(2, "0")}:${String(mm).padStart(2, "0")}:${String(ss).padStart(2, "0")}`;
+  return precision > 0
+    ? `${base}.${frac.toString().padStart(precision, "0")}`
+    : base;
+}

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

@@ -0,0 +1,153 @@
+import { Cursor, advance } from "./core.js";
+
+/**
+ * `UUID_HEX16[b]` packs the two lowercase ASCII hex chars of byte `b`, low char
+ * in the low byte. Drives the lookup-table UUID formatter {@link formatUUIDTable}.
+ */
+const UUID_HEX16 = new Uint16Array(256);
+for (let b = 0; b < 256; b++) {
+  const hex = b.toString(16).padStart(2, "0");
+  UUID_HEX16[b] = hex.charCodeAt(0) | (hex.charCodeAt(1) << 8);
+}
+
+/**
+ * Reusable 36-byte scratch for {@link formatUUIDTable}. The four `-` separators
+ * are written once and never touched again; each call overwrites only the 32
+ * hex slots, then copies the bytes out as a string.
+ */
+const UUID_OUT = Buffer.alloc(36);
+UUID_OUT[8] = UUID_OUT[13] = UUID_OUT[18] = UUID_OUT[23] = 0x2d; // '-'
+
+/**
+ * Read a `UUID`: 16 raw bytes (two little-endian `UInt64` halves on the wire).
+ * Returns a zero-copy view; pass it to {@link formatUUID} for the canonical
+ * `xxxxxxxx-...` string.
+ *
+ * The view shares memory with the response buffer, so keeping it alive pins the
+ * whole chunk; copy with `Buffer.from(...)` if it must outlive the row.
+ *
+ * FAST ALTERNATIVE: if you stringify every UUID, use {@link formatUUIDTable}
+ * (lookup table, no BigInt, ~1.6x faster).
+ */
+export function readUUID(state: Cursor): Buffer {
+  const start = advance(state, 16);
+  return state.buf.subarray(start, start + 16);
+}
+
+/**
+ * Read a `UUID` as a single 128-bit `bigint` (`hi << 64 | lo`) — useful for
+ * numeric storage, comparison, or de-duplication without a string.
+ *
+ * Reads the halves with `DataView.getBigUint64` rather than
+ * `Buffer.readBigUInt64LE`: V8 inlines the DataView accessors, measurably faster
+ * for 8-byte reads. For the canonical string, use {@link readUUID} + {@link formatUUID}.
+ */
+export function readUUIDBigInt(state: Cursor): bigint {
+  const start = advance(state, 16);
+  const hi = state.view.getBigUint64(start, true);
+  const lo = state.view.getBigUint64(start + 8, true);
+  return (hi << 64n) | lo;
+}
+
+/**
+ * Read a `UUID` as its two raw little-endian `UInt64` halves, `[hi, lo]` — the
+ * faithful wire split with no combining work. Cheaper than {@link readUUIDBigInt}
+ * (skips `hi << 64 | lo`) and a compact two-value key for comparison/dedup. For
+ * the canonical string, use {@link readUUID} + {@link formatUUID}.
+ */
+export function readUUIDHiLo(state: Cursor): [hi: bigint, lo: bigint] {
+  const start = advance(state, 16);
+  const hi = state.view.getBigUint64(start, true);
+  const lo = state.view.getBigUint64(start + 8, true);
+  return [hi, lo];
+}
+
+/**
+ * Format a `UUID` (raw 16 bytes from {@link readUUID}) as the canonical
+ * `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` string.
+ *
+ * THE TRAP: ClickHouse stores a UUID as two little-endian `UInt64` halves (high
+ * then low), so each half is byte-reversed vs the text form. Reading each half
+ * with `readBigUInt64LE` undoes that; concatenating high then low gives the 32
+ * canonical hex digits. (Hexing the 16 bytes in wire order scrambles the value.)
+ * Kept aside from the read so the hot path can skip stringifying when raw bytes
+ * suffice.
+ *
+ * FAST ALTERNATIVE: to format every value, {@link formatUUIDTable} does the same
+ * via a byte->hex lookup table with no BigInt (~1.6x faster).
+ */
+export function formatUUID(b: Buffer): string {
+  const hex = ((b.readBigUInt64LE(0) << 64n) | b.readBigUInt64LE(8))
+    .toString(16)
+    .padStart(32, "0");
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+
+/**
+ * Fast {@link formatUUID}: same canonical string via a byte -> two-hex-char
+ * lookup table (`UUID_HEX16`) written into a reused 36-byte buffer (`UUID_OUT`,
+ * dashes preset), no BigInt, no slicing. ~1.6x faster (see `readUUID.bench.ts`).
+ * Takes the raw 16 bytes from {@link readUUID}.
+ *
+ * Same byte-reversal as formatUUID: emit the high half in reverse (`b[7]..b[0]`)
+ * then the low half (`b[15]..b[8]`).
+ *
+ * SAFE TO TOGGLE — opt-in fast formatter, not the default. `UUID_OUT` is shared
+ * scratch, so NOT reentrant; safe for synchronous formatting because the bytes
+ * are copied into the returned string before the next call (don't alias
+ * `UUID_OUT`). Worth it only when you stringify every UUID.
+ */
+export function formatUUIDTable(b: Buffer): string {
+  let p: number;
+  // High half: bytes b[7]..b[0] -> hex positions 0..7 (chars 0..15).
+  p = UUID_HEX16[b[7]!]!;
+  UUID_OUT[0] = p & 0xff;
+  UUID_OUT[1] = p >>> 8;
+  p = UUID_HEX16[b[6]!]!;
+  UUID_OUT[2] = p & 0xff;
+  UUID_OUT[3] = p >>> 8;
+  p = UUID_HEX16[b[5]!]!;
+  UUID_OUT[4] = p & 0xff;
+  UUID_OUT[5] = p >>> 8;
+  p = UUID_HEX16[b[4]!]!;
+  UUID_OUT[6] = p & 0xff;
+  UUID_OUT[7] = p >>> 8;
+  p = UUID_HEX16[b[3]!]!;
+  UUID_OUT[9] = p & 0xff;
+  UUID_OUT[10] = p >>> 8;
+  p = UUID_HEX16[b[2]!]!;
+  UUID_OUT[11] = p & 0xff;
+  UUID_OUT[12] = p >>> 8;
+  p = UUID_HEX16[b[1]!]!;
+  UUID_OUT[14] = p & 0xff;
+  UUID_OUT[15] = p >>> 8;
+  p = UUID_HEX16[b[0]!]!;
+  UUID_OUT[16] = p & 0xff;
+  UUID_OUT[17] = p >>> 8;
+  // Low half: bytes b[15]..b[8] -> hex positions 8..15 (chars 19..35).
+  p = UUID_HEX16[b[15]!]!;
+  UUID_OUT[19] = p & 0xff;
+  UUID_OUT[20] = p >>> 8;
+  p = UUID_HEX16[b[14]!]!;
+  UUID_OUT[21] = p & 0xff;
+  UUID_OUT[22] = p >>> 8;
+  p = UUID_HEX16[b[13]!]!;
+  UUID_OUT[24] = p & 0xff;
+  UUID_OUT[25] = p >>> 8;
+  p = UUID_HEX16[b[12]!]!;
+  UUID_OUT[26] = p & 0xff;
+  UUID_OUT[27] = p >>> 8;
+  p = UUID_HEX16[b[11]!]!;
+  UUID_OUT[28] = p & 0xff;
+  UUID_OUT[29] = p >>> 8;
+  p = UUID_HEX16[b[10]!]!;
+  UUID_OUT[30] = p & 0xff;
+  UUID_OUT[31] = p >>> 8;
+  p = UUID_HEX16[b[9]!]!;
+  UUID_OUT[32] = p & 0xff;
+  UUID_OUT[33] = p >>> 8;
+  p = UUID_HEX16[b[8]!]!;
+  UUID_OUT[34] = p & 0xff;
+  UUID_OUT[35] = p >>> 8;
+  return UUID_OUT.toString("latin1");
+}

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

@@ -0,0 +1,70 @@
+import { Cursor, advance } from "./core.js";
+
+/**
+ * Read a LEB128 unsigned varint (used for string/array lengths).
+ *
+ * Returns a JS `number`, so it is NOT bigint-friendly: only values up to
+ * `Number.MAX_SAFE_INTEGER` (2^53 - 1) are representable exactly. A varint
+ * larger than that throws rather than silently losing precision. RowBinary
+ * lengths never approach this in practice.
+ *
+ * The loop is unrolled: each byte carries 7 bits, so its place value is the
+ * constant 2^(7*k). The overwhelmingly common 1–2 byte case costs one or two
+ * reads and a compare.
+ *
+ * Multipliers must stay as `*` (not `<<`): JS bitwise shift is 32-bit and would wrap past bit 31.
+ *
+ * SAFE TO TOGGLE — how many bytes to handle:
+ * - If you know the maximum blob/array size, keep only the steps you need and
+ *   delete the rest along with the overflow guard. E.g. lengths < 2^28 fit in
+ *   4 bytes, so everything below the `* 268435456` step can go.
+ * - Keep all eight steps (the default) when lengths are untrusted.
+ * If you genuinely need lengths beyond 2^53, create a bigint version of this
+ * function with a bigint accumulator instead of removing the guard.
+ *
+ * OPTIMIZATION HINT — for a known invariant, emit a dedicated named variant
+ * rather than toggling here. E.g. a `readUVarint32` for lengths guaranteed to be
+ * 32-bit would unroll only the first five bytes and throw past 2^32 - 1.
+ */
+export function readUVarint(state: Cursor): number {
+  // Each byte reserves its space through `advance(1)` (the bounds check), but
+  // the read itself stays inlined as `state.buf[...]` rather than calling
+  // readUInt8 — this is the hottest loop in the reader.
+  let byte = state.buf[advance(state, 1)]!;
+  if (byte < 0x80) return byte; // 1 byte  -> 2^0
+  let result = byte & 0x7f;
+
+  byte = state.buf[advance(state, 1)]!;
+  if (byte < 0x80) return result + byte * 128; // 2^7
+  result += (byte & 0x7f) * 128;
+
+  byte = state.buf[advance(state, 1)]!;
+  if (byte < 0x80) return result + byte * 16384; // 2^14
+  result += (byte & 0x7f) * 16384;
+
+  byte = state.buf[advance(state, 1)]!;
+  if (byte < 0x80) return result + byte * 2097152; // 2^21
+  result += (byte & 0x7f) * 2097152;
+
+  byte = state.buf[advance(state, 1)]!;
+  if (byte < 0x80) return result + byte * 268435456; // 2^28
+  result += (byte & 0x7f) * 268435456;
+
+  byte = state.buf[advance(state, 1)]!;
+  if (byte < 0x80) return result + byte * 34359738368; // 2^35
+  result += (byte & 0x7f) * 34359738368;
+
+  byte = state.buf[advance(state, 1)]!;
+  if (byte < 0x80) return result + byte * 4398046511104; // 2^42
+  result += (byte & 0x7f) * 4398046511104;
+
+  // 8th byte: only its low 4 payload bits (bits 49..52) fit under 2^53. A larger
+  // payload, or a continuation bit signalling a 9th byte, overflows MAX_SAFE_INTEGER.
+  byte = state.buf[advance(state, 1)]!;
+  if (byte > 0x0f) {
+    throw new RangeError(
+      "RowBinary: varint exceeds Number.MAX_SAFE_INTEGER (2^53 - 1)",
+    );
+  }
+  return result + byte * 562949953421312; // 2^49
+}