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

package/README.md

@@ -63,12 +63,12 @@ npm i @clickhouse/client-web
 
 Node.js must be available in the environment to run the Node.js client. The client is compatible with all the [maintained](https://github.com/nodejs/release#readme) Node.js releases.
 
-| Node.js version | Supported?  |
-| --------------- | ----------- |
-| 24.x            | ✔           |
-| 22.x            | ✔           |
-| 20.x            | ✔           |
-| 18.x            | Best effort |
+| Node.js version | Supported? |
+| --------------- | ---------- |
+| 26.x            | ✔          |
+| 24.x            | ✔          |
+| 22.x            | ✔          |
+| 20.x            | ✔          |
 
 ### TypeScript
 
@@ -110,6 +110,18 @@ See more examples in the [examples directory](./examples).
 
 See the [ClickHouse website](https://clickhouse.com/docs/integrations/javascript) for the full documentation.
 
+## Changelog
+
+Each package keeps its own changelog:
+
+- `@clickhouse/client` — [`packages/client-node/CHANGELOG.md`](./packages/client-node/CHANGELOG.md)
+- `@clickhouse/client-web` — [`packages/client-web/CHANGELOG.md`](./packages/client-web/CHANGELOG.md)
+- `@clickhouse/client-common` (deprecated) — [`packages/client-common/CHANGELOG.md`](./packages/client-common/CHANGELOG.md)
+- `@clickhouse/datatype-parser` — [`packages/datatype-parser/CHANGELOG.md`](./packages/datatype-parser/CHANGELOG.md)
+- `@clickhouse/rowbinary` — [`skills/clickhouse-js-node-rowbinary/CHANGELOG.md`](./skills/clickhouse-js-node-rowbinary/CHANGELOG.md)
+
+History through `@clickhouse/client` 1.23.0 lives in the now-frozen repository-wide [`CHANGELOG.md`](./CHANGELOG.md).
+
 ## AI Agent Skills
 
 This repository contains agent skills for working with the client:

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-declare const _default: "1.23.0-head.dbc2960.1";
+declare const _default: "1.23.0";
 export default _default;

package/dist/version.js

@@ -1,4 +1,4 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.default = "1.23.0-head.dbc2960.1";
+exports.default = "1.23.0";
 //# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -1 +1 @@
-{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":";;AAAA,kBAAe,uBAAuB,CAAC"}
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":";;AAAA,kBAAe,QAAQ,CAAC"}

package/package.json

@@ -2,7 +2,7 @@
   "name": "@clickhouse/client",
   "description": "Official JS client for ClickHouse DB - Node.js implementation",
   "homepage": "https://clickhouse.com",
-  "version": "1.23.0-head.dbc2960.1",
+  "version": "1.23.0",
   "license": "Apache-2.0",
   "keywords": [
     "clickhouse",
@@ -15,13 +15,14 @@
   },
   "private": false,
   "engines": {
-    "node": ">=16"
+    "node": ">=20"
   },
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
     "dist",
-    "skills"
+    "skills",
+    "CHANGELOG.md"
   ],
   "agents": {
     "skills": [
@@ -34,14 +35,14 @@
         "path": "./skills/clickhouse-js-node-troubleshooting"
       },
       {
-        "name": "clickhouse-js-node-rowbinary-parser",
-        "path": "./skills/clickhouse-js-node-rowbinary-parser"
+        "name": "clickhouse-js-node-rowbinary",
+        "path": "./skills/clickhouse-js-node-rowbinary"
       }
     ]
   },
   "scripts": {
     "pack": "npm pack",
-    "prepack": "rm -rf skills && cp ../../README.md ../../LICENSE . && cp -r ../../skills . && RBP=skills/clickhouse-js-node-rowbinary-parser && rm -rf $RBP/tests $RBP/node_modules $RBP/dist $RBP/package.json $RBP/package-lock.json $RBP/tsconfig.json $RBP/tsconfig.build.json $RBP/vitest.config.ts $RBP/.gitignore $RBP/LICENSE $RBP/eval_result*.md",
+    "prepack": "rm -rf skills && cp ../../README.md ../../LICENSE . && cp -r ../../skills . && RBP=skills/clickhouse-js-node-rowbinary && rm -rf $RBP/tests $RBP/node_modules $RBP/dist $RBP/package.json $RBP/package-lock.json $RBP/tsconfig.json $RBP/tsconfig.build.json $RBP/vitest.config.ts $RBP/.gitignore $RBP/LICENSE $RBP/eval_result*.md",
     "typecheck": "tsc --noEmit",
     "lint": "eslint --max-warnings=0 .",
     "lint:fix": "eslint . --fix",

package/skills/AGENTS.md

@@ -0,0 +1,8 @@
+# Recommendations for AI agents — `skills/`
+
+Guidance for the shipped agent skills. See the [repo-root `AGENTS.md`](../AGENTS.md) for cross-cutting guidance. The `@clickhouse/rowbinary` skill has its own [`clickhouse-js-node-rowbinary/AGENTS.md`](clickhouse-js-node-rowbinary/AGENTS.md).
+
+- Each shipped skill must also be listed in the `agents.skills` array of
+  [`packages/client-node/package.json`](../packages/client-node/package.json) so downstream tooling can
+  discover it. The [`Skills E2E`](../.github/workflows/e2e-skills.yml) workflow
+  (`tests/e2e/skills/check.js`) asserts that the packaged tarball contains the declared skills.

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

@@ -0,0 +1,44 @@
+# Recommendations for AI agents — `@clickhouse/rowbinary`
+
+Guidance for the [`clickhouse-js-node-rowbinary`](.) package (the RowBinary codec library and agent skill). See the [repo-root `AGENTS.md`](../../AGENTS.md) for cross-cutting guidance.
+
+This package has a symmetric reader/writer codebase.
+
+## Tests
+
+The tests follow a few conventions worth preserving:
+
+- **Reader and writer tests are separate files.** Readers are tested in `tests/*.test.ts`; writers in
+  `tests/*.write.test.ts`. Keep the two independent: a writer test must **never** decode its bytes back
+  through a reader (and vice versa), so a bug on one side cannot mask a bug on the other. Writer tests
+  assert the encoded bytes against **live ClickHouse output** as the source of truth.
+- **Each case is an isolated `it()` with a fully-inline body.** Write the assertion out per case, e.g.
+  `expect(encode(writer, value)).toEqual(await query("SELECT … FORMAT RowBinary"))`. Do **not** hide the
+  assertion behind a thunk-factory helper (`it("name", expectFoo(...))`), and do **not** wrap the query
+  in a per-file helper — embed the literal SQL inline, including any `SETTINGS` clause, so the full
+  query is visible in the test. The only shared helpers are the generic `query()` (`tests/clickhouse.ts`,
+  runs SQL → bytes) and `encode()` (`tests/encode.ts`, value → bytes). Repeating SQL across cases is
+  fine; reviewability beats DRY here. See [`tests/Integers.write.test.ts`](tests/Integers.write.test.ts)
+  as the canonical example.
+
+## No defensive validation in readers/writers
+
+These are hot-path codecs. **Do not add runtime validation of input values** (`isFinite`,
+range/`NaN` checks, type guards, etc.) to the `readX`/`writeX` functions. The data at this level is
+expected to be correct, and an invalid value is a programming error — document the precondition in the
+JSDoc instead (see `writeUVarint` and the `writeDate*`/`writeDateTime` writers as the canonical
+examples). A `Math.round`-style transform that silently shifts a _valid_ value to the wrong encoding is
+a correctness bug and must be fixed; rejecting an _invalid_ value is not our job here.
+
+Two narrow exceptions where a check **is** warranted:
+
+1. **It keeps the protocol in sync.** A check belongs in only when skipping it would desync the wire
+   stream — e.g. `writeIPv6` requires exactly 16 bytes because a wrong length shifts every subsequent
+   field, and `parseIPv6` rejects malformed groups because it can't otherwise produce 16 well-defined
+   bytes. These guard the _framing_, not the user's data semantics.
+2. **The cost is genuinely zero or it can't reach the server.** Pure parse-time helpers (string →
+   bytes, before anything is on the wire) may validate, since there's no hot loop and no server to fall
+   back on.
+
+Otherwise, prefer letting the ClickHouse server reject bad bytes server-side over guarding client-side:
+it already validates, and duplicating that on the encode path costs throughput for no real safety.

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

@@ -0,0 +1,49 @@
+# Changelog — `@clickhouse/rowbinary`
+
+> This file tracks the standalone `@clickhouse/rowbinary` package (the RowBinary
+> parser library and agent skill). Entries relevant to it (through
+> `@clickhouse/client` 1.23.0) were previously recorded in the now-frozen
+> repository-wide [`CHANGELOG.md`](../../CHANGELOG.md).
+
+# 0.2.0
+
+## New features
+
+- Added the RowBinary **writer** — the encode mirror of the reader: type-specific `writeX(sink, value)` building blocks and combinators that compose with no per-element closures, exported from `@clickhouse/rowbinary/writer` (or the per-type modules). ([#911])
+
+  `writeRows(writeRow)` drives an `Iterable<T>` of rows into a plain `RowBinary` payload. Note its shape: it is a **streaming generator**, not a one-shot `Writer<readonly T[]>`. It writes into a fixed-size buffer (`bufferSize`, default 64 KiB), yields each batch of whole rows when the buffer fills — rewinding so a half-written row never leaks — and starts a fresh buffer for the rest, so a result larger than the buffer (or an unbounded row source) streams out chunk by chunk. An oversized row grows the buffer (doubling) rather than failing, and per-buffer fill is published on the `@clickhouse/rowbinary:writeRows.flush` `node:diagnostics_channel` for buffer-utilization metrics. ([#915])
+
+  ```ts
+  import {
+    writeRows,
+    writeTupleNamed,
+    writeUInt64,
+    writeString,
+  } from "@clickhouse/rowbinary/writer";
+
+  const writeRow = writeTupleNamed({ id: writeUInt64, name: writeString });
+  for (const chunk of writeRows(writeRow)(rows, 64 * 1024)) send(chunk);
+  ```
+
+  Writer edge-case hardening: `writeDate`/`writeDate32`/`writeDateTime` floor to the calendar day / whole second instead of rounding (so a non-midnight `Date` or sub-second `DateTime` no longer rounds up); `parseIPv6` rejects malformed hex groups instead of silently encoding `0`; and `writeGeometry` validates the discriminant before writing its byte, so an out-of-range value can't leave a partial payload. ([#916])
+
+[#911]: https://github.com/ClickHouse/clickhouse-js/pull/911
+[#915]: https://github.com/ClickHouse/clickhouse-js/pull/915
+[#916]: https://github.com/ClickHouse/clickhouse-js/pull/916
+
+# 0.1.2
+
+## Improvements
+
+- Bumped the bundled `@clickhouse/datatype-parser` dependency to `0.1.2`. ([#895])
+- Patch release. ([#903])
+
+# 0.1.1
+
+## New features
+
+- Initial release of `@clickhouse/rowbinary`: a RowBinary reader library (and the companion agent skill) shipping type-specific, monomorphizable building blocks for decoding `RowBinary` / `RowBinaryWithNames` / `RowBinaryWithNamesAndTypes` streams (full-buffer and chunked), plus a skill that guides an agent to generate bespoke high-performance parsers from a query's column types. The same library is also bundled into `@clickhouse/client` (registered in `agents.skills`). Requires Node.js `>=20`. A matching RowBinary writer is planned. ([#864])
+
+[#864]: https://github.com/ClickHouse/clickhouse-js/pull/864
+[#895]: https://github.com/ClickHouse/clickhouse-js/pull/895
+[#903]: https://github.com/ClickHouse/clickhouse-js/pull/903

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
@@ -208,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)