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

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

@@ -0,0 +1,102 @@
+import {
+  readArray,
+  readMap,
+  readNullable,
+  readTupleNamed,
+} from "../composite.js";
+import { type Reader, advance } from "../core.js";
+import { readFloat64 } from "../floats.js";
+import { readUInt16, readUInt32 } from "../integers.js";
+import { readString } from "../strings.js";
+import { readUVarint } from "../varint.js";
+
+/**
+ * Example: a telemetry table — composite readers that nest.
+ *
+ * Columns (the trigger):
+ *   host   String
+ *   tags   Map(String, String)
+ *   cpu    Array(Float64)
+ *   region Nullable(String)
+ *   window Tuple(start UInt32, count UInt16)
+ *
+ * The combinators compose exactly the way the column type nests:
+ * `readMap(k, v)`, `readArray(elem)`, `readNullable(inner)`, and
+ * `readTupleNamed({...})` each take sub-readers and return a `Reader`. This is the
+ * generic (closure-per-element) API; a generated parser would monomorphize these
+ * into inlined per-type loops, but the result shape is exactly this.
+ */
+export type TelemetryRow = {
+  host: string;
+  tags: Map<string, string>;
+  cpu: number[];
+  region: string | null;
+  window: { start: number; count: number };
+};
+
+export const readTelemetryRow: Reader<TelemetryRow> = (s) => ({
+  host: readString(s),
+  tags: readMap(readString, readString)(s),
+  cpu: readArray(readFloat64)(s),
+  region: readNullable(readString)(s),
+  window: readTupleNamed({ start: readUInt32, count: readUInt16 })(s),
+});
+
+/**
+ * Optimized {@link readTelemetryRow}, fully monomorphized: the API version above
+ * builds FOUR combinator closures per row (`readMap(...)`, `readArray(...)`,
+ * `readNullable(...)`, `readTupleNamed(...)`) and, for the named tuple, iterates
+ * a keys array building an object field by field. Here every loop and branch is
+ * inlined and the `window` object is a flat literal — no per-row closures, no
+ * key iteration. The most composite-heavy example.
+ *
+ * MEASURED (Node 24 / V8, `telemetry.bench.ts`): ~1.4x faster — four per-row
+ * combinator closures and the named-tuple key iteration removed.
+ */
+export const readTelemetryRowFast: Reader<TelemetryRow> = (s) => {
+  const { buf, view } = s;
+
+  // host String: length prefix, then the bytes.
+  let len = readUVarint(s);
+  let start = advance(s, len);
+  const host = buf.toString("utf8", start, start + len);
+
+  // tags Map(String, String): count, then key/value strings.
+  const mapN = readUVarint(s);
+  const tags = new Map<string, string>();
+  for (let i = 0; i < mapN; i++) {
+    len = readUVarint(s);
+    start = advance(s, len);
+    const k = buf.toString("utf8", start, start + len);
+    len = readUVarint(s);
+    start = advance(s, len);
+    tags.set(k, buf.toString("utf8", start, start + len));
+  }
+
+  // cpu Array(Float64): count, then 8 bytes each.
+  const cpuN = readUVarint(s);
+  const cpu = new Array<number>(cpuN);
+  for (let i = 0; i < cpuN; i++) {
+    cpu[i] = view.getFloat64(advance(s, 8), true);
+  }
+
+  // region Nullable(String): null-flag byte, then if non-null a string.
+  let region: string | null;
+  if (buf[advance(s, 1)]! !== 0) {
+    region = null;
+  } else {
+    len = readUVarint(s);
+    start = advance(s, len);
+    region = buf.toString("utf8", start, start + len);
+  }
+
+  // window Tuple(start UInt32, count UInt16): two adjacent fixed-width fields,
+  // bounds-checked once (6 bytes), then read at literal offsets.
+  const w = advance(s, 6);
+  const window = {
+    start: view.getUint32(w, true),
+    count: view.getUint16(w + 4, true),
+  };
+
+  return { host, tags, cpu, region, window };
+};

package/skills/clickhouse-js-node-rowbinary-parser/src/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-parser/src/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-parser/src/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-parser/src/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-parser/src/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);
+}

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

@@ -0,0 +1,93 @@
+import { Cursor, advance } from "./core.js";
+
+/**
+ * Read an `IPv4`: stored as a 4-byte little-endian `UInt32`. Returns the raw
+ * 32-bit value (the little-endian load already orders the octets); pass it to
+ * {@link formatIPv4} for the dotted-quad string.
+ */
+export function readIPv4(state: Cursor): number {
+  return state.view.getUint32(advance(state, 4), true);
+}
+
+/**
+ * Read an `IPv6`: 16 bytes in network (big-endian) order. Returns the raw bytes
+ * as a zero-copy view; pass them to {@link formatIPv6} for the canonical string.
+ *
+ * The view shares memory with the response buffer, so keeping it alive pins the
+ * whole response chunk in memory. If the value must outlive the row/response,
+ * copy it with `Buffer.from(...)`.
+ */
+export function readIPv6(state: Cursor): Buffer {
+  const start = advance(state, 16);
+  return state.buf.subarray(start, start + 16);
+}
+
+/**
+ * Format an `IPv4` (the raw 32-bit value from {@link readIPv4}) as a dotted-quad
+ * string. Kept aside so the hot read path can skip building a string when the
+ * numeric value is all the caller needs.
+ */
+export function formatIPv4(value: number): string {
+  return `${(value >>> 24) & 0xff}.${(value >>> 16) & 0xff}.${(value >>> 8) & 0xff}.${value & 0xff}`;
+}
+
+/**
+ * Join groups `[from, to)` as colon-separated lowercase hex, by concatenating
+ * into a string in a loop. Benchmarks faster than `slice().map().join(":")`,
+ * which allocates an intermediate array. Returns `""` for an empty range.
+ */
+function joinGroupsHex(g: number[], from: number, to: number): string {
+  if (from >= to) return "";
+  let s = g[from]!.toString(16);
+  for (let i = from + 1; i < to; i++) s += ":" + g[i]!.toString(16);
+  return s;
+}
+
+/**
+ * Format an `IPv6` (the raw 16 bytes from {@link readIPv6}) as the canonical
+ * RFC 5952 string: lowercase, no leading zeros, the longest run of zero groups
+ * (>= 2) collapsed to `::` (leftmost on a tie), and the `::ffff:a.b.c.d` form
+ * for IPv4-mapped addresses (matching ClickHouse).
+ *
+ * Kept aside from the read so the hot path only formats when a string is
+ * actually needed.
+ */
+export function formatIPv6(b: Buffer): string {
+  // IPv4-mapped (::ffff:a.b.c.d): first 10 bytes zero, then 0xffff.
+  let mapped = b[10] === 0xff && b[11] === 0xff;
+  for (let i = 0; mapped && i < 10; i++) {
+    if (b[i] !== 0) mapped = false;
+  }
+  if (mapped) {
+    return `::ffff:${b[12]}.${b[13]}.${b[14]}.${b[15]}`;
+  }
+
+  // Eight 16-bit groups, big-endian.
+  const g: number[] = [];
+  for (let i = 0; i < 8; i++) {
+    g.push((b[2 * i]! << 8) | b[2 * i + 1]!);
+  }
+
+  // Longest run of >= 2 zero groups becomes "::" (leftmost wins on a tie).
+  let bestStart = -1;
+  let bestLen = 0;
+  let curStart = -1;
+  let curLen = 0;
+  for (let i = 0; i < 8; i++) {
+    if (g[i] === 0) {
+      if (curStart < 0) curStart = i;
+      curLen++;
+      if (curLen > bestLen) {
+        bestLen = curLen;
+        bestStart = curStart;
+      }
+    } else {
+      curStart = -1;
+      curLen = 0;
+    }
+  }
+  if (bestLen < 2) {
+    return joinGroupsHex(g, 0, 8);
+  }
+  return `${joinGroupsHex(g, 0, bestStart)}::${joinGroupsHex(g, bestStart + bestLen, 8)}`;
+}

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

@@ -0,0 +1,33 @@
+import { Cursor } from "./core.js";
+import { readUVarint } from "./varint.js";
+import { readString } from "./strings.js";
+import { readDynamic } from "./dynamic.js";
+
+/**
+ * Read a `JSON` value. ClickHouse's `JSON` is NOT JSON text and NOT BSON — it is
+ * a list of (path, value) pairs built on the same machinery as `Dynamic`:
+ *
+ *   <varuint pathCount>  then pathCount x ( <String path> <Dynamic value> )
+ *
+ * Nested objects are FLATTENED to dotted paths (`{a:{b:2}}` -> path `"a.b"`), and
+ * each leaf value is a self-describing `Dynamic`, so this just loops
+ * {@link readString} + {@link readDynamic}. Returns a `Map` keyed by the flat
+ * dotted path. Path order on the wire is not significant.
+ *
+ * GOTCHA: a null-valued path is NOT stored at all — `{"a":null}` serializes as
+ * zero paths, identical to `{}`. JSON arrays come back as `Array(Nullable(T))`.
+ *
+ * LIMITATION — typed paths only. This reads a plain `JSON` column, where every
+ * path is dynamic (tagged). A `JSON(a T, ...)` with DECLARED typed paths
+ * serializes those paths' values WITHOUT a type tag, so they cannot be decoded
+ * without the schema; read each typed path with its known `T` reader instead.
+ */
+export function readJSON(state: Cursor): Map<string, unknown> {
+  const n = readUVarint(state);
+  const out = new Map<string, unknown>();
+  for (let i = 0; i < n; i++) {
+    const path = readString(state);
+    out.set(path, readDynamic(state));
+  }
+  return out;
+}

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

@@ -0,0 +1,18 @@
+import { type Reader } from "./core.js";
+
+/**
+ * `LowCardinality(T)` is TRANSPARENT in RowBinary: it is encoded byte-for-byte
+ * the same as `T`, with NO dictionary/index layer. (The dictionary encoding
+ * exists only in the Native format — do not look for it here.) So there is
+ * nothing to decode at this level: use `T`'s own reader directly.
+ *
+ * This identity combinator exists only to document that, and to let a generated
+ * parser name the wrapper at the call site if it wants the type to read
+ * literally — it returns the inner reader unchanged:
+ *
+ *   readLowCardinality(readString) === readString
+ *
+ * Prefer just calling the inner reader.
+ */
+export const readLowCardinality = <T>(readValue: Reader<T>): Reader<T> =>
+  readValue;

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

@@ -0,0 +1,23 @@
+import { readArray, readTupleNamed } from "./composite.js";
+import { type Reader } from "./core.js";
+
+/**
+ * `Nested(a T1, b T2, …)` has NO wire format of its own:
+ *  - `flatten_nested = 1` (the default): the column expands into separate
+ *    columns `a Array(T1)`, `b Array(T2)`, … — decode each with `readArray`.
+ *  - `flatten_nested = 0`: the column is `Array(Tuple(a T1, b T2, …))` — decode
+ *    with `readArray` + `readTupleNamed`.
+ *
+ * Either way it reuses existing readers; there is no dedicated Nested wire. This
+ * thin alias just composes the two for the `flatten_nested = 0` shape, as
+ * documentation that "Nested === Array(Tuple(...))":
+ *
+ *   readNested({ a: readUInt8, b: readString })
+ *     === readArray(readTupleNamed({ a: readUInt8, b: readString }))
+ *
+ * When generating code, prefer inlining (monomorphize the array + tuple) over
+ * this generic composition.
+ */
+export const readNested = <T extends Record<string, unknown>>(fields: {
+  [K in keyof T]: Reader<T[K]>;
+}): Reader<T[]> => readArray(readTupleNamed(fields));

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

@@ -0,0 +1,29 @@
+import { type Reader } from "./core.js";
+
+/**
+ * `Nothing` is the empty type: it has NO values and occupies ZERO bytes. It is
+ * never a column on its own (you cannot materialize a value of it) — it only
+ * appears wrapped, as the inferred element of an untyped literal:
+ *
+ *   []   -> Array(Nothing)     -> always the empty array (varint length 0x00)
+ *   NULL -> Nullable(Nothing)  -> always NULL (lone flag byte 0x01)
+ *
+ * So a `Nothing` value is NEVER read: `readArray`'s element reader and
+ * `readNullable`'s inner reader are not called in those cases (the array is
+ * empty / the value is NULL). There is nothing to decode.
+ *
+ * Wire this in as the inner reader to make that invariant loud: it throws if it
+ * is ever actually invoked, which would mean a `Nothing` reader was placed where
+ * a real element/inner type was expected.
+ *
+ *   readArray(readNothing)      // [] — readNothing never runs
+ *   readNullable(readNothing)   // null — readNothing never runs
+ */
+export const readNothing: Reader<never> = () => {
+  throw new Error(
+    "RowBinary: Nothing is zero-width and is never decoded — it only appears as " +
+      "an empty Array(Nothing) or a NULL Nullable(Nothing), where the inner reader " +
+      "is not called. Reaching here means a Nothing reader was wired where a real " +
+      "element/inner type was expected.",
+  );
+};