@clickhouse/client 1.23.0-head.fae5998.1 → 1.23.0

package/skills/{clickhouse-js-node-rowbinary-parser → clickhouse-js-node-rowbinary}/README.md

@@ -1,10 +1,10 @@
-# ClickHouse Node.js RowBinary Parser Generator
+# ClickHouse Node.js RowBinary Codec Generator
 
-**If JS had a -O3 compiler flag, this skill would be it.** (for RowBinary parsing)
+**If JS had a -O3 compiler flag, this skill would be it.** (for RowBinary read & write)
 
-A skill and a library that lets a coding agent generate bespoke RowBinary parsers on the first pass from the column type definitions of a ClickHouse response. The [spirit](#the-spirit) behind the approach.
+A skill and a library that lets a coding agent generate bespoke RowBinary codecs on the first pass from the column type definitions of a ClickHouse response. The [spirit](#the-spirit) behind the approach.
 
-**Reader only** for now. Today this covers reading (decoding) RowBinary streams. A matching RowBinary writer (encoding) is planned.
+**Reads and writes.** Both directions are covered: readers (decode bytes → values) and writers (encode values → bytes), split under `src/readers/` and `src/writers/`. The reader path is the more mature one — the writers mirror it type-for-type, with a few decode-only paths (`Dynamic`, `JSON`, the runtime header/compile path, and the columnar typed-array path) not yet mirrored.
 
 ## Status
 
@@ -12,7 +12,7 @@ A skill and a library that lets a coding agent generate bespoke RowBinary parser
 - ✅ Opus 4.8: 71% -> 94.7% pass rate
 - ✅ Haiku 4.5: 52% -> 86.0% pass rate
 - ✅ Composer 2.5 Fast: 3x parser performance
-- ✅ 469/469 tests
+- ✅ 724/724 tests (readers + writers)
 - ✅ type-checked
 - ✅ benchmarked
 
@@ -35,7 +35,7 @@ const readOrderRow: Reader<OrderRow> = (s) => ({
   id: readUInt8(s),
   uid: formatUUID(readUUID(s)),
   price: readDecimal64(2)(s),
-  status: readEnum8(s),
+  status: readInt8(s), // raw enum int; `readEnum8(map)` resolves it to the name
 });
 ```
 
@@ -70,14 +70,74 @@ npx skills-npm setup
 As a skill only:
 
 ```bash
-npx skills add ClickHouse/clickhouse-js/skills/clickhouse-js-node-rowbinary-parser
+npx skills add ClickHouse/clickhouse-js/skills/clickhouse-js-node-rowbinary
 ```
 
 ```console
-> Hey, Claude, tell me what the rowbinary parser skill can do for me.
-> A lot! It generates custom, high-performance RowBinary parsers…
-> Super, generate a parser for the queries in app/src/model.ts.
-< Reading skill clickhouse-js-node-rowbinary-parser…
+> Hey, Claude, tell me what the rowbinary skill can do for me.
+> A lot! It generates custom, high-performance RowBinary readers and writers…
+> Super, generate a reader for the queries in app/src/model.ts.
+< Reading skill clickhouse-js-node-rowbinary…
+```
+
+## Using it with the ClickHouse JS client
+
+This library only **decodes** the bytes — it doesn't open connections. Pair it
+with the official client to fetch a `RowBinary` response and feed the byte chunks
+into `streamRowBatches(chunks, readRow)`.
+
+`RowBinary` isn't one of the formats the client decodes itself, so don't use
+`client.query({ format: ... })` for it. Instead use `client.exec({ query })` with
+the `FORMAT RowBinary` clause written into the SQL yourself — `exec` hands back the
+**raw, undecoded byte stream** of the response, which is exactly what this library
+consumes. (Use plain `RowBinary`, not `RowBinaryWithNamesAndTypes`, unless your
+reader also skips the leading names/types header.)
+
+The row reader below is the `orders` example from [EXAMPLES.md](EXAMPLES.md); swap
+in the reader the skill generates for your own columns.
+
+```ts
+import {
+  type Reader,
+  readUInt8,
+  readInt8,
+  readUUID,
+  formatUUID,
+  readDecimal64,
+  type DecimalValue,
+  streamRowBatches,
+} from "@clickhouse/rowbinary";
+import { createClient } from "@clickhouse/client";
+
+type OrderRow = {
+  id: number;
+  uid: string;
+  price: DecimalValue;
+  status: number;
+};
+
+const readOrderRow: Reader<OrderRow> = (s) => ({
+  id: readUInt8(s),
+  uid: formatUUID(readUUID(s)),
+  price: readDecimal64(2)(s),
+  status: readInt8(s), // raw enum int; `readEnum8(map)` resolves it to the name
+});
+
+// `exec` resolves to a Node `Stream.Readable`. It is already an
+// `AsyncIterable<Uint8Array>` (chunks are `Buffer`/`Uint8Array`, which
+// `streamRowBatches` normalizes), so pass `stream` straight in:
+
+const client = createClient();
+
+const { stream } = await client.exec({
+  query: "SELECT id, uid, price, status FROM orders FORMAT RowBinary",
+});
+
+for await (const rows of streamRowBatches(stream, readOrderRow)) {
+  for (const row of rows) console.log(row); // { id, uid, price: [unscaled, scale], status }
+}
+
+await client.close();
 ```
 
 ## Why it's worth it
@@ -129,6 +189,13 @@ than shipping a generic, runtime-driven decoder, it emits straight-line code
 that reads each column in order, so the parser only contains the logic the
 specific result shape needs.
 
+**Schema only known at runtime?** `compileRowBinaryWithNamesAndTypes(cursor)`
+reads the `RowBinaryWithNamesAndTypes` header and folds each column type into a
+reader on the fly (type strings parsed by `@clickhouse/datatype-parser`),
+returning a `readRows` driver for the rest of the stream — a generic, no-codegen
+path for dynamic schemas. The specialized codegen above stays the fast path when
+the types are fixed.
+
 ## Correctness on the gotcha-heavy types
 
 For a plain `UInt64, String, DateTime` result a strong model already writes fast,
@@ -201,18 +268,22 @@ Measure, don't assume.
 
 ## Scope
 
-- **In scope:** `RowBinary`, `RowBinaryWithNames`, and
+- **In scope (reading):** `RowBinary`, `RowBinaryWithNames`, and
   `RowBinaryWithNamesAndTypes` decoding for Node.js — full-buffer and streaming
   (chunked) via `advance()`/`NeedMoreData`, `readRows()`, and the async
   `streamRowBatches()` (with a built-in small-chunk warning and the optional
   `coalesceChunks()` debounce filter).
-- **Planned:** RowBinary **writing / encoding** (the inverse of everything above)
+- **In scope (writing):** the inverse encode path — a `writeX` mirroring every
+  `readX`, appending bytes to a `Sink`, plus `writeRows()`. Imported from
+  `@clickhouse/rowbinary/writer`. A handful of decode-only paths are not yet
+  mirrored: `Dynamic`, `JSON`, the runtime header/compile path, and the columnar
+  typed-array path.
 - **Out of scope (for now):** browsers and Edge runtimes, non-RowBinary formats
   (JSON / CSV / TSV / Parquet), and big-endian hosts.
 
 ## The spirit
 
-A RowBinary parser generator is a narrow thing. But it's built as an instance of
+A RowBinary codec generator is a narrow thing. But it's built as an instance of
 a broader bet about what libraries become once a capable LLM is part of the
 toolchain. Three shifts, each already visible in this repo:
 

package/skills/clickhouse-js-node-rowbinary/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: clickhouse-js-node-rowbinary
+description: >
+  Generate TypeScript/JavaScript code that reads/decodes AND writes/encodes
+  ClickHouse RowBinary streams for the ClickHouse HTTP server.
+  Use this skill whenever a user wants to parse or produce `RowBinary`,
+  `RowBinaryWithNames`, or `RowBinaryWithNamesAndTypes`.
+  Node.js only, doesn't cover browsers.
+---
+
+# 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](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](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.
+
+**Prefer the `Native` format when** columnar load and client-side analytics are
+the main goal (fold/scan/filter columns, feed typed arrays to a Worker or WASM).
+`Native` is column-major, so it loads straight into one typed array per column
+with no transpose.
+
+For help choosing and consuming a `JSON*` format (or CSV / TSV) instead, use the
+**`clickhouse-js-node-coding`** skill.
+
+## Core guidance (both directions)
+
+These principles apply whether you are generating a reader or a writer; the
+side-specific operational guidance is in [reader.md](reader.md) /
+[writer.md](writer.md).
+
+- **Little-endian only.** RowBinary is little-endian; target x86/ARM. Read and
+  write every multi-byte number with `DataView` accessors passing a **literal**
+  `true` for the `littleEndian` flag.
+
+- **Correct first, then optimize.** First emit a correct codec built from the
+  plain per-type API. Only after it's correct (and tested) specialize it. Don't
+  bake performance assumptions in before correctness.
+
+- **Monomorphize generic/composite types.** Emit specialized, inlined code per
+  type combination instead of passing functions as arguments where the type is
+  known ahead of time.
+
+- **Inline the leaf ops.** The per-type `readX`/`writeX` functions are the
+  correct, composable reference; the generated codec should INLINE their bodies,
+  not call them, so the row loop is straight-line with no per-field indirection
+  (and so the fixed-width coalescing can fold the offset arithmetic together).
+
+- **Annotate the type per column.** Inlining erases the type structure, so put a
+  short comment above each column's encode/decode block naming the ClickHouse
+  type it handles.
+
+- **Shared scratch is not reentrant.** Some hot methods reuse a module-level
+  scratch buffer as a write-then-read pair — correct only because the access is
+  fully synchronous. An `async`/`yield` boundary between populating and reading
+  it corrupts the value.
+
+- **TypeScript by default.** Generate TypeScript code and helpers unless the user
+  explicitly asks for plain JavaScript.
+
+## Worked examples
+
+Six end-to-end examples with real speedup are catalogued in [EXAMPLES.md](EXAMPLES.md).
+
+## Out of scope
+
+- **JSON / CSV / TSV / Parquet parsing** → use `clickhouse-js-node-coding`.
+- **Connection errors, hangs, type mismatches** → use
+  `clickhouse-js-node-troubleshooting`.
+- **Browser / Web Worker / Edge** → `@clickhouse/client-web`.
+
+## Still Stuck?
+
+- [ClickHouse RowBinary format](https://clickhouse.com/docs/interfaces/formats#rowbinary)
+- [ClickHouse data types](https://clickhouse.com/docs/sql-reference/data-types)
+- [ClickHouse JS client docs](https://clickhouse.com/docs/integrations/javascript)

package/skills/{clickhouse-js-node-rowbinary-parser/SKILL.md → clickhouse-js-node-rowbinary/reader.md}

@@ -1,46 +1,12 @@
----
-name: clickhouse-js-node-rowbinary-parser
-description: >
-  Generate TypeScript/JavaScript code that reads and decodes ClickHouse
-  RowBinary streams from the ClickHouse HTTP server.
-  Use this skill whenever a user wants to parse `RowBinary`,
-  `RowBinaryWithNames`, or `RowBinaryWithNamesAndTypes`.
-  Node.js only, doesn't cover browsers.
----
-
-# ClickHouse JS RowBinary Parser Generator for Node.js
-
-## 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.
-
-**Prefer the `Native` format when** columnar load and client-side analytics are
-the main goal (fold/scan/filter columns, feed typed arrays to a Worker or WASM).
-`Native` is column-major, so it loads straight into one typed array per column
-with no transpose.
-
-For help choosing and consuming a `JSON*` format (or CSV / TSV) instead, use the
-**`clickhouse-js-node-coding`** skill.
-
-## Second: complete buffer, or incremental stream?
+# RowBinary reader (decode) for Node.js
+
+Decoding a `RowBinary` / `RowBinaryWithNames` / `RowBinaryWithNamesAndTypes`
+response from ClickHouse into JS values. Read [SKILL.md](SKILL.md) first for the
+format gate ("is RowBinary even the right format?") and the principles that
+apply to **both** directions; this file covers the decisions and the per-type
+reference specific to **reading**. Writing? See [writer.md](writer.md).
+
+## First: complete buffer, or incremental stream?
 
 Decide this before writing the reader — it changes the shape of the code and is
 a real performance fork.
@@ -56,7 +22,7 @@ a real performance fork.
 
 The exposed API is streaming by default and requires an optimisation pass.
 
-## Third: row objects, or columnar (typed arrays)?
+## Second: row objects, or columnar (typed arrays)?
 
 The default output is one object per row (array-of-structs). For a **numeric,
 fixed-width result that the consumer reads column-wise**, decode instead into one
@@ -77,43 +43,39 @@ bandwidth). Measured in `tests/iot.columnar.bench.ts`; rationale in
   complete-row count is `(chunk.length / stride) | 0`, and the leftover bytes
   carry to the next chunk. Yield one typed-array batch per chunk, each owning a
   fresh transferable `ArrayBuffer` (see `streamSensorColumns` in
-  `src/columnar.ts`).
+  `src/readers/columnar.ts`).
 - **Stay row-oriented when** downstream code is row-shaped, the row is
   string-dominated (columnar's win is numeric — a JS string allocates either
   way), or the schema is nested/heterogeneous (`Array`/`Map`/`Tuple`).
 - **Hybrid:** store columnar, expose a lazy `rowAt(i)` accessor that builds an
   object only for rows actually touched (see `iotRowAt` in `src/examples/iot.ts`).
 
-## Core guidance
-
-When generating a parser, follow these:
+## Third: are the column types known ahead of time?
 
-- **Little-endian only.** RowBinary is little-endian; target x86/ARM. Read every
-  multi-byte number with `DataView` accessors passing a **literal** `true` for
-  the `littleEndian` flag.
+- **Known (the default).** Generate a straight-line reader specialized to those
+  types — everything below.
+- **Only at runtime** (the schema varies, or you just want to decode an arbitrary
+  `RowBinaryWithNamesAndTypes` stream). Call
+  `compileRowBinaryWithNamesAndTypes(cursor)` (`src/readers/rowBinaryWithNamesAndTypes.ts`):
+  it reads the header, folds each column type's AST into a `Reader`
+  (`astToReader`, `src/readers/compile.ts`; type strings parsed by
+  `@clickhouse/datatype-parser`), and returns a `readRows` driver for the rest of
+  the stream. Generic and unoptimized (no codegen), so prefer the specialized
+  path whenever the types are fixed.
 
-- **Correct first, then optimize.** First emit a correct reader built from the
-  plain per-type API. Only after it's correct (and tested) specialize it. Don't
-  bake performance assumptions in before correctness.
+## Reader guidance
 
-- **Monomorphize generic/composite types.** Emit specialized, inlined code per
-  type combination instead of passing functions as arguments where the type
-  is known ahead of time.
+On top of the shared principles in [SKILL.md](SKILL.md), the read path has its own:
 
 - **Streaming: throw + restart, not generators.** To signal "need more bytes",
   a synchronous reader that throws a sentinel (`NeedMoreData`) and restarts the
-  row beats generators for realistic chunk sizes;
+  row beats generators for realistic chunk sizes.
 
 - **Keep an eye on chunk sizes.** Partial trailing rows, small chunks are a silent
   throughput killer: `streamRowBatches` warns once when
   rows-per-chunk falls too low, and `coalesceChunks(source, { minSize, timeoutMs })`
   merges small chunks in front of it when the source size isn't yours to raise.
 
-- **Shared scratch is not reentrant.** Some hot methods reuse a module-level
-  scratch buffer as a write-then-read pair — correct only because reads are fully
-  synchronous. An `async`/`yield` boundary between populating and reading it
-  corrupts the value.
-
 - **Hoist the cursor into locals.** Prefer the working buffer and view declared
   once at the top of the generated reader, and keep the read offset in a **local variable**,
   operating on it directly instead of re-reading from an object.
@@ -122,69 +84,43 @@ When generating a parser, follow these:
   neighbouring fixed-width columns has a known combined size, so bounds-check it
   ONCE.
 
-- **Inline the leaf reads.** The per-type `readX` functions are the correct,
-  composable reference; the generated parser should INLINE their bodies, not call
-  them, so the row reader is straight-line with no per-field indirection (and so
-  the two points above can fold the offset arithmetic together).
-
-- **Annotate the decoded type per column.** Inlining erases the type structure,
-  so put a short comment above each column's decode block naming the ClickHouse
-  type it reads.
-
 - **Pre-allocate small result arrays.** RowBinary gives every array/map its
   element count up front (the LEB128 prefix), so DEFAULT is to `new Array(n)`.
   NOTE: for **large** arrays the application will iterate or compute over repeatedly,
   prefer `[]` + `push` (faster to traverse in V8) — or a typed array (`Float64Array`…)
   for numeric elements.
 
-- **TypeScript by default.** Generate TypeScript parsers and helpers unless the
-  user explicitly asks for plain JavaScript.
-
-## Type family references
-
-The readers live as real code under `src/`, split by type family.
-
-| Result contains (trigger)                                                                                                                      | Open                                                                                                                                                                  |
-| ---------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Always** — cursor state, `advance()`, `NeedMoreData`, `Reader<T>`                                                                            | `src/core.ts`                                                                                                                                                         |
-| LEB128 length/count prefixes for `String`/`Array`/`Map` (`readUVarint`)                                                                        | `src/varint.ts`                                                                                                                                                       |
-| `Int8`–`Int256`, `UInt8`–`UInt256`                                                                                                             | `src/integers.ts`                                                                                                                                                     |
-| `Bool`                                                                                                                                         | `src/bool.ts`                                                                                                                                                         |
-| `Enum8`, `Enum16`                                                                                                                              | `src/enums.ts`                                                                                                                                                        |
-| `Float32`, `Float64`, `BFloat16`                                                                                                               | `src/floats.ts`                                                                                                                                                       |
-| `Decimal32/64/128/256`, `Decimal(P, S)`                                                                                                        | `src/decimals.ts`                                                                                                                                                     |
-| `String`, `FixedString(N)`                                                                                                                     | `src/strings.ts`                                                                                                                                                      |
-| `UUID`                                                                                                                                         | `src/uuid.ts`                                                                                                                                                         |
-| `IPv4`, `IPv6`                                                                                                                                 | `src/ip.ts`                                                                                                                                                           |
-| `Date`, `Date32`, `DateTime`, `DateTime(tz)`, `DateTime64(P[, tz])`                                                                            | `src/datetime.ts`                                                                                                                                                     |
-| `Time`, `Time64(P)`                                                                                                                            | `src/time.ts`                                                                                                                                                         |
-| `IntervalNanosecond` … `IntervalYear`                                                                                                          | `src/interval.ts`                                                                                                                                                     |
-| `Array(T)`, `Map(K, V)`, `Tuple(...)`, `Nullable(T)`, `Variant(...)`, `QBit(...)`                                                              | `src/composite.ts`                                                                                                                                                    |
-| `Point`, `Ring`, `LineString`, `MultiLineString`, `Polygon`, `MultiPolygon`, `Geometry`                                                        | `src/geo.ts`                                                                                                                                                          |
-| `Dynamic` (and `Variant`/`Interval`/`Nested`/`Dynamic` nested inside it)                                                                       | `src/dynamic.ts`                                                                                                                                                      |
-| `JSON`                                                                                                                                         | `src/json.ts`                                                                                                                                                         |
-| The whole result — loop rows to EOF (`readRows`)                                                                                               | `src/rows.ts`                                                                                                                                                         |
-| A chunked HTTP response — `streamRowBatches`, `coalesceChunks`                                                                                 | `src/stream.ts`                                                                                                                                                       |
-| **Numeric/fixed-width result read column-wise** (aggregate/scan/plot, hand to a Worker/WASM) → decode into typed arrays, not row objects (~4x) | `src/columnar.ts` (`streamSensorColumns` — streaming, yields transferable typed-array batches); `decodeIotColumnar` in `src/examples/iot.ts` is the whole-buffer form |
-| `LowCardinality(T)` — transparent, decode as `T`                                                                                               | `src/lowCardinality.ts`                                                                                                                                               |
-| `SimpleAggregateFunction(f, T)` — transparent, decode as `T`                                                                                   | `src/simpleAggregateFunction.ts`                                                                                                                                      |
-| `Nested(...)` — no wire of its own; `Array(Tuple(...))`                                                                                        | `src/nested.ts`                                                                                                                                                       |
-| `Nothing` — zero-width, never decoded (only wrapped)                                                                                           | `src/nothing.ts`                                                                                                                                                      |
-| `AggregateFunction(...)` — opaque state; finalize server-side                                                                                  | `src/aggregateFunction.ts`                                                                                                                                            |
-
-## Worked examples
-
-Six end-to-end examples with real speedup are catalogued in [EXAMPLES.md](EXAMPLES.md).
-
-## Out of scope
-
-- **JSON / CSV / TSV / Parquet parsing** → use `clickhouse-js-node-coding`.
-- **Connection errors, hangs, type mismatches** → use
-  `clickhouse-js-node-troubleshooting`.
-- **Browser / Web Worker / Edge** → `@clickhouse/client-web`.
-
-## Still Stuck?
-
-- [ClickHouse RowBinary format](https://clickhouse.com/docs/interfaces/formats#rowbinary)
-- [ClickHouse data types](https://clickhouse.com/docs/sql-reference/data-types)
-- [ClickHouse JS client docs](https://clickhouse.com/docs/integrations/javascript)
+## Reader type family references
+
+The readers live as real code under `src/readers/`, split by type family.
+
+| Result contains (trigger)                                                                                                                      | Open                                                                                                                                                                          |
+| ---------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Always** — cursor state, `advance()`, `NeedMoreData`, `Reader<T>`                                                                            | `src/readers/core.ts`                                                                                                                                                         |
+| LEB128 length/count prefixes for `String`/`Array`/`Map` (`readUVarint`)                                                                        | `src/readers/varint.ts`                                                                                                                                                       |
+| `Int8`–`Int256`, `UInt8`–`UInt256`                                                                                                             | `src/readers/integers.ts`                                                                                                                                                     |
+| `Bool`                                                                                                                                         | `src/readers/bool.ts`                                                                                                                                                         |
+| `Enum8`, `Enum16` (resolve to the value's name; `readInt8`/`readInt16` for the raw int)                                                        | `src/readers/enums.ts`                                                                                                                                                        |
+| `Float32`, `Float64`, `BFloat16`                                                                                                               | `src/readers/floats.ts`                                                                                                                                                       |
+| `Decimal32/64/128/256`, `Decimal(P, S)`                                                                                                        | `src/readers/decimals.ts`                                                                                                                                                     |
+| `String`, `FixedString(N)`                                                                                                                     | `src/readers/strings.ts`                                                                                                                                                      |
+| `UUID`                                                                                                                                         | `src/readers/uuid.ts`                                                                                                                                                         |
+| `IPv4`, `IPv6`                                                                                                                                 | `src/readers/ip.ts`                                                                                                                                                           |
+| `Date`, `Date32`, `DateTime`, `DateTime(tz)`, `DateTime64(P[, tz])`                                                                            | `src/readers/datetime.ts`                                                                                                                                                     |
+| `Time`, `Time64(P)`                                                                                                                            | `src/readers/time.ts`                                                                                                                                                         |
+| `IntervalNanosecond` … `IntervalYear`                                                                                                          | `src/readers/interval.ts`                                                                                                                                                     |
+| `Array(T)`, `Map(K, V)`, `Tuple(...)`, `Nullable(T)`, `Variant(...)`, `QBit(...)`                                                              | `src/readers/composite.ts`                                                                                                                                                    |
+| `Point`, `Ring`, `LineString`, `MultiLineString`, `Polygon`, `MultiPolygon`, `Geometry`                                                        | `src/readers/geo.ts`                                                                                                                                                          |
+| `Dynamic` (and `Variant`/`Interval`/`Nested`/`Dynamic` nested inside it)                                                                       | `src/readers/dynamic.ts`                                                                                                                                                      |
+| `JSON`                                                                                                                                         | `src/readers/json.ts`                                                                                                                                                         |
+| The whole result — loop rows to EOF (`readRows`)                                                                                               | `src/readers/rows.ts`                                                                                                                                                         |
+| A chunked HTTP response — `streamRowBatches`, `coalesceChunks`                                                                                 | `src/readers/stream.ts`                                                                                                                                                       |
+| The `RowBinaryWithNamesAndTypes` header — column names + type strings (`readHeader`)                                                           | `src/readers/header.ts`                                                                                                                                                       |
+| Fold one parsed type AST into a `Reader` (`astToReader`) — AST in, reader out                                                                  | `src/readers/compile.ts`                                                                                                                                                      |
+| **Types known only at runtime** — compile a whole header into a row reader (`compileRowBinaryWithNamesAndTypes`, `typeStringToReader`)         | `src/readers/rowBinaryWithNamesAndTypes.ts`                                                                                                                                   |
+| **Numeric/fixed-width result read column-wise** (aggregate/scan/plot, hand to a Worker/WASM) → decode into typed arrays, not row objects (~4x) | `src/readers/columnar.ts` (`streamSensorColumns` — streaming, yields transferable typed-array batches); `decodeIotColumnar` in `src/examples/iot.ts` is the whole-buffer form |
+| `LowCardinality(T)` — transparent, decode as `T`                                                                                               | `src/readers/lowCardinality.ts`                                                                                                                                               |
+| `SimpleAggregateFunction(f, T)` — transparent, decode as `T`                                                                                   | `src/readers/simpleAggregateFunction.ts`                                                                                                                                      |
+| `Nested(...)` — no wire of its own; `Array(Tuple(...))`                                                                                        | `src/readers/nested.ts`                                                                                                                                                       |
+| `Nothing` — zero-width, never decoded (only wrapped)                                                                                           | `src/readers/nothing.ts`                                                                                                                                                      |
+| `AggregateFunction(...)` — opaque state; finalize server-side                                                                                  | `src/readers/aggregateFunction.ts`                                                                                                                                            |

package/skills/{clickhouse-js-node-rowbinary-parser → clickhouse-js-node-rowbinary}/src/examples/carts.ts

@@ -1,8 +1,12 @@
-import { readArray, readNullable, readTupleNamed } from "../composite.js";
-import { type Reader, advance } from "../core.js";
-import { readInt32, readUInt16, readUInt32 } from "../integers.js";
-import { readString } from "../strings.js";
-import { readUVarint } from "../varint.js";
+import {
+  readArray,
+  readNullable,
+  readTupleNamed,
+} from "../readers/composite.js";
+import { type Reader, advance } from "../readers/core.js";
+import { readInt32, readUInt16, readUInt32 } from "../readers/integers.js";
+import { readString } from "../readers/strings.js";
+import { readUVarint } from "../readers/varint.js";
 
 /**
  * Example: a carts table — nested generics.

package/skills/{clickhouse-js-node-rowbinary-parser → clickhouse-js-node-rowbinary}/src/examples/events.ts

@@ -1,8 +1,8 @@
-import { type Reader, advance } from "../core.js";
-import { readDateTime } from "../datetime.js";
-import { readUInt64 } from "../integers.js";
-import { readString } from "../strings.js";
-import { readUVarint } from "../varint.js";
+import { type Reader, advance } from "../readers/core.js";
+import { readDateTime } from "../readers/datetime.js";
+import { readUInt64 } from "../readers/integers.js";
+import { readString } from "../readers/strings.js";
+import { readUVarint } from "../readers/varint.js";
 
 /**
  * Example: a plain events table — the scalar baseline.

package/skills/{clickhouse-js-node-rowbinary-parser → clickhouse-js-node-rowbinary}/src/examples/iot.ts

@@ -1,7 +1,7 @@
-import { type Reader, advance } from "../core.js";
-import { readDateTime64P3 } from "../datetime.js";
-import { readFloat32, readFloat64 } from "../floats.js";
-import { readUInt8, readUInt32 } from "../integers.js";
+import { type Reader, advance } from "../readers/core.js";
+import { readDateTime64P3 } from "../readers/datetime.js";
+import { readFloat32, readFloat64 } from "../readers/floats.js";
+import { readUInt8, readUInt32 } from "../readers/integers.js";
 
 /**
  * Example: a table of IoT sensor readings — the dense, fixed-width NUMERIC case

package/skills/{clickhouse-js-node-rowbinary-parser → clickhouse-js-node-rowbinary}/src/examples/ledger.ts

@@ -1,10 +1,10 @@
-import { type Reader, advance } from "../core.js";
+import { type Reader, advance } from "../readers/core.js";
 import {
   type DecimalValue,
   readDecimal64,
   readDecimal128,
-} from "../decimals.js";
-import { readInt64, readUInt128, readUInt256 } from "../integers.js";
+} from "../readers/decimals.js";
+import { readInt64, readUInt128, readUInt256 } from "../readers/integers.js";
 
 /**
  * Example: a financial ledger — the WIDE-NUMERIC case where RowBinary wins on

package/skills/{clickhouse-js-node-rowbinary-parser → clickhouse-js-node-rowbinary}/src/examples/logs.ts

@@ -1,7 +1,7 @@
-import { type Reader, advance } from "../core.js";
-import { readDateTime } from "../datetime.js";
-import { readString } from "../strings.js";
-import { readUVarint } from "../varint.js";
+import { type Reader, advance } from "../readers/core.js";
+import { readDateTime } from "../readers/datetime.js";
+import { readString } from "../readers/strings.js";
+import { readUVarint } from "../readers/varint.js";
 
 /**
  * Example: an application log table — the STRING-HEAVY case where the skill

package/skills/{clickhouse-js-node-rowbinary-parser → clickhouse-js-node-rowbinary}/src/examples/observability.ts

@@ -4,15 +4,14 @@ import {
   readNullable,
   readTupleNamed,
   readVariant,
-} from "../composite.js";
-import { type Reader, advance } from "../core.js";
-import { readDateTime64P3 } from "../datetime.js";
-import { readEnum8 } from "../enums.js";
-import { readFloat64 } from "../floats.js";
-import { readInt64, readUInt64 } from "../integers.js";
-import { readString } from "../strings.js";
-import { formatUUID, formatUUIDTable, readUUID } from "../uuid.js";
-import { readUVarint } from "../varint.js";
+} from "../readers/composite.js";
+import { type Reader, advance } from "../readers/core.js";
+import { readDateTime64P3 } from "../readers/datetime.js";
+import { readFloat64 } from "../readers/floats.js";
+import { readInt8, readInt64, readUInt64 } from "../readers/integers.js";
+import { readString } from "../readers/strings.js";
+import { formatUUID, formatUUIDTable, readUUID } from "../readers/uuid.js";
+import { readUVarint } from "../readers/varint.js";
 
 /**
  * Example: an observability/events table — the gotcha-heavy one. It packs the
@@ -60,7 +59,7 @@ export type ObsRow = {
 export const readObsRow: Reader<ObsRow> = (s) => ({
   id: readUInt64(s),
   ts: readDateTime64P3(s).toISOString(),
-  level: readEnum8(s),
+  level: readInt8(s),
   traceId: formatUUID(readUUID(s)),
   payload: readVariant([readFloat64, readInt64, readString])(s),
   tags: readMap(readString, readString)(s),