Carts

1import {
2  readArray,
3  readNullable,
4  readTupleNamed,
5} from "../readers/composite.js";
6import { type Reader, advance } from "../readers/core.js";
7import { readInt32, readUInt16, readUInt32 } from "../readers/integers.js";
8import { readString } from "../readers/strings.js";
9import { readUVarint } from "../readers/varint.js";
10
11/**
12 * Example: a carts table — nested generics.
13 *
14 * Columns (the trigger):
15 *   cart_id   UInt32
16 *   items     Array(Tuple(sku String, qty UInt16))
17 *   discounts Array(Nullable(Int32))
18 *
19 * The element reader of an `Array` can itself be a combinator: `items` is an
20 * `Array` whose element is a named `Tuple`, `discounts` an `Array` whose element
21 * is a `Nullable`. Combinators nest to any depth, matching the column type.
22 */
23export type CartRow = {
24  cartId: number;
25  items: { sku: string; qty: number }[];
26  discounts: (number | null)[];
27};
28
29export const readCartRow: Reader<CartRow> = (s) => ({
30  cartId: readUInt32(s),
31  items: readArray(readTupleNamed({ sku: readString, qty: readUInt16 }))(s),
32  discounts: readArray(readNullable(readInt32))(s),
33});
34
35/**
36 * Optimized {@link readCartRow}, monomorphized through the nesting: the API
37 * version rebuilds the outer `readArray`, the inner `readTupleNamed`, and the
38 * `readNullable` closures on every row (and the tuple reader iterates a keys
39 * array per element). Here both arrays are inlined loops, the tuple element is a
40 * flat object literal, and the nullable is an inline branch — no closures, no key
41 * iteration, at either nesting level.
42 *
43 * MEASURED (Node 24 / V8, `carts.bench.ts`): ~2x faster — nested combinators
44 * (outer `readArray`, inner `readTupleNamed` / `readNullable`) rebuilt per row in
45 * the API version, all flattened here.
46 */
47export const readCartRowFast: Reader<CartRow> = (s) => {
48  const { buf, view } = s;
49
50  // cart_id UInt32.
51  const cartId = view.getUint32(advance(s, 4), true);
52
53  // items Array(Tuple(sku String, qty UInt16)): count, then per element a
54  // length-prefixed string and a 2-byte int.
55  const itemsN = readUVarint(s);
56  const items = new Array<{ sku: string; qty: number }>(itemsN);
57  for (let i = 0; i < itemsN; i++) {
58    const len = readUVarint(s);
59    const start = advance(s, len);
60    const sku = buf.toString("utf8", start, start + len);
61    const qty = view.getUint16(advance(s, 2), true);
62    items[i] = { sku, qty };
63  }
64
65  // discounts Array(Nullable(Int32)): count, then per element a null-flag byte
66  // and, if non-null, a 4-byte int.
67  const discN = readUVarint(s);
68  const discounts = new Array<number | null>(discN);
69  for (let i = 0; i < discN; i++) {
70    discounts[i] =
71      buf[advance(s, 1)]! !== 0 ? null : view.getInt32(advance(s, 4), true);
72  }
73
74  return { cartId, items, discounts };
75};