Strings

1import { type Reader, Cursor, advance } from "./core.js";
2import { readUVarint } from "./varint.js";
3
4/**
5 * Read a `String`: a varint byte-length prefix followed by that many bytes,
6 * decoded as UTF-8.
7 *
8 * NOTE: ClickHouse `String` is arbitrary bytes, not guaranteed UTF-8. For binary
9 * columns, read `state.buf.subarray(start, start + len)` and skip the decode to
10 * keep the raw bytes.
11 */
12export function readString(state: Cursor): string {
13  const len = readUVarint(state);
14  const start = advance(state, len);
15  return state.buf.toString("utf8", start, start + len);
16}
17
18/**
19 * Read a `FixedString(N)`: exactly `size` raw bytes, decoded as UTF-8. Curried:
20 * `readFixedString(N)` returns the reader.
21 *
22 * The value is right-padded with NUL bytes to `size`; those trailing `\x00` are
23 * part of the stored value and are preserved here. Trim them
24 * (`.replace(/\x00+$/, "")`) only if your column holds NUL-terminated text.
25 *
26 * ClickHouse server returns `FixedString`s in JSON with the trailing NULs,
27 * therefore this reader preserves them as well.
28 */
29export function readFixedString(size: number): Reader<string> {
30  return (state) => {
31    const start = advance(state, size);
32    return state.buf.toString("utf8", start, start + size);
33  };
34}
35
36/**
37 * Read a `FixedString(N)` as raw bytes (no UTF-8 decode) — for binary columns.
38 * Curried: `readFixedStringBytes(N)` returns the reader. Returns a zero-copy
39 * view: no allocation, but the slice shares memory with the response, so
40 * retaining any one slice pins the entire chunk buffer in memory.
41 *
42 * SAFE TO TOGGLE — if the bytes outlive the row/response, return an independent
43 * copy instead so the chunk can be freed:
44 *
45 *   // return Buffer.from(state.buf.subarray(start, start + size));
46 *
47 * Make an educated tradeoff: view (default) when consumed immediately, a copy
48 * when retained.
49 */
50export function readFixedStringBytes(size: number): Reader<Buffer> {
51  return (state) => {
52    const start = advance(state, size);
53    return state.buf.subarray(start, start + size);
54  };
55}