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

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

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

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

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

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

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

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]!,
+  };
+}