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

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

@@ -0,0 +1,98 @@
+import { type Reader, advance } from "../core.js";
+import {
+  type DecimalValue,
+  readDecimal64,
+  readDecimal128,
+} from "../decimals.js";
+import { readInt64, readUInt128, readUInt256 } from "../integers.js";
+
+/**
+ * Example: a financial ledger — the WIDE-NUMERIC case where RowBinary wins on
+ * *correctness*, not merely speed, and the headline of the wide-int/decimal
+ * comparison in `ledger.bench.ts`.
+ *
+ * Columns (the trigger — generate this reader when a result has these types):
+ *   txn_id   UInt128
+ *   account  Int64
+ *   amount   Decimal128(18)
+ *   balance  Decimal128(18)
+ *   fee      Decimal64(4)
+ *   volume   UInt256
+ *
+ * Every value here exceeds what a JS `number` (IEEE-754 double, 53-bit mantissa)
+ * can hold exactly, and ClickHouse emits them as **bare JSON numbers**. So
+ * `JSON.parse` silently rounds every field — the only correct JSON path is to
+ * quote the values server-side and re-parse each string into a `bigint` /
+ * decimal pair by hand. RowBinary reads each as an exact `bigint` straight off
+ * the wire. The whole row is fixed-width (16+8+16+16+8+32 = 96 bytes).
+ */
+export type LedgerRow = {
+  txn_id: bigint;
+  account: bigint;
+  amount: DecimalValue;
+  balance: DecimalValue;
+  fee: DecimalValue;
+  volume: bigint;
+};
+
+/**
+ * API-combinator reader: correct and clear, one leaf reader per column. A fine
+ * default; `readLedgerRowFast` is the monomorphized form `ledger.bench.ts`
+ * measures. Both return identical values.
+ */
+export const readLedgerRow: Reader<LedgerRow> = (s) => ({
+  txn_id: readUInt128(s),
+  account: readInt64(s),
+  amount: readDecimal128(18)(s),
+  balance: readDecimal128(18)(s),
+  fee: readDecimal64(4)(s),
+  volume: readUInt256(s),
+});
+
+/**
+ * Optimized, monomorphized reader: the six column bounds checks coalesce into
+ * one `advance(s, 96)`; each wide value is composed from 64-bit words read at
+ * constant offsets off that base, with the high word read **signed** for the
+ * signed types (`Int64`, the `Decimal128` unscaled value, no high word needed
+ * for the unsigned `UInt128`/`UInt256`). Stays streaming-safe (one `advance`).
+ *
+ *   txn_id   UInt128        @ o+0   lo + (hi<<64)            unsigned
+ *   account  Int64          @ o+16  getBigInt64
+ *   amount   Decimal128(18) @ o+24  lo + (hiSigned<<64)  -> [v, 18]
+ *   balance  Decimal128(18) @ o+40  lo + (hiSigned<<64)  -> [v, 18]
+ *   fee      Decimal64(4)   @ o+56  getBigInt64          -> [v, 4]
+ *   volume   UInt256        @ o+64  w0 + w1<<64 + w2<<128 + w3<<192  unsigned
+ */
+export const readLedgerRowFast: Reader<LedgerRow> = (s) => {
+  const { view } = s;
+  const o = advance(s, 96); // one bounds check for the whole 96-byte row
+
+  // UInt128 — unsigned, both words unsigned.
+  const txn_id =
+    view.getBigUint64(o, true) + (view.getBigUint64(o + 8, true) << 64n);
+
+  // Int64 — signed.
+  const account = view.getBigInt64(o + 16, true);
+
+  // Decimal128(18) — Int128 unscaled (low word unsigned, high word signed), scale 18.
+  const amount: DecimalValue = [
+    view.getBigUint64(o + 24, true) + (view.getBigInt64(o + 32, true) << 64n),
+    18,
+  ];
+  const balance: DecimalValue = [
+    view.getBigUint64(o + 40, true) + (view.getBigInt64(o + 48, true) << 64n),
+    18,
+  ];
+
+  // Decimal64(4) — Int64 unscaled, scale 4.
+  const fee: DecimalValue = [view.getBigInt64(o + 56, true), 4];
+
+  // UInt256 — unsigned, four unsigned words.
+  const volume =
+    view.getBigUint64(o + 64, true) +
+    (view.getBigUint64(o + 72, true) << 64n) +
+    (view.getBigUint64(o + 80, true) << 128n) +
+    (view.getBigUint64(o + 88, true) << 192n);
+
+  return { txn_id, account, amount, balance, fee, volume };
+};

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

@@ -0,0 +1,73 @@
+import { type Reader, advance } from "../core.js";
+import { readDateTime } from "../datetime.js";
+import { readString } from "../strings.js";
+import { readUVarint } from "../varint.js";
+
+/**
+ * Example: an application log table — the STRING-HEAVY case where the skill
+ * steers you AWAY from RowBinary and toward a `JSON*` format. The honest
+ * counter-case to the IoT and ledger studies; see `logs.bench.ts`.
+ *
+ * Columns (the trigger — generate this reader when a result has these types):
+ *   ts        DateTime
+ *   level     LowCardinality(String)
+ *   service   LowCardinality(String)
+ *   message   String
+ *   trace_id  String
+ *
+ * Four of the five columns are text consumed wholesale, and `LowCardinality(T)`
+ * is transparent in RowBinary (decodes as the inner `String`, no dictionary on
+ * the wire). A RowBinary string read is a varint length + `buf.toString("utf8",
+ * …)` per field in JS; V8's native `JSON.parse` builds the same JS strings in
+ * optimized C++ and tends to WIN here. This reader exists so the comparison is
+ * apples-to-apples — not because RowBinary is the right call for this shape.
+ */
+export type LogRow = {
+  ts: Date;
+  level: string;
+  service: string;
+  message: string;
+  trace_id: string;
+};
+
+/**
+ * API-combinator reader: one leaf reader per column, the clear default. There is
+ * little to monomorphize on a mostly-string row — the only fixed-width field is
+ * `ts` — so `readLogRowFast` below is barely different and barely faster; the
+ * real lesson (see `logs.bench.ts`) is that JSON beats both.
+ */
+export const readLogRow: Reader<LogRow> = (s) => ({
+  ts: readDateTime(s),
+  level: readString(s), // LowCardinality(String) — transparent, decode as String
+  service: readString(s), // LowCardinality(String) — transparent, decode as String
+  message: readString(s),
+  trace_id: readString(s),
+});
+
+/**
+ * Optimized {@link readLogRow}: the four string reads inlined (varint length +
+ * `buf.toString` in place) and the `DateTime` read written out. Note how little
+ * monomorphization can do when the row is dominated by variable-length strings —
+ * there are no adjacent fixed-width columns to coalesce, so this stays close to
+ * the API version. Included to make `logs.bench.ts` a fair fight; the takeaway
+ * is to pick `JSONEachRow` for this shape, not to tune this reader.
+ */
+export const readLogRowFast: Reader<LogRow> = (s) => {
+  const { buf } = s;
+  // DateTime: 4-byte LE Unix seconds.
+  const ts = new Date(s.view.getUint32(advance(s, 4), true) * 1000);
+  // Four UTF-8 Strings (the two LowCardinality columns are plain String on the wire).
+  let len = readUVarint(s);
+  let o = advance(s, len);
+  const level = buf.toString("utf8", o, o + len);
+  len = readUVarint(s);
+  o = advance(s, len);
+  const service = buf.toString("utf8", o, o + len);
+  len = readUVarint(s);
+  o = advance(s, len);
+  const message = buf.toString("utf8", o, o + len);
+  len = readUVarint(s);
+  o = advance(s, len);
+  const trace_id = buf.toString("utf8", o, o + len);
+  return { ts, level, service, message, trace_id };
+};

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

@@ -0,0 +1,142 @@
+import {
+  readArray,
+  readMap,
+  readNullable,
+  readTupleNamed,
+  readVariant,
+} from "../composite.js";
+import { type Reader, advance } from "../core.js";
+import { readDateTime64P3 } from "../datetime.js";
+import { readEnum8 } from "../enums.js";
+import { readFloat64 } from "../floats.js";
+import { readInt64, readUInt64 } from "../integers.js";
+import { readString } from "../strings.js";
+import { formatUUID, formatUUIDTable, readUUID } from "../uuid.js";
+import { readUVarint } from "../varint.js";
+
+/**
+ * Example: an observability/events table — the gotcha-heavy one. It packs the
+ * traps that trip a from-scratch decoder; the skill's job is getting them right.
+ *
+ * Columns (the trigger):
+ *   id       UInt64
+ *   ts       DateTime64(3, 'UTC')
+ *   level    Enum8('debug'=1, 'info'=2, 'warn'=3, 'error'=4)
+ *   trace_id UUID
+ *   payload  Variant(String, Int64, Float64)
+ *   tags     Map(LowCardinality(String), String)
+ *   metrics  Array(Tuple(name LowCardinality(String), value Float64))
+ *   attrs    Array(Nullable(Int64))
+ *
+ * Gotchas exercised, all in one row:
+ * - `Variant(String, Int64, Float64)`: the discriminant indexes the alternatives
+ *   SORTED BY TYPE NAME — ["Float64", "Int64", "String"] → 0=Float64, 1=Int64,
+ *   2=String (NOT declaration order); `0xFF` = NULL. `readVariant` takes the
+ *   readers in that sorted order.
+ * - `DateTime64(3)`: 8-byte Int64 of millisecond ticks; P=3 is exactly a `Date`'s
+ *   resolution, so `readDateTime64P3` returns a plain `Date` (here ISO-stringed).
+ * - `LowCardinality(String)` (in the Map key and the Tuple field) is TRANSPARENT
+ *   in RowBinary — decode as plain `String`, no dictionary layer.
+ * - `UUID` is two little-endian `UInt64` halves, byte-reversed vs the text form.
+ * - `Array(Nullable(Int64))`: per element a null flag then (if present) an Int64,
+ *   kept as `bigint`.
+ */
+export type ObsRow = {
+  id: bigint;
+  ts: string;
+  level: number;
+  traceId: string;
+  payload: number | bigint | string | null;
+  tags: Map<string, string>;
+  metrics: { name: string; value: number }[];
+  attrs: (bigint | null)[];
+};
+
+/**
+ * API-combinator reader. Note the `Variant` readers are in sorted-type-name
+ * order (Float64, Int64, String), and `LowCardinality` columns just use the
+ * inner `String` reader.
+ */
+export const readObsRow: Reader<ObsRow> = (s) => ({
+  id: readUInt64(s),
+  ts: readDateTime64P3(s).toISOString(),
+  level: readEnum8(s),
+  traceId: formatUUID(readUUID(s)),
+  payload: readVariant([readFloat64, readInt64, readString])(s),
+  tags: readMap(readString, readString)(s),
+  metrics: readArray(readTupleNamed({ name: readString, value: readFloat64 }))(
+    s,
+  ),
+  attrs: readArray(readNullable(readInt64))(s),
+});
+
+/**
+ * Optimized {@link readObsRow}, flattened per the SKILL.md guidance:
+ * - `buf`/`view` hoisted to locals.
+ * - the leading run of FIXED-WIDTH columns — `id` UInt64 (8) + `ts` DateTime64 (8)
+ *   + `level` Enum8 (1) + `trace_id` UUID (16) = 33 bytes — is bounds-checked ONCE
+ *   (`advance(s, 33)`) and read at constant offsets, instead of four `advance`s.
+ * - the `Variant` is an inlined `switch` over the discriminant (sorted order).
+ * - leaf reads inlined, `formatUUIDTable` for the UUID, pre-sized arrays.
+ * The variable-width columns (`payload`/`tags`/`metrics`/`attrs`) each start a new
+ * `advance` run because their size isn't known until decoded.
+ */
+export const readObsRowFast: Reader<ObsRow> = (s) => {
+  const { buf, view } = s;
+
+  // One bounds check for the 33-byte fixed-width head.
+  const o = advance(s, 33);
+  const id = view.getBigUint64(o, true);
+  const ts = new Date(Number(view.getBigInt64(o + 8, true))).toISOString();
+  const level = view.getInt8(o + 16);
+  const traceId = formatUUIDTable(buf.subarray(o + 17, o + 33));
+
+  // payload Variant(String, Int64, Float64): 1-byte discriminant (sorted names:
+  // 0=Float64, 1=Int64, 2=String), 0xFF = NULL.
+  let payload: number | bigint | string | null;
+  const disc = buf[advance(s, 1)]!;
+  if (disc === 0xff) {
+    payload = null;
+  } else if (disc === 0) {
+    payload = view.getFloat64(advance(s, 8), true);
+  } else if (disc === 1) {
+    payload = view.getBigInt64(advance(s, 8), true);
+  } else {
+    const len = readUVarint(s);
+    const st = advance(s, len);
+    payload = buf.toString("utf8", st, st + len);
+  }
+
+  // tags Map(LowCardinality(String) -> String): count, then key/value strings.
+  const tagN = readUVarint(s);
+  const tags = new Map<string, string>();
+  for (let i = 0; i < tagN; i++) {
+    let len = readUVarint(s);
+    let st = advance(s, len);
+    const k = buf.toString("utf8", st, st + len);
+    len = readUVarint(s);
+    st = advance(s, len);
+    tags.set(k, buf.toString("utf8", st, st + len));
+  }
+
+  // metrics Array(Tuple(name LowCardinality(String), value Float64)).
+  const mN = readUVarint(s);
+  const metrics = new Array<{ name: string; value: number }>(mN);
+  for (let i = 0; i < mN; i++) {
+    const len = readUVarint(s);
+    const st = advance(s, len);
+    const name = buf.toString("utf8", st, st + len);
+    const value = view.getFloat64(advance(s, 8), true);
+    metrics[i] = { name, value };
+  }
+
+  // attrs Array(Nullable(Int64)).
+  const aN = readUVarint(s);
+  const attrs = new Array<bigint | null>(aN);
+  for (let i = 0; i < aN; i++) {
+    attrs[i] =
+      buf[advance(s, 1)]! !== 0 ? null : view.getBigInt64(advance(s, 8), true);
+  }
+
+  return { id, ts, level, traceId, payload, tags, metrics, attrs };
+};

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

@@ -0,0 +1,65 @@
+import { type Reader, advance } from "../core.js";
+import { type DecimalValue, readDecimal64 } from "../decimals.js";
+import { readEnum8 } from "../enums.js";
+import { readUInt8 } from "../integers.js";
+import { formatUUID, formatUUIDTable, readUUID } from "../uuid.js";
+
+/**
+ * Example: an orders table — UUID, Decimal, and Enum (awkward-as-JSON types).
+ *
+ * Columns (the trigger):
+ *   id     UInt8
+ *   uid    UUID
+ *   price  Decimal64(2)
+ *   status Enum8('new' = 1, 'shipped' = 2, 'done' = 3)
+ *
+ * Shows the parse/format split and faithful values: `uid` is read as raw bytes
+ * then formatted with `formatUUID`; `price` stays the exact `[unscaled, scale]`
+ * pair (`[1234n, 2]` == 12.34), not a lossy float; `status` decodes to the
+ * underlying `Int8` value (1/2/3), the name<->value map being type metadata, not
+ * on the wire. The declared scale `2` is baked into `readDecimal64(2)`.
+ */
+export type OrderRow = {
+  id: number;
+  uid: string;
+  price: DecimalValue;
+  status: number;
+};
+
+export const readOrderRow: Reader<OrderRow> = (s) => ({
+  id: readUInt8(s),
+  uid: formatUUID(readUUID(s)),
+  price: readDecimal64(2)(s),
+  status: readEnum8(s),
+});
+
+/**
+ * Optimized {@link readOrderRow}, flattened per the SKILL.md guidance:
+ * - `buf`/`view` hoisted to locals (one property load, not one per field).
+ * - every column here is FIXED-WIDTH, so the whole row — `id` UInt8 (1) + `uid`
+ *   UUID (16) + `price` Decimal64 (8) + `status` Enum8 (1) = 26 bytes — is
+ *   bounds-checked ONCE (`advance(s, 26)`) and read at constant offsets, instead
+ *   of four separate `advance`s. (This is the exact worked example in SKILL.md.)
+ * - the four leaf reads are inlined, and the BigInt `formatUUID` is swapped for
+ *   the lookup-table `formatUUIDTable` (~1.6x on its own; see `readUUID.bench.ts`).
+ *   Since this example formats every UUID to a string, that swap is the dominant
+ *   win — the `readDecimal64(2)` closure (rebuilt per row above) is inlined too.
+ *
+ * MEASURED (Node 24 / V8, `orders.bench.ts`): ~2.6x faster — the largest win of
+ * the examples, dominated by the `formatUUIDTable` swap (every row stringifies a
+ * UUID; the table formatter is ~1.7x on its own and the row is otherwise cheap).
+ *
+ * `formatUUIDTable` uses a shared scratch buffer, so it is non-reentrant — fine
+ * here because the bytes are copied into the returned string synchronously before
+ * the next call.
+ */
+export const readOrderRowFast: Reader<OrderRow> = (s) => {
+  const { buf, view } = s;
+  // One bounds check for the whole 26-byte fixed-width row.
+  const o = advance(s, 26);
+  const id = buf[o]!;
+  const uid = formatUUIDTable(buf.subarray(o + 1, o + 17));
+  const price: DecimalValue = [view.getBigInt64(o + 17, true), 2];
+  const status = view.getInt8(o + 25);
+  return { id, uid, price, status };
+};

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

@@ -0,0 +1,60 @@
+import { readArray, readNullable } from "../composite.js";
+import { type Reader, advance } from "../core.js";
+import { readInt32, readUInt32 } from "../integers.js";
+import { readString } from "../strings.js";
+import { readUVarint } from "../varint.js";
+
+/**
+ * Example: a profiles table — Array and Nullable wrappers.
+ *
+ * Columns (the trigger):
+ *   id    UInt32
+ *   tags  Array(String)
+ *   score Nullable(Int32)
+ *
+ * `readArray(elem)` reads a LEB128 length then that many elements; `readNullable`
+ * reads a 1-byte present/NULL flag then the value. Both are combinators: pass the
+ * inner reader and they return a `Reader`. Empty array and NULL are the sharp
+ * cases (a single byte each).
+ */
+export type ProfileRow = { id: number; tags: string[]; score: number | null };
+
+export const readProfileRow: Reader<ProfileRow> = (s) => ({
+  id: readUInt32(s),
+  tags: readArray(readString)(s),
+  score: readNullable(readInt32)(s),
+});
+
+/**
+ * Optimized {@link readProfileRow}, monomorphized: `readArray(readString)` and
+ * `readNullable(readInt32)` each allocate a fresh combinator closure on EVERY
+ * row in the version above; here the array loop and the null-flag branch are
+ * inlined, so no per-row closures are created and the element/inner reads are
+ * straight-line. This is the kind of win the SKILL's "monomorphize" step targets;
+ * see `profiles.bench.ts`.
+ *
+ * MEASURED (Node 24 / V8, `profiles.bench.ts`): ~1.3x faster — removing the two
+ * per-row combinator closures (`readArray(readString)`, `readNullable(readInt32)`)
+ * is the win.
+ */
+export const readProfileRowFast: Reader<ProfileRow> = (s) => {
+  const { buf, view } = s;
+
+  // id UInt32.
+  const id = view.getUint32(advance(s, 4), true);
+
+  // tags Array(String): count, then each a length-prefixed UTF-8 string.
+  const n = readUVarint(s);
+  const tags = new Array<string>(n);
+  for (let i = 0; i < n; i++) {
+    const len = readUVarint(s);
+    const start = advance(s, len);
+    tags[i] = buf.toString("utf8", start, start + len);
+  }
+
+  // score Nullable(Int32): null-flag byte, then if non-null a 4-byte int.
+  const score =
+    buf[advance(s, 1)]! !== 0 ? null : view.getInt32(advance(s, 4), true);
+
+  return { id, tags, score };
+};

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