@clickhouse/rowbinary: when your library is also a parser compiler

Summary

ClickHouse's @clickhouse/rowbinary is a Node.js reader and writer for the RowBinary, RowBinaryWithNames, and RowBinaryWithNamesAndTypes formats, offering both a generic parser and an accompanying Agent Skill. RowBinary avoids per-row overhead but is difficult to consume in JavaScript because nested types, LEB128 varints, precision-sensitive DateTime64 values, and recursive self-describing types require extensive runtime dispatch; JSON alternatives can also round large UInt64 values. The package provides small, composable, monomorphizable reading primitives, while SKILL.md instructs a coding agent to assemble query-specific parsers with inlined operations and selected policies such as BigInt handling and array materialization. Generated parsers run 1.5–3.4x faster than composing library functions in loops, with a fixed-width benchmark parser reaching 3.41x faster, and produce reviewable source that can be tested and benchmarked like ordinary application code.

Takeaways

1. 1

   The library supports RowBinary, RowBinaryWithNames, and RowBinaryWithNamesAndTypes, with full-buffer and chunked-stream reading variants plus writers.

2. 2

   For a fixed-width orders schema, the generated parser performs one bounds check for a 26-byte row and reads columns at constant offsets.

3. 3

   The generated parser is regular source code intended for human review, testing, and benchmarking; Haiku's reported pass rate improved from 52% to 86% with focused sub-agents.