@clickhouse/client 1.23.0-head.287977a.1 → 1.23.0-head.71b2e8a.1

package/README.md

@@ -1,78 +1,39 @@
-<p align="center">
-<img src=".static/logo.svg" width="200px" align="center">
-<h1 align="center">ClickHouse JS client</h1>
-</p>
-<br/>
-<p align="center">
-<a href="https://www.npmjs.com/package/@clickhouse/client">
-<img alt="NPM Version" src="https://img.shields.io/npm/v/%40clickhouse%2Fclient?color=%233178C6&logo=npm">
-</a>
+# @clickhouse/client
 
-<a href="https://www.npmjs.com/package/@clickhouse/client">
-<img alt="NPM Downloads" src="https://img.shields.io/npm/dw/%40clickhouse%2Fclient?color=%233178C6&logo=npm">
-</a>
+Official Node.js client for [ClickHouse](https://clickhouse.com/), written
+purely in TypeScript and thoroughly tested against actual ClickHouse versions.
 
-<a href="https://github.com/ClickHouse/clickhouse-js/actions/workflows/tests-node.yml">
-<img src="https://github.com/ClickHouse/clickhouse-js/actions/workflows/tests-node.yml/badge.svg?branch=main">
-</a>
+It is built on top of the Node.js [HTTP](https://nodejs.org/api/http.html) and
+[Stream](https://nodejs.org/api/stream.html) APIs and supports streaming for
+both selects and inserts. The client has zero external dependencies and is
+optimized for maximum performance.
 
-<a href="https://github.com/ClickHouse/clickhouse-js/actions/workflows/tests-web.yml">
-<img src="https://github.com/ClickHouse/clickhouse-js/actions/workflows/tests-web.yml/badge.svg?branch=main">
-</a>
-
-<a href="https://codecov.io/gh/ClickHouse/clickhouse-js">
-<img src="https://codecov.io/gh/ClickHouse/clickhouse-js/graph/badge.svg?token=B832WB00WJ">
-</a>
-
-<img src="https://api.scorecard.dev/projects/github.com/ClickHouse/clickhouse-js/badge">
-</p>
-
-## About
-
-Official JS client for [ClickHouse](https://clickhouse.com/), written purely in TypeScript, thoroughly tested with actual ClickHouse versions.
-
-The client has zero external dependencies and is optimized for maximum performance.
-
-The repository consists of four packages:
-
-- `@clickhouse/client` - a version of the client designed for Node.js platform only. It is built on top of [HTTP](https://nodejs.org/api/http.html)
-  and [Stream](https://nodejs.org/api/stream.html) APIs; supports streaming for both selects and inserts.
-- `@clickhouse/client-web` - a version of the client built on top of [Fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API)
-  and [Web Streams](https://developer.mozilla.org/en-US/docs/Web/API/Streams_API) APIs; supports streaming for selects.
-  Compatible with Chrome/Firefox browsers and Cloudflare workers.
-- `@clickhouse/client-common` - shared common types and the base framework for building a custom client implementation.
-- `@clickhouse/rowbinary` - a library for reading (and soon writing) ClickHouse RowBinary format.
+> Looking for a browser / edge runtime (Cloudflare Workers, etc.) instead? Use
+> [`@clickhouse/client-web`](https://www.npmjs.com/package/@clickhouse/client-web).
 
 ## Installation
 
-Node.js client:
-
 ```sh
 npm i @clickhouse/client
 ```
 
-Web client (browsers, Cloudflare workers):
-
-```sh
-npm i @clickhouse/client-web
-```
-
 ## Environment requirements
 
-### Node.js
+Node.js must be available in the environment to run the client. The client is
+compatible with all the [maintained](https://github.com/nodejs/release#readme)
+Node.js releases.
 
-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? |
+| --------------- | ---------- |
+| 26.x            | ✔          |
+| 24.x            | ✔          |
+| 22.x            | ✔          |
+| 20.x            | ✔          |
 
-| Node.js version | Supported?  |
-| --------------- | ----------- |
-| 24.x            | ✔           |
-| 22.x            | ✔           |
-| 20.x            | ✔           |
-| 18.x            | Best effort |
-
-### TypeScript
-
-If using TypeScript, version [4.5](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-5.html) or above is required to enable [inline import and export syntax](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-5.html#type-modifiers-on-import-names).
+If using TypeScript, version
+[4.5](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-5.html)
+or above is required to enable
+[inline import and export syntax](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-5.html#type-modifiers-on-import-names).
 
 ## Compatibility with ClickHouse
 
@@ -80,12 +41,13 @@ If using TypeScript, version [4.5](https://www.typescriptlang.org/docs/handbook/
 | -------------- | ---------- |
 | 1.12.0+        | 24.8+      |
 
-The client may work with older versions too; however, this is best-effort support and is not guaranteed.
+The client may work with older versions too; however, this is best-effort
+support and is not guaranteed.
 
 ## Quick start
 
 ```ts
-import { createClient } from "@clickhouse/client"; // or '@clickhouse/client-web'
+import { createClient } from "@clickhouse/client";
 
 const client = createClient({
   url: process.env.CLICKHOUSE_URL ?? "http://localhost:8123",
@@ -104,41 +66,24 @@ console.log(tables);
 await client.close();
 ```
 
-See more examples in the [examples directory](./examples).
+See more examples in the
+[examples directory](https://github.com/ClickHouse/clickhouse-js/tree/main/examples).
 
 ## Documentation
 
-See the [ClickHouse website](https://clickhouse.com/docs/integrations/javascript) for the full documentation.
-
-## AI Agent Skills
-
-This repository contains agent skills for working with the client:
-
-- `clickhouse-js-node-troubleshooting` — troubleshooting playbook for the Node.js client.
-
-Install via CLI:
+See the [ClickHouse website](https://clickhouse.com/docs/integrations/javascript)
+for the full documentation.
 
-```sh
-# per project
-npx skills add ClickHouse/clickhouse-js
-# globally
-npx skills add ClickHouse/clickhouse-js -g
-```
-
-Or ask your agent to install it for you:
+## Changelog
 
-> install agent skills from ClickHouse/clickhouse-js
-
-## Usage examples
-
-We have a wide range of [examples](./examples), aiming to cover various scenarios of client usage. The overview is available in the [examples README](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/README.md#overview).
+See [`CHANGELOG.md`](https://github.com/ClickHouse/clickhouse-js/blob/main/packages/client-node/CHANGELOG.md).
 
 ## Contact us
 
-If you have any questions or need help, feel free to reach out to us in the [Community Slack](https://clickhouse.com/slack) (`#clickhouse-js` channel) or via [GitHub issues](https://github.com/ClickHouse/clickhouse-js/issues).
-
-## Contributing
+If you have any questions or need help, feel free to reach out to us in the
+[Community Slack](https://clickhouse.com/slack) (`#clickhouse-js` channel) or
+via [GitHub issues](https://github.com/ClickHouse/clickhouse-js/issues).
 
-Check out our [contributing guide](./CONTRIBUTING.md).
+## License
 
-If you'd like to build a client for an alternative runtime (such as Bun or Cloudflare Workers) or an alternative protocol (such as the native ClickHouse protocol or gRPC over a proxy), see [Building specialized clients for alternative runtimes and protocols](./ALTERNATIVE_CLIENTS.md).
+[Apache 2.0](https://github.com/ClickHouse/clickhouse-js/blob/main/LICENSE)

package/dist/index.d.ts

@@ -13,7 +13,7 @@ export { type BaseClickHouseClientConfigOptions, type BaseQueryParams, type Quer
  * applied to them in `./common/index` are NOT propagated to consumers of this package.
  * Importing these values from `@clickhouse/client` is the recommended, non-deprecated path.
  */
-import { ClickHouseError as ClickHouseError_, parseError as parseError_, ClickHouseLogLevel as ClickHouseLogLevel_, SettingsMap as SettingsMap_, parseColumnType as parseColumnType_, isProgressRow as isProgressRow_, isRow as isRow_, isException as isException_, TupleParam as TupleParam_ } from "./common/index";
+import { ClickHouseError as ClickHouseError_, parseError as parseError_, ClickHouseLogLevel as ClickHouseLogLevel_, SettingsMap as SettingsMap_, parseColumnType as parseColumnType_, isProgressRow as isProgressRow_, isRow as isRow_, isException as isException_, TupleParam as TupleParam_, extractErrorAtTheEndOfChunk as extractErrorAtTheEndOfChunk_ } from "./common/index";
 export declare const ClickHouseError: typeof ClickHouseError_;
 export type ClickHouseError = ClickHouseError_;
 export declare const parseError: typeof parseError_;
@@ -70,3 +70,5 @@ export declare const ClickHouseSpanKind: {
     readonly CONSUMER: 4;
 };
 export declare const defaultJSONHandling: import("./common/index").JSONHandling;
+export declare const EXCEPTION_TAG_HEADER_NAME = "x-clickhouse-exception-tag";
+export declare const extractErrorAtTheEndOfChunk: typeof extractErrorAtTheEndOfChunk_;

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.defaultJSONHandling = exports.ClickHouseSpanKind = exports.ClickHouseSpanStatusCode = exports.ClickHouseSpanNames = exports.TupleParam = exports.isException = exports.isRow = exports.isProgressRow = exports.SimpleColumnTypes = exports.parseColumnType = exports.RecordsJSONFormats = exports.SingleDocumentJSONFormats = exports.StreamableJSONFormats = exports.StreamableFormats = exports.SupportedRawFormats = exports.SupportedJSONFormats = exports.SettingsMap = exports.ClickHouseLogLevel = exports.parseError = exports.ClickHouseError = exports.drainStream = exports.ResultSet = exports.createClient = exports.ClickHouseClient = void 0;
+exports.extractErrorAtTheEndOfChunk = exports.EXCEPTION_TAG_HEADER_NAME = exports.defaultJSONHandling = exports.ClickHouseSpanKind = exports.ClickHouseSpanStatusCode = exports.ClickHouseSpanNames = exports.TupleParam = exports.isException = exports.isRow = exports.isProgressRow = exports.SimpleColumnTypes = exports.parseColumnType = exports.RecordsJSONFormats = exports.SingleDocumentJSONFormats = exports.StreamableJSONFormats = exports.StreamableFormats = exports.SupportedRawFormats = exports.SupportedJSONFormats = exports.SettingsMap = exports.ClickHouseLogLevel = exports.parseError = exports.ClickHouseError = exports.drainStream = exports.ResultSet = exports.createClient = exports.ClickHouseClient = void 0;
 var client_1 = require("./client");
 Object.defineProperty(exports, "ClickHouseClient", { enumerable: true, get: function () { return client_1.NodeClickHouseClient; } });
 var client_2 = require("./client");
@@ -40,4 +40,6 @@ exports.ClickHouseSpanNames = index_1.ClickHouseSpanNames;
 exports.ClickHouseSpanStatusCode = index_1.ClickHouseSpanStatusCode;
 exports.ClickHouseSpanKind = index_1.ClickHouseSpanKind;
 exports.defaultJSONHandling = index_1.defaultJSONHandling;
+exports.EXCEPTION_TAG_HEADER_NAME = index_1.EXCEPTION_TAG_HEADER_NAME;
+exports.extractErrorAtTheEndOfChunk = index_1.extractErrorAtTheEndOfChunk;
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,mCAGkB;AAFhB,0GAAA,oBAAoB,OAAoB;AAG1C,mCAAwC;AAA/B,sGAAA,YAAY,OAAA;AAErB,2CAA8D;AAArD,uGAAA,SAAS,OAAA;AAClB,8CAAkD;AAAzC,qGAAA,WAAW,OAAA;AA2DpB;;;;;;;GAOG;AACH,0CAqBwB;AAEX,QAAA,eAAe,GAAG,uBAAgB,CAAC;AAEnC,QAAA,UAAU,GAAG,kBAAW,CAAC;AACzB,QAAA,kBAAkB,GAAG,0BAAmB,CAAC;AAEzC,QAAA,WAAW,GAAG,mBAAY,CAAC;AAE3B,QAAA,oBAAoB,GAAG,4BAAqB,CAAC;AAC7C,QAAA,mBAAmB,GAAG,2BAAoB,CAAC;AAC3C,QAAA,iBAAiB,GAAG,yBAAkB,CAAC;AACvC,QAAA,qBAAqB,GAAG,6BAAsB,CAAC;AAC/C,QAAA,yBAAyB,GAAG,iCAA0B,CAAC;AACvD,QAAA,kBAAkB,GAAG,0BAAmB,CAAC;AACtD,4JAA4J;AAC/I,QAAA,eAAe,GAAG,uBAAgB,CAAC;AAChD,4JAA4J;AAC/I,QAAA,iBAAiB,GAAG,yBAAkB,CAAC;AACvC,QAAA,aAAa,GAAG,qBAAc,CAAC;AAC/B,QAAA,KAAK,GAAG,aAAM,CAAC;AACf,QAAA,WAAW,GAAG,mBAAY,CAAC;AAC3B,QAAA,UAAU,GAAG,kBAAW,CAAC;AAEzB,QAAA,mBAAmB,GAAG,2BAAoB,CAAC;AAC3C,QAAA,wBAAwB,GAAG,gCAAyB,CAAC;AACrD,QAAA,kBAAkB,GAAG,0BAAmB,CAAC;AACzC,QAAA,mBAAmB,GAAG,2BAAoB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,mCAGkB;AAFhB,0GAAA,oBAAoB,OAAoB;AAG1C,mCAAwC;AAA/B,sGAAA,YAAY,OAAA;AAErB,2CAA8D;AAArD,uGAAA,SAAS,OAAA;AAClB,8CAAkD;AAAzC,qGAAA,WAAW,OAAA;AA2DpB;;;;;;;GAOG;AACH,0CAuBwB;AAEX,QAAA,eAAe,GAAG,uBAAgB,CAAC;AAEnC,QAAA,UAAU,GAAG,kBAAW,CAAC;AACzB,QAAA,kBAAkB,GAAG,0BAAmB,CAAC;AAEzC,QAAA,WAAW,GAAG,mBAAY,CAAC;AAE3B,QAAA,oBAAoB,GAAG,4BAAqB,CAAC;AAC7C,QAAA,mBAAmB,GAAG,2BAAoB,CAAC;AAC3C,QAAA,iBAAiB,GAAG,yBAAkB,CAAC;AACvC,QAAA,qBAAqB,GAAG,6BAAsB,CAAC;AAC/C,QAAA,yBAAyB,GAAG,iCAA0B,CAAC;AACvD,QAAA,kBAAkB,GAAG,0BAAmB,CAAC;AACtD,4JAA4J;AAC/I,QAAA,eAAe,GAAG,uBAAgB,CAAC;AAChD,4JAA4J;AAC/I,QAAA,iBAAiB,GAAG,yBAAkB,CAAC;AACvC,QAAA,aAAa,GAAG,qBAAc,CAAC;AAC/B,QAAA,KAAK,GAAG,aAAM,CAAC;AACf,QAAA,WAAW,GAAG,mBAAY,CAAC;AAC3B,QAAA,UAAU,GAAG,kBAAW,CAAC;AAEzB,QAAA,mBAAmB,GAAG,2BAAoB,CAAC;AAC3C,QAAA,wBAAwB,GAAG,gCAAyB,CAAC;AACrD,QAAA,kBAAkB,GAAG,0BAAmB,CAAC;AACzC,QAAA,mBAAmB,GAAG,2BAAoB,CAAC;AAC3C,QAAA,yBAAyB,GAAG,iCAA0B,CAAC;AACvD,QAAA,2BAA2B,GAAG,mCAA4B,CAAC"}

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-declare const _default: "1.23.0-head.287977a.1";
+declare const _default: "1.23.0-head.71b2e8a.1";
 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.287977a.1";
+exports.default = "1.23.0-head.71b2e8a.1";
 //# sourceMappingURL=version.js.map

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.287977a.1",
+  "version": "1.23.0-head.71b2e8a.1",
   "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,18 +35,28 @@
         "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 ../../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",
-    "build": "rm -rf dist; tsc"
+    "build": "rm -rf dist; tsc",
+    "test:unit": "CLICKHOUSE_TEST_SKIP_INIT=1 TEST_MODE=unit vitest",
+    "test:unit:bun": "CLICKHOUSE_TEST_SKIP_INIT=1 TEST_MODE=unit bun --bun vitest",
+    "test:integration": "TEST_MODE=integration vitest",
+    "test:integration:tls": "TEST_MODE=tls vitest",
+    "test:integration:dist": "npm --prefix ../.. run build && TEST_TARGET=dist TEST_MODE=integration vitest",
+    "test:integration:local_cluster": "CLICKHOUSE_TEST_ENVIRONMENT=local_cluster TEST_MODE=integration vitest",
+    "test:integration:cloud": "CLICKHOUSE_TEST_ENVIRONMENT=cloud TEST_MODE=integration vitest",
+    "test:oss-dependents": "TEST_MODE=oss-dependents vitest",
+    "test:all": "TEST_MODE=all vitest",
+    "test:coverage": "VITEST_COVERAGE=true TEST_MODE=all vitest"
   },
   "dependencies": {},
   "devDependencies": {

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)