Uuid

1import { Sink, reserve } from "./core.js";
2
3/**
4 * Parse a canonical `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` UUID string into the
5 * raw 16 wire bytes — the inverse of `formatUUID`. ClickHouse stores a UUID as
6 * two little-endian `UInt64` halves (high then low), so the 32 hex digits are
7 * split at the midpoint and each half written little-endian. Pair with
8 * {@link writeUUID}.
9 */
10export function parseUUID(text: string): Buffer {
11  const hex = text.replace(/-/g, "");
12  if (hex.length !== 32) {
13    throw new RangeError(
14      `RowBinary: invalid UUID string ${JSON.stringify(text)}`,
15    );
16  }
17  const v = BigInt("0x" + hex);
18  // SAFE: allocUnsafe — the two writeBigUInt64LE calls below overwrite all 16
19  // bytes (offsets 0..7 and 8..15), so no uninitialized pool memory survives.
20  const b = Buffer.allocUnsafe(16);
21  b.writeBigUInt64LE(v >> 64n, 0); // high half -> first 8 bytes
22  b.writeBigUInt64LE(v & 0xffffffffffffffffn, 8); // low half -> last 8 bytes
23  return b;
24}
25
26/**
27 * Write a `UUID` from its raw 16 wire bytes (as produced by `readUUID` or
28 * {@link parseUUID}): copied verbatim. The inverse of `readUUID`. Throws unless
29 * exactly 16 bytes are given.
30 */
31export function writeUUID(sink: Sink, value: Uint8Array): void {
32  if (value.length !== 16) {
33    throw new RangeError(
34      `RowBinary: UUID must be 16 bytes, got ${value.length}`,
35    );
36  }
37  const o = reserve(sink, 16);
38  sink.buf.set(value, o);
39}
40
41/**
42 * Write a `UUID` from a single 128-bit `bigint` (`hi << 64 | lo`) — the inverse
43 * of `readUUIDBigInt`. The high 64 bits go to the first little-endian `UInt64`
44 * half, the low 64 bits to the second.
45 */
46export function writeUUIDBigInt(sink: Sink, value: bigint): void {
47  const o = reserve(sink, 16);
48  sink.buf.writeBigUInt64LE((value >> 64n) & 0xffffffffffffffffn, o);
49  sink.buf.writeBigUInt64LE(value & 0xffffffffffffffffn, o + 8);
50}
51
52/**
53 * Write a `UUID` from its two raw little-endian `UInt64` halves `[hi, lo]` — the
54 * inverse of `readUUIDHiLo`, the faithful wire split with no combining work.
55 */
56export function writeUUIDHiLo(sink: Sink, [hi, lo]: [bigint, bigint]): void {
57  const o = reserve(sink, 16);
58  sink.buf.writeBigUInt64LE(hi, o);
59  sink.buf.writeBigUInt64LE(lo, o + 8);
60}