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

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

@@ -0,0 +1,34 @@
+import { type Reader } from "./core.js";
+
+/**
+ * `AggregateFunction(func, T…)` holds an OPAQUE serialized aggregation STATE
+ * (what `-State` combinators produce). In RowBinary this state is written RAW,
+ * with **NO length prefix** and a layout entirely specific to `func` (and to the
+ * ClickHouse version): `sumState(UInt64)` is 8 bytes, `uniqState(...)` is a
+ * variable-length hash-set blob, etc.
+ *
+ * So it cannot be decoded generically (there is no schema in the bytes) and
+ * cannot even be SKIPPED generically (there is no length to skip past) — without
+ * knowing `func`'s exact byte layout you cannot find where it ends, and every
+ * later column in the row misaligns. There is therefore NO generic reader.
+ *
+ * Fix it server-side (RECOMMENDED): finalize with the `-Merge` combinator or
+ * `finalizeAggregation()` in SQL so the column becomes a normal value
+ * (`sum` -> `UInt64`, `uniq` -> `UInt64`, `avg` -> `Float64`, …) and use the
+ * matching reader. Never ship raw `-State` columns to the client unless you
+ * intend to merge them later.
+ *
+ * ESCAPE HATCH: a few functions' state IS just a value of a known type (e.g.
+ * `sumState(UInt64)` is literally that `UInt64`), so you may decode it as that
+ * type — fragile and version-specific; only when you truly know the layout. See
+ * `tests/aggregateFunction.test.ts`.
+ *
+ * This reader throws to stop a generic parser from silently misaligning the row.
+ */
+export const readAggregateFunction: Reader<never> = () => {
+  throw new Error(
+    "RowBinary: AggregateFunction is opaque, unframed aggregation state with no " +
+      "length prefix — not generically decodable or skippable. Finalize server-side " +
+      "(-Merge / finalizeAggregation()) and decode the concrete result type instead.",
+  );
+};

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

@@ -0,0 +1,10 @@
+import { Cursor } from "./core.js";
+import { readUInt8 } from "./integers.js";
+
+/**
+ * Read a `Bool`: 1 byte, stored as `UInt8` (`0` = false, `1` = true). Treats any
+ * non-zero byte as true.
+ */
+export function readBool(state: Cursor): boolean {
+  return readUInt8(state) !== 0;
+}

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

@@ -0,0 +1,125 @@
+/**
+ * Streaming COLUMNAR decode for an all-numeric, fixed-width RowBinary result —
+ * one concrete example reader that ties together the three wins this skill keeps
+ * pointing at. The schema is hard-coded on purpose: a real columnar reader is
+ * MONOMORPHIZED to its result, so the row loop is straight-line constant-offset
+ * reads with no per-field dispatch. Generate one shaped like this per schema.
+ *
+ * The example schema (`sensor_id UInt32, ts DateTime64(3), value Float64,
+ * quality Float32, status UInt8`) — every column fixed-width, stride 25 bytes:
+ *
+ *   sensor_id  UInt32         @ o+0   getUint32     -> Uint32Array
+ *   ts         DateTime64(3)  @ o+4   2x getUint32  -> BigInt64Array (raw ms ticks)
+ *   value      Float64        @ o+12  getFloat64    -> Float64Array
+ *   quality    Float32        @ o+20  getFloat32    -> Float32Array
+ *   status     UInt8          @ o+24  buf[o+24]     -> Uint8Array
+ *
+ * The three wins:
+ *
+ *  1. COLUMNAR (struct-of-arrays). One typed array per column, not one object
+ *     per row — removes the per-row object / `Date` / number-boxing allocation
+ *     that dominates a numeric decode (~4x in plain JS; see `src/examples/iot.ts`
+ *     and `tests/iot.columnar.bench.ts`). Keep `ts` as raw `BigInt64Array` ticks
+ *     and make a `Date` lazily, per displayed row — never allocate 50k `Date`s.
+ *     The `Int64` column is itself filled WITHOUT allocating a bigint per row:
+ *     copy the two little-endian 32-bit words straight into a `Uint32Array` view
+ *     over its buffer (`getBigInt64` would box a bigint each row); the bigint is
+ *     materialized lazily, only when the consumer reads `ts[i]`.
+ *
+ *  2. TRANSFERABLE. Each column is a fresh, exactly-sized typed array that OWNS
+ *     its `ArrayBuffer` at offset 0, so a batch ships to a Worker / WASM kernel
+ *     zero-copy: `postMessage(batch, columns.map(c => c.buffer))`.
+ *
+ *  3. RESPECTS INCOMPLETE BUFFERS (streaming). Because the stride is constant,
+ *     honoring a partial trailing row is pure ARITHMETIC: the number of complete
+ *     rows in the buffer is `(work.length / STRIDE) | 0`. No `advance()`, no
+ *     `NeedMoreData`, no throw/restart — the leftover `work.length % STRIDE` bytes
+ *     just carry to the next chunk. Strictly cheaper than the row-oriented
+ *     `streamRowBatches`, which re-decodes the partial row on every boundary.
+ *
+ * SCOPE: fixed-width numeric columns only — the ClickHouse types with a 1:1
+ * native TypedArray (`Int8/16/32/64`, `UInt8/16/32/64`, `Float32/64`). Anything
+ * whose value isn't one native-typed number has no constant stride to divide by
+ * (`String`/`Array`/`Map`/`Tuple`) or no 1:1 array (`Int128`+, `Decimal*`,
+ * `BFloat16`); decode those row-wise. `Bool`/`Enum`/`Date*`/`DateTime*` ride
+ * their underlying int here for the RAW value.
+ */
+
+/** One decoded batch of the example schema: `rows` complete rows, one typed array per column. */
+export interface SensorColumnBatch {
+  /** Number of complete rows decoded in this batch. */
+  rows: number;
+  columns: {
+    sensor_id: Uint32Array;
+    ts: BigInt64Array; // raw DateTime64(3) ms ticks
+    value: Float64Array;
+    quality: Float32Array;
+    status: Uint8Array;
+  };
+}
+
+/** Byte stride of one fixed-width row: 4 + 8 + 8 + 4 + 1. */
+const STRIDE = 25;
+
+const EMPTY_CHUNK = Buffer.alloc(0);
+
+/**
+ * Stream a chunked RowBinary response of the example schema into columnar
+ * batches: one `{ rows, columns }` per incoming chunk, holding exactly the rows
+ * that completed within it.
+ *
+ * BACKPRESSURE: a pull stream — the next chunk is requested only when the
+ * consumer asks for the next batch. SMALL CHUNKS: tiny chunks mean tiny batches
+ * (more allocations, worse Worker amortization); compose `coalesceChunks` (from
+ * `./stream.js`) in front to merge them up to a target size first.
+ */
+export async function* streamSensorColumns(
+  chunks: AsyncIterable<Uint8Array>,
+): AsyncGenerator<SensorColumnBatch, void, undefined> {
+  let carry: Buffer = EMPTY_CHUNK;
+  for await (const chunk of chunks) {
+    // Wrap as a Buffer VIEW over the chunk's bytes — no copy (a Buffer made from
+    // an ArrayBuffer slice shares it). We own the chunk for the life of this
+    // generator, so holding a view into it is safe.
+    const incoming = Buffer.from(
+      chunk.buffer,
+      chunk.byteOffset,
+      chunk.byteLength,
+    );
+    const work =
+      carry.length === 0 ? incoming : Buffer.concat([carry, incoming]);
+
+    // Complete rows available right now — pure arithmetic, since STRIDE is fixed.
+    const n = (work.length / STRIDE) | 0;
+    if (n > 0) {
+      const view = new DataView(work.buffer, work.byteOffset, work.byteLength);
+      const sensor_id = new Uint32Array(n);
+      const ts = new BigInt64Array(n);
+      // Uint32 view over ts's OWN bytes: 2 little-endian words per Int64,
+      // [lo, hi, lo, hi, ...]. Filling ts through this view copies the raw bytes
+      // and skips the per-row bigint allocation `getBigInt64` would force; the
+      // bigint is materialized lazily, only for rows the consumer indexes.
+      const tsWords = new Uint32Array(ts.buffer);
+      const value = new Float64Array(n);
+      const quality = new Float32Array(n);
+      const status = new Uint8Array(n);
+      for (let i = 0, o = 0; i < n; i++, o += STRIDE) {
+        sensor_id[i] = view.getUint32(o, true); // UInt32        @ o+0
+        // DateTime64(3) Int64 @ o+4: two LE 32-bit words, no bigint allocated.
+        tsWords[i * 2] = view.getUint32(o + 4, true); // low word
+        tsWords[i * 2 + 1] = view.getUint32(o + 8, true); // high word
+        value[i] = view.getFloat64(o + 12, true); // Float64       @ o+12
+        quality[i] = view.getFloat32(o + 20, true); // Float32       @ o+20
+        status[i] = work[o + 24]!; // UInt8         @ o+24
+      }
+      yield { rows: n, columns: { sensor_id, ts, value, quality, status } };
+    }
+    // Carry the partial trailing row (if any) to the next chunk.
+    carry = work.subarray(n * STRIDE);
+  }
+  if (carry.length > 0) {
+    throw new Error(
+      `RowBinary stream ended mid-row: ${carry.length} trailing byte(s) left undecoded`,
+    );
+  }
+}

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

@@ -0,0 +1,318 @@
+/**
+ * The fold: turn a parsed ClickHouse data-type AST (from
+ * `@clickhouse/datatype-parser`) into a RowBinary value {@link Reader}.
+ *
+ * AST in, reader out — nothing else. Reading the `RowBinaryWithNamesAndTypes`
+ * header, parsing type strings, and assembling a row reader live in
+ * `rowBinaryWithNamesAndTypes.ts`; this module is just the type-to-reader
+ * mapping.
+ *
+ * It composes the existing GENERIC curried combinators at runtime, exactly as a
+ * hand-written reader would — no code generation and no monomorphization (those
+ * are the deliberate next step; see the `MONOMORPHIZE` notes throughout the
+ * combinator modules). The shape mirrors {@link readDynamicType} in
+ * `dynamic.ts`, which performs the same "type → Reader" mapping but driven by
+ * ClickHouse's BINARY type encoding rather than the textual type's AST.
+ */
+
+import { NodeKind, type Node } from "@clickhouse/datatype-parser";
+
+import type { Reader } from "./core.js";
+import {
+  readInt8,
+  readInt16,
+  readInt32,
+  readInt64,
+  readInt128,
+  readInt256,
+  readUInt8,
+  readUInt16,
+  readUInt32,
+  readUInt64,
+  readUInt128,
+  readUInt256,
+} from "./integers.js";
+import { readFloat32, readFloat64, readBFloat16 } from "./floats.js";
+import { readBool } from "./bool.js";
+import { readString, readFixedString } from "./strings.js";
+import { readUUID } from "./uuid.js";
+import { readIPv4, readIPv6 } from "./ip.js";
+import {
+  readDate,
+  readDate32,
+  readDateTime,
+  readDateTime64,
+} from "./datetime.js";
+import { readTime, readTime64 } from "./time.js";
+import { readInterval } from "./interval.js";
+import {
+  readDecimal32,
+  readDecimal64,
+  readDecimal128,
+  readDecimal256,
+} from "./decimals.js";
+import { readEnum8, readEnum16 } from "./enums.js";
+import {
+  readArray,
+  readMap,
+  readNullable,
+  readTuple,
+  readTupleNamed,
+  readVariant,
+  readQBit,
+} from "./composite.js";
+import { readLowCardinality } from "./lowCardinality.js";
+import { readNested } from "./nested.js";
+import { readNothing } from "./nothing.js";
+import {
+  readPoint,
+  readRing,
+  readLineString,
+  readPolygon,
+  readMultiLineString,
+  readMultiPolygon,
+  readGeometry,
+} from "./geo.js";
+import { readJSON } from "./json.js";
+import { readDynamic } from "./dynamic.js";
+
+/**
+ * Thrown when a ClickHouse type cannot be turned into a RowBinary reader —
+ * either the type string did not parse, or the parsed type is unsupported or
+ * malformed for RowBinary decoding (`AggregateFunction`, a missing argument, a
+ * malformed `Nested(...)`, …).
+ *
+ * A dedicated class so callers can `catch (e) { if (e instanceof
+ * RowBinaryTypeError) … }` and branch on a bad-type error specifically rather
+ * than string-matching a generic `Error`. Note the standalone
+ * `@clickhouse/datatype-parser` is itself NON-throwing (it returns a
+ * `ParseResult`); this is the error the compile layer raises on top of it.
+ */
+export class RowBinaryTypeError extends Error {
+  /** The full ClickHouse type string being compiled, when the throw site knows it. */
+  readonly typeString?: string;
+  /**
+   * Byte offset into `typeString` where parsing stopped — set for PARSE
+   * failures (from the underlying parser), undefined for fold-time errors.
+   */
+  readonly position?: number;
+
+  constructor(
+    message: string,
+    options: { typeString?: string; position?: number } = {},
+  ) {
+    super(message);
+    this.name = "RowBinaryTypeError";
+    this.typeString = options.typeString;
+    this.position = options.position;
+  }
+}
+
+/**
+ * The fold itself: turn a parsed type-AST node into a value {@link Reader},
+ * recursing into element / key / field types for composites. The shape mirrors
+ * the server's `EXPLAIN AST` data-type subtree (see the parser's `ast.ts`).
+ */
+export function astToReader(node: Node): Reader<unknown> {
+  switch (node.kind) {
+    case NodeKind.EnumDataType:
+      // Explicit-value enum: the wire value is the underlying int; the
+      // name<->value map is metadata we don't need to decode.
+      return node.name === "Enum16" ? readEnum16 : readEnum8;
+    case NodeKind.TupleDataType:
+      return tupleReader(node);
+    case NodeKind.DataType:
+      return dataTypeReader(node);
+    default:
+      // Literal / Function / Identifier / NameTypePair are argument nodes,
+      // consumed by their parent — never a standalone column type.
+      throw new RowBinaryTypeError(
+        `cannot build a column reader for a ${node.kind} node (${node.name || "?"})`,
+      );
+  }
+}
+
+/**
+ * Fold a generic `DataType` node (`name` + optional `arguments`) — the bulk of
+ * the type system: scalars, the parameterized types, and the
+ * wrappers/composites that recurse through {@link astToReader}.
+ */
+function dataTypeReader(node: Node): Reader<unknown> {
+  switch (node.name) {
+    // --- wrappers & composites (recurse into argument types) ---
+    case "Nullable":
+      return readNullable(astToReader(requireArg(node, 0)));
+    case "LowCardinality":
+      // Transparent in RowBinary: just the inner type's reader.
+      return readLowCardinality(astToReader(requireArg(node, 0)));
+    case "Array":
+      return readArray(astToReader(requireArg(node, 0)));
+    case "QBit":
+      // QBit(element_type, dimension): wire-identical to Array(element_type);
+      // the dimension (arg 1) is metadata, not in the value stream.
+      return readQBit(astToReader(requireArg(node, 0)));
+    case "Map":
+      return readMap(
+        astToReader(requireArg(node, 0)),
+        astToReader(requireArg(node, 1)),
+      );
+    case "Variant":
+      return variantReader(node);
+    case "Nested":
+      return nestedReader(node);
+
+    // --- parameterized scalars ---
+    case "FixedString":
+      return readFixedString(literalInt(requireArg(node, 0)));
+    case "DateTime":
+    case "DateTime32":
+      // An optional timezone argument is metadata; the value wire is the same.
+      return readDateTime;
+    case "DateTime64":
+      // DateTime64(P [, 'tz']); default precision 3 if somehow omitted.
+      return readDateTime64(
+        node.arguments.length > 0 ? literalInt(node.arguments[0]!) : 3,
+      );
+    case "Time64":
+      return readTime64(literalInt(requireArg(node, 0)));
+    case "Decimal":
+      return decimalReader(node);
+    case "Decimal32":
+      return readDecimal32(literalInt(requireArg(node, 0)));
+    case "Decimal64":
+      return readDecimal64(literalInt(requireArg(node, 0)));
+    case "Decimal128":
+      return readDecimal128(literalInt(requireArg(node, 0)));
+    case "Decimal256":
+      return readDecimal256(literalInt(requireArg(node, 0)));
+    // Auto-assigned enums arrive as a plain DataType (no explicit values); the
+    // wire value is still the underlying int.
+    case "Enum8":
+      return readEnum8;
+    case "Enum16":
+      return readEnum16;
+
+    default: {
+      // Interval<Unit> (IntervalSecond, IntervalDay, …): all decode to the
+      // signed Int64 count; the unit lives in the type name, not the wire.
+      if (node.name.startsWith("Interval")) return readInterval;
+      const leaf = NULLARY[node.name];
+      if (leaf !== undefined) return leaf;
+      throw new RowBinaryTypeError(`unsupported RowBinary type: ${node.name}`);
+    }
+  }
+}
+
+/** Folds a `Tuple(...)` — named (object) when every element is named, else positional (array). */
+function tupleReader(node: Node): Reader<unknown> {
+  const readers = node.arguments.map(astToReader);
+  const names = node.element_names;
+  const named =
+    names.length === readers.length && names.every((n) => n.length > 0);
+  if (named) {
+    const fields: Record<string, Reader<unknown>> = {};
+    for (let i = 0; i < names.length; i++) fields[names[i]!] = readers[i]!;
+    return readTupleNamed(fields);
+  }
+  return readTuple(readers);
+}
+
+/**
+ * Folds a `Variant(...)`. The 1-byte discriminant indexes the alternatives
+ * sorted by type NAME (ClickHouse's global ordering), and the server writes the
+ * type string with alternatives ALREADY in that sorted order — so for a
+ * header-sourced type the AST argument order is the discriminant order and we
+ * pass them straight through. (A hand-written, non-normalized `Variant(...)`
+ * string would need sorting first.)
+ */
+function variantReader(node: Node): Reader<unknown> {
+  return readVariant(node.arguments.map(astToReader));
+}
+
+/**
+ * Folds a `Nested(name Type, …)`: on the wire it IS `Array(Tuple(...))` with
+ * the field names, so we compose {@link readNested} (= `readArray(readTupleNamed)`)
+ * over the `NameTypePair` children.
+ */
+function nestedReader(node: Node): Reader<unknown> {
+  const fields: Record<string, Reader<unknown>> = {};
+  for (const child of node.arguments) {
+    if (child.kind !== NodeKind.NameTypePair || child.data_type === null) {
+      throw new RowBinaryTypeError(
+        "malformed Nested(...): expected name/type pairs",
+      );
+    }
+    fields[child.name] = astToReader(child.data_type);
+  }
+  return readNested(fields);
+}
+
+/** Folds `Decimal(P, S)` to the right width by precision P; scale S drives decoding. */
+function decimalReader(node: Node): Reader<unknown> {
+  const precision = literalInt(requireArg(node, 0));
+  const scale = literalInt(requireArg(node, 1));
+  if (precision <= 9) return readDecimal32(scale);
+  if (precision <= 18) return readDecimal64(scale);
+  if (precision <= 38) return readDecimal128(scale);
+  return readDecimal256(scale);
+}
+
+/** The nullary (no-argument) scalar types, mapped to their leaf readers. */
+const NULLARY: Record<string, Reader<unknown>> = {
+  UInt8: readUInt8,
+  UInt16: readUInt16,
+  UInt32: readUInt32,
+  UInt64: readUInt64,
+  UInt128: readUInt128,
+  UInt256: readUInt256,
+  Int8: readInt8,
+  Int16: readInt16,
+  Int32: readInt32,
+  Int64: readInt64,
+  Int128: readInt128,
+  Int256: readInt256,
+  Float32: readFloat32,
+  Float64: readFloat64,
+  BFloat16: readBFloat16,
+  Bool: readBool,
+  String: readString,
+  UUID: readUUID,
+  IPv4: readIPv4,
+  IPv6: readIPv6,
+  Date: readDate,
+  Date32: readDate32,
+  Time: readTime,
+  Nothing: readNothing,
+  // Geo types.
+  Point: readPoint,
+  Ring: readRing,
+  LineString: readLineString,
+  Polygon: readPolygon,
+  MultiLineString: readMultiLineString,
+  MultiPolygon: readMultiPolygon,
+  Geometry: readGeometry as Reader<unknown>,
+  // Self-describing types: bare `JSON` / `Dynamic` (any args are metadata).
+  JSON: readJSON,
+  Dynamic: readDynamic,
+};
+
+/** Argument accessor that fails loudly instead of returning `undefined`. */
+function requireArg(node: Node, index: number): Node {
+  const arg = node.arguments[index];
+  if (arg === undefined) {
+    throw new RowBinaryTypeError(
+      `type ${node.name} is missing argument ${index}`,
+    );
+  }
+  return arg;
+}
+
+/** Reads an integer out of a `Literal` argument node (e.g. the N in FixedString(N)). */
+function literalInt(node: Node): number {
+  if (node.kind !== NodeKind.Literal) {
+    throw new RowBinaryTypeError(
+      `expected a literal argument, got a ${node.kind} node`,
+    );
+  }
+  return Number(node.value);
+}

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

@@ -0,0 +1,181 @@
+import { type Reader } from "./core.js";
+import { readUInt8 } from "./integers.js";
+import { readUVarint } from "./varint.js";
+
+/**
+ * Read a `Nullable(T)`: a 1-byte null flag (0 = present, non-zero = NULL).
+ * Curried: pass the inner reader, get a `Reader<T | null>`.
+ *
+ * GOTCHA: the inner value bytes follow ONLY when the flag is 0. A NULL is the
+ * single `0x01` flag byte with nothing after it — so do NOT read the inner value
+ * when the flag is set, or the cursor desyncs.
+ *
+ * `readValue` decodes the inner `T`. This generic combinator is the reference
+ * shape; when generating code, MONOMORPHIZE — emit a dedicated `readNullableX`
+ * that inlines the inner read:
+ *
+ *   const readNullableUInt32 = (s) => readUInt8(s) !== 0 ? null : readUInt32(s);
+ */
+export function readNullable<T>(readValue: Reader<T>): Reader<T | null> {
+  return (state) => (readUInt8(state) !== 0 ? null : readValue(state));
+}
+
+/**
+ * Read an `Array(T)`: a LEB128 element count, then that many `T` values
+ * back-to-back. An empty array is just the count byte `0x00`. Curried: pass the
+ * element reader, get a `Reader<T[]>`.
+ *
+ * ARRAY LAYOUT: the count is known up front (the LEB128 prefix), so a generated
+ * reader can pre-size. Pick by how the result is used:
+ *  - small / consumed-as-is (the common case) → DEFAULT to `new Array(n)` +
+ *    index assignment; it skips `push`'s repeated capacity growth. A clean-room
+ *    benchmark found this edged out `push` on the small composite arrays here
+ *    (`baseline/README.md`).
+ *  - large + iterated/computed-over downstream → `[]` + `push` keeps it a PACKED
+ *    elements kind (faster to traverse; a pre-sized array is HOLEY), or use a
+ *    typed array (`Float64Array`…) for numeric elements.
+ * This generic combinator uses `push` for simplicity; the monomorphized
+ * `readArrayX` below should choose per the rule above.
+ *
+ * `readElement` decodes one element. This generic combinator is the reference
+ * shape; when generating code, MONOMORPHIZE — emit a dedicated `readArrayX` that
+ * inlines the element read in the loop (and pre-sizes for the common small case):
+ *
+ *   function readArrayUInt32(s) {
+ *     const n = readUVarint(s);
+ *     const out = new Array(n);
+ *     for (let i = 0; i < n; i++) out[i] = readUInt32(s);
+ *     return out;
+ *   }
+ */
+export function readArray<T>(readElement: Reader<T>): Reader<T[]> {
+  return (state) => {
+    const n = readUVarint(state);
+    const out: T[] = [];
+    for (let i = 0; i < n; i++) out.push(readElement(state));
+    return out;
+  };
+}
+
+/**
+ * Read a `QBit(element_type, dimension)` vector. `QBit` is a vector-search type
+ * whose ON-DISK layout is quantized and bit-transposed — but that is a STORAGE /
+ * Native-format concern. In RowBinary a `QBit` is fully TRANSPARENT: it is the
+ * plain vector, encoded byte-for-byte like `Array(element_type)` (a LEB128
+ * length, then `dimension` element values). So this is just {@link readArray}.
+ *
+ * `element_type` is one of `BFloat16` / `Float32` / `Float64`, so `readElement`
+ * is the matching float reader. When generating code, MONOMORPHIZE — inline the
+ * element read in the loop.
+ */
+export function readQBit<T>(readElement: Reader<T>): Reader<T[]> {
+  return readArray(readElement);
+}
+
+/**
+ * Read a `Tuple(...)` into a positional array: each element's value back-to-back,
+ * with NO count and NO delimiter. Curried: pass one reader per element (in
+ * order), get a `Reader` of the tuple. For a named tuple as an object, use
+ * {@link readTupleNamed} (identical wire).
+ *
+ * Reference shape; when generating code, MONOMORPHIZE — emit the inline sequence
+ * with no array-of-readers and no loop:
+ *
+ *   [readUInt32(s), readString(s)]
+ */
+export function readTuple<T extends readonly unknown[]>(readers: {
+  [K in keyof T]: Reader<T[K]>;
+}): Reader<T> {
+  return (state) => {
+    const out: unknown[] = [];
+    for (const read of readers as ReadonlyArray<Reader<unknown>>) {
+      out.push(read(state));
+    }
+    return out as unknown as T;
+  };
+}
+
+/**
+ * Read a named `Tuple(name1 T1, ...)` into an object. The wire is identical to
+ * an unnamed tuple — values back-to-back, no count or delimiter — so the
+ * `readers` object's keys MUST be listed in the tuple's declared field order
+ * (JS iterates string keys in insertion order), and each reader runs in that
+ * order. Curried: pass the readers object, get a `Reader` of the result object.
+ *
+ * Reference shape; when generating code, MONOMORPHIZE — emit the inline object
+ * literal instead of looping over entries:
+ *
+ *   { id: readUInt32(s), name: readString(s) }
+ */
+export function readTupleNamed<T extends Record<string, unknown>>(readers: {
+  [K in keyof T]: Reader<T[K]>;
+}): Reader<T> {
+  const fns = readers as Record<string, Reader<unknown>>;
+  const keys = Object.keys(fns);
+  return (state) => {
+    const out: Record<string, unknown> = {};
+    for (const key of keys) out[key] = fns[key]!(state);
+    return out as T;
+  };
+}
+
+/**
+ * Read a `Map(K, V)`: a LEB128 pair count, then that many key/value pairs with
+ * key and value interleaved (k, v, k, v, ...) — a flattened `Array(Tuple(K, V))`.
+ * An empty map is just the count byte `0x00`. Curried: pass the key and value
+ * readers, get a `Reader<Map<K, V>>`.
+ *
+ * The key is read BEFORE the value in each pair. Returns a JS `Map`, which keeps
+ * insertion order and accepts any key type.
+ *
+ * Reference shape; when generating code, MONOMORPHIZE — inline both reads in the
+ * loop.
+ */
+export function readMap<K, V>(
+  readKey: Reader<K>,
+  readValue: Reader<V>,
+): Reader<Map<K, V>> {
+  return (state) => {
+    const n = readUVarint(state);
+    const out = new Map<K, V>();
+    for (let i = 0; i < n; i++) {
+      const key = readKey(state);
+      out.set(key, readValue(state));
+    }
+    return out;
+  };
+}
+
+/**
+ * Read a `Variant(T1, ..., Tn)`: a 1-byte discriminant selecting the active
+ * alternative, then that alternative's value. Discriminant `0xFF` means NULL.
+ * Curried: pass the alternative readers (in sorted-type-name order), get a
+ * `Reader`.
+ *
+ * GOTCHA: the discriminant indexes the alternatives sorted by type NAME
+ * (ClickHouse globally sorts them), NOT their declaration order. So `readers`
+ * MUST be ordered by sorted type name. E.g. `Variant(UInt8, String)` sorts to
+ * ["String", "UInt8"], so discriminant 0 = String and 1 = UInt8.
+ *
+ * Reference shape; when generating code, MONOMORPHIZE — emit a `switch` over the
+ * discriminant with each branch inlined, alternatives in sorted order, `0xFF`
+ * -> null.
+ */
+export function readVariant<T extends readonly unknown[]>(readers: {
+  [K in keyof T]: Reader<T[K]>;
+}): Reader<T[number] | null> {
+  const fns = readers as ReadonlyArray<Reader<T[number]>>;
+  return (state) => {
+    const discriminant = readUInt8(state);
+    if (discriminant === 0xff) return null;
+    const fn = fns[discriminant];
+    if (fn === undefined) {
+      // Out-of-range discriminant (corrupted/truncated input): fail loudly
+      // instead of throwing a cryptic "fns[discriminant] is not a function".
+      throw new RangeError(
+        `RowBinary Variant: discriminant ${discriminant} out of range (${fns.length} alternatives)`,
+      );
+    }
+    return fn(state);
+  };
+}