Profiles

1import { readArray, readNullable } from "../readers/composite.js";
2import { type Reader, advance } from "../readers/core.js";
3import { readInt32, readUInt32 } from "../readers/integers.js";
4import { readString } from "../readers/strings.js";
5import { readUVarint } from "../readers/varint.js";
6
7/**
8 * Example: a profiles table — Array and Nullable wrappers.
9 *
10 * Columns (the trigger):
11 *   id    UInt32
12 *   tags  Array(String)
13 *   score Nullable(Int32)
14 *
15 * `readArray(elem)` reads a LEB128 length then that many elements; `readNullable`
16 * reads a 1-byte present/NULL flag then the value. Both are combinators: pass the
17 * inner reader and they return a `Reader`. Empty array and NULL are the sharp
18 * cases (a single byte each).
19 */
20export type ProfileRow = { id: number; tags: string[]; score: number | null };
21
22export const readProfileRow: Reader<ProfileRow> = (s) => ({
23  id: readUInt32(s),
24  tags: readArray(readString)(s),
25  score: readNullable(readInt32)(s),
26});
27
28/**
29 * Optimized {@link readProfileRow}, monomorphized: `readArray(readString)` and
30 * `readNullable(readInt32)` each allocate a fresh combinator closure on EVERY
31 * row in the version above; here the array loop and the null-flag branch are
32 * inlined, so no per-row closures are created and the element/inner reads are
33 * straight-line. This is the kind of win the SKILL's "monomorphize" step targets;
34 * see `profiles.bench.ts`.
35 *
36 * MEASURED (Node 24 / V8, `profiles.bench.ts`): ~1.3x faster — removing the two
37 * per-row combinator closures (`readArray(readString)`, `readNullable(readInt32)`)
38 * is the win.
39 */
40export const readProfileRowFast: Reader<ProfileRow> = (s) => {
41  const { buf, view } = s;
42
43  // id UInt32.
44  const id = view.getUint32(advance(s, 4), true);
45
46  // tags Array(String): count, then each a length-prefixed UTF-8 string.
47  const n = readUVarint(s);
48  const tags = new Array<string>(n);
49  for (let i = 0; i < n; i++) {
50    const len = readUVarint(s);
51    const start = advance(s, len);
52    tags[i] = buf.toString("utf8", start, start + len);
53  }
54
55  // score Nullable(Int32): null-flag byte, then if non-null a 4-byte int.
56  const score =
57    buf[advance(s, 1)]! !== 0 ? null : view.getInt32(advance(s, 4), true);
58
59  return { id, tags, score };
60};