@clickhouse/client 1.23.0-head.dbc2960.1 → 1.23.0

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

@@ -0,0 +1,11 @@
+import { writeInt64 } from "./integers.js";
+
+/**
+ * Write an `Interval` — any of `IntervalNanosecond` ... `IntervalYear`: a signed
+ * `Int64` count of the unit. The inverse of `readInterval`; the unit lives in the
+ * column type, not the bytes, so all 11 interval types share this writer.
+ *
+ * It IS `writeInt64` — assigned directly rather than wrapped, so there is no extra
+ * call frame on the wire-write path.
+ */
+export const writeInterval = writeInt64;

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

@@ -0,0 +1,121 @@
+import { Sink, reserve } from "./core.js";
+
+/**
+ * Write an `IPv4`: the raw 32-bit value (as produced by `readIPv4`) as a 4-byte
+ * little-endian `UInt32`. The inverse of `readIPv4`; pair with {@link parseIPv4}
+ * to start from a dotted-quad string.
+ */
+export function writeIPv4(sink: Sink, value: number): void {
+  sink.view.setUint32(reserve(sink, 4), value, true);
+}
+
+/**
+ * Write an `IPv6`: the raw 16 bytes (network order, as produced by `readIPv6`)
+ * copied verbatim. The inverse of `readIPv6`; pair with {@link parseIPv6} to
+ * start from a string. Throws unless exactly 16 bytes.
+ */
+export function writeIPv6(sink: Sink, value: Uint8Array): void {
+  if (value.length !== 16) {
+    throw new RangeError(
+      `RowBinary: IPv6 must be 16 bytes, got ${value.length}`,
+    );
+  }
+  const o = reserve(sink, 16);
+  sink.buf.set(value, o);
+}
+
+/** Parse one dotted-quad field into a 0..255 octet, throwing on anything else. */
+function parseOctet(part: string): number {
+  const octet = Number(part);
+  if (!Number.isInteger(octet) || octet < 0 || octet > 255) {
+    throw new RangeError(
+      `RowBinary: invalid IPv4 octet ${JSON.stringify(part)}`,
+    );
+  }
+  return octet;
+}
+
+/**
+ * Parse a dotted-quad IPv4 string into the raw 32-bit value — the inverse of
+ * `formatIPv4`. `"1.2.3.4"` -> `0x01020304`. Pair with {@link writeIPv4}.
+ *
+ * The four octets are read explicitly rather than in a loop (only ever four);
+ * `>>> 0` coerces the assembled value back to an unsigned 32-bit number.
+ */
+export function parseIPv4(text: string): number {
+  const parts = text.split(".");
+  if (parts.length !== 4) {
+    throw new RangeError(
+      `RowBinary: invalid IPv4 string ${JSON.stringify(text)}`,
+    );
+  }
+  const a = parseOctet(parts[0]!);
+  const b = parseOctet(parts[1]!);
+  const c = parseOctet(parts[2]!);
+  const d = parseOctet(parts[3]!);
+  return ((a << 24) | (b << 16) | (c << 8) | d) >>> 0;
+}
+
+/**
+ * Parse an IPv6 string into its raw 16 bytes (network order) — the inverse of
+ * `formatIPv6`, accepting the canonical forms it emits (`::` zero-run compression
+ * and the `::ffff:a.b.c.d` IPv4-mapped form) as well as the fully expanded form.
+ * Pair with {@link writeIPv6}.
+ *
+ * Rejects malformed input (throws): a parse-time helper validates because it
+ * must produce exactly 16 well-defined bytes and there is no hot loop or server
+ * to fall back on — see the "No defensive validation" exceptions in AGENTS.md.
+ */
+export function parseIPv6(text: string): Buffer {
+  const halves = text.split("::");
+  if (halves.length > 2) {
+    throw new RangeError(
+      `RowBinary: invalid IPv6 string ${JSON.stringify(text)}`,
+    );
+  }
+
+  // Expand a colon-separated side into 16-bit groups, splitting a trailing
+  // embedded IPv4 (a.b.c.d) into its two groups.
+  const toGroups = (side: string): number[] => {
+    if (side === "") return [];
+    const groups: number[] = [];
+    for (const part of side.split(":")) {
+      if (part.includes(".")) {
+        const v4 = parseIPv4(part);
+        groups.push((v4 >>> 16) & 0xffff, v4 & 0xffff);
+      } else {
+        // 1–4 hex digits only. Parsing strictly rather than `parseInt(...) &
+        // 0xffff` rejects malformed groups instead of silently turning them
+        // into 0 (`NaN & 0xffff`) or wrapping negatives like "-1" to 0xffff.
+        if (!/^[0-9a-fA-F]{1,4}$/.test(part)) {
+          throw new RangeError(
+            `RowBinary: invalid IPv6 group ${JSON.stringify(part)}`,
+          );
+        }
+        groups.push(parseInt(part, 16));
+      }
+    }
+    return groups;
+  };
+
+  const head = toGroups(halves[0]!);
+  const tail = halves.length === 2 ? toGroups(halves[1]!) : [];
+  const groups =
+    halves.length === 2
+      ? [...head, ...new Array(8 - head.length - tail.length).fill(0), ...tail]
+      : head;
+  if (groups.length !== 8) {
+    throw new RangeError(
+      `RowBinary: invalid IPv6 string ${JSON.stringify(text)}`,
+    );
+  }
+  // SAFE: allocUnsafe — the loop below writes all 16 bytes (out[0..15] for the
+  // 8 groups), and `out` is only allocated here, past every throw, so an
+  // uninitialized buffer is never returned.
+  const out = Buffer.allocUnsafe(16);
+  for (let i = 0; i < 8; i++) {
+    out[2 * i] = (groups[i]! >>> 8) & 0xff;
+    out[2 * i + 1] = groups[i]! & 0xff;
+  }
+  return out;
+}

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

@@ -0,0 +1,12 @@
+import { type Writer } from "./core.js";
+
+/**
+ * `LowCardinality(T)` is TRANSPARENT in RowBinary (no dictionary layer on the
+ * wire), so there is nothing extra to encode: use `T`'s own writer directly.
+ * This identity combinator mirrors `readLowCardinality` and returns the inner
+ * writer unchanged:
+ *
+ *   writeLowCardinality(writeString) === writeString
+ */
+export const writeLowCardinality = <T>(writeValue: Writer<T>): Writer<T> =>
+  writeValue;

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

@@ -0,0 +1,17 @@
+import { type Writer } from "./core.js";
+import { writeArray, writeTupleNamed } from "./composite.js";
+
+/**
+ * Inverse of `readNested`: `Nested(...)` has no wire format of its own, so for the
+ * `flatten_nested = 0` shape it is simply `Array(Tuple(a T1, b T2, …))`. This thin
+ * alias composes the existing array + named-tuple writers, mirroring the reader:
+ *
+ *   writeNested({ a: writeUInt8, b: writeString })
+ *     === writeArray(writeTupleNamed({ a: writeUInt8, b: writeString }))
+ *
+ * When generating code, prefer inlining (monomorphize the array + tuple) over this
+ * generic composition.
+ */
+export const writeNested = <T extends Record<string, unknown>>(writers: {
+  [K in keyof T]: Writer<T[K]>;
+}): Writer<readonly T[]> => writeArray(writeTupleNamed(writers));

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

@@ -0,0 +1,21 @@
+import { type Writer } from "./core.js";
+
+/**
+ * Inverse of `readNothing`: a `Nothing` value is NEVER written either. It only
+ * appears wrapped, where the wrapper short-circuits before reaching it:
+ *
+ *   writeArray(writeNothing)      // only the empty array [] (length 0x00)
+ *   writeNullable(writeNothing)   // only null (lone flag byte 0x01)
+ *
+ * In both cases the element/inner writer is not invoked. This writer throws if it
+ * is ever actually called, which would mean a `Nothing` writer was placed where a
+ * real element/inner type was expected.
+ */
+export const writeNothing: Writer<never> = () => {
+  throw new Error(
+    "RowBinary: Nothing is zero-width and is never encoded — it only appears as " +
+      "an empty Array(Nothing) or a NULL Nullable(Nothing), where the inner writer " +
+      "is not called. Reaching here means a Nothing writer was wired where a real " +
+      "element/inner type was expected.",
+  );
+};

package/skills/clickhouse-js-node-rowbinary/src/writers/rows.ts

@@ -0,0 +1,144 @@
+import { channel } from "node:diagnostics_channel";
+import { BufferFull, Sink, type Writer } from "./core.js";
+
+/** Default sink size when `writeRows` isn't given one — a typical flush chunk. */
+const DEFAULT_BUFFER_SIZE = 64 * 1024;
+
+/**
+ * Payload of {@link FLUSH_CHANNEL_NAME}, published once per buffer `writeRows`
+ * flushes — the hook for buffer-capacity-utilization metrics (e.g. an OTEL
+ * `used_bytes` / `capacity_bytes` counter pair, divided in the backend for a
+ * byte-weighted average fill). Identity (table, `query_id`, …) is deliberately
+ * NOT here: carry it in `AsyncLocalStorage` and read it in the subscriber, which
+ * runs synchronously on the publisher's call stack, so its async context is live.
+ */
+export interface WriteRowsFlush {
+  /** Bytes actually written into the buffer just flushed (`<= capacityBytes`). */
+  usedBytes: number;
+  /** That buffer's capacity; doubles from `bufferSize` to fit an oversized row. */
+  capacityBytes: number;
+  /**
+   * The configured initial buffer size for this run. `capacityBytes > bufferSize`
+   * means the buffer had to grow to fit an oversized row, and `usedBytes /
+   * bufferSize` is the overflow magnitude — the signal that `bufferSize` is too
+   * small. (Growth is sticky: once grown, every later flush in the run reports the
+   * larger `capacityBytes`, so compare against `bufferSize`, not a prior capacity.)
+   */
+  bufferSize: number;
+  /** Why it flushed: `"full"` mid-stream (next row overflowed) or `"end"` (rows ran out). */
+  reason: "full" | "end";
+}
+
+/**
+ * `node:diagnostics_channel` name {@link writeRows} publishes a {@link WriteRowsFlush}
+ * once per flushed buffer. Subscribe to observe buffer-capacity utilization; with no
+ * subscriber `writeRows` skips the publish entirely (a single `hasSubscribers`
+ * check per buffer, off the per-row path), so it's free when unused.
+ */
+export const FLUSH_CHANNEL_NAME = "@clickhouse/rowbinary:writeRows.flush";
+
+/** Created once — `channel()` is idempotent (same name → same object). */
+const flushChannel = channel(FLUSH_CHANNEL_NAME);
+
+/**
+ * Drive `writeRow` over every row of an iterable into a plain `RowBinary` payload
+ * — the encode mirror of `readRows`. Rows are concatenated with NO count, length
+ * prefix, or delimiter (just as the reader expects), so `writeRow` must emit
+ * EXACTLY one row's bytes. Curried: `writeRows(writeRow)` returns the driver.
+ *
+ * Returns a GENERATOR rather than a `Writer<readonly T[]>` on purpose. A `Sink`
+ * wraps a FIXED-length buffer, so a large (or unbounded) result won't fit in one
+ * pass — when a row would overflow, `writeRow` throws {@link BufferFull} from
+ * `reserve`, and a plain `(sink, rows) => void` would let that escape mid-row,
+ * leaving the caller unable to tell how many rows actually made it in. Instead
+ * this owns the sink: it catches `BufferFull`, rewinds to the last COMPLETE row
+ * boundary (never a half-written row), `yield`s that batch, and starts a FRESH
+ * `Sink` for the rows that didn't fit. Because each flush gets its own buffer,
+ * every yielded `Buffer` stays valid after the generator resumes — safe to retain
+ * or hand to an async sink, no copy needed. The caller supplies a `bufferSize`,
+ * not a sink, and `rows` is an `Iterable<T>` (not a fixed array), so the same
+ * driver handles a future infinite/streaming row source unchanged.
+ *
+ * The driver loop is just a `for...of` — the generator yields each batch of whole
+ * rows whenever it stops accumulating (on overflow, or when the rows run out), so
+ * the final batch comes through the same channel and there's nothing to flush
+ * afterwards:
+ *
+ *   const drive = writeRows(writeRow);
+ *   for (const chunk of drive(rows, 64 * 1024)) send(chunk);
+ *
+ * OVERSIZED ROWS: when a single row won't fit even an empty buffer, the buffer is
+ * GROWN (doubled) and the row retried — never dropped, never thrown. The first
+ * time this happens `writeRows` `console.warn`s ONCE (the buffer may keep doubling
+ * after that) so an under-sized `bufferSize` or a pathologically large row doesn't
+ * pass unnoticed.
+ *
+ * METRICS: each flushed buffer is published as a {@link WriteRowsFlush} on the
+ * {@link FLUSH_CHANNEL_NAME} diagnostics channel — wire it to a utilization metric.
+ * No subscriber means no publish (one `hasSubscribers` check per buffer).
+ *
+ * When generating code, inline the per-column writes into the loop body,
+ * mirroring the reader.
+ */
+export function writeRows<T>(
+  writeRow: Writer<T>,
+): (rows: Iterable<T>, bufferSize?: number) => Generator<Buffer, void, void> {
+  return function* (rows, bufferSize = DEFAULT_BUFFER_SIZE) {
+    if (!Number.isSafeInteger(bufferSize) || bufferSize <= 0)
+      // Guard the growth loop: a 0 / NaN / negative size makes the first row
+      // overflow forever (`size *= 2` never escapes 0/NaN), so fail fast instead.
+      throw new RangeError(
+        `RowBinary writeRows: bufferSize must be a positive integer, got ${bufferSize}`,
+      );
+    let size = bufferSize;
+    let warned = false;
+    let sink = new Sink(Buffer.allocUnsafe(size));
+    for (const row of rows) {
+      while (true) {
+        const committed = sink.pos; // start of this row — the last clean boundary
+        try {
+          writeRow(sink, row);
+          break; // row written cleanly — on to the next
+        } catch (e) {
+          if (e !== BufferFull) throw e;
+          if (committed === 0) {
+            // An empty buffer couldn't hold even this one row: double it and
+            // retry the SAME row — never drop it. Nothing was written, so the
+            // discarded sink had no bytes to flush.
+            size *= 2;
+            if (!warned) {
+              warned = true;
+              console.warn(
+                `RowBinary writeRows: a row didn't fit bufferSize=${bufferSize}; ` +
+                  `growing the buffer beyond it (possibly more than once). Raise bufferSize.`,
+              );
+            }
+            sink = new Sink(Buffer.allocUnsafe(size));
+            continue;
+          }
+          sink.pos = committed; // drop the partially written row, then flush
+          if (flushChannel.hasSubscribers)
+            flushChannel.publish({
+              usedBytes: committed,
+              capacityBytes: size,
+              bufferSize,
+              reason: "full",
+            } satisfies WriteRowsFlush);
+          yield sink.bytes();
+          sink = new Sink(Buffer.allocUnsafe(size)); // fresh buffer; retry the row
+        }
+      }
+    }
+    if (sink.pos > 0) {
+      // the final batch
+      if (flushChannel.hasSubscribers)
+        flushChannel.publish({
+          usedBytes: sink.pos,
+          capacityBytes: size,
+          bufferSize,
+          reason: "end",
+        } satisfies WriteRowsFlush);
+      yield sink.bytes();
+    }
+  };
+}

package/skills/clickhouse-js-node-rowbinary/src/writers/simpleAggregateFunction.ts

@@ -0,0 +1,12 @@
+import { type Writer } from "./core.js";
+
+/**
+ * `SimpleAggregateFunction(func, T)` is TRANSPARENT in RowBinary — the column
+ * holds a finished value of `T` — so encode the inner `T` directly. Identity
+ * combinator mirroring `readSimpleAggregateFunction`:
+ *
+ *   writeSimpleAggregateFunction(writeUInt64) === writeUInt64
+ */
+export const writeSimpleAggregateFunction = <T>(
+  writeValue: Writer<T>,
+): Writer<T> => writeValue;

package/skills/clickhouse-js-node-rowbinary/src/writers/strings.ts

@@ -0,0 +1,77 @@
+import { type Writer, Sink, reserve } from "./core.js";
+import { writeUVarint } from "./varint.js";
+
+/**
+ * Write a `String` from a JS string: a varint byte-length prefix followed by the
+ * UTF-8 bytes. The inverse of `readString`.
+ *
+ * Split from {@link writeStringBytes} (rather than one function branching on the
+ * argument type) so each is monomorphic — V8 keeps a single shape per call site
+ * instead of going megamorphic on a `string | Uint8Array` parameter.
+ */
+export function writeString(sink: Sink, value: string): void {
+  const len = Buffer.byteLength(value, "utf8");
+  writeUVarint(sink, len);
+  const o = reserve(sink, len);
+  sink.buf.write(value, o, len, "utf8");
+}
+
+/**
+ * Write a `String` from raw bytes: a varint byte-length prefix followed by the
+ * bytes verbatim. Use this for ClickHouse `String` columns holding arbitrary
+ * (non-UTF-8) bytes, mirroring the reader's note that `String` is not guaranteed
+ * UTF-8. The bytes counterpart of {@link writeString} (see the note there on why
+ * they are kept as two monomorphic functions).
+ */
+export function writeStringBytes(sink: Sink, value: Uint8Array): void {
+  writeUVarint(sink, value.length);
+  const o = reserve(sink, value.length);
+  sink.buf.set(value, o);
+}
+
+/**
+ * Write a `FixedString(N)` from a string: exactly `size` bytes, UTF-8 encoded and
+ * right-padded with NUL bytes (`\x00`) to `size`. Curried: `writeFixedString(N)`
+ * returns the writer. The inverse of `readFixedString` — which preserves the
+ * trailing NULs, so re-encoding a value it produced is byte-exact.
+ *
+ * Throws if the UTF-8 encoding exceeds `size` bytes (it would not fit the column).
+ */
+export function writeFixedString(size: number): Writer<string> {
+  return (sink, value) => {
+    const len = Buffer.byteLength(value, "utf8");
+    if (len > size) {
+      throw new RangeError(
+        `RowBinary: FixedString value is ${len} bytes, exceeds FixedString(${size})`,
+      );
+    }
+    const o = reserve(sink, size);
+    sink.buf.write(value, o, len, "utf8");
+    // The sink's buffer may be uninitialized (allocUnsafe); zero the padding.
+    // POTENTIAL OPTIMIZATION: drop this fill when the buffer is known to be
+    // zero-initialized. Kept by default — relying on a zeroed buffer is a footgun
+    // (a pooled/reused sink would leak stale bytes into the column).
+    sink.buf.fill(0, o + len, o + size);
+  };
+}
+
+/**
+ * Write a `FixedString(N)` from raw bytes: exactly `size` bytes, the value copied
+ * verbatim and right-padded with NUL bytes if shorter. Curried:
+ * `writeFixedStringBytes(N)` returns the writer. The inverse of
+ * `readFixedStringBytes` (binary columns).
+ *
+ * Throws if the value is longer than `size`.
+ */
+export function writeFixedStringBytes(size: number): Writer<Uint8Array> {
+  return (sink, value) => {
+    if (value.length > size) {
+      throw new RangeError(
+        `RowBinary: FixedString value is ${value.length} bytes, exceeds FixedString(${size})`,
+      );
+    }
+    const o = reserve(sink, size);
+    sink.buf.set(value, o);
+    sink.buf.fill(0, o + value.length, o + size);
+  };
+}

package/skills/clickhouse-js-node-rowbinary/src/writers/time.ts

@@ -0,0 +1,54 @@
+import { type Writer, Sink } from "./core.js";
+import { type ScaledTicks, type Seconds } from "../readers/time.js";
+import { writeInt32, writeInt64 } from "./integers.js";
+
+/**
+ * Write a `Time`: 4-byte signed `Int32` seconds-of-day. The inverse of `readTime`;
+ * pair with {@link parseTime} to start from an "[-]HH:MM:SS" string.
+ */
+export function writeTime(sink: Sink, value: Seconds): void {
+  writeInt32(sink, value);
+}
+
+/**
+ * Write a `Time64(P)`: 8-byte signed `Int64` count of `10^-P`-second ticks, from
+ * a {@link ScaledTicks} `[ticks, precision]`. The inverse of `readTime64`; the
+ * precision lives in the type, so only `ticks` is written. Pair with
+ * {@link parseTime64} to start from a string.
+ */
+export const writeTime64: Writer<ScaledTicks> = (sink, [ticks]) =>
+  writeInt64(sink, ticks);
+
+/**
+ * Parse an "[-]HH:MM:SS" string into signed seconds-of-day — the inverse of
+ * `formatTime`. The hour field may exceed two digits (range ±999:59:59).
+ */
+export function parseTime(text: string): Seconds {
+  const neg = text.startsWith("-");
+  const body = neg ? text.slice(1) : text;
+  const [hh, mm, ss] = body.split(":");
+  const seconds = Number(hh) * 3600 + Number(mm) * 60 + Number(ss);
+  return neg ? -seconds : seconds;
+}
+
+/**
+ * Parse an "[-]HH:MM:SS[.fff]" string into a {@link ScaledTicks} at the given
+ * `precision` — the inverse of `formatTime64`. A shorter fraction is right-padded
+ * with zeros to `precision`; a longer one is truncated.
+ */
+export function parseTime64(text: string, precision: number): ScaledTicks {
+  const neg = text.startsWith("-");
+  const body = neg ? text.slice(1) : text;
+  const dot = body.indexOf(".");
+  const timePart = dot < 0 ? body : body.slice(0, dot);
+  const fracPart = dot < 0 ? "" : body.slice(dot + 1);
+  const [hh, mm, ss] = timePart.split(":");
+  const scale = 10n ** BigInt(precision);
+  const wholeSeconds =
+    BigInt(Number(hh) * 3600 + Number(mm) * 60 + Number(ss)) * scale;
+  const frac = BigInt(
+    (fracPart + "0".repeat(precision)).slice(0, precision) || "0",
+  );
+  const ticks = wholeSeconds + frac;
+  return [neg ? -ticks : ticks, precision];
+}

package/skills/clickhouse-js-node-rowbinary/src/writers/uuid.ts

@@ -0,0 +1,60 @@
+import { Sink, reserve } from "./core.js";
+
+/**
+ * Parse a canonical `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` UUID string into the
+ * raw 16 wire bytes — the inverse of `formatUUID`. ClickHouse stores a UUID as
+ * two little-endian `UInt64` halves (high then low), so the 32 hex digits are
+ * split at the midpoint and each half written little-endian. Pair with
+ * {@link writeUUID}.
+ */
+export function parseUUID(text: string): Buffer {
+  const hex = text.replace(/-/g, "");
+  if (hex.length !== 32) {
+    throw new RangeError(
+      `RowBinary: invalid UUID string ${JSON.stringify(text)}`,
+    );
+  }
+  const v = BigInt("0x" + hex);
+  // SAFE: allocUnsafe — the two writeBigUInt64LE calls below overwrite all 16
+  // bytes (offsets 0..7 and 8..15), so no uninitialized pool memory survives.
+  const b = Buffer.allocUnsafe(16);
+  b.writeBigUInt64LE(v >> 64n, 0); // high half -> first 8 bytes
+  b.writeBigUInt64LE(v & 0xffffffffffffffffn, 8); // low half -> last 8 bytes
+  return b;
+}
+
+/**
+ * Write a `UUID` from its raw 16 wire bytes (as produced by `readUUID` or
+ * {@link parseUUID}): copied verbatim. The inverse of `readUUID`. Throws unless
+ * exactly 16 bytes are given.
+ */
+export function writeUUID(sink: Sink, value: Uint8Array): void {
+  if (value.length !== 16) {
+    throw new RangeError(
+      `RowBinary: UUID must be 16 bytes, got ${value.length}`,
+    );
+  }
+  const o = reserve(sink, 16);
+  sink.buf.set(value, o);
+}
+
+/**
+ * Write a `UUID` from a single 128-bit `bigint` (`hi << 64 | lo`) — the inverse
+ * of `readUUIDBigInt`. The high 64 bits go to the first little-endian `UInt64`
+ * half, the low 64 bits to the second.
+ */
+export function writeUUIDBigInt(sink: Sink, value: bigint): void {
+  const o = reserve(sink, 16);
+  sink.buf.writeBigUInt64LE((value >> 64n) & 0xffffffffffffffffn, o);
+  sink.buf.writeBigUInt64LE(value & 0xffffffffffffffffn, o + 8);
+}
+
+/**
+ * Write a `UUID` from its two raw little-endian `UInt64` halves `[hi, lo]` — the
+ * inverse of `readUUIDHiLo`, the faithful wire split with no combining work.
+ */
+export function writeUUIDHiLo(sink: Sink, [hi, lo]: [bigint, bigint]): void {
+  const o = reserve(sink, 16);
+  sink.buf.writeBigUInt64LE(hi, o);
+  sink.buf.writeBigUInt64LE(lo, o + 8);
+}

package/skills/clickhouse-js-node-rowbinary/src/writers/varint.ts

@@ -0,0 +1,64 @@
+import { Sink, reserve } from "./core.js";
+
+/**
+ * Write a LEB128 unsigned varint — the encode mirror of `readUVarint` (used for
+ * string/array/map lengths).
+ *
+ * Takes a JS `number`, so it is NOT bigint-friendly: the value MUST be a
+ * non-negative integer no larger than `Number.MAX_SAFE_INTEGER` (2^53 - 1). That
+ * precondition is NOT checked here — at this level the data is expected to be
+ * correct (a length the encoder itself produced), and an out-of-range value is a
+ * programming error the server will reject. If you genuinely need lengths beyond
+ * 2^53, write a bigint version with a bigint accumulator instead of widening this
+ * one.
+ *
+ * UNROLLED, mirroring `readUVarint`: branch on magnitude so the exact byte count
+ * is known up front for a single {@link reserve}, with no length-counting loop.
+ * Each byte carries 7 payload bits low-first, with the continuation bit (`+ 0x80`)
+ * set while more bits remain. `/` and `%` (never `>>>`/`&`): JS bitwise operators
+ * are 32-bit and would corrupt values past bit 31. The overwhelmingly common
+ * 1–2 byte case costs one or two compares.
+ */
+export function writeUVarint(sink: Sink, value: number): void {
+  if (value < 0x80) {
+    sink.buf[reserve(sink, 1)] = value;
+    return;
+  }
+  if (value < 0x4000) {
+    const o = reserve(sink, 2);
+    sink.buf[o] = (value % 128) + 0x80;
+    sink.buf[o + 1] = Math.floor(value / 128);
+    return;
+  }
+  if (value < 0x200000) {
+    const o = reserve(sink, 3);
+    sink.buf[o] = (value % 128) + 0x80;
+    sink.buf[o + 1] = (Math.floor(value / 128) % 128) + 0x80;
+    sink.buf[o + 2] = Math.floor(value / 16384);
+    return;
+  }
+  if (value < 0x10000000) {
+    const o = reserve(sink, 4);
+    sink.buf[o] = (value % 128) + 0x80;
+    sink.buf[o + 1] = (Math.floor(value / 128) % 128) + 0x80;
+    sink.buf[o + 2] = (Math.floor(value / 16384) % 128) + 0x80;
+    sink.buf[o + 3] = Math.floor(value / 2097152);
+    return;
+  }
+  // >= 2^28 — rare for RowBinary lengths. Fall back to a short loop writing into
+  // a single span sized by a leading magnitude count (still one reserve()).
+  let size = 5;
+  for (
+    let v = Math.floor(value / 268435456);
+    v >= 0x80;
+    v = Math.floor(v / 128)
+  )
+    size++;
+  const o = reserve(sink, size);
+  let v = value;
+  for (let i = 0; i < size - 1; i++) {
+    sink.buf[o + i] = (v % 128) + 0x80;
+    v = Math.floor(v / 128);
+  }
+  sink.buf[o + size - 1] = v;
+}