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

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

@@ -0,0 +1,125 @@
+import { type Writer, Sink, reserve } from "./core.js";
+import { type Point } from "../readers/geo.js";
+import { writeUInt8 } from "./integers.js";
+import { writeUVarint } from "./varint.js";
+
+/**
+ * Write a `Point`: `Tuple(Float64, Float64)` -> `[x, y]`. Inverse of `readPoint`.
+ * A single `reserve(16)` then two inlined `setFloat64`s — no per-coordinate
+ * `writeFloat64` call and only one bounds check.
+ */
+export function writePoint(sink: Sink, [x, y]: Point): void {
+  const o = reserve(sink, 16);
+  sink.view.setFloat64(o, x, true);
+  sink.view.setFloat64(o + 8, y, true);
+}
+
+/**
+ * Write a `Ring`: `Array(Point)` — a LEB128 point count, then each point. The
+ * inverse of `readRing`; a SINGLE `reserve(16 * length)` covers the whole point
+ * block (one bounds check per ring, not per point), then the coordinates are
+ * written into it inline, mirroring the reader.
+ */
+export function writeRing(sink: Sink, points: readonly Point[]): void {
+  writeUVarint(sink, points.length);
+  let p = reserve(sink, points.length * 16);
+  for (let i = 0; i < points.length; i++) {
+    const [x, y] = points[i]!;
+    sink.view.setFloat64(p, x, true);
+    sink.view.setFloat64(p + 8, y, true);
+    p += 16;
+  }
+}
+
+/** Write a `LineString`: `Array(Point)` (identical wire to a `Ring`). Inverse of `readLineString`. */
+export function writeLineString(sink: Sink, points: readonly Point[]): void {
+  writeUVarint(sink, points.length);
+  let p = reserve(sink, points.length * 16);
+  for (let i = 0; i < points.length; i++) {
+    const [x, y] = points[i]!;
+    sink.view.setFloat64(p, x, true);
+    sink.view.setFloat64(p + 8, y, true);
+    p += 16;
+  }
+}
+
+/** Write a `Polygon`: `Array(Ring)` — outer ring first, then holes. Inverse of `readPolygon`. */
+export function writePolygon(sink: Sink, rings: readonly Point[][]): void {
+  writeUVarint(sink, rings.length);
+  for (let i = 0; i < rings.length; i++) writeRing(sink, rings[i]!);
+}
+
+/** Write a `MultiLineString`: `Array(LineString)`. Inverse of `readMultiLineString`. */
+export function writeMultiLineString(
+  sink: Sink,
+  lines: readonly Point[][],
+): void {
+  writeUVarint(sink, lines.length);
+  for (let i = 0; i < lines.length; i++) writeLineString(sink, lines[i]!);
+}
+
+/** Write a `MultiPolygon`: `Array(Polygon)`. Inverse of `readMultiPolygon`. */
+export function writeMultiPolygon(
+  sink: Sink,
+  polygons: readonly Point[][][],
+): void {
+  writeUVarint(sink, polygons.length);
+  for (let i = 0; i < polygons.length; i++) writePolygon(sink, polygons[i]!);
+}
+
+/**
+ * A tagged `Geometry` value for {@link writeGeometry}: the alternative's
+ * `discriminant` paired with its value, or `null` for NULL. Like
+ * `readVariant`/`writeVariant`, `readGeometry` returns only the value — and the
+ * geo value shapes overlap (LineString and Ring are both `Point[]`,
+ * MultiLineString and Polygon both `Point[][]`) — so encode must be told which geo
+ * type it is via the discriminant.
+ *
+ * Discriminants (sorted by type name): LineString(0), MultiLineString(1),
+ * MultiPolygon(2), Point(3), Polygon(4), Ring(5); `0xFF` = NULL.
+ */
+export type GeometryValue =
+  | readonly [discriminant: number, value: unknown]
+  | null;
+
+/**
+ * Write a `Geometry`: a 1-byte discriminant then the chosen geo type's value. The
+ * inverse of `readGeometry` (a switch over the discriminant with each branch
+ * inlined). Takes a tagged {@link GeometryValue} because the value shapes are
+ * ambiguous on their own.
+ */
+export const writeGeometry: Writer<GeometryValue> = (sink, value) => {
+  if (value === null) {
+    writeUInt8(sink, 0xff);
+    return;
+  }
+  // The discriminant byte is written inside each case, only after the switch
+  // has accepted it — an out-of-range value throws from `default` before the
+  // sink is advanced, so it never leaves a partially-written payload behind
+  // (mirrors `writeVariant`).
+  const [discriminant, geo] = value;
+  switch (discriminant) {
+    case 0:
+      writeUInt8(sink, discriminant);
+      return writeLineString(sink, geo as Point[]);
+    case 1:
+      writeUInt8(sink, discriminant);
+      return writeMultiLineString(sink, geo as Point[][]);
+    case 2:
+      writeUInt8(sink, discriminant);
+      return writeMultiPolygon(sink, geo as Point[][][]);
+    case 3:
+      writeUInt8(sink, discriminant);
+      return writePoint(sink, geo as Point);
+    case 4:
+      writeUInt8(sink, discriminant);
+      return writePolygon(sink, geo as Point[][]);
+    case 5:
+      writeUInt8(sink, discriminant);
+      return writeRing(sink, geo as Point[]);
+    default:
+      throw new RangeError(
+        `RowBinary: unknown Geometry discriminant ${discriminant}`,
+      );
+  }
+};

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

@@ -0,0 +1,90 @@
+import { Sink, reserve } from "./core.js";
+
+// --- Writers: the encode mirror of the readers in `integers.ts`. Each writeX is
+// the inverse of the matching readX.
+
+/** Write a `UInt8`: 1 byte (0 .. 255). Mirror of `readUInt8`. */
+export function writeUInt8(sink: Sink, value: number): void {
+  sink.buf[reserve(sink, 1)] = value;
+}
+
+/** Write an `Int8`: 1 byte, two's-complement signed (-128 .. 127). Mirror of `readInt8`. */
+export function writeInt8(sink: Sink, value: number): void {
+  sink.view.setInt8(reserve(sink, 1), value);
+}
+
+/** Write a `UInt16`: 2 bytes, little-endian. Mirror of `readUInt16`. */
+export function writeUInt16(sink: Sink, value: number): void {
+  sink.view.setUint16(reserve(sink, 2), value, true);
+}
+
+/** Write an `Int16`: 2 bytes, little-endian, two's-complement. Mirror of `readInt16`. */
+export function writeInt16(sink: Sink, value: number): void {
+  sink.view.setInt16(reserve(sink, 2), value, true);
+}
+
+/** Write a `UInt32`: 4 bytes, little-endian. Mirror of `readUInt32`. */
+export function writeUInt32(sink: Sink, value: number): void {
+  sink.view.setUint32(reserve(sink, 4), value, true);
+}
+
+/** Write an `Int32`: 4 bytes, little-endian, two's-complement. Mirror of `readInt32`. */
+export function writeInt32(sink: Sink, value: number): void {
+  sink.view.setInt32(reserve(sink, 4), value, true);
+}
+
+/**
+ * Write a `UInt64`: 8 bytes, little-endian. Takes a `bigint` (mirror of
+ * `readUInt64`). Uses Node's `Buffer.writeBigUInt64LE`, which writes the 64-bit
+ * value straight from the bigint — no narrowing to a JS number. The value must be
+ * in `[0, 2^64)`.
+ */
+export function writeUInt64(sink: Sink, value: bigint): void {
+  sink.buf.writeBigUInt64LE(value, reserve(sink, 8));
+}
+
+/**
+ * Write an `Int64`: 8 bytes, little-endian, two's-complement. Takes a `bigint`
+ * (mirror of `readInt64`). Uses Node's `Buffer.writeBigInt64LE`, writing the
+ * signed 64-bit value straight from the bigint (range `[-2^63, 2^63)`).
+ */
+export function writeInt64(sink: Sink, value: bigint): void {
+  sink.buf.writeBigInt64LE(value, reserve(sink, 8));
+}
+
+/** Mask reducing a bigint word to its unsigned 64-bit (two's-complement) value. */
+const MASK64 = (1n << 64n) - 1n;
+
+/**
+ * Write a `UInt128`/`Int128`: 16 bytes, little-endian, as two 64-bit words (low
+ * then high). Each word is masked to 64 bits with `& MASK64` — a pure bigint
+ * operation that yields the correct unsigned (two's-complement) representation for
+ * negatives too — and written with Node's `Buffer.writeBigUInt64LE`, so this one
+ * function serves both `readUInt128` and `readInt128` without narrowing to a JS
+ * number.
+ */
+export function writeUInt128(sink: Sink, value: bigint): void {
+  const o = reserve(sink, 16);
+  sink.buf.writeBigUInt64LE(value & MASK64, o);
+  sink.buf.writeBigUInt64LE((value >> 64n) & MASK64, o + 8);
+}
+
+/** Write an `Int128`: 16 bytes LE two's-complement. Same word layout as {@link writeUInt128}. */
+export const writeInt128 = writeUInt128;
+
+/**
+ * Write a `UInt256`/`Int256`: 32 bytes, little-endian, as four 64-bit words
+ * (least-significant first). Like {@link writeUInt128}, each word is masked with
+ * `& MASK64` and written via `Buffer.writeBigUInt64LE`, handling both unsigned and
+ * signed (two's complement) values straight from the bigint.
+ */
+export function writeUInt256(sink: Sink, value: bigint): void {
+  const o = reserve(sink, 32);
+  sink.buf.writeBigUInt64LE(value & MASK64, o);
+  sink.buf.writeBigUInt64LE((value >> 64n) & MASK64, o + 8);
+  sink.buf.writeBigUInt64LE((value >> 128n) & MASK64, o + 16);
+  sink.buf.writeBigUInt64LE((value >> 192n) & MASK64, o + 24);
+}
+
+/** Write an `Int256`: 32 bytes LE two's-complement. Same word layout as {@link writeUInt256}. */
+export const writeInt256 = writeUInt256;

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