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

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

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

@@ -0,0 +1,101 @@
+/**
+ * Barrel re-export of the RowBinary WRITER — the encode mirror of `reader.ts`,
+ * split by type family across parallel `*.ts` modules (the readers stay in
+ * their own files untouched). Import from here for everything in one place, or
+ * from a specific module (e.g. `./integers.js`, `./strings.js`) to
+ * pull in only the sub-writers a given result needs — the latter is what a
+ * generated encoder should do, copying just the modules its column types require.
+ *
+ * Each `writeX` is the inverse of the matching `readX`: it appends the value's
+ * RowBinary bytes to a {@link Sink} (the write-side mirror of the reader's
+ * `Cursor`). Leaf writers are `Writer<T>`s directly; combinators (e.g.
+ * `writeArray`) take sub-writers and return a `Writer`, so types compose with no
+ * per-element closures — exactly like the reader combinators.
+ *
+ *   const sink = new Sink(Buffer.allocUnsafe(64));
+ *   writeUInt8(sink, 255);
+ *   sink.bytes(); // the encoded RowBinary
+ *
+ * - core — Sink, Writer<T>, reserve (mirror of Cursor, Reader<T>, advance)
+ * - varint — writeUVarint
+ *
+ * The dynamic AST-based encode path (the inverse of `compile.ts` /
+ * `rowBinaryWithNamesAndTypes.ts` / `dynamic.ts`) is intentionally NOT part of
+ * this barrel yet.
+ */
+export { Sink, reserve, BufferFull, type Writer } from "./core.js";
+export { writeUVarint } from "./varint.js";
+export {
+  writeUInt8,
+  writeInt8,
+  writeUInt16,
+  writeInt16,
+  writeUInt32,
+  writeInt32,
+  writeUInt64,
+  writeInt64,
+  writeUInt128,
+  writeInt128,
+  writeUInt256,
+  writeInt256,
+} from "./integers.js";
+export { writeBool } from "./bool.js";
+export { writeEnum8, writeEnum16 } from "./enums.js";
+export { writeFloat32, writeFloat64, writeBFloat16 } from "./floats.js";
+export {
+  writeDecimal32,
+  writeDecimal64,
+  writeDecimal128,
+  writeDecimal256,
+  parseDecimal,
+} from "./decimals.js";
+export {
+  writeString,
+  writeStringBytes,
+  writeFixedString,
+  writeFixedStringBytes,
+} from "./strings.js";
+export {
+  writeUUID,
+  writeUUIDBigInt,
+  writeUUIDHiLo,
+  parseUUID,
+} from "./uuid.js";
+export { writeIPv4, writeIPv6, parseIPv4, parseIPv6 } from "./ip.js";
+export {
+  writeDate,
+  writeDate32,
+  writeDateTime,
+  writeDateTime64,
+  writeDateTime64P3,
+  writeDateTime64P6,
+  writeDateTime64P9,
+} from "./datetime.js";
+export { writeTime, writeTime64, parseTime, parseTime64 } from "./time.js";
+export { writeInterval } from "./interval.js";
+export {
+  writeNullable,
+  writeArray,
+  writeQBit,
+  writeTuple,
+  writeTupleNamed,
+  writeMap,
+  writeVariant,
+  type VariantValue,
+} from "./composite.js";
+export { writeRows, FLUSH_CHANNEL_NAME, type WriteRowsFlush } from "./rows.js";
+export {
+  writePoint,
+  writeRing,
+  writeLineString,
+  writePolygon,
+  writeMultiLineString,
+  writeMultiPolygon,
+  writeGeometry,
+  type GeometryValue,
+} from "./geo.js";
+export { writeLowCardinality } from "./lowCardinality.js";
+export { writeSimpleAggregateFunction } from "./simpleAggregateFunction.js";
+export { writeNested } from "./nested.js";
+export { writeNothing } from "./nothing.js";
+export { writeAggregateFunction } from "./aggregateFunction.js";

package/skills/clickhouse-js-node-rowbinary/writer.md

@@ -0,0 +1,96 @@
+# RowBinary writer (encode) for Node.js
+
+Encoding JS values into a `RowBinary` payload to send to ClickHouse. Read
+[SKILL.md](SKILL.md) first for the format gate ("is RowBinary even the right
+format?") and the principles that apply to **both** directions; this file covers
+what's specific to **writing**. Reading? See [reader.md](reader.md).
+
+Each `writeX` encodes one value, appending its RowBinary bytes to a `Sink` (a
+caller-supplied byte buffer plus the current write offset — state only, no write
+methods). Leaf writers (`writeUInt8`, `writeString`, …) encode directly;
+combinators (`writeArray`, `writeTuple`, …) take sub-writers and return a writer,
+so composite types compose with no per-element closures. For the `Sink`/`Writer<T>`
+types and how to drain the encoded bytes, see `src/writers/core.ts`. Import the
+barrel as `@clickhouse/rowbinary/writer`, or a per-type module for just what you
+need. (Structurally this is the mirror of the decode side in
+[reader.md](reader.md), but you don't need the read side to write.)
+
+## Writer guidance
+
+On top of the shared principles in [SKILL.md](SKILL.md), the write path has its own:
+
+- **Reserve before you write.** Every fixed-width write goes through `reserve()`,
+  which bounds-checks against the fixed-length buffer and throws the `BufferFull`
+  sentinel when the chunk is full — your cue to flush what's written and continue
+  into a fresh buffer. Exact signature, return value, and throw contract are in
+  `src/writers/core.ts`.
+
+- **Coalesce `reserve()` across a run of adjacent fixed-width columns.** Their
+  combined size is statically known, so reserve ONCE for the whole run and write
+  each value at a constant offset off the returned base — one bounds-check instead
+  of one per column. Only applies where every column in the run is fixed-width (a
+  variable-width writer like `writeString` reserves on its own).
+
+- **Hoist sink state into locals in the generated writer.** `Sink.buf`/`Sink.view`
+  are `readonly`, so bind them to locals once at the top and address them directly
+  instead of through `sink.` on every write. Keep the write position (`sink.pos`)
+  in a local too — but sync it back to `sink.pos` before any `reserve()` or
+  `BufferFull` throw, since those read and mutate it to decide capacity and where a
+  flushed buffer resumes.
+
+- **Stream the whole result with `writeRows`, not a one-shot writer.** When you
+  need to encode a large or unbounded row source, reach for `writeRows` rather than
+  a `Writer<readonly T[]>`: it owns a fixed buffer and yields it as a generator,
+  streaming the result out chunk by chunk instead of demanding it all fit at once.
+  It never leaks a half-written row (it rewinds to the last whole-row boundary
+  before flushing) and never fails on a single big row (it grows the buffer to fit).
+  It also publishes a per-flush diagnostics-channel event for buffer-utilization
+  metrics. Signature, default buffer size, channel name and payload type, the
+  growth/rewind details, and a usage example are all in `src/writers/rows.ts`.
+
+- **No defensive validation on the hot path.** Don't add `isFinite`/`NaN`/range
+  checks to `writeX`; document the precondition in JSDoc instead. Two narrow
+  exceptions — framing-keeping checks and zero-cost parse-time helpers — are
+  spelled out in [AGENTS.md](AGENTS.md); `src/writers/ip.ts` is the worked
+  example (`writeIPv6`, `parseIPv6`).
+
+- **Lossy time conversions floor, never round.** Every date/time writer in
+  `src/writers/datetime.ts` drops the sub-unit it can't encode by flooring toward
+  −∞, so a caller's value is never silently shifted _up_ to the wrong
+  day/second/tick and pre-1970 instants stay correct (not rounded toward the
+  epoch). See its JSDoc for the per-function specifics.
+
+## Writer type family references
+
+The writers live as real code under `src/writers/`, one file per type family
+(same basenames as the readers, under the `writers/` directory).
+
+| Value to encode (trigger)                                                               | Open                                     |
+| --------------------------------------------------------------------------------------- | ---------------------------------------- |
+| **Always** — sink state, `reserve()`, `BufferFull`, `Writer<T>`                         | `src/writers/core.ts`                    |
+| LEB128 length/count prefixes for `String`/`Array`/`Map` (`writeUVarint`)                | `src/writers/varint.ts`                  |
+| `Int8`–`Int256`, `UInt8`–`UInt256`                                                      | `src/writers/integers.ts`                |
+| `Bool` (`writeBool`)                                                                    | `src/writers/bool.ts`                    |
+| `Enum8`, `Enum16` (`writeEnum8`/`writeEnum16`; pass the raw int)                        | `src/writers/enums.ts`                   |
+| `Float32`, `Float64`, `BFloat16`                                                        | `src/writers/floats.ts`                  |
+| `Decimal32/64/128/256`, `Decimal(P, S)` (`parseDecimal`)                                | `src/writers/decimals.ts`                |
+| `String`, `FixedString(N)` (`writeString`/`writeStringBytes`/`writeFixedString`)        | `src/writers/strings.ts`                 |
+| `UUID` (`writeUUID`, `parseUUID`)                                                       | `src/writers/uuid.ts`                    |
+| `IPv4`, `IPv6` (`writeIPv4`/`writeIPv6`, `parseIPv4`/`parseIPv6`)                       | `src/writers/ip.ts`                      |
+| `Date`, `Date32`, `DateTime`, `DateTime(tz)`, `DateTime64(P[, tz])`                     | `src/writers/datetime.ts`                |
+| `Time`, `Time64(P)` (`parseTime`/`parseTime64`)                                         | `src/writers/time.ts`                    |
+| `IntervalNanosecond` … `IntervalYear`                                                   | `src/writers/interval.ts`                |
+| `Array(T)`, `Map(K, V)`, `Tuple(...)`, `Nullable(T)`, `Variant(...)`, `QBit(...)`       | `src/writers/composite.ts`               |
+| `Point`, `Ring`, `LineString`, `MultiLineString`, `Polygon`, `MultiPolygon`, `Geometry` | `src/writers/geo.ts`                     |
+| The whole result — write rows from a value source (`writeRows`)                         | `src/writers/rows.ts`                    |
+| `LowCardinality(T)` — transparent, encode as `T`                                        | `src/writers/lowCardinality.ts`          |
+| `SimpleAggregateFunction(f, T)` — transparent, encode as `T`                            | `src/writers/simpleAggregateFunction.ts` |
+| `Nested(...)` — no wire of its own; `Array(Tuple(...))`                                 | `src/writers/nested.ts`                  |
+| `Nothing` — zero-width, never encoded (only wrapped)                                    | `src/writers/nothing.ts`                 |
+| `AggregateFunction(...)` — opaque state; produce server-side                            | `src/writers/aggregateFunction.ts`       |
+
+**No writer counterpart yet** — these reader paths are decode-only for now:
+`dynamic.ts`, `json.ts`, `stream.ts`, the `RowBinaryWithNamesAndTypes`
+header/compile/runtime path (`header.ts`, `compile.ts`,
+`rowBinaryWithNamesAndTypes.ts`), and the columnar typed-array path
+(`columnar.ts`). The AST-based dynamic encode path is intentionally not built.

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

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