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

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,56 +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`).
 
-## Fourth: are the column types known ahead of time?
+## Third: are the column types known ahead of time?
 
 - **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/rowBinaryWithNamesAndTypes.ts`):
+  `compileRowBinaryWithNamesAndTypes(cursor)` (`src/readers/rowBinaryWithNamesAndTypes.ts`):
   it reads the header, folds each column type's AST into a `Reader`
-  (`astToReader`, `src/compile.ts`; type strings parsed by
+  (`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.
 
-## Core guidance
-
-When generating a parser, follow these:
-
-- **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.
+## Reader guidance
 
-- **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.
-
-- **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.
@@ -135,72 +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`                                                                                                                                                       |
-| The `RowBinaryWithNamesAndTypes` header — column names + type strings (`readHeader`)                                                           | `src/header.ts`                                                                                                                                                       |
-| Fold one parsed type AST into a `Reader` (`astToReader`) — AST in, reader out                                                                  | `src/compile.ts`                                                                                                                                                      |
-| **Types known only at runtime** — compile a whole header into a row reader (`compileRowBinaryWithNamesAndTypes`, `typeStringToReader`)         | `src/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/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),

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

@@ -1,8 +1,7 @@
-import { type Reader, advance } from "../core.js";
-import { type DecimalValue, readDecimal64 } from "../decimals.js";
-import { readEnum8 } from "../enums.js";
-import { readUInt8 } from "../integers.js";
-import { formatUUID, formatUUIDTable, readUUID } from "../uuid.js";
+import { type Reader, advance } from "../readers/core.js";
+import { type DecimalValue, readDecimal64 } from "../readers/decimals.js";
+import { readInt8, readUInt8 } from "../readers/integers.js";
+import { formatUUID, formatUUIDTable, readUUID } from "../readers/uuid.js";
 
 /**
  * Example: an orders table — UUID, Decimal, and Enum (awkward-as-JSON types).
@@ -15,9 +14,11 @@ import { formatUUID, formatUUIDTable, readUUID } from "../uuid.js";
  *
  * Shows the parse/format split and faithful values: `uid` is read as raw bytes
  * then formatted with `formatUUID`; `price` stays the exact `[unscaled, scale]`
- * pair (`[1234n, 2]` == 12.34), not a lossy float; `status` decodes to the
- * underlying `Int8` value (1/2/3), the name<->value map being type metadata, not
- * on the wire. The declared scale `2` is baked into `readDecimal64(2)`.
+ * pair (`[1234n, 2]` == 12.34), not a lossy float; `status` is read as the raw
+ * underlying `Int8` (1/2/3) with `readInt8` — a hand-written reader that bakes
+ * in the schema can skip name resolution, whereas the generic `readEnum8(map)`
+ * (used by the dynamic/header path) resolves the value to its name. The declared
+ * scale `2` is baked into `readDecimal64(2)`.
  */
 export type OrderRow = {
   id: number;
@@ -30,7 +31,7 @@ export const readOrderRow: Reader<OrderRow> = (s) => ({
   id: readUInt8(s),
   uid: formatUUID(readUUID(s)),
   price: readDecimal64(2)(s),
-  status: readEnum8(s),
+  status: readInt8(s),
 });
 
 /**

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

@@ -1,8 +1,8 @@
-import { readArray, readNullable } from "../composite.js";
-import { type Reader, advance } from "../core.js";
-import { readInt32, readUInt32 } from "../integers.js";
-import { readString } from "../strings.js";
-import { readUVarint } from "../varint.js";
+import { readArray, readNullable } from "../readers/composite.js";
+import { type Reader, advance } from "../readers/core.js";
+import { readInt32, readUInt32 } from "../readers/integers.js";
+import { readString } from "../readers/strings.js";
+import { readUVarint } from "../readers/varint.js";
 
 /**
  * Example: a profiles table — Array and Nullable wrappers.

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

@@ -3,12 +3,12 @@ import {
   readMap,
   readNullable,
   readTupleNamed,
-} from "../composite.js";
-import { type Reader, advance } from "../core.js";
-import { readFloat64 } from "../floats.js";
-import { readUInt16, readUInt32 } from "../integers.js";
-import { readString } from "../strings.js";
-import { readUVarint } from "../varint.js";
+} from "../readers/composite.js";
+import { type Reader, advance } from "../readers/core.js";
+import { readFloat64 } from "../readers/floats.js";
+import { readUInt16, readUInt32 } from "../readers/integers.js";
+import { readString } from "../readers/strings.js";
+import { readUVarint } from "../readers/varint.js";
 
 /**
  * Example: a telemetry table — composite readers that nest.

package/skills/{clickhouse-js-node-rowbinary-parser/src → clickhouse-js-node-rowbinary/src/readers}/compile.ts

@@ -115,10 +115,12 @@ export class RowBinaryTypeError extends Error {
  */
 export function astToReader(node: Node): Reader<unknown> {
   switch (node.kind) {
-    case NodeKind.EnumDataType:
-      // Explicit-value enum: the wire value is the underlying int; the
-      // name<->value map is metadata we don't need to decode.
-      return node.name === "Enum16" ? readEnum16 : readEnum8;
+    case NodeKind.EnumDataType: {
+      // Explicit-value enum: the wire value is the underlying int, which we
+      // resolve to its NAME via the `'name' = value` pairs the type carries.
+      const map = enumNameMap(node);
+      return node.name === "Enum16" ? readEnum16(map) : readEnum8(map);
+    }
     case NodeKind.TupleDataType:
       return tupleReader(node);
     case NodeKind.DataType:
@@ -185,12 +187,13 @@ function dataTypeReader(node: Node): Reader<unknown> {
       return readDecimal128(literalInt(requireArg(node, 0)));
     case "Decimal256":
       return readDecimal256(literalInt(requireArg(node, 0)));
-    // Auto-assigned enums arrive as a plain DataType (no explicit values); the
-    // wire value is still the underlying int.
+    // A bare `Enum8`/`Enum16` (no explicit values — only reachable from a
+    // hand-written type string) has no names to resolve, so the reader falls
+    // back to the stringified underlying int.
     case "Enum8":
-      return readEnum8;
+      return readEnum8(new Map());
     case "Enum16":
-      return readEnum16;
+      return readEnum16(new Map());
 
     default: {
       // Interval<Unit> (IntervalSecond, IntervalDay, …): all decode to the
@@ -247,6 +250,13 @@ function nestedReader(node: Node): Reader<unknown> {
   return readNested(fields);
 }
 
+/** Builds an enum's underlying-int -> name lookup from its `'name' = value` pairs. */
+function enumNameMap(node: Node): ReadonlyMap<number, string> {
+  const map = new Map<number, string>();
+  for (const ev of node.values) map.set(Number(ev.value), ev.name);
+  return map;
+}
+
 /** Folds `Decimal(P, S)` to the right width by precision P; scale S drives decoding. */
 function decimalReader(node: Node): Reader<unknown> {
   const precision = literalInt(requireArg(node, 0));

package/skills/{clickhouse-js-node-rowbinary-parser/src → clickhouse-js-node-rowbinary/src/readers}/dynamic.ts

@@ -15,6 +15,7 @@ import {
   readUInt256,
 } from "./integers.js";
 import { readBool } from "./bool.js";
+import { readEnum8, readEnum16 } from "./enums.js";
 import { readFloat32, readFloat64 } from "./floats.js";
 import { readString, readFixedString } from "./strings.js";
 import { readUUID } from "./uuid.js";
@@ -143,23 +144,26 @@ export function readDynamicType(state: Cursor): Reader<unknown> {
       return readString;
     case 0x16:
       return readFixedString(readUVarint(state));
-    // Enum8 / Enum16: a count then (name String, value Int8/Int16) pairs. The
-    // name<->value map is metadata; the stored value is the underlying int.
+    // Enum8 / Enum16: a count then (name String, value Int8/Int16) pairs. We
+    // collect them into the name<->value map so the value resolves to its name,
+    // matching the textual-type path in compile.ts.
     case 0x17: {
       const n = readUVarint(state);
+      const map = new Map<number, string>();
       for (let i = 0; i < n; i++) {
-        readString(state);
-        readInt8(state);
+        const name = readString(state);
+        map.set(readInt8(state), name);
       }
-      return readInt8;
+      return readEnum8(map);
     }
     case 0x18: {
       const n = readUVarint(state);
+      const map = new Map<number, string>();
       for (let i = 0; i < n; i++) {
-        readString(state);
-        readInt16(state);
+        const name = readString(state);
+        map.set(readInt16(state), name);
       }
-      return readInt16;
+      return readEnum16(map);
     }
     // Decimals: header carries precision P then scale S (both varint). Only S
     // matters for decoding; P is consumed and dropped. Returns [unscaled, S].

package/skills/clickhouse-js-node-rowbinary/src/readers/enums.ts

@@ -0,0 +1,40 @@
+import { type Reader, advance } from "./core.js";
+
+/**
+ * Maps an enum's underlying integer to its name. Built from the type's
+ * `'name' = value` pairs (which live in the column type, not the wire) by the
+ * compile step / dynamic decoder and handed to the readers below.
+ */
+export type EnumNameMap = ReadonlyMap<number, string>;
+
+/**
+ * Read an `Enum8` and resolve it to its NAME — the ergonomic default, since the
+ * point of an enum is usually the label, not the raw `Int8`.
+ *
+ * This is a factory: the name<->value map is metadata carried by the type, not
+ * the bytes, so it is supplied once (per column) and closed over. A value with
+ * no matching name falls back to its stringified integer rather than throwing,
+ * so a decode never blows up on an unexpected wire value.
+ *
+ * Need the raw underlying integer instead (e.g. a monomorphized hot path that
+ * has the schema baked in)? Read it directly with {@link readInt8} — that is the
+ * fast, allocation-free path the enum's name resolution sits on top of.
+ */
+export function readEnum8(valueToName: EnumNameMap): Reader<string> {
+  return (state) =>
+    resolveName(valueToName, state.view.getInt8(advance(state, 1)));
+}
+
+/**
+ * Read an `Enum16` (2-byte underlying `Int16`) and resolve it to its NAME. See
+ * {@link readEnum8}; use {@link readInt16} for the raw underlying integer.
+ */
+export function readEnum16(valueToName: EnumNameMap): Reader<string> {
+  return (state) =>
+    resolveName(valueToName, state.view.getInt16(advance(state, 2), true));
+}
+
+function resolveName(valueToName: EnumNameMap, value: number): string {
+  const name = valueToName.get(value);
+  return name !== undefined ? name : String(value);
+}

package/skills/clickhouse-js-node-rowbinary/src/writers/aggregateFunction.ts

@@ -0,0 +1,18 @@
+import { type Writer } from "./core.js";
+
+/**
+ * Inverse of `readAggregateFunction`: an `AggregateFunction(func, T…)` column is
+ * OPAQUE, unframed aggregation state with a layout specific to `func` and the
+ * server version, so it cannot be produced generically from a value. Build the
+ * state server-side (the `-State` combinators) rather than encoding it on the
+ * client.
+ *
+ * This writer throws to stop a generic encoder from emitting a misaligned row.
+ */
+export const writeAggregateFunction: Writer<never> = () => {
+  throw new Error(
+    "RowBinary: AggregateFunction is opaque, unframed aggregation state with no " +
+      "length prefix — not generically encodable. Produce the state server-side " +
+      "(the -State combinators) instead of encoding it on the client.",
+  );
+};

package/skills/clickhouse-js-node-rowbinary/src/writers/bool.ts

@@ -0,0 +1,10 @@
+import { Sink } from "./core.js";
+import { writeUInt8 } from "./integers.js";
+
+/**
+ * Write a `Bool`: 1 byte, stored as `UInt8` (`false` -> 0, `true` -> 1). Mirror
+ * of `readBool`.
+ */
+export function writeBool(sink: Sink, value: boolean): void {
+  writeUInt8(sink, value ? 1 : 0);
+}