clickhouse-js-node-rowbinary

ClickHouse JS RowBinary Codec Generator for Node.js

This skill generates both directions of the wire format: readers (decode bytes → values) and writers (encode values → bytes, the mirror). A given task normally needs only one side. This file is the shared entry point — the format gate plus the principles common to both directions; the per-direction decisions, guidance, and the per-type reference tables live in two sibling files.

Pick your side — read only the one you need:

• Decoding a RowBinary* response from ClickHouse into JS values → reader.md. Streaming vs whole-buffer, row-objects vs columnar, fixed vs runtime schema, and the per-type reader reference.
• Encoding JS values into a RowBinary payload to send to ClickHouse → writer.md. The Sink/writeX building blocks, writeRows streaming, and the per-type writer reference.

The per-type code is real, split by direction under src/readers/ and src/writers/.

First: is RowBinary even the right format?

RowBinary exists for throughput, but it is not automatically the fastest path — match the format to the shape of the data before committing to a bespoke parser.

Prefer a JSON* format (e.g. JSONEachRow) when the result is mostly strings / JSON-like values that you consume wholesale — randomly accessing essentially every field, running string/regexp methods on them, treating values as text. V8's native JSON.parse is heavily optimized C++ and builds JS strings and objects faster than a JS-level RowBinary decoder can; pair it with HTTP response compression (gzip / zstd, which crushes JSON's repetitive keys) and the wire cost shrinks too.

RowBinary clearly wins when the result is dominated by:

• Wide numerics — Int128/Int256/UInt128/UInt256, Decimal128/Decimal256.
• Binary / fixed-width blobs — IPv4, IPv6, UUID, FixedString.
• High-volume fixed-width numeric columns generally, where each value is a single DataView read.