@clickhouse/client 1.22.0 → 1.23.0-head.70ad405.1

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

@@ -0,0 +1,140 @@
+import { type Writer } from "./core.js";
+import { writeUInt8 } from "./integers.js";
+import { writeUVarint } from "./varint.js";
+
+// --- Writers: the encode mirror of the combinators in `composite.ts`. Each takes
+// sub-WRITERS (instead of sub-readers) and returns a Writer; MONOMORPHIZE when
+// generating code, exactly as noted for the readers.
+
+/**
+ * Write a `Nullable(T)`: a 1-byte null flag (0 = present, 1 = NULL), then the
+ * inner value ONLY when present. The inverse of `readNullable`; curried — pass the
+ * inner writer, get a `Writer<T | null>`.
+ */
+export function writeNullable<T>(writeValue: Writer<T>): Writer<T | null> {
+  return (sink, value) => {
+    if (value === null) {
+      writeUInt8(sink, 1);
+    } else {
+      writeUInt8(sink, 0);
+      writeValue(sink, value);
+    }
+  };
+}
+
+/**
+ * Write an `Array(T)`: a LEB128 element count, then each element back-to-back. The
+ * inverse of `readArray`; curried — pass the element writer, get a `Writer<T[]>`.
+ */
+export function writeArray<T>(writeElement: Writer<T>): Writer<readonly T[]> {
+  return (sink, values) => {
+    writeUVarint(sink, values.length);
+    // C-style loop, not for-of: this is a hot path and we don't want the
+    // iterator protocol overhead on a plain array.
+    for (let i = 0; i < values.length; i++) writeElement(sink, values[i]!);
+  };
+}
+
+/**
+ * Write a `QBit(element_type, dimension)`: in RowBinary it is byte-for-byte an
+ * `Array(element_type)`, so this is just {@link writeArray}. The inverse of
+ * `readQBit`.
+ */
+export function writeQBit<T>(writeElement: Writer<T>): Writer<readonly T[]> {
+  return writeArray(writeElement);
+}
+
+/**
+ * Write a `Tuple(...)` from a positional array: each element's value
+ * back-to-back, with NO count and NO delimiter. The inverse of `readTuple`;
+ * curried — pass one writer per element (in order), get a `Writer` of the tuple.
+ */
+export function writeTuple<T extends readonly unknown[]>(writers: {
+  [K in keyof T]: Writer<T[K]>;
+}): Writer<T> {
+  const fns = writers as ReadonlyArray<Writer<unknown>>;
+  return (sink, value) => {
+    for (let i = 0; i < fns.length; i++) fns[i]!(sink, value[i]);
+  };
+}
+
+/**
+ * Write a named `Tuple(name1 T1, ...)` from an object. The wire is identical to an
+ * unnamed tuple — values back-to-back, no count or delimiter — so the writers run
+ * in the `writers` object's key order, which MUST match the tuple's declared field
+ * order. The inverse of `readTupleNamed`; curried.
+ */
+export function writeTupleNamed<T extends Record<string, unknown>>(writers: {
+  [K in keyof T]: Writer<T[K]>;
+}): Writer<T> {
+  const fns = writers as Record<string, Writer<unknown>>;
+  const keys = Object.keys(fns);
+  return (sink, value) => {
+    // C-style loop, not for-of: hot path, plain array of keys.
+    for (let i = 0; i < keys.length; i++) {
+      const key = keys[i]!;
+      fns[key]!(sink, value[key]);
+    }
+  };
+}
+
+/**
+ * Write a `Map(K, V)`: a LEB128 pair count, then key/value interleaved
+ * (k, v, k, v, ...). The inverse of `readMap`; curried — pass the key and value
+ * writers, get a `Writer<Map<K, V>>` (`Map` iteration order is preserved).
+ */
+export function writeMap<K, V>(
+  writeKey: Writer<K>,
+  writeValue: Writer<V>,
+): Writer<ReadonlyMap<K, V>> {
+  return (sink, map) => {
+    writeUVarint(sink, map.size);
+    // for-of is intentional here: it is the fastest way to iterate a `Map`
+    // (unlike plain arrays, where a C-style index loop wins).
+    for (const [key, value] of map) {
+      writeKey(sink, key);
+      writeValue(sink, value);
+    }
+  };
+}
+
+/**
+ * A tagged `Variant` value for {@link writeVariant}: the active alternative's
+ * `discriminant` (its index in the sorted-type-name order) paired with its value,
+ * or `null` for a NULL.
+ *
+ * WHY TAGGED: `readVariant` returns only the decoded VALUE — the discriminant is
+ * consumed from the wire and not surfaced — so encode cannot recover which
+ * alternative a bare value belongs to (e.g. is `5` the `UInt8` or the `Int32`
+ * alternative?). The discriminant must therefore be supplied explicitly, the
+ * encode-side analog of the `readGeometry` switch.
+ */
+export type VariantValue =
+  | readonly [discriminant: number, value: unknown]
+  | null;
+
+/**
+ * Write a `Variant(T1, ..., Tn)`: a 1-byte discriminant then the chosen
+ * alternative's value (discriminant `0xFF` = NULL, no value). The inverse of
+ * `readVariant`; curried — pass the alternative writers in sorted-type-name order
+ * (same order the reader expects), get a `Writer<VariantValue>`.
+ */
+export function writeVariant(
+  writers: ReadonlyArray<Writer<never>>,
+): Writer<VariantValue> {
+  return (sink, value) => {
+    if (value === null) {
+      writeUInt8(sink, 0xff);
+      return;
+    }
+    const [discriminant, inner] = value;
+    const fn = writers[discriminant] as Writer<unknown> | undefined;
+    if (fn === undefined) {
+      throw new RangeError(
+        `RowBinary Variant: discriminant ${discriminant} out of range (${writers.length} alternatives)`,
+      );
+    }
+    writeUInt8(sink, discriminant);
+    fn(sink, inner);
+  };
+}

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

@@ -0,0 +1,92 @@
+/**
+ * Thrown by {@link reserve} when the sink's buffer is full — i.e. lacks the bytes
+ * a write needs. The encode-side mirror of the reader's `NeedMoreData`. Like the
+ * reader, the `Sink` treats its buffer as a FIXED-length window: when a write
+ * would overflow it, `reserve` throws this sentinel WITHOUT moving the position,
+ * so a driver can flush the bytes written so far down the connection (a transport
+ * filter can glue successive buffers back together) and continue into a fresh
+ * buffer.
+ *
+ * A bare sentinel, NOT an `Error` subclass, on purpose — exactly as `NeedMoreData`
+ * on the read side: constructing an `Error` captures a stack trace (the expensive
+ * part of throwing), pure waste on a path that fires once per buffer boundary.
+ */
+export const BufferFull = Symbol("RowBinary.BufferFull");
+
+/**
+ * The write-side mirror of the reader's `Cursor`: the cursor every writer threads
+ * through. A `Buffer` to write into, the current write position, and a
+ * `DataView` over the same bytes. The encode counterpart of decode's `Cursor`.
+ *
+ * Deliberately STATE only — no write methods. Encoding lives in the free
+ * `writeX(sink, value)` functions in the sibling modules, so a generated encoder
+ * pulls in only the per-type writers a result needs (exactly like the reader
+ * side). `view`/`buf` are public so those free functions can reach them.
+ *
+ * Like a `Cursor`, a `Sink` wraps a FIXED-length buffer (supplied by the caller):
+ * it never reallocates. {@link reserve} throws {@link BufferFull} when the next
+ * write would overflow, the encode mirror of the reader's `advance` throwing
+ * `NeedMoreData` on underflow. Size the buffer to a chunk you intend to flush, and
+ * pull the written bytes with {@link Sink.bytes}.
+ */
+export class Sink {
+  pos = 0;
+
+  /**
+   * The buffer being written into. Only `buf.subarray(0, pos)` (see
+   * {@link Sink.bytes}) holds written bytes; the tail is unwritten headroom.
+   * Built with the buffer's own `byteOffset`/`byteLength` view in
+   * {@link Sink.view}, exactly like the reader's `Cursor`.
+   */
+  readonly buf: Buffer;
+
+  /**
+   * `DataView` over {@link Sink.buf}, for fixed-width integer/float writes. Built
+   * with the buffer's own `byteOffset`/`byteLength`: a `Buffer` is often a window
+   * into a larger pooled `ArrayBuffer`, so `new DataView(buf.buffer)` alone would
+   * point at the wrong bytes.
+   */
+  readonly view: DataView;
+
+  constructor(buf: Buffer) {
+    this.buf = buf;
+    this.view = new DataView(buf.buffer, buf.byteOffset, buf.byteLength);
+  }
+
+  /**
+   * The written bytes — `buf.subarray(0, pos)`. A zero-copy VIEW into the sink's
+   * buffer, so use `Buffer.from(sink.bytes())` if you need an independent copy.
+   */
+  bytes(): Buffer {
+    return this.buf.subarray(0, this.pos);
+  }
+}
+
+/**
+ * A `Writer<T>` encodes one value of type `T` into the sink, advancing it — the
+ * mirror of the reader's `Reader<T>`. Leaf writers (e.g. `writeUInt32`) are
+ * `Writer`s directly; combinators (e.g. `writeArray`) take sub-`Writer`s and
+ * return a `Writer`, so types compose with no per-element closures.
+ */
+export type Writer<T> = (sink: Sink, value: T) => void;
+
+/**
+ * Reserve `n` bytes for the next write: bounds-check them, advance the position
+ * past them, and return the offset the write starts at (the value BEFORE
+ * advancing). The write-side mirror of the reader's `advance`: every fixed-width
+ * write goes through it, so the capacity check and position bookkeeping live in
+ * one place:
+ *
+ *   function writeInt32(s, v) { s.view.setInt32(reserve(s, 4), v, true); }
+ *
+ * Throws {@link BufferFull} when fewer than `n` bytes remain, WITHOUT moving
+ * the position — the buffer is fixed-length, exactly as the reader's input is, so
+ * a driver flushes what is written and retries the row into a fresh buffer.
+ */
+export function reserve(sink: Sink, n: number): number {
+  const start = sink.pos;
+  const next = start + n;
+  if (next > sink.buf.length) throw BufferFull;
+  sink.pos = next;
+  return start;
+}

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

@@ -0,0 +1,123 @@
+import { type Writer, Sink, reserve } from "./core.js";
+import { type Microseconds, type Nanoseconds } from "../readers/datetime.js";
+
+const MS_PER_DAY = 86_400_000;
+
+/**
+ * Write a `Date`: 2-byte `UInt16` count of days since 1970-01-01 (UTC). The
+ * inverse of `readDate` — the `Date` it produced is at UTC midnight, so
+ * `getTime() / 86_400_000` recovers the whole-day count exactly. A non-midnight
+ * input is floored to its calendar day (matching ClickHouse's truncation),
+ * never rounded up into the next day.
+ *
+ * PRECONDITION: a valid `Date` whose day count fits the `UInt16` range
+ * (1970-01-01 … ~2149-06-06). Like every leaf writer (see `writeUVarint`) this
+ * is not range-checked — an invalid or out-of-range `Date` (e.g. a pre-1970 one,
+ * which belongs in {@link writeDate32}) is a programming error; the resulting
+ * bytes are rejected server-side.
+ */
+export function writeDate(sink: Sink, value: Date): void {
+  sink.view.setUint16(
+    reserve(sink, 2),
+    Math.floor(value.getTime() / MS_PER_DAY),
+    true,
+  );
+}
+
+/**
+ * Write a `Date32`: 4-byte signed `Int32` count of days since 1970-01-01 (UTC),
+ * negative for pre-1970 dates. The inverse of `readDate32`. A non-midnight input
+ * is floored toward -inf to its calendar day, so pre-1970 instants land on the
+ * correct (more negative) day rather than rounding toward the epoch.
+ *
+ * PRECONDITION: a valid `Date` whose day count fits `Int32`. Not range-checked
+ * (as elsewhere) — an invalid `Date` is a programming error, rejected server-side.
+ */
+export function writeDate32(sink: Sink, value: Date): void {
+  sink.view.setInt32(
+    reserve(sink, 4),
+    Math.floor(value.getTime() / MS_PER_DAY),
+    true,
+  );
+}
+
+/**
+ * Write a `DateTime`: 4-byte `UInt32` Unix seconds. The inverse of `readDateTime`;
+ * the column timezone is metadata, not in the bytes. Sub-second components are
+ * floored away (matching the reader and `writeDateTime64`'s `Math.floor`), never
+ * rounded up to the next second.
+ *
+ * PRECONDITION: a valid `Date` whose Unix-seconds fit the `UInt32` range
+ * (1970-01-01 … 2106-02-07). Not range-checked (as elsewhere) — an invalid or
+ * out-of-range `Date` is a programming error, rejected server-side.
+ */
+export function writeDateTime(sink: Sink, value: Date): void {
+  sink.view.setUint32(
+    reserve(sink, 4),
+    Math.floor(value.getTime() / 1000),
+    true,
+  );
+}
+
+/**
+ * Write a `DateTime64(P)`: 8-byte signed `Int64` count of `10^-P`-second ticks.
+ * Curried: `writeDateTime64(P)` returns the writer. The inverse of
+ * `readDateTime64`, which returns `[date, nanoseconds]` (date truncated to whole
+ * seconds, nanoseconds the sub-second remainder regardless of P). This recombines
+ * them: `ticks = seconds * 10^P + nanoseconds / 10^(9 - P)`. The reader floors
+ * seconds toward -inf with a non-negative remainder, so the seconds are computed
+ * with `Math.floor` on the cheap JS-number millisecond value (not bigint division,
+ * which truncates toward zero) — exact for negative instants too.
+ */
+export function writeDateTime64(
+  precision: number,
+): Writer<[Date, Nanoseconds]> {
+  const scale = 10n ** BigInt(precision);
+  const nsPerTick = 10n ** BigInt(9 - precision);
+  return (sink, [date, nanoseconds]) => {
+    const seconds = BigInt(Math.floor(date.getTime() / 1000));
+    sink.buf.writeBigInt64LE(
+      seconds * scale + BigInt(nanoseconds) / nsPerTick,
+      reserve(sink, 8),
+    );
+  };
+}
+
+/**
+ * Write a `DateTime64(3)` (milliseconds) from a plain `Date` — the inverse of
+ * `readDateTime64P3`. P=3 is a `Date`'s own resolution, so the tick count is
+ * exactly `getTime()` in milliseconds.
+ */
+export function writeDateTime64P3(sink: Sink, value: Date): void {
+  sink.buf.writeBigInt64LE(BigInt(value.getTime()), reserve(sink, 8));
+}
+
+/**
+ * Write a `DateTime64(6)` (microseconds) from `[date, microseconds]` — the
+ * inverse of `readDateTime64P6`. `ticks = seconds * 1_000_000 + micros`.
+ */
+export function writeDateTime64P6(
+  sink: Sink,
+  [date, microseconds]: [Date, Microseconds],
+): void {
+  const seconds = BigInt(Math.floor(date.getTime() / 1000));
+  sink.buf.writeBigInt64LE(
+    seconds * 1_000_000n + BigInt(microseconds),
+    reserve(sink, 8),
+  );
+}
+
+/**
+ * Write a `DateTime64(9)` (nanoseconds) from `[date, nanoseconds]` — the inverse
+ * of `readDateTime64P9`. `ticks = seconds * 1_000_000_000 + nanos`.
+ */
+export function writeDateTime64P9(
+  sink: Sink,
+  [date, nanoseconds]: [Date, Nanoseconds],
+): void {
+  const seconds = BigInt(Math.floor(date.getTime() / 1000));
+  sink.buf.writeBigInt64LE(
+    seconds * 1_000_000_000n + BigInt(nanoseconds),
+    reserve(sink, 8),
+  );
+}

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

@@ -0,0 +1,51 @@
+import { type Writer } from "./core.js";
+import { type DecimalValue } from "../readers/decimals.js";
+import {
+  writeInt32,
+  writeInt64,
+  writeInt128,
+  writeInt256,
+} from "./integers.js";
+
+/**
+ * Parse a fixed-point decimal string into a {@link DecimalValue} at the given
+ * `scale` — the inverse of `formatDecimal`. `"1.5000"` with scale 4 ->
+ * `[15000n, 4]`. A shorter fraction is right-padded with zeros to `scale`; a
+ * longer one is truncated (not rounded). Plug in only when you start from a
+ * string; if you already have the unscaled bigint, build the pair directly.
+ */
+export function parseDecimal(text: string, scale: number): DecimalValue {
+  const neg = text.startsWith("-");
+  const body = neg ? text.slice(1) : text;
+  const dot = body.indexOf(".");
+  const intPart = dot < 0 ? body : body.slice(0, dot);
+  const fracPart = dot < 0 ? "" : body.slice(dot + 1);
+  const frac = (fracPart + "0".repeat(scale)).slice(0, scale);
+  let unscaled = BigInt((intPart || "0") + frac);
+  if (neg) unscaled = -unscaled;
+  return [unscaled, scale];
+}
+
+/**
+ * Write a `Decimal32(P, S)`: the `unscaled` part of a {@link DecimalValue} as a
+ * 4-byte little-endian signed integer (same wire as `Int32`). The inverse of
+ * `readDecimal32`; the `scale` lives in the type, so only `unscaled` is written
+ * (it must fit in `Int32`).
+ *
+ * `Decimal(P, S)` picks the width by precision P, exactly as the readers: P<=9 ->
+ * Decimal32, <=18 -> Decimal64, <=38 -> Decimal128, <=76 -> Decimal256.
+ */
+export const writeDecimal32: Writer<DecimalValue> = (sink, [unscaled]) =>
+  writeInt32(sink, Number(unscaled));
+
+/** Write a `Decimal64(P, S)`: 8-byte LE signed integer. Inverse of `readDecimal64`. */
+export const writeDecimal64: Writer<DecimalValue> = (sink, [unscaled]) =>
+  writeInt64(sink, unscaled);
+
+/** Write a `Decimal128(P, S)`: 16-byte LE signed integer. Inverse of `readDecimal128`. */
+export const writeDecimal128: Writer<DecimalValue> = (sink, [unscaled]) =>
+  writeInt128(sink, unscaled);
+
+/** Write a `Decimal256(P, S)`: 32-byte LE signed integer. Inverse of `readDecimal256`. */
+export const writeDecimal256: Writer<DecimalValue> = (sink, [unscaled]) =>
+  writeInt256(sink, unscaled);

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

@@ -0,0 +1,18 @@
+import { Sink, reserve } from "./core.js";
+
+/**
+ * Write an `Enum8`: the value's underlying signed `Int8` (1 byte). Mirror of
+ * `readEnum8` — the name<->value map lives in the column type, so take the raw
+ * numeric value.
+ */
+export function writeEnum8(sink: Sink, value: number): void {
+  sink.view.setInt8(reserve(sink, 1), value);
+}
+
+/**
+ * Write an `Enum16`: the value's underlying signed `Int16` (2 bytes,
+ * little-endian). Mirror of `readEnum16`.
+ */
+export function writeEnum16(sink: Sink, value: number): void {
+  sink.view.setInt16(reserve(sink, 2), value, true);
+}

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

@@ -0,0 +1,40 @@
+import { Sink, reserve } from "./core.js";
+
+/** Write a `Float32`: 4 bytes, little-endian IEEE 754. Mirror of `readFloat32`. */
+export function writeFloat32(sink: Sink, value: number): void {
+  sink.view.setFloat32(reserve(sink, 4), value, true);
+}
+
+/** Write a `Float64`: 8 bytes, little-endian IEEE 754. Mirror of `readFloat64`. */
+export function writeFloat64(sink: Sink, value: number): void {
+  sink.view.setFloat64(reserve(sink, 8), value, true);
+}
+
+/**
+ * Scratch view for narrowing a float32 to a `BFloat16`: BFloat16's 16 bits are
+ * the top half of an IEEE 754 float32, so we stage the float32 and take its high
+ * 16 bits back out.
+ */
+const bf16Scratch = new DataView(new ArrayBuffer(4));
+
+/**
+ * Write a `BFloat16`: 2 bytes, little-endian — the high 16 bits of `value`'s
+ * float32 representation (same 8-bit exponent, 7-bit mantissa). Mirror of
+ * `readBFloat16`: it widens a BFloat16 to a float32 by placing the bits in the
+ * top half, so here we stage the float32 and take that top half back.
+ *
+ * NOTE: this TRUNCATES the float32 mantissa to BFloat16's 7 bits (no rounding),
+ * matching the reader's exact inverse for values that originated as BFloat16. An
+ * arbitrary float32 loses precision, exactly as ClickHouse's own BFloat16 cast.
+ *
+ * NOTE: `bf16Scratch` is module-level shared state written-then-read; safe
+ * because the body is synchronous (do NOT introduce an `await`/`yield` between
+ * the `setFloat32` and the `getUint16`).
+ */
+export function writeBFloat16(sink: Sink, value: number): void {
+  bf16Scratch.setFloat32(0, value, true);
+  // The float32's little-endian bytes are [lo16, hi16]; the high 16 bits at byte
+  // offset 2 are the BFloat16 payload.
+  const bits = bf16Scratch.getUint16(2, true);
+  sink.view.setUint16(reserve(sink, 2), bits, true);
+}

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;