Add optional in-band exception stream transformer to Node ResultSet

[Copilot]

Summary

Adopts a stream transformer that parses ClickHouse's in-band HTTP exception block (the format-agnostic __exception__ trailer appended after a 200 status, 25.11+). It is wired into the Node ResultSet as an opt-in transformer over the internal stream, off by default. The compression handling from the original draft was dropped since the client already decodes Content-Encoding upstream.

• New transformer (packages/client-node/src/utils/exception_stream.ts): ClickHouseExceptionStream passes result bytes through while retaining a 16 KiB sliding tail, then parses the block backwards at end-of-stream. On detection it errors with ClickHouseException (or, with throwOnException: false, ends cleanly and exposes it via getException() / clickhouse-exception event). Also exports ClickHouseStreamError and DEFAULT_MAX_BLOCK_SIZE.
• Compression removed: dropped zlib, decompressorFor, clickHouseResponseParser, and the compose/header-bag plumbing; the transformer now expects an already-decompressed body.
• ResultSet wiring (result_set.ts): new exceptionStream?: boolean option. When enabled and the X-ClickHouse-Exception-Tag header is present, the transformer is inserted between the consumed stream and the row parser; otherwise the pipeline is unchanged.

const rs = ResultSet.instance({
  stream, format, query_id, log_error, response_headers,
  exceptionStream: true, // opt-in; no-op without the exception-tag header
})

This is an initial adoption; tighter integration (public exports, reconciliation with the existing extractErrorAtTheEndOfChunk path, guaranteed delivery of pre-exception rows) is left for a follow-up.

Checklist

• Unit and integration tests covering the common scenarios were added
• A human-readable description of the changes was provided to include in CHANGELOG
• For significant changes, documentation in https://github.com/ClickHouse/clickhouse-docs was updated with further explanations or tutorials

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[codecov]

Codecov Report

❌ Patch coverage is 75.70093% with 26 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
packages/client-node/src/utils/exception_stream.ts	74.00%	10 Missing and 16 partials ⚠️

📢 Thoughts on this report? Let us know!

[Copilot]

Pull request overview

Adds an opt-in Node-side Transform stream to detect ClickHouse’s in-band HTTP exception trailer (__exception__ block appended after a 200 response in 25.11+), and wires it into ResultSet.stream() behind a new exceptionStream?: boolean option (only activated when the x-clickhouse-exception-tag header is present).

Changes:

• Introduces ClickHouseExceptionStream (plus related error types) that forwards bytes while retaining a bounded tail and parsing the exception trailer at end-of-stream.
• Adds exceptionStream?: boolean to Node ResultSet and conditionally inserts the transformer into the internal streaming pipeline.
• Adds unit tests covering pass-through, detection across chunk boundaries, truncated blocks, and ResultSet integration behavior.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 4 comments.

File	Description
packages/client-node/src/utils/index.ts	Re-exports the new exception-stream utility from the utils barrel.
packages/client-node/src/utils/exception_stream.ts	Implements the ClickHouseExceptionStream Transform and exception parsing logic.
packages/client-node/src/result_set.ts	Adds an exceptionStream option and conditionally wires the transformer into ResultSet.stream().
packages/client-node/tests/unit/node_exception_stream.test.ts	Adds unit/integration-style tests for the transformer and ResultSet wiring.