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

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

@@ -0,0 +1,77 @@
+/**
+ * Thrown by {@link advance} when the buffer lacks the bytes a read needs — the
+ * "need more bytes" signal for incremental decoding over a still-filling buffer.
+ * A driver catches it (`err === NeedMoreData`), waits for more input, and retries
+ * the row from its last committed position.
+ *
+ * A bare sentinel, NOT an `Error` subclass, on purpose: constructing an Error
+ * captures a stack trace — the expensive part of throwing — and on a path that
+ * starves once per chunk that cost is pure waste. Throwing a constant skips it,
+ * which is why throw + restart beats a generator's yield for realistic chunks
+ * (see `streamingRow.bench.ts`).
+ */
+export const NeedMoreData = Symbol("RowBinary.NeedMoreData");
+
+/**
+ * The cursor state every reader threads through: the input `Buffer`, the current
+ * position, and a `DataView` over the same bytes.
+ *
+ * Deliberately STATE only — no read methods. Decoding lives in the free
+ * `readX(state, ...)` functions in the sibling modules, so a generated parser
+ * pulls in only the per-type readers a result needs. `view`/`buf` are public so
+ * those free functions can reach them.
+ */
+export class Cursor {
+  pos = 0;
+
+  /**
+   * Node-only skill, so the input is a `Buffer`: number reads go through
+   * {@link Cursor.view} (DataView), while `String`/`FixedString` use the
+   * fast `buf.toString("utf8", ...)`.
+   */
+  readonly buf: Buffer;
+
+  /**
+   * `DataView` over the same bytes, for fixed-width integer/float reads. Built
+   * with the buffer's own `byteOffset`/`byteLength`: a `Buffer` is often a window
+   * into a larger pooled `ArrayBuffer`, so `new DataView(buf.buffer)` alone would
+   * point at the wrong bytes.
+   */
+  readonly view: DataView;
+
+  constructor(buf: Buffer) {
+    this.buf = buf;
+    this.view = new DataView(buf.buffer, buf.byteOffset, buf.byteLength);
+  }
+}
+
+/**
+ * A `Reader<T>` decodes one value of type `T` from the cursor, advancing it. Leaf
+ * readers (e.g. `readUInt32`) are `Reader`s directly; combinators (e.g.
+ * `readArray`) take sub-`Reader`s and return a `Reader`, so types compose with no
+ * per-element closures.
+ */
+export type Reader<T> = (state: Cursor) => T;
+
+/**
+ * Reserve `n` bytes for the next read: bounds-check them, advance the cursor past
+ * them, and return the offset the read starts at (the value BEFORE advancing).
+ * Every fixed-width read goes through this, so the length check and cursor
+ * bookkeeping live in one place:
+ *
+ *   function readInt32(s) { return s.view.getInt32(advance(s, 4), true); }
+ *
+ * Throws {@link NeedMoreData} when fewer than `n` bytes remain, WITHOUT moving the
+ * cursor, so a driver can rewind to its last committed row and retry.
+ *
+ * SAFE TO TOGGLE: for a complete in-memory buffer the check never fires — a parser
+ * for that case can drop `advance` and read against `state.pos` directly, trading
+ * streaming tolerance for one fewer compare per read.
+ */
+export function advance(state: Cursor, n: number): number {
+  const start = state.pos;
+  const next = start + n;
+  if (next > state.buf.length) throw NeedMoreData;
+  state.pos = next;
+  return start;
+}

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

@@ -0,0 +1,113 @@
+import { type Reader, Cursor } from "./core.js";
+import { readInt32, readInt64, readUInt16, readUInt32 } from "./integers.js";
+
+/**
+ * Semantic aliases for `number` that mark the unit of a temporal value in a
+ * return type. They are plain `number`s (no runtime brand) — purely to make
+ * `[Date, Nanoseconds]` etc. self-documenting at the call site.
+ */
+export type Milliseconds = number;
+export type Microseconds = number;
+export type Nanoseconds = number;
+
+/**
+ * Read a `Date`: 2-byte `UInt16` count of days since 1970-01-01 (UTC), returned
+ * as a JS `Date` at UTC midnight. A ClickHouse `Date` has no time or timezone;
+ * `.toISOString().slice(0, 10)` gives "YYYY-MM-DD".
+ *
+ * SAFE TO TOGGLE: a `Date` is an object allocation per value. On a hot path that
+ * only needs the calendar number, read the raw `UInt16` (days) instead.
+ */
+export function readDate(state: Cursor): Date {
+  return new Date(readUInt16(state) * 86_400_000);
+}
+
+/**
+ * Read a `Date32`: 4-byte signed `Int32` count of days since 1970-01-01 (UTC),
+ * returned as a JS `Date` at UTC midnight (pre-1970 dates are negative day
+ * counts, which `Date` handles).
+ */
+export function readDate32(state: Cursor): Date {
+  return new Date(readInt32(state) * 86_400_000);
+}
+
+/**
+ * Read a `DateTime` (and `DateTime(tz)`): 4-byte `UInt32` Unix seconds, returned
+ * as a JS `Date` (exact at second resolution). The instant is UTC-based; a
+ * column's timezone is display metadata, not in the bytes.
+ */
+export function readDateTime(state: Cursor): Date {
+  return new Date(readUInt32(state) * 1000);
+}
+
+/**
+ * Read a `DateTime64(P)` (and `DateTime64(P, tz)`): 8-byte signed `Int64` count
+ * of `10^-P`-second ticks since the epoch. Curried: `readDateTime64(P)` returns
+ * the reader.
+ *
+ * Returns a pair `[date, nanoseconds]`: `date` is a JS `Date` truncated to whole
+ * seconds, and `nanoseconds` is the sub-second remainder in nanoseconds
+ * (0..999_999_999). The split keeps full precision a `Date` alone (millisecond
+ * resolution) can't hold. `nanoseconds` is always in ns regardless of P. Timezone
+ * is metadata.
+ *
+ * For the typical precisions, prefer the specialized variants
+ * {@link readDateTime64P3} (ms — returns a plain `Date`),
+ * {@link readDateTime64P6} (µs), and {@link readDateTime64P9} (ns).
+ */
+export function readDateTime64(precision: number): Reader<[Date, Nanoseconds]> {
+  return (state) => {
+    const ticks = readInt64(state);
+    const scale = 10n ** BigInt(precision);
+    let sec = ticks / scale;
+    let frac = ticks % scale;
+    if (frac < 0n) {
+      // Floor toward -inf so the fractional remainder stays in [0, scale).
+      frac += scale;
+      sec -= 1n;
+    }
+    return [new Date(Number(sec) * 1000), Number(frac) * 10 ** (9 - precision)];
+  };
+}
+
+/**
+ * Read a `DateTime64(3)` ({@link Milliseconds}) — the most common precision — as
+ * a plain JS `Date`. P=3 is exactly a `Date`'s own millisecond resolution, so the
+ * instant is represented losslessly with no separate fraction. Specialized
+ * variant of {@link readDateTime64} with the scale baked in.
+ */
+export function readDateTime64P3(state: Cursor): Date {
+  return new Date(Number(readInt64(state)));
+}
+
+/**
+ * Read a `DateTime64(6)` (microseconds) as `[date, microseconds]`: a JS `Date`
+ * truncated to whole seconds plus the sub-second remainder in microseconds.
+ * Specialized variant of {@link readDateTime64}.
+ */
+export function readDateTime64P6(state: Cursor): [Date, Microseconds] {
+  const ticks = readInt64(state);
+  let sec = ticks / 1_000_000n;
+  let frac = ticks % 1_000_000n; // microseconds within the second
+  if (frac < 0n) {
+    frac += 1_000_000n;
+    sec -= 1n;
+  }
+  return [new Date(Number(sec) * 1000), Number(frac)];
+}
+
+/**
+ * Read a `DateTime64(9)` (nanoseconds) as `[date, nanoseconds]`: a JS `Date`
+ * truncated to whole seconds plus the sub-second remainder in nanoseconds.
+ * Specialized variant of {@link readDateTime64} with the scale baked in.
+ */
+export function readDateTime64P9(state: Cursor): [Date, Nanoseconds] {
+  const ticks = readInt64(state);
+  let sec = ticks / 1_000_000_000n;
+  let frac = ticks % 1_000_000_000n; // nanoseconds within the second
+  if (frac < 0n) {
+    frac += 1_000_000_000n;
+    sec -= 1n;
+  }
+  return [new Date(Number(sec) * 1000), Number(frac)];
+}

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

@@ -0,0 +1,57 @@
+import { type Reader } from "./core.js";
+import { readInt32, readInt64, readInt128, readInt256 } from "./integers.js";
+
+/**
+ * A decimal kept lossless as its raw parts: `value = unscaled / 10 ** scale`.
+ * The `readDecimal*` readers return this so no precision or scale information is
+ * thrown away at decode time.
+ */
+export type DecimalValue = readonly [unscaled: bigint, scale: number];
+
+/**
+ * Format a {@link DecimalValue} as a fixed-point decimal string with `scale`
+ * fractional digits (e.g. `[15000n, 4]` -> `"1.5000"`). Plug in only when you
+ * need a string.
+ *
+ * Trailing zeros are preserved to reflect the declared scale, deliberately unlike
+ * ClickHouse's text output, which trims them (`"1.5"`) and drops the point for
+ * integers (`"10"`).
+ */
+export function formatDecimal([unscaled, scale]: DecimalValue): string {
+  if (scale === 0) return unscaled.toString();
+  if (unscaled < 0n) {
+    const digits = (-unscaled).toString().padStart(scale + 1, "0");
+    const point = digits.length - scale;
+    return `-${digits.slice(0, point)}.${digits.slice(point)}`;
+  }
+  const digits = unscaled.toString().padStart(scale + 1, "0");
+  const point = digits.length - scale;
+  return `${digits.slice(0, point)}.${digits.slice(point)}`;
+}
+
+/**
+ * Read a `Decimal32(P, S)`: a 4-byte little-endian signed integer (same wire
+ * shape as `Int32`) scaled by 10^S. Pass the column's scale `S`; returns a
+ * `Reader` of the raw `[unscaled, scale]` pair (see {@link formatDecimal}).
+ *
+ * `Decimal(P, S)` is an alias: pick the width reader by precision P — P<=9 ->
+ * Decimal32, <=18 -> Decimal64, <=38 -> Decimal128, <=76 -> Decimal256.
+ */
+export function readDecimal32(scale: number): Reader<DecimalValue> {
+  return (state) => [BigInt(readInt32(state)), scale];
+}
+
+/** Read a `Decimal64(P, S)`: 8-byte LE signed integer scaled by 10^S. Returns `[unscaled, scale]`; see {@link formatDecimal}. */
+export function readDecimal64(scale: number): Reader<DecimalValue> {
+  return (state) => [readInt64(state), scale];
+}
+
+/** Read a `Decimal128(P, S)`: 16-byte LE signed integer scaled by 10^S. Returns `[unscaled, scale]`; see {@link formatDecimal}. */
+export function readDecimal128(scale: number): Reader<DecimalValue> {
+  return (state) => [readInt128(state), scale];
+}
+
+/** Read a `Decimal256(P, S)`: 32-byte LE signed integer scaled by 10^S. Returns `[unscaled, scale]`; see {@link formatDecimal}. */
+export function readDecimal256(scale: number): Reader<DecimalValue> {
+  return (state) => [readInt256(state), scale];
+}

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

@@ -0,0 +1,328 @@
+import { type Reader, Cursor } from "./core.js";
+import { readUVarint } from "./varint.js";
+import {
+  readInt8,
+  readInt16,
+  readInt32,
+  readInt64,
+  readInt128,
+  readInt256,
+  readUInt8,
+  readUInt16,
+  readUInt32,
+  readUInt64,
+  readUInt128,
+  readUInt256,
+} from "./integers.js";
+import { readBool } from "./bool.js";
+import { readFloat32, readFloat64 } from "./floats.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 {
+  readDecimal32,
+  readDecimal64,
+  readDecimal128,
+  readDecimal256,
+} from "./decimals.js";
+import {
+  INTERVAL_UNITS,
+  type IntervalValue,
+  readInterval,
+} from "./interval.js";
+import {
+  readArray,
+  readMap,
+  readNullable,
+  readTuple,
+  readTupleNamed,
+  readVariant,
+} from "./composite.js";
+import { readJSON } from "./json.js";
+
+/**
+ * Read one `Dynamic` value. A `Dynamic` is SELF-DESCRIBING: every value is a
+ * binary TYPE ENCODING followed by the value's RowBinary bytes. So unlike every
+ * other reader, the type is not known until runtime — this is the one place a
+ * generic runtime dispatch is correct and unavoidable. {@link readDynamicType}
+ * parses the type header into a value `Reader`; here we just invoke it.
+ *
+ * GOTCHA — wrappers are erased. `Dynamic` stores the CONCRETE type of the stored
+ * value, never a wrapper: a non-null `Nullable(UInt8)` is stored as plain
+ * `UInt8`, an active `Variant(...)` as just its current alternative's type. A
+ * NULL (from any source) is stored as `Nothing` (tag 0x00) and decodes to
+ * `null`. So you never see Nullable/Variant tags here.
+ *
+ * For a Dynamic-heavy hot path where the same few types recur, parse the type
+ * once and reuse the returned reader across rows instead of re-parsing.
+ */
+export function readDynamic(state: Cursor): unknown {
+  return readDynamicType(state)(state);
+}
+
+/**
+ * Parse a binary TYPE ENCODING (the header ClickHouse writes before each
+ * `Dynamic` value) and return a `Reader` that reads ONE value of that type. The
+ * type bytes are consumed now; the returned reader consumes only value bytes
+ * when called. Composites recurse: element/key/field types are parsed eagerly
+ * into inner readers, then composed with the existing combinators
+ * ({@link readArray}/{@link readTuple}/{@link readMap}/...).
+ *
+ * The leading byte is a 1-byte tag; parameterized types (FixedString, Enum,
+ * Decimal, DateTime64, timezone'd DateTime) carry extra LEB128/varint and string
+ * fields in the header, which we consume to reach the value reader.
+ *
+ * Only the tags ClickHouse actually emits for stored `Dynamic` values are
+ * handled (wrappers are erased — see {@link readDynamic}). Unknown tags throw
+ * with the tag value so you can extend this switch for the types your data
+ * actually contains.
+ */
+export function readDynamicType(state: Cursor): Reader<unknown> {
+  const tag = readUInt8(state);
+  switch (tag) {
+    // Nothing — a stored NULL. Zero value bytes.
+    case 0x00:
+      return () => null;
+    // Unsigned integers.
+    case 0x01:
+      return readUInt8;
+    case 0x02:
+      return readUInt16;
+    case 0x03:
+      return readUInt32;
+    case 0x04:
+      return readUInt64;
+    case 0x05:
+      return readUInt128;
+    case 0x06:
+      return readUInt256;
+    // Signed integers.
+    case 0x07:
+      return readInt8;
+    case 0x08:
+      return readInt16;
+    case 0x09:
+      return readInt32;
+    case 0x0a:
+      return readInt64;
+    case 0x0b:
+      return readInt128;
+    case 0x0c:
+      return readInt256;
+    // Floats.
+    case 0x0d:
+      return readFloat32;
+    case 0x0e:
+      return readFloat64;
+    // Dates and times. The timezone'd variants carry a tz string in the header
+    // (metadata only — identical value wire to the untimezoned form).
+    case 0x0f:
+      return readDate;
+    case 0x10:
+      return readDate32;
+    case 0x11:
+      return readDateTime;
+    case 0x12:
+      readString(state); // timezone name (metadata)
+      return readDateTime;
+    case 0x13:
+      return readDateTime64(readUVarint(state));
+    case 0x14: {
+      const precision = readUVarint(state);
+      readString(state); // timezone name (metadata)
+      return readDateTime64(precision);
+    }
+    // String / FixedString(N).
+    case 0x15:
+      return readString;
+    case 0x16:
+      return readFixedString(readUVarint(state));
+    // Enum8 / Enum16: a count then (name String, value Int8/Int16) pairs. The
+    // name<->value map is metadata; the stored value is the underlying int.
+    case 0x17: {
+      const n = readUVarint(state);
+      for (let i = 0; i < n; i++) {
+        readString(state);
+        readInt8(state);
+      }
+      return readInt8;
+    }
+    case 0x18: {
+      const n = readUVarint(state);
+      for (let i = 0; i < n; i++) {
+        readString(state);
+        readInt16(state);
+      }
+      return readInt16;
+    }
+    // Decimals: header carries precision P then scale S (both varint). Only S
+    // matters for decoding; P is consumed and dropped. Returns [unscaled, S].
+    case 0x19: {
+      readUVarint(state);
+      return readDecimal32(readUVarint(state));
+    }
+    case 0x1a: {
+      readUVarint(state);
+      return readDecimal64(readUVarint(state));
+    }
+    case 0x1b: {
+      readUVarint(state);
+      return readDecimal128(readUVarint(state));
+    }
+    case 0x1c: {
+      readUVarint(state);
+      return readDecimal256(readUVarint(state));
+    }
+    case 0x1d:
+      return readUUID;
+    // Array(T): parse the element type once, then read a length-prefixed run.
+    case 0x1e:
+      return readArray(readDynamicType(state));
+    // Tuple(...): a field count, then that many element type encodings.
+    case 0x1f: {
+      const n = readUVarint(state);
+      const fields: Array<Reader<unknown>> = [];
+      for (let i = 0; i < n; i++) fields.push(readDynamicType(state));
+      return readTuple(fields);
+    }
+    // Named Tuple: a count, then (name String, type) pairs. Names shape the
+    // result object; the value wire is identical to an unnamed tuple.
+    case 0x20: {
+      const n = readUVarint(state);
+      const fields: Record<string, Reader<unknown>> = {};
+      for (let i = 0; i < n; i++) {
+        const name = readString(state);
+        fields[name] = readDynamicType(state);
+      }
+      return readTupleNamed(fields);
+    }
+    // Set (0x21): a type used inside IN-expressions, not a stored column value.
+    case 0x21:
+      throw new RangeError(
+        "RowBinary: Dynamic type 0x21 (Set) has no decodable value form",
+      );
+    // Interval (0x22): the header carries a 1-byte unit kind (0x00 Nanosecond
+    // ... 0x0a Year), then the value is a signed Int64 count of that unit. Here
+    // — unlike a standalone Interval* column — the unit IS in the wire, so we
+    // pair it with the count as an IntervalValue rather than dropping it.
+    case 0x22: {
+      const kind = readUInt8(state);
+      const unit = INTERVAL_UNITS[kind];
+      if (unit === undefined) {
+        throw new RangeError(
+          `RowBinary: unknown Interval kind ${kind} in Dynamic type encoding`,
+        );
+      }
+      return (s): IntervalValue => [readInterval(s), unit];
+    }
+    // Nullable(T): a NULL flag byte then (if not null) the inner value. At the
+    // TOP level Dynamic erases Nullable, but NESTED inside Array/Tuple/Map the
+    // element type really is Nullable(T) — e.g. Array(Nullable(UInt8)) — so the
+    // tag does appear here.
+    case 0x23:
+      return readNullable(readDynamicType(state));
+    // Function (0x24): a higher-order function type (lambda), header-only with no
+    // stored value form.
+    case 0x24:
+      throw new RangeError(
+        "RowBinary: Dynamic type 0x24 (Function) has no decodable value form",
+      );
+    // AggregateFunction (0x25): an opaque, UNFRAMED aggregation state with a
+    // function-specific layout and no length prefix, so it cannot be decoded OR
+    // skipped generically. Finalize server-side before putting it in a Dynamic.
+    case 0x25:
+      throw new RangeError(
+        "RowBinary: Dynamic type 0x25 (AggregateFunction) is an opaque unframed state — finalize it server-side",
+      );
+    // LowCardinality(T): transparent — keep the inner type's reader as-is.
+    case 0x26:
+      return readDynamicType(state);
+    // Map(K, V): parse the key type then the value type.
+    case 0x27: {
+      const key = readDynamicType(state);
+      const value = readDynamicType(state);
+      return readMap(key, value);
+    }
+    case 0x28:
+      return readIPv4;
+    case 0x29:
+      return readIPv6;
+    // Variant (0x2a): the header is (count, then each alternative's type
+    // encoding). ClickHouse writes the alternatives ALREADY SORTED by type name,
+    // so the parsed readers line up with the discriminant directly. The value is
+    // a 1-byte discriminant (0xff = NULL) then the chosen value. NOTE: top-level
+    // Dynamic erases Variant, so this tag only appears NESTED.
+    case 0x2a: {
+      const n = readUVarint(state);
+      const alternatives: Array<Reader<unknown>> = [];
+      for (let i = 0; i < n; i++) alternatives.push(readDynamicType(state));
+      return readVariant(alternatives);
+    }
+    // Dynamic (0x2b): a Dynamic nested inside a Dynamic. The header is a single
+    // max_dynamic_types byte; the value is itself a type-encoding + value, so it
+    // is just a recursive readDynamic. We skip max_dynamic_types because it does
+    // NOT affect value decoding — it is a storage/Native-format overflow
+    // threshold; in RowBinary every value is normalized to a plain (tag, value).
+    case 0x2b:
+      readUInt8(state); // max_dynamic_types — storage threshold, not used to decode
+      return readDynamic;
+    // Custom type (0x2c): the type name is written as a String and must be
+    // re-parsed to learn the real type — we don't have a type-name parser.
+    case 0x2c:
+      throw new RangeError(
+        "RowBinary: Dynamic type 0x2c (custom type, name-encoded) is not supported — requires parsing the type name string",
+      );
+    case 0x2d:
+      return readBool;
+    // SimpleAggregateFunction (0x2e): transparent — the value is just its
+    // underlying type T. The header is (function_name String, argument types);
+    // extend here by consuming those, then returning T's reader.
+    case 0x2e:
+      throw new RangeError(
+        "RowBinary: Dynamic type 0x2e (SimpleAggregateFunction) is not supported yet — consume the header, then read the inner T",
+      );
+    // Nested(...) (0x2f): on the wire it IS Array(Tuple(...)). The header is
+    // identical to a named Tuple's (count, then (name String, type) pairs), and
+    // the value is an Array of those tuples, so compose readArray + readTupleNamed.
+    case 0x2f: {
+      const n = readUVarint(state);
+      const fields: Record<string, Reader<unknown>> = {};
+      for (let i = 0; i < n; i++) {
+        const name = readString(state);
+        fields[name] = readDynamicType(state);
+      }
+      return readArray(readTupleNamed(fields));
+    }
+    // JSON (0x30): the type-encoding header is a version byte, max_dynamic_paths
+    // (varuint), max_dynamic_types (uint8), then the typed-path / skip-path /
+    // skip-regexp lists. We consume it to reach the value body. Typed paths are
+    // serialized WITHOUT a Dynamic tag, so a schema-less reader can't decode them
+    // — bail if any are declared.
+    case 0x30: {
+      readUInt8(state); // serialization version (observed 0x00)
+      readUVarint(state); // max_dynamic_paths
+      readUInt8(state); // max_dynamic_types
+      const typedPaths = readUVarint(state);
+      if (typedPaths !== 0) {
+        throw new RangeError(
+          "RowBinary: JSON with declared typed paths is not supported — read each typed path with its known type",
+        );
+      }
+      const skipPaths = readUVarint(state);
+      for (let i = 0; i < skipPaths; i++) readString(state);
+      const skipRegexps = readUVarint(state);
+      for (let i = 0; i < skipRegexps; i++) readString(state);
+      return readJSON;
+    }
+    default:
+      throw new RangeError(
+        `RowBinary: unknown Dynamic type tag 0x${tag.toString(16)} (not in the binary type encoding table)`,
+      );
+  }
+}

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

@@ -0,0 +1,28 @@
+import { Cursor, advance } from "./core.js";
+
+/**
+ * Read an `Enum8`: the value's underlying signed `Int8`. The name<->value map
+ * lives in the column's type, not the bytes. Two strategies, both better than one
+ * shared name-resolving reader:
+ *
+ * - Keep the number: carry the raw Int8 and map to a name only where needed —
+ *   most hot loops never need it.
+ * - Or generate a per-enum reader with a baked-in constant map, so the JIT can
+ *   monomorphize each enum's decode:
+ *
+ *     const STATUS = { 1: "active", 2: "closed" } as const;
+ *     const readStatusEnum = (s) => STATUS[readInt8(s) as keyof typeof STATUS];
+ */
+export function readEnum8(state: Cursor): number {
+  return state.view.getInt8(advance(state, 1));
+}
+
+/**
+ * Read an `Enum16`: the value's underlying signed `Int16` (2 bytes). The
+ * name<->value map lives in the column's type definition, not the bytes. Prefer
+ * keeping the number, or a generated per-enum reader with a baked-in constant
+ * map so the JIT can optimize each enum's decode independently.
+ */
+export function readEnum16(state: Cursor): number {
+  return state.view.getInt16(advance(state, 2), true);
+}

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

@@ -0,0 +1,71 @@
+import { readArray, readNullable, readTupleNamed } from "../composite.js";
+import { type Reader, advance } from "../core.js";
+import { readInt32, readUInt16, readUInt32 } from "../integers.js";
+import { readString } from "../strings.js";
+import { readUVarint } from "../varint.js";
+
+/**
+ * Example: a carts table — nested generics.
+ *
+ * Columns (the trigger):
+ *   cart_id   UInt32
+ *   items     Array(Tuple(sku String, qty UInt16))
+ *   discounts Array(Nullable(Int32))
+ *
+ * The element reader of an `Array` can itself be a combinator: `items` is an
+ * `Array` whose element is a named `Tuple`, `discounts` an `Array` whose element
+ * is a `Nullable`. Combinators nest to any depth, matching the column type.
+ */
+export type CartRow = {
+  cartId: number;
+  items: { sku: string; qty: number }[];
+  discounts: (number | null)[];
+};
+
+export const readCartRow: Reader<CartRow> = (s) => ({
+  cartId: readUInt32(s),
+  items: readArray(readTupleNamed({ sku: readString, qty: readUInt16 }))(s),
+  discounts: readArray(readNullable(readInt32))(s),
+});
+
+/**
+ * Optimized {@link readCartRow}, monomorphized through the nesting: the API
+ * version rebuilds the outer `readArray`, the inner `readTupleNamed`, and the
+ * `readNullable` closures on every row (and the tuple reader iterates a keys
+ * array per element). Here both arrays are inlined loops, the tuple element is a
+ * flat object literal, and the nullable is an inline branch — no closures, no key
+ * iteration, at either nesting level.
+ *
+ * MEASURED (Node 24 / V8, `carts.bench.ts`): ~2x faster — nested combinators
+ * (outer `readArray`, inner `readTupleNamed` / `readNullable`) rebuilt per row in
+ * the API version, all flattened here.
+ */
+export const readCartRowFast: Reader<CartRow> = (s) => {
+  const { buf, view } = s;
+
+  // cart_id UInt32.
+  const cartId = view.getUint32(advance(s, 4), true);
+
+  // items Array(Tuple(sku String, qty UInt16)): count, then per element a
+  // length-prefixed string and a 2-byte int.
+  const itemsN = readUVarint(s);
+  const items = new Array<{ sku: string; qty: number }>(itemsN);
+  for (let i = 0; i < itemsN; i++) {
+    const len = readUVarint(s);
+    const start = advance(s, len);
+    const sku = buf.toString("utf8", start, start + len);
+    const qty = view.getUint16(advance(s, 2), true);
+    items[i] = { sku, qty };
+  }
+
+  // discounts Array(Nullable(Int32)): count, then per element a null-flag byte
+  // and, if non-null, a 4-byte int.
+  const discN = readUVarint(s);
+  const discounts = new Array<number | null>(discN);
+  for (let i = 0; i < discN; i++) {
+    discounts[i] =
+      buf[advance(s, 1)]! !== 0 ? null : view.getInt32(advance(s, 4), true);
+  }
+
+  return { cartId, items, discounts };
+};