@clickhouse/client 1.22.0 → 1.23.0-head.70ad405.1

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

@@ -0,0 +1,332 @@
+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 { readEnum8, readEnum16 } from "./enums.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. We
+    // collect them into the name<->value map so the value resolves to its name,
+    // matching the textual-type path in compile.ts.
+    case 0x17: {
+      const n = readUVarint(state);
+      const map = new Map<number, string>();
+      for (let i = 0; i < n; i++) {
+        const name = readString(state);
+        map.set(readInt8(state), name);
+      }
+      return readEnum8(map);
+    }
+    case 0x18: {
+      const n = readUVarint(state);
+      const map = new Map<number, string>();
+      for (let i = 0; i < n; i++) {
+        const name = readString(state);
+        map.set(readInt16(state), name);
+      }
+      return readEnum16(map);
+    }
+    // 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/src/readers/enums.ts

@@ -0,0 +1,40 @@
+import { type Reader, advance } from "./core.js";
+
+/**
+ * Maps an enum's underlying integer to its name. Built from the type's
+ * `'name' = value` pairs (which live in the column type, not the wire) by the
+ * compile step / dynamic decoder and handed to the readers below.
+ */
+export type EnumNameMap = ReadonlyMap<number, string>;
+
+/**
+ * Read an `Enum8` and resolve it to its NAME — the ergonomic default, since the
+ * point of an enum is usually the label, not the raw `Int8`.
+ *
+ * This is a factory: the name<->value map is metadata carried by the type, not
+ * the bytes, so it is supplied once (per column) and closed over. A value with
+ * no matching name falls back to its stringified integer rather than throwing,
+ * so a decode never blows up on an unexpected wire value.
+ *
+ * Need the raw underlying integer instead (e.g. a monomorphized hot path that
+ * has the schema baked in)? Read it directly with {@link readInt8} — that is the
+ * fast, allocation-free path the enum's name resolution sits on top of.
+ */
+export function readEnum8(valueToName: EnumNameMap): Reader<string> {
+  return (state) =>
+    resolveName(valueToName, state.view.getInt8(advance(state, 1)));
+}
+
+/**
+ * Read an `Enum16` (2-byte underlying `Int16`) and resolve it to its NAME. See
+ * {@link readEnum8}; use {@link readInt16} for the raw underlying integer.
+ */
+export function readEnum16(valueToName: EnumNameMap): Reader<string> {
+  return (state) =>
+    resolveName(valueToName, state.view.getInt16(advance(state, 2), true));
+}
+
+function resolveName(valueToName: EnumNameMap, value: number): string {
+  const name = valueToName.get(value);
+  return name !== undefined ? name : String(value);
+}

package/skills/clickhouse-js-node-rowbinary/src/readers/floats.ts

@@ -0,0 +1,32 @@
+import { Cursor, advance } from "./core.js";
+
+/**
+ * Scratch view for widening a `BFloat16`: its 16 bits are the top half of an
+ * IEEE 754 float32, so we stage them into a 4-byte buffer and read a float32.
+ */
+const bf16Scratch = new DataView(new ArrayBuffer(4));
+
+/** Read a `Float32`: 4 bytes, little-endian IEEE 754 single precision. */
+export function readFloat32(state: Cursor): number {
+  return state.view.getFloat32(advance(state, 4), true);
+}
+
+/** Read a `Float64`: 8 bytes, little-endian IEEE 754 double precision. */
+export function readFloat64(state: Cursor): number {
+  return state.view.getFloat64(advance(state, 8), true);
+}
+
+/**
+ * Read a `BFloat16`: 2 bytes, little-endian. BFloat16 is the high 16 bits of a
+ * float32 (same 8-bit exponent, 7-bit mantissa), so placing the bits in the top
+ * half of a 32-bit float and reading it back is exact.
+ *
+ * NOTE: `bf16Scratch` is module-level shared state written-then-read in this
+ * function. That is safe because the read is synchronous; do NOT introduce an
+ * `await`/`yield` between the `setUint32` and the `getFloat32`.
+ */
+export function readBFloat16(state: Cursor): number {
+  const bits = state.view.getUint16(advance(state, 2), true);
+  bf16Scratch.setUint32(0, bits * 0x10000, true);
+  return bf16Scratch.getFloat32(0, true);
+}

package/skills/clickhouse-js-node-rowbinary/src/readers/geo.ts

@@ -0,0 +1,109 @@
+import { Cursor } from "./core.js";
+import { readFloat64 } from "./floats.js";
+import { readUInt8 } from "./integers.js";
+import { readUVarint } from "./varint.js";
+
+/** A geo `Point`: `[x, y]`, the base of every ClickHouse geo type. */
+export type Point = [x: number, y: number];
+
+// Geo types are concrete compositions of Point = Tuple(Float64, Float64). They
+// are monomorphic (no sub-readers) — the generator can emit them as-is.
+
+/** Read a `Point`: `Tuple(Float64, Float64)` -> `[x, y]`. */
+export function readPoint(state: Cursor): Point {
+  const x = readFloat64(state);
+  const y = readFloat64(state);
+  return [x, y];
+}
+
+/**
+ * Read a `Ring`: `Array(Point)` — a LEB128 point count, then that many points.
+ * `LineString` has the identical wire (see {@link readLineString}). `readPoint`
+ * is inlined here (two `readFloat64`s) to drop a call per point on this hot path.
+ */
+export function readRing(state: Cursor): Point[] {
+  const n = readUVarint(state);
+  const out: Point[] = [];
+  for (let i = 0; i < n; i++) {
+    const x = readFloat64(state);
+    const y = readFloat64(state);
+    out.push([x, y]);
+  }
+  return out;
+}
+
+/**
+ * Read a `LineString`: `Array(Point)` (identical wire to a `Ring`). Points are
+ * inlined (two `readFloat64`s) to drop a call per point on this hot path.
+ */
+export function readLineString(state: Cursor): Point[] {
+  const n = readUVarint(state);
+  const out: Point[] = [];
+  for (let i = 0; i < n; i++) {
+    const x = readFloat64(state);
+    const y = readFloat64(state);
+    out.push([x, y]);
+  }
+  return out;
+}
+
+/** Read a `Polygon`: `Array(Ring)` — the outer ring first, then any holes. */
+export function readPolygon(state: Cursor): Point[][] {
+  const n = readUVarint(state);
+  const out: Point[][] = [];
+  for (let i = 0; i < n; i++) out.push(readRing(state));
+  return out;
+}
+
+/** Read a `MultiLineString`: `Array(LineString)` (identical wire to a `Polygon`). */
+export function readMultiLineString(state: Cursor): Point[][] {
+  const n = readUVarint(state);
+  const out: Point[][] = [];
+  for (let i = 0; i < n; i++) out.push(readLineString(state));
+  return out;
+}
+
+/** Read a `MultiPolygon`: `Array(Polygon)`. */
+export function readMultiPolygon(state: Cursor): Point[][][] {
+  const n = readUVarint(state);
+  const out: Point[][][] = [];
+  for (let i = 0; i < n; i++) out.push(readPolygon(state));
+  return out;
+}
+
+/**
+ * Read a `Geometry`: a named `Variant` over the six geo types. This is the
+ * MONOMORPHIZED form of `readVariant` for a concrete variant — a switch over the
+ * discriminant with each branch inlined, no reader array. The alternatives,
+ * sorted by type name (so in discriminant order), are LineString(0),
+ * MultiLineString(1), MultiPolygon(2), Point(3), Polygon(4), Ring(5); 0xFF is NULL.
+ *
+ * NOTE: the value shapes overlap — LineString and Ring are both `Point[]`,
+ * MultiLineString and Polygon both `Point[][]` — so the value alone does not say
+ * which geo type it was. If you need the kind, branch on the discriminant.
+ */
+export function readGeometry(
+  state: Cursor,
+): Point | Point[] | Point[][] | Point[][][] | null {
+  const discriminant = readUInt8(state);
+  switch (discriminant) {
+    case 0:
+      return readLineString(state);
+    case 1:
+      return readMultiLineString(state);
+    case 2:
+      return readMultiPolygon(state);
+    case 3:
+      return readPoint(state);
+    case 4:
+      return readPolygon(state);
+    case 5:
+      return readRing(state);
+    case 0xff:
+      return null;
+    default:
+      throw new RangeError(
+        `RowBinary: unknown Geometry discriminant ${discriminant}`,
+      );
+  }
+}

package/skills/clickhouse-js-node-rowbinary/src/readers/header.ts

@@ -0,0 +1,29 @@
+/**
+ * The `RowBinaryWithNamesAndTypes` HEADER: the column names and their type
+ * strings the server writes before the row data. Parsing the type strings into
+ * readers lives in `compile.ts`; this module is just the wire read.
+ */
+
+import type { Cursor } from "./core.js";
+import { readUVarint } from "./varint.js";
+import { readString } from "./strings.js";
+
+/** Column names and their type strings, in stream order. */
+export interface RowBinaryHeader {
+  names: string[];
+  types: string[];
+}
+
+/**
+ * Read the `RowBinaryWithNamesAndTypes` header off the cursor: a LEB128 column
+ * count, then that many column-name `String`s, then that many type-string
+ * `String`s. Leaves the cursor at the first row's bytes.
+ */
+export function readHeader(state: Cursor): RowBinaryHeader {
+  const count = readUVarint(state);
+  const names: string[] = new Array(count);
+  for (let i = 0; i < count; i++) names[i] = readString(state);
+  const types: string[] = new Array(count);
+  for (let i = 0; i < count; i++) types[i] = readString(state);
+  return { names, types };
+}

package/skills/clickhouse-js-node-rowbinary/src/readers/integers.ts

@@ -0,0 +1,95 @@
+import { Cursor, advance } from "./core.js";
+
+/** Read a single unsigned byte and advance. */
+export function readUInt8(state: Cursor): number {
+  return state.buf[advance(state, 1)]!;
+}
+
+/** Read an `Int8`: 1 byte, two's-complement signed (-128 .. 127). */
+export function readInt8(state: Cursor): number {
+  return state.view.getInt8(advance(state, 1));
+}
+
+/** Read a `UInt16`: 2 bytes, little-endian (0 .. 65535). */
+export function readUInt16(state: Cursor): number {
+  return state.view.getUint16(advance(state, 2), true);
+}
+
+/**
+ * Read an `Int16`: 2 bytes, little-endian, two's-complement signed (-32768 ..
+ * 32767). `DataView` reads from any offset and decodes explicitly little-endian,
+ * so the value never depends on host byte order.
+ */
+export function readInt16(state: Cursor): number {
+  return state.view.getInt16(advance(state, 2), true);
+}
+
+/** Read a `UInt32`: 4 bytes, little-endian (0 .. 4294967295). */
+export function readUInt32(state: Cursor): number {
+  return state.view.getUint32(advance(state, 4), true);
+}
+
+/** Read an `Int32`: 4 bytes, little-endian, two's-complement signed. */
+export function readInt32(state: Cursor): number {
+  return state.view.getInt32(advance(state, 4), true);
+}
+
+/**
+ * Read a `UInt64`: 8 bytes, little-endian. Returns a `bigint`.
+ * SAFE TO TOGGLE: if the values fit in 53 bits, wrap in `Number(...)`.
+ */
+export function readUInt64(state: Cursor): bigint {
+  return state.view.getBigUint64(advance(state, 8), true);
+}
+
+/**
+ * Read an `Int64`: 8 bytes, little-endian, two's-complement. Returns a `bigint`
+ * (range exceeds `Number.MAX_SAFE_INTEGER`).
+ * SAFE TO TOGGLE: if the values fit in 53 bits, wrap in `Number(...)`.
+ */
+export function readInt64(state: Cursor): bigint {
+  return state.view.getBigInt64(advance(state, 8), true);
+}
+
+/** Read a `UInt128`: 16 bytes, little-endian. Always a `bigint`. */
+export function readUInt128(state: Cursor): bigint {
+  const start = advance(state, 16);
+  const lo = state.view.getBigUint64(start, true);
+  const hi = state.view.getBigUint64(start + 8, true);
+  return (hi << 64n) + lo;
+}
+
+/**
+ * Read an `Int128`: 16 bytes, little-endian, two's-complement. Always a
+ * `bigint`, composed from the low (unsigned) and high (signed) 64-bit words —
+ * reading the high word signed extends the sign across all 128 bits.
+ */
+export function readInt128(state: Cursor): bigint {
+  const start = advance(state, 16);
+  const lo = state.view.getBigUint64(start, true);
+  const hi = state.view.getBigInt64(start + 8, true);
+  return (hi << 64n) + lo;
+}
+
+/** Read a `UInt256`: 32 bytes, little-endian. Always a `bigint`. */
+export function readUInt256(state: Cursor): bigint {
+  const start = advance(state, 32);
+  const w0 = state.view.getBigUint64(start, true);
+  const w1 = state.view.getBigUint64(start + 8, true);
+  const w2 = state.view.getBigUint64(start + 16, true);
+  const w3 = state.view.getBigUint64(start + 24, true);
+  return w0 + (w1 << 64n) + (w2 << 128n) + (w3 << 192n);
+}
+
+/**
+ * Read an `Int256`: 32 bytes, little-endian, two's-complement. Always a
+ * `bigint`. The most-significant 64-bit word is read signed.
+ */
+export function readInt256(state: Cursor): bigint {
+  const start = advance(state, 32);
+  const w0 = state.view.getBigUint64(start, true);
+  const w1 = state.view.getBigUint64(start + 8, true);
+  const w2 = state.view.getBigUint64(start + 16, true);
+  const w3 = state.view.getBigInt64(start + 24, true);
+  return (w3 << 192n) + (w2 << 128n) + (w1 << 64n) + w0;
+}

package/skills/clickhouse-js-node-rowbinary/src/readers/interval.ts

@@ -0,0 +1,54 @@
+import { Cursor } from "./core.js";
+import { readInt64 } from "./integers.js";
+
+/** The 11 `Interval` units, in ClickHouse's ascending order. */
+export type IntervalUnit =
+  | "Nanosecond"
+  | "Microsecond"
+  | "Millisecond"
+  | "Second"
+  | "Minute"
+  | "Hour"
+  | "Day"
+  | "Week"
+  | "Month"
+  | "Quarter"
+  | "Year";
+
+/**
+ * `Interval` units indexed by the kind byte the binary type encoding writes
+ * after the `0x22` tag (`0x00` = Nanosecond ... `0x0a` = Year). Exported because
+ * the `Dynamic` reader needs it to decode an `Interval` nested in a `Dynamic`.
+ */
+export const INTERVAL_UNITS: readonly IntervalUnit[] = [
+  "Nanosecond",
+  "Microsecond",
+  "Millisecond",
+  "Second",
+  "Minute",
+  "Hour",
+  "Day",
+  "Week",
+  "Month",
+  "Quarter",
+  "Year",
+];
+
+/**
+ * An `Interval` decoded where the unit is carried IN the wire (inside a
+ * `Dynamic`): the signed `Int64` count plus its unit. A standalone `Interval*`
+ * column has no unit byte — there, use {@link readInterval} and take the unit
+ * from the column type instead.
+ */
+export type IntervalValue = readonly [count: bigint, unit: IntervalUnit];
+
+/**
+ * Read an `Interval` — any of `IntervalNanosecond` ... `IntervalYear`: a signed
+ * `Int64` count of the unit. The unit is in the type name, not the bytes, and
+ * all 11 interval types share this exact wire, so this one reader covers them
+ * all; the caller knows the unit from the column type. Returns a `bigint`; wrap
+ * in `Number(...)` if the counts are known to fit in 53 bits.
+ */
+export function readInterval(state: Cursor): bigint {
+  return readInt64(state);
+}