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

package/skills/clickhouse-js-node-rowbinary/src/readers/rowBinaryWithNamesAndTypes.ts

@@ -0,0 +1,155 @@
+/**
+ * The `RowBinaryWithNamesAndTypes` entry point: read the header off a cursor,
+ * compile each column's type string into a reader, and hand back a driver that
+ * decodes the rest of the stream.
+ *
+ * This ties together the pieces: {@link readHeader} (wire), the parser
+ * (`@clickhouse/datatype-parser`), and {@link astToReader} (the AST → reader
+ * fold in `compile.ts`), then assembles a named-tuple row reader over the
+ * columns and a {@link readRows} driver for the row data.
+ */
+
+import { parseDataType } from "@clickhouse/datatype-parser";
+
+import type { Reader, Cursor } from "./core.js";
+import { readHeader } from "./header.js";
+import { readRows } from "./rows.js";
+import { astToReader, RowBinaryTypeError } from "./compile.js";
+
+/** One decoded row, keyed by column name. */
+export type Row = Record<string, unknown>;
+
+/**
+ * The product of compiling a `RowBinaryWithNamesAndTypes` header: the column
+ * metadata, the per-column readers, and — the headline — `readRows`, the
+ * {@link Reader} that decodes every remaining row of the stream.
+ */
+export interface CompiledStream {
+  /** Column names, in stream order (from the header). */
+  names: string[];
+  /** Column type strings, in stream order (from the header). */
+  types: string[];
+  /** One folded reader per column, in stream order. */
+  columnReaders: Reader<unknown>[];
+  /** Reads exactly one row into a `{ [name]: value }` object. */
+  readRow: Reader<Row>;
+  /**
+   * Reads the REST of the stream (all rows after the header) into an array.
+   * Streaming-aware via {@link readRows}: on a partial trailing row it rewinds
+   * to the last complete row and returns what it has.
+   */
+  readRows: Reader<Row[]>;
+}
+
+/**
+ * Parse one ClickHouse type string and fold it into a {@link Reader}. Throws a
+ * {@link RowBinaryTypeError} if the parser rejects the string (e.g. the
+ * deliberately unsupported `AggregateFunction` / `SimpleAggregateFunction`) —
+ * carrying the `typeString` and the parse `position`.
+ */
+export function typeStringToReader(typeStr: string): Reader<unknown> {
+  const result = parseDataType(typeStr);
+  if (!result.ok()) {
+    const err = result.error!;
+    throw new RowBinaryTypeError(
+      `cannot compile type ${JSON.stringify(typeStr)}: ${err.message}`,
+      { typeString: typeStr, position: err.position },
+    );
+  }
+  return astToReader(result.ast!);
+}
+
+/** Resolves a ClickHouse type string to a reader — `typeStringToReader` or a cache wrapping it. */
+export type TypeReaderResolver = (typeStr: string) => Reader<unknown>;
+
+/**
+ * Build an LRU-cached {@link typeStringToReader}. The full ClickHouse type
+ * STRING is a perfect cache key: two columns of the same type compile to the
+ * same reader, and a reader is stateless (it only ever touches the cursor it is
+ * handed), so one instance is safe to share across columns and across streams —
+ * a cache hit skips the parse + AST fold entirely.
+ *
+ * Worth it when you decode many `RowBinaryWithNamesAndTypes` responses whose
+ * schemas overlap (e.g. the same query run repeatedly): keep one cache and pass
+ * it to {@link compileRowBinaryWithNamesAndTypes}, so a recurring type is
+ * compiled once rather than once per response. A single response rarely repeats
+ * a type across its own columns, so the win is across calls, not within one.
+ *
+ * Classic Map-based LRU: a `Map` iterates in insertion order, so on a HIT we
+ * delete + re-set the entry to move it to the most-recently-used end, and on
+ * overflow we evict the oldest key (the first the `Map` yields). `maxSize` caps
+ * memory. A parse FAILURE is never cached — {@link typeStringToReader} throws
+ * before anything is stored — so fixing a bad type is not shadowed by a cached
+ * error.
+ */
+export function createTypeReaderCache(maxSize = 256): TypeReaderResolver {
+  const cache = new Map<string, Reader<unknown>>();
+  return (typeStr) => {
+    const cached = cache.get(typeStr);
+    if (cached !== undefined) {
+      // Touch on hit. A Map iterates in INSERTION order, not usage order — so on
+      // its own `keys().next()` would give the oldest-added key, not the
+      // least-recently-USED one. Deleting and re-inserting moves this key to the
+      // tail, which is what turns insertion order INTO recency order: every
+      // access (hit here, or miss below) lands the key at the tail, leaving the
+      // head as the genuine least-recently-used entry.
+      cache.delete(typeStr);
+      cache.set(typeStr, cached);
+      return cached;
+    }
+    const reader = typeStringToReader(typeStr); // may throw — then nothing is cached
+    cache.set(typeStr, reader);
+    if (cache.size > maxSize) {
+      // The head is the least-recently-used key (see touch-on-hit above), so it
+      // is the correct one to evict.
+      const lru = cache.keys().next().value;
+      if (lru !== undefined) cache.delete(lru);
+    }
+    return reader;
+  };
+}
+
+/**
+ * The headline entry point. Reads the `RowBinaryWithNamesAndTypes` header off
+ * `state`, compiles each column type into a combinator reader, and returns the
+ * column metadata plus the readers — including `readRows`, the reader for the
+ * REST of the stream. After this call the cursor sits at the first row, so:
+ *
+ *   const s = new Cursor(buf);
+ *   const { names, readRows } = compileRowBinaryWithNamesAndTypes(s);
+ *   const rows = readRows(s);   // decode every remaining row
+ *
+ * Pass `resolveType` to reuse readers across calls — e.g. a shared
+ * {@link createTypeReaderCache}. It defaults to {@link typeStringToReader}
+ * (compile every column afresh).
+ */
+export function compileRowBinaryWithNamesAndTypes(
+  state: Cursor,
+  resolveType: TypeReaderResolver = typeStringToReader,
+): CompiledStream {
+  const { names, types } = readHeader(state);
+  const columnReaders = types.map((t) => resolveType(t));
+
+  // Build the row reader POSITIONALLY — by column index, NOT by keying the
+  // readers on column name and handing them to `readTupleNamed`. The header is
+  // an ordered list and RowBinary has no row delimiter, so every row MUST read
+  // exactly these readers, in exactly this order. Keying readers by name first
+  // would corrupt the stream on legal-but-awkward headers:
+  //   - duplicate column names (e.g. two `SELECT 1 AS x, 2 AS x`) collapse to a
+  //     single entry in a `Record`, so fewer readers run than there are columns;
+  //   - integer-like names (`0`, `1`, …) are reordered ahead of string keys by
+  //     `Object.keys()`, so the readers would run out of header order.
+  // Either desyncs the cursor and misreads every subsequent row. Reading by
+  // index sidesteps both. The row OBJECT is still keyed by name; on a duplicate
+  // name the last column with that name wins in the object, but every column is
+  // still consumed off the wire in order, so the cursor stays in sync.
+  const readRow: Reader<Row> = (s) => {
+    const row: Row = {};
+    for (let i = 0; i < columnReaders.length; i++) {
+      row[names[i]!] = columnReaders[i]!(s);
+    }
+    return row;
+  };
+
+  return { names, types, columnReaders, readRow, readRows: readRows(readRow) };
+}

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

@@ -0,0 +1,18 @@
+import { type Writer } from "./core.js";
+
+/**
+ * Inverse of `readAggregateFunction`: an `AggregateFunction(func, T…)` column is
+ * OPAQUE, unframed aggregation state with a layout specific to `func` and the
+ * server version, so it cannot be produced generically from a value. Build the
+ * state server-side (the `-State` combinators) rather than encoding it on the
+ * client.
+ *
+ * This writer throws to stop a generic encoder from emitting a misaligned row.
+ */
+export const writeAggregateFunction: Writer<never> = () => {
+  throw new Error(
+    "RowBinary: AggregateFunction is opaque, unframed aggregation state with no " +
+      "length prefix — not generically encodable. Produce the state server-side " +
+      "(the -State combinators) instead of encoding it on the client.",
+  );
+};

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

@@ -0,0 +1,10 @@
+import { Sink } from "./core.js";
+import { writeUInt8 } from "./integers.js";
+
+/**
+ * Write a `Bool`: 1 byte, stored as `UInt8` (`false` -> 0, `true` -> 1). Mirror
+ * of `readBool`.
+ */
+export function writeBool(sink: Sink, value: boolean): void {
+  writeUInt8(sink, value ? 1 : 0);
+}

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