Add chdb/hypequery — run hypequery on embedded chDB

[ShawnChen-Sirius]

Lets @hypequery/clickhouse run its type-safe
query builder against in-process chDB instead of a remote ClickHouse server, by passing a
chDB-backed adapter to hypequery's existing createQueryBuilder({ adapter }) hook.

Discussed in hypequery/hypequery#237 (maintainer is on board).

import { createQueryBuilder } from '@hypequery/clickhouse'
import { Session } from 'chdb'
import { chdbAdapter } from 'chdb/hypequery'

const db = createQueryBuilder({ adapter: chdbAdapter({ session: new Session('./db') }) })

How

hypequery renders final SQL itself (?-positional params), so the adapter just runs the
SQL on chDB and returns JSONEachRow rows. It implements the DatabaseAdapter contract:

• query — rows
• stream — chDB's chunked cursor wrapped as a ReadableStream<T[]>
• render — mirrors hypequery's substituteParameters/escapeValue so generated SQL
  matches the built-in HTTP adapter exactly

No @clickhouse/client and no ClickHouse server involved. The adapter is duck-typed and
imports nothing from @hypequery/clickhouse at runtime, so it stays an optional, types-only
peer dependency. Shipped as the chdb/hypequery subpath.

It is self-contained against the currently published @hypequery/clickhouse (it does not
depend on any hypequery change). A small follow-up can switch the copied render helpers to
imports once hypequery exports them (hypequery/hypequery PR for that is separate).

Tests

A real @hypequery/clickhouse builder chain runs against embedded chDB: filter + aggregate

• group + order, value escaping, rawQuery passthrough, and streaming.

🤖 Generated with Claude Code

Note

Add chdbAdapter to integrate hypequery with embedded chDB

• Adds a new chdb/hypequery subpath export with an ESM entry (hypequery.mjs) and TypeScript declarations (hypequery.d.mts).
• chdbAdapter(opts?) returns a hypequery-compatible DatabaseAdapter with query(), stream(), and render() methods backed by chDB's queryAsync and queryStream.
• Includes substituteParameters and escapeValue helpers that inject typed JS values as SQL-safe literals and throw on placeholder/param count mismatch.
• stream() wraps chDB's async iterator into a Web ReadableStream<T[]> but requires a bound session — throws at call time if none is provided.
• Declares @hypequery/clickhouse >=2 as an optional peer dependency.

^{Macroscope summarized ebb0eda.}

[ShawnChen-Sirius]

@chibugai, review it

[Copilot]

Pull request overview

Adds a new optional integration subpath (chdb/hypequery) so @hypequery/clickhouse can execute its rendered SQL against embedded chDB (no ClickHouse server / no @clickhouse/client required at runtime).

Changes:

• Adds integrations/hypequery.mjs implementing a hypequery-shaped DatabaseAdapter (query/stream/render) backed by chDB.
• Adds integrations/hypequery.d.mts types and exposes the ./hypequery subpath export.
• Adds vitest coverage exercising builder execution, escaping behavior, rawQuery passthrough, and streaming.

Reviewed changes

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

Show a summary per file

File	Description
test/v3/integrations/hypequery.test.ts	Adds integration tests validating hypequery builder + streaming against embedded chDB.
package.json	Exposes chdb/hypequery, includes integration files in published package, and adds optional peer/dev dependency for hypequery.
package-lock.json	Lockfile updates to include new dev dependency chain (notably @hypequery/clickhouse and its transitive deps).
integrations/hypequery.mjs	Implements the chDB-backed hypequery adapter, including SQL placeholder substitution and stream wrapping.
integrations/hypequery.d.mts	Provides a structural DatabaseAdapter type surface for consumers importing chdb/hypequery.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.