@clickhouse/client 1.22.0 → 1.23.0-head.287977a.1

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

@@ -0,0 +1,61 @@
+import { type Reader, Cursor } from "./core.js";
+import { readInt32, readInt64 } from "./integers.js";
+
+/** Semantic alias for `number` marking a seconds value (see {@link readTime}). */
+export type Seconds = number;
+
+/**
+ * A signed sub-second duration kept lossless as its raw parts: the value is
+ * `ticks / 10 ** precision` seconds. Used by `Time64` (a time-of-day duration,
+ * which has no natural JS type), carrying the precision so nothing is lost.
+ */
+export type ScaledTicks = readonly [ticks: bigint, precision: number];
+
+/**
+ * Read a `Time`: 4-byte signed `Int32` seconds-of-day (range ±999:59:59).
+ * Returns the raw seconds; pass it to {@link formatTime}.
+ */
+export function readTime(state: Cursor): Seconds {
+  return readInt32(state);
+}
+
+/**
+ * Read a `Time64(P)`: 8-byte signed `Int64` count of `10^-P`-second ticks.
+ * Curried: `readTime64(P)` returns the reader. Returns `[ticks, precision]` (a
+ * {@link ScaledTicks}); pass it to {@link formatTime64}.
+ */
+export function readTime64(precision: number): Reader<ScaledTicks> {
+  return (state) => [readInt64(state), precision];
+}
+
+/**
+ * Format a `Time` value (signed seconds-of-day) as "[-]HH:MM:SS". The hour
+ * field can exceed two digits (the range is ±999:59:59).
+ */
+export function formatTime(seconds: Seconds): string {
+  const sign = seconds < 0 ? "-" : "";
+  const s = Math.abs(seconds);
+  const hh = Math.floor(s / 3600);
+  const mm = Math.floor((s % 3600) / 60);
+  const ss = s % 60;
+  return `${sign}${String(hh).padStart(2, "0")}:${String(mm).padStart(2, "0")}:${String(ss).padStart(2, "0")}`;
+}
+
+/**
+ * Format a `Time64` [ticks, precision] (signed sub-second time-of-day) as
+ * "[-]HH:MM:SS[.fff]".
+ */
+export function formatTime64([ticks, precision]: ScaledTicks): string {
+  const sign = ticks < 0n ? "-" : "";
+  const t = ticks < 0n ? -ticks : ticks;
+  const scale = 10n ** BigInt(precision);
+  const totalSec = Number(t / scale);
+  const frac = t % scale;
+  const hh = Math.floor(totalSec / 3600);
+  const mm = Math.floor((totalSec % 3600) / 60);
+  const ss = totalSec % 60;
+  const base = `${sign}${String(hh).padStart(2, "0")}:${String(mm).padStart(2, "0")}:${String(ss).padStart(2, "0")}`;
+  return precision > 0
+    ? `${base}.${frac.toString().padStart(precision, "0")}`
+    : base;
+}

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

@@ -0,0 +1,153 @@
+import { Cursor, advance } from "./core.js";
+
+/**
+ * `UUID_HEX16[b]` packs the two lowercase ASCII hex chars of byte `b`, low char
+ * in the low byte. Drives the lookup-table UUID formatter {@link formatUUIDTable}.
+ */
+const UUID_HEX16 = new Uint16Array(256);
+for (let b = 0; b < 256; b++) {
+  const hex = b.toString(16).padStart(2, "0");
+  UUID_HEX16[b] = hex.charCodeAt(0) | (hex.charCodeAt(1) << 8);
+}
+
+/**
+ * Reusable 36-byte scratch for {@link formatUUIDTable}. The four `-` separators
+ * are written once and never touched again; each call overwrites only the 32
+ * hex slots, then copies the bytes out as a string.
+ */
+const UUID_OUT = Buffer.alloc(36);
+UUID_OUT[8] = UUID_OUT[13] = UUID_OUT[18] = UUID_OUT[23] = 0x2d; // '-'
+
+/**
+ * Read a `UUID`: 16 raw bytes (two little-endian `UInt64` halves on the wire).
+ * Returns a zero-copy view; pass it to {@link formatUUID} for the canonical
+ * `xxxxxxxx-...` string.
+ *
+ * The view shares memory with the response buffer, so keeping it alive pins the
+ * whole chunk; copy with `Buffer.from(...)` if it must outlive the row.
+ *
+ * FAST ALTERNATIVE: if you stringify every UUID, use {@link formatUUIDTable}
+ * (lookup table, no BigInt, ~1.6x faster).
+ */
+export function readUUID(state: Cursor): Buffer {
+  const start = advance(state, 16);
+  return state.buf.subarray(start, start + 16);
+}
+
+/**
+ * Read a `UUID` as a single 128-bit `bigint` (`hi << 64 | lo`) — useful for
+ * numeric storage, comparison, or de-duplication without a string.
+ *
+ * Reads the halves with `DataView.getBigUint64` rather than
+ * `Buffer.readBigUInt64LE`: V8 inlines the DataView accessors, measurably faster
+ * for 8-byte reads. For the canonical string, use {@link readUUID} + {@link formatUUID}.
+ */
+export function readUUIDBigInt(state: Cursor): bigint {
+  const start = advance(state, 16);
+  const hi = state.view.getBigUint64(start, true);
+  const lo = state.view.getBigUint64(start + 8, true);
+  return (hi << 64n) | lo;
+}
+
+/**
+ * Read a `UUID` as its two raw little-endian `UInt64` halves, `[hi, lo]` — the
+ * faithful wire split with no combining work. Cheaper than {@link readUUIDBigInt}
+ * (skips `hi << 64 | lo`) and a compact two-value key for comparison/dedup. For
+ * the canonical string, use {@link readUUID} + {@link formatUUID}.
+ */
+export function readUUIDHiLo(state: Cursor): [hi: bigint, lo: bigint] {
+  const start = advance(state, 16);
+  const hi = state.view.getBigUint64(start, true);
+  const lo = state.view.getBigUint64(start + 8, true);
+  return [hi, lo];
+}
+
+/**
+ * Format a `UUID` (raw 16 bytes from {@link readUUID}) as the canonical
+ * `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` string.
+ *
+ * THE TRAP: ClickHouse stores a UUID as two little-endian `UInt64` halves (high
+ * then low), so each half is byte-reversed vs the text form. Reading each half
+ * with `readBigUInt64LE` undoes that; concatenating high then low gives the 32
+ * canonical hex digits. (Hexing the 16 bytes in wire order scrambles the value.)
+ * Kept aside from the read so the hot path can skip stringifying when raw bytes
+ * suffice.
+ *
+ * FAST ALTERNATIVE: to format every value, {@link formatUUIDTable} does the same
+ * via a byte->hex lookup table with no BigInt (~1.6x faster).
+ */
+export function formatUUID(b: Buffer): string {
+  const hex = ((b.readBigUInt64LE(0) << 64n) | b.readBigUInt64LE(8))
+    .toString(16)
+    .padStart(32, "0");
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+
+/**
+ * Fast {@link formatUUID}: same canonical string via a byte -> two-hex-char
+ * lookup table (`UUID_HEX16`) written into a reused 36-byte buffer (`UUID_OUT`,
+ * dashes preset), no BigInt, no slicing. ~1.6x faster (see `readUUID.bench.ts`).
+ * Takes the raw 16 bytes from {@link readUUID}.
+ *
+ * Same byte-reversal as formatUUID: emit the high half in reverse (`b[7]..b[0]`)
+ * then the low half (`b[15]..b[8]`).
+ *
+ * SAFE TO TOGGLE — opt-in fast formatter, not the default. `UUID_OUT` is shared
+ * scratch, so NOT reentrant; safe for synchronous formatting because the bytes
+ * are copied into the returned string before the next call (don't alias
+ * `UUID_OUT`). Worth it only when you stringify every UUID.
+ */
+export function formatUUIDTable(b: Buffer): string {
+  let p: number;
+  // High half: bytes b[7]..b[0] -> hex positions 0..7 (chars 0..15).
+  p = UUID_HEX16[b[7]!]!;
+  UUID_OUT[0] = p & 0xff;
+  UUID_OUT[1] = p >>> 8;
+  p = UUID_HEX16[b[6]!]!;
+  UUID_OUT[2] = p & 0xff;
+  UUID_OUT[3] = p >>> 8;
+  p = UUID_HEX16[b[5]!]!;
+  UUID_OUT[4] = p & 0xff;
+  UUID_OUT[5] = p >>> 8;
+  p = UUID_HEX16[b[4]!]!;
+  UUID_OUT[6] = p & 0xff;
+  UUID_OUT[7] = p >>> 8;
+  p = UUID_HEX16[b[3]!]!;
+  UUID_OUT[9] = p & 0xff;
+  UUID_OUT[10] = p >>> 8;
+  p = UUID_HEX16[b[2]!]!;
+  UUID_OUT[11] = p & 0xff;
+  UUID_OUT[12] = p >>> 8;
+  p = UUID_HEX16[b[1]!]!;
+  UUID_OUT[14] = p & 0xff;
+  UUID_OUT[15] = p >>> 8;
+  p = UUID_HEX16[b[0]!]!;
+  UUID_OUT[16] = p & 0xff;
+  UUID_OUT[17] = p >>> 8;
+  // Low half: bytes b[15]..b[8] -> hex positions 8..15 (chars 19..35).
+  p = UUID_HEX16[b[15]!]!;
+  UUID_OUT[19] = p & 0xff;
+  UUID_OUT[20] = p >>> 8;
+  p = UUID_HEX16[b[14]!]!;
+  UUID_OUT[21] = p & 0xff;
+  UUID_OUT[22] = p >>> 8;
+  p = UUID_HEX16[b[13]!]!;
+  UUID_OUT[24] = p & 0xff;
+  UUID_OUT[25] = p >>> 8;
+  p = UUID_HEX16[b[12]!]!;
+  UUID_OUT[26] = p & 0xff;
+  UUID_OUT[27] = p >>> 8;
+  p = UUID_HEX16[b[11]!]!;
+  UUID_OUT[28] = p & 0xff;
+  UUID_OUT[29] = p >>> 8;
+  p = UUID_HEX16[b[10]!]!;
+  UUID_OUT[30] = p & 0xff;
+  UUID_OUT[31] = p >>> 8;
+  p = UUID_HEX16[b[9]!]!;
+  UUID_OUT[32] = p & 0xff;
+  UUID_OUT[33] = p >>> 8;
+  p = UUID_HEX16[b[8]!]!;
+  UUID_OUT[34] = p & 0xff;
+  UUID_OUT[35] = p >>> 8;
+  return UUID_OUT.toString("latin1");
+}

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

@@ -0,0 +1,70 @@
+import { Cursor, advance } from "./core.js";
+
+/**
+ * Read a LEB128 unsigned varint (used for string/array lengths).
+ *
+ * Returns a JS `number`, so it is NOT bigint-friendly: only values up to
+ * `Number.MAX_SAFE_INTEGER` (2^53 - 1) are representable exactly. A varint
+ * larger than that throws rather than silently losing precision. RowBinary
+ * lengths never approach this in practice.
+ *
+ * The loop is unrolled: each byte carries 7 bits, so its place value is the
+ * constant 2^(7*k). The overwhelmingly common 1–2 byte case costs one or two
+ * reads and a compare.
+ *
+ * Multipliers must stay as `*` (not `<<`): JS bitwise shift is 32-bit and would wrap past bit 31.
+ *
+ * SAFE TO TOGGLE — how many bytes to handle:
+ * - If you know the maximum blob/array size, keep only the steps you need and
+ *   delete the rest along with the overflow guard. E.g. lengths < 2^28 fit in
+ *   4 bytes, so everything below the `* 268435456` step can go.
+ * - Keep all eight steps (the default) when lengths are untrusted.
+ * If you genuinely need lengths beyond 2^53, create a bigint version of this
+ * function with a bigint accumulator instead of removing the guard.
+ *
+ * OPTIMIZATION HINT — for a known invariant, emit a dedicated named variant
+ * rather than toggling here. E.g. a `readUVarint32` for lengths guaranteed to be
+ * 32-bit would unroll only the first five bytes and throw past 2^32 - 1.
+ */
+export function readUVarint(state: Cursor): number {
+  // Each byte reserves its space through `advance(1)` (the bounds check), but
+  // the read itself stays inlined as `state.buf[...]` rather than calling
+  // readUInt8 — this is the hottest loop in the reader.
+  let byte = state.buf[advance(state, 1)]!;
+  if (byte < 0x80) return byte; // 1 byte  -> 2^0
+  let result = byte & 0x7f;
+
+  byte = state.buf[advance(state, 1)]!;
+  if (byte < 0x80) return result + byte * 128; // 2^7
+  result += (byte & 0x7f) * 128;
+
+  byte = state.buf[advance(state, 1)]!;
+  if (byte < 0x80) return result + byte * 16384; // 2^14
+  result += (byte & 0x7f) * 16384;
+
+  byte = state.buf[advance(state, 1)]!;
+  if (byte < 0x80) return result + byte * 2097152; // 2^21
+  result += (byte & 0x7f) * 2097152;
+
+  byte = state.buf[advance(state, 1)]!;
+  if (byte < 0x80) return result + byte * 268435456; // 2^28
+  result += (byte & 0x7f) * 268435456;
+
+  byte = state.buf[advance(state, 1)]!;
+  if (byte < 0x80) return result + byte * 34359738368; // 2^35
+  result += (byte & 0x7f) * 34359738368;
+
+  byte = state.buf[advance(state, 1)]!;
+  if (byte < 0x80) return result + byte * 4398046511104; // 2^42
+  result += (byte & 0x7f) * 4398046511104;
+
+  // 8th byte: only its low 4 payload bits (bits 49..52) fit under 2^53. A larger
+  // payload, or a continuation bit signalling a 9th byte, overflows MAX_SAFE_INTEGER.
+  byte = state.buf[advance(state, 1)]!;
+  if (byte > 0x0f) {
+    throw new RangeError(
+      "RowBinary: varint exceeds Number.MAX_SAFE_INTEGER (2^53 - 1)",
+    );
+  }
+  return result + byte * 562949953421312; // 2^49
+}