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

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

@@ -0,0 +1,51 @@
+import { type Reader, advance } from "../core.js";
+import { readDateTime } from "../datetime.js";
+import { readUInt64 } from "../integers.js";
+import { readString } from "../strings.js";
+import { readUVarint } from "../varint.js";
+
+/**
+ * Example: a plain events table — the scalar baseline.
+ *
+ * Columns (the trigger — generate this reader when a result has these types):
+ *   id   UInt64
+ *   name String
+ *   ts   DateTime('UTC')
+ *
+ * A wide integer (returned as `bigint`, never a lossy `number`), an arbitrary
+ * `String`, and a `DateTime` rendered to an ISO-8601 string here for a stable,
+ * timezone-independent result (the raw reader returns a JS `Date`). Drive it over
+ * a whole result with `readRows(readEventRow)`.
+ */
+export type EventRow = { id: bigint; name: string; ts: string };
+
+export const readEventRow: Reader<EventRow> = (s) => ({
+  id: readUInt64(s),
+  name: readString(s),
+  ts: readDateTime(s).toISOString(),
+});
+
+/**
+ * Optimized {@link readEventRow}: the same three reads inlined into one function
+ * body — no per-field reader calls, the `String` length + slice and the
+ * `DateTime` math written out in place. All scalars, so there is little for the
+ * monomorphization to remove (the JIT already inlines the leaf readers); see
+ * `events.bench.ts`. Still goes through `advance()`, so it stays streaming-safe.
+ *
+ * MEASURED (Node 24 / V8, `events.bench.ts`): ~1.05x — essentially ON PAR, within
+ * run-to-run noise. A purely scalar row has no per-row closures to remove and V8
+ * already inlines the leaf readers, so there is no real win here: prefer the
+ * clearer API `readEventRow` unless your own profiling says otherwise. (Contrast
+ * the composite examples, where monomorphization removes per-row closures and
+ * wins 1.3x–2.7x.)
+ */
+export const readEventRowFast: Reader<EventRow> = (s) => {
+  const id = s.view.getBigUint64(advance(s, 8), true);
+  const len = readUVarint(s);
+  const start = advance(s, len);
+  const name = s.buf.toString("utf8", start, start + len);
+  const ts = new Date(
+    s.view.getUint32(advance(s, 4), true) * 1000,
+  ).toISOString();
+  return { id, name, ts };
+};

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

@@ -0,0 +1,158 @@
+import { type Reader, advance } from "../core.js";
+import { readDateTime64P3 } from "../datetime.js";
+import { readFloat32, readFloat64 } from "../floats.js";
+import { readUInt8, readUInt32 } from "../integers.js";
+
+/**
+ * Example: a table of IoT sensor readings — the dense, fixed-width NUMERIC case
+ * that RowBinary is built for, and the headline of the RowBinary-vs-JSON
+ * comparison in `iot.bench.ts`.
+ *
+ * Columns (the trigger — generate this reader when a result has these types):
+ *   sensor_id   UInt32
+ *   ts          DateTime64(3)
+ *   temperature Float64
+ *   humidity    Float64
+ *   pressure    Float64
+ *   battery     Float32
+ *   status      UInt8
+ *
+ * Every column is fixed-width and there is not a single string or composite in
+ * the row, so the whole record is a flat 4 + 8 + 8 + 8 + 8 + 4 + 1 = 41-byte
+ * run. This is the shape where a JS RowBinary decoder beats `JSON.parse`: the
+ * wire is ~1/3 the size and each field is one `DataView` read, versus JSON's
+ * tokenize-and-number-parse over a much larger, key-repeating text.
+ */
+export type IotRow = {
+  sensor_id: number;
+  ts: Date;
+  temperature: number;
+  humidity: number;
+  pressure: number;
+  battery: number;
+  status: number;
+};
+
+/**
+ * API-combinator reader: correct and clear, one leaf reader per column. A fine
+ * default; `readIotRowFast` is the monomorphized form `iot.bench.ts` measures.
+ */
+export const readIotRow: Reader<IotRow> = (s) => ({
+  sensor_id: readUInt32(s),
+  ts: readDateTime64P3(s),
+  temperature: readFloat64(s),
+  humidity: readFloat64(s),
+  pressure: readFloat64(s),
+  battery: readFloat32(s),
+  status: readUInt8(s),
+});
+
+/**
+ * Optimized {@link readIotRow}: every column is fixed-width, so the seven
+ * separate bounds checks coalesce into one `advance(s, 41)` and each field is
+ * read at a constant offset off that base — no per-field reader calls, no cursor
+ * write-back between fields. Stays streaming-safe (one `advance`), so a row that
+ * straddles a chunk boundary still rewinds and retries cleanly.
+ *
+ *   sensor_id    UInt32        @ o+0   getUint32
+ *   ts           DateTime64(3) @ o+4   getBigInt64 (ms ticks -> Date)
+ *   temperature  Float64       @ o+12  getFloat64
+ *   humidity     Float64       @ o+20  getFloat64
+ *   pressure     Float64       @ o+28  getFloat64
+ *   battery      Float32       @ o+36  getFloat32
+ *   status       UInt8         @ o+40  buf[o+40]
+ */
+export const readIotRowFast: Reader<IotRow> = (s) => {
+  const { buf, view } = s;
+  const o = advance(s, 41); // one bounds check for the whole 41-byte row
+  const sensor_id = view.getUint32(o, true);
+  // DateTime64(3): Int64 millisecond ticks; ms fits a JS number, so Number() is exact here.
+  const ts = new Date(Number(view.getBigInt64(o + 4, true)));
+  const temperature = view.getFloat64(o + 12, true);
+  const humidity = view.getFloat64(o + 20, true);
+  const pressure = view.getFloat64(o + 28, true);
+  const battery = view.getFloat32(o + 36, true);
+  const status = buf[o + 40]!;
+  return { sensor_id, ts, temperature, humidity, pressure, battery, status };
+};
+
+/** Byte width of one fixed-width IoT row: 4 + 8 + 8 + 8 + 8 + 4 + 1. */
+export const IOT_ROW_BYTES = 41;
+
+/**
+ * Columnar (struct-of-arrays) form of the IoT result: one typed array per
+ * column instead of one object per row. `ts` is kept as epoch milliseconds in a
+ * `Float64Array` (format the few you display; don't allocate 50k `Date`s).
+ */
+export type IotColumns = {
+  sensor_id: Uint32Array;
+  ts: Float64Array; // epoch ms
+  temperature: Float64Array;
+  humidity: Float64Array;
+  pressure: Float64Array;
+  battery: Float32Array;
+  status: Uint8Array;
+};
+
+/**
+ * Decode the whole IoT result into columns (SoA) rather than row objects (AoS).
+ *
+ * MEASURED (`iot.columnar.bench.ts`): ~4x faster than `readIotRowFast` over the
+ * same buffer, and several times smaller in memory. The win is entirely from
+ * what it does NOT do — no per-row object, no `Date`, no number boxing — so the
+ * cost drops to one unboxed store per field. It is a NUMERIC win; it would not
+ * help a string column (a JS string must be allocated either way).
+ *
+ * WHOLE-BUFFER ONLY: this needs the complete response in one `Buffer`. Because
+ * every IoT column is fixed-width the row stride is known, so the exact row
+ * count is `buf.length / IOT_ROW_BYTES` — one exact allocation per column, no
+ * growth, no bounds check in the loop.
+ *
+ * Reach for this when the consumer is column-oriented (aggregate / filter /
+ * scan / plot / feed a Worker or WASM kernel via the transferable
+ * `ArrayBuffer`s). Prefer the row reader when downstream code is row-shaped.
+ */
+export function decodeIotColumnar(buf: Buffer): IotColumns {
+  const view = new DataView(buf.buffer, buf.byteOffset, buf.byteLength);
+  const n = (buf.length / IOT_ROW_BYTES) | 0;
+  // Hold each column in a LOCAL so the fill loop writes through a register-held
+  // typed-array reference, not a property load off a result object every
+  // iteration; assemble the object once, on return.
+  const sensor_id = new Uint32Array(n);
+  const ts = new Float64Array(n);
+  const temperature = new Float64Array(n);
+  const humidity = new Float64Array(n);
+  const pressure = new Float64Array(n);
+  const battery = new Float32Array(n);
+  const status = new Uint8Array(n);
+  let o = 0;
+  for (let i = 0; i < n; i++) {
+    sensor_id[i] = view.getUint32(o, true); // UInt32
+    ts[i] = Number(view.getBigInt64(o + 4, true)); // DateTime64(3) ms ticks
+    temperature[i] = view.getFloat64(o + 12, true); // Float64
+    humidity[i] = view.getFloat64(o + 20, true); // Float64
+    pressure[i] = view.getFloat64(o + 28, true); // Float64
+    battery[i] = view.getFloat32(o + 36, true); // Float32
+    status[i] = buf[o + 40]!; // UInt8
+    o += IOT_ROW_BYTES;
+  }
+  return { sensor_id, ts, temperature, humidity, pressure, battery, status };
+}
+
+/**
+ * Hybrid accessor: reconstruct a single {@link IotRow} object from columns on
+ * demand (here is where `ts` becomes a `Date`). Store columnar, and pay the
+ * object/`Date` cost only for the rows a caller actually touches — best when
+ * row access is sparse.
+ */
+export function iotRowAt(c: IotColumns, i: number): IotRow {
+  return {
+    sensor_id: c.sensor_id[i]!,
+    ts: new Date(c.ts[i]!),
+    temperature: c.temperature[i]!,
+    humidity: c.humidity[i]!,
+    pressure: c.pressure[i]!,
+    battery: c.battery[i]!,
+    status: c.status[i]!,
+  };
+}

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 };
+};