Make @hyperdx/common-utils forward-compatible with @clickhouse/client 1.23

[Copilot]

Summary

Discovered in:

• An E2E test for @clickhouse/client package beta version #1553 by @peter-leonov-ch

In @clickhouse/client* 1.23, @clickhouse/client-common is deprecated: @clickhouse/client (Node) and @clickhouse/client-web (Web) no longer depend on it — each now bundles and re-exports its own copy of the shared types. This repo imported types from client-common but got its runtime from the platform packages, so under 1.23 the two same-named ClickHouseSettings aliases become distinct nominal types (their index signature references a private-membered SettingsMap class), breaking the common-utils declaration build and cascading into every downstream job.

This change repoints imports so each file's ClickHouse types come from the same platform package as its runtime, making the repo compile against both the current pin and 1.23. No @clickhouse/client* version bumps — the actual upgrade can land later with no further code changes.

• Type imports → platform package
  • clickhouse/browser.ts (web runtime) → @clickhouse/client-web
  • clickhouse/node.ts (node runtime) → @clickhouse/client
  • __tests__/clickhouse.test.ts, metadata.int.test.ts, queryChartConfig.int.test.ts → @clickhouse/client (matches the client they instantiate; also clears the clientClickHouseSettings private-property errors)
  • packages/cli/src/api/client.ts → @clickhouse/client; dropped the now-unused @clickhouse/client-common dep from cli package.json
• Intentionally retained on client-common — clickhouse/index.ts and core/metadata.ts. These are cross-platform/barrel modules, and ResponseHeaders is not re-exported by the platform packages at the pinned 1.12.1, so migrating them would break the current build. This is the only remaining (justified) client-common usage.
• Shared base-class bridge — import swaps alone don't suffice for 1.23: BaseClickhouseClient feeds one platform-neutral settings object into both a WebClickHouseClient | NodeClickHouseClient union and both subclasses, whose settings types diverge under 1.23. Bridged with a single typed getClient() override per subclass plus a neutral→platform cast on processClickhouseSettings() — type-only, following the file's existing // client library type mismatch convention.

// node.ts — subclass narrows the base class's platform-agnostic client once
protected getClient(): NodeClickHouseClient {
  // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- subclass always builds a node client
  return super.getClient() as NodeClickHouseClient;
}

The only lockfile delta is the cli client-common removal; no version entries change.

Screenshots or video

N/A — non-UI change.

How to test on Vercel preview

N/A — non-UI change.

References

• Linear Issue:
• Related PRs: An E2E test for @clickhouse/client package beta version #1553 (experimental 1.23 bump that surfaced the failure; not landing)

[changeset-bot]

🦋 Changeset detected

Latest commit: 4c2c9b3

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages

Name	Type
@hyperdx/common-utils	Patch
@hyperdx/cli	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
hyperdx-oss	Ready	Preview, Comment	Jun 22, 2026 11:08pm
hyperdx-storybook	Ready	Preview, Comment	Jun 22, 2026 11:08pm

[greptile-apps]

Greptile Summary

This PR repoints ClickHouse type imports from the deprecated @clickhouse/client-common to the platform-specific packages (@clickhouse/client / @clickhouse/client-web), preparing @hyperdx/common-utils and @hyperdx/cli to compile cleanly against @clickhouse/client* 1.23 without a version bump today. The core bridge — a typed getClient() override per subclass and a neutral-to-platform cast on processClickhouseSettings() — is applied to node.ts and browser.ts and follows the file's existing // client library type mismatch convention.

• clickhouse/node.ts and clickhouse/browser.ts each gain a getClient() override that narrows the base class's WebClickHouseClient | NodeClickHouseClient union to the platform-specific type, plus an as ClickHouseSettings cast on processClickhouseSettings() — the two changes required for 1.23 nominal-type compatibility.
• @clickhouse/client-common is intentionally retained in clickhouse/index.ts and core/metadata.ts (cross-platform barrel modules that re-export ResponseHeaders, which platform packages don't expose at the pinned 1.12.1), and removed from the cli package's devDependencies since client.ts now imports directly from @clickhouse/client.

Confidence Score: 3/5

Safe at the current 1.12.1 pin — no runtime behaviour changes — but the stated goal of requiring no further code changes when upgrading to 1.23 is not fully achieved for ProxyClickhouseClient in cli/client.ts.

The node.ts and browser.ts forward-compat bridge (getClient() override + ClickHouseSettings cast) was not applied to ProxyClickhouseClient in cli/src/api/client.ts, which also always builds a Node client. That class will still produce the same nominal-type compile errors under 1.23 that motivated the PR, meaning the 1.23 bump will still require a follow-up fix to client.ts before CI passes.

packages/cli/src/api/client.ts — ProxyClickhouseClient.__query needs the same getClient() narrowing override and processClickhouseSettings() cast that node.ts and browser.ts received.

Important Files Changed

Filename	Overview
packages/common-utils/src/clickhouse/node.ts	Adds getClient() override to narrow the base class union type to NodeClickHouseClient, and applies an as-cast on processClickhouseSettings() result. Both patterns are correct and consistent with the PR's forward-compat strategy.
packages/common-utils/src/clickhouse/browser.ts	Same getClient() override and settings cast applied for the web client path. Mirrors the node.ts changes correctly.
packages/cli/src/api/client.ts	Import moved from client-common to @clickhouse/client, but ProxyClickhouseClient is missing both the getClient() narrowing override and the as-cast on processClickhouseSettings() that node.ts and browser.ts received, leaving it incompatible with @clickhouse/client 1.23.
packages/cli/package.json	Removes @clickhouse/client-common from cli devDependencies now that client.ts imports directly from @clickhouse/client.
.changeset/clickhouse-client-forward-compat.md	Accurate changeset entry describing the patch-level import repoint for forward-compatibility.

Class Diagram

%%{init: {'theme': 'neutral'}}%%
classDiagram
    class BaseClickhouseClient {
        +client: WebClickHouseClient | NodeClickHouseClient
        +getClient() WebClickHouseClient | NodeClickHouseClient
        +processClickhouseSettings() ClickHouseSettings~client-common~
        +abstract __query()
    }

    class ClickhouseClient_node {
        +getClient() NodeClickHouseClient ✅ override added
        +__query() cast applied ✅
    }

    class ClickhouseClient_browser {
        +getClient() WebClickHouseClient ✅ override added
        +__query() cast applied ✅
    }

    class ProxyClickhouseClient {
        +getClient() WebClickHouseClient | NodeClickHouseClient ❌ no override
        +__query() no cast ❌
    }

    BaseClickhouseClient <|-- ClickhouseClient_node : node.ts
    BaseClickhouseClient <|-- ClickhouseClient_browser : browser.ts
    BaseClickhouseClient <|-- ProxyClickhouseClient : cli/client.ts

    note for ClickhouseClient_node "Types from @clickhouse/client"
    note for ClickhouseClient_browser "Types from @clickhouse/client-web"
    note for ProxyClickhouseClient "Types from @clickhouse/client\nbut missing 1.23 bridge fixes"

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
classDiagram
    class BaseClickhouseClient {
        +client: WebClickHouseClient | NodeClickHouseClient
        +getClient() WebClickHouseClient | NodeClickHouseClient
        +processClickhouseSettings() ClickHouseSettings~client-common~
        +abstract __query()
    }

    class ClickhouseClient_node {
        +getClient() NodeClickHouseClient ✅ override added
        +__query() cast applied ✅
    }

    class ClickhouseClient_browser {
        +getClient() WebClickHouseClient ✅ override added
        +__query() cast applied ✅
    }

    class ProxyClickhouseClient {
        +getClient() WebClickHouseClient | NodeClickHouseClient ❌ no override
        +__query() no cast ❌
    }

    BaseClickhouseClient <|-- ClickhouseClient_node : node.ts
    BaseClickhouseClient <|-- ClickhouseClient_browser : browser.ts
    BaseClickhouseClient <|-- ProxyClickhouseClient : cli/client.ts

    note for ClickhouseClient_node "Types from @clickhouse/client"
    note for ClickhouseClient_browser "Types from @clickhouse/client-web"
    note for ProxyClickhouseClient "Types from @clickhouse/client\nbut missing 1.23 bridge fixes"

Loading

Comments Outside Diff (1)

1. packages/cli/src/api/client.ts, line 348-389 (link)

   ProxyClickhouseClient missing both forward-compat fixes applied to node.ts / browser.ts

   ProxyClickhouseClient always creates a Node client (line 327 createClient from @clickhouse/client) but omits the two 1.23-compatibility patterns the PR applies to the analogous node.ts class:

   1. Missing getClient() narrowing override — without it, this.getClient() still returns the base class's WebClickHouseClient | NodeClickHouseClient union. Under 1.23, calling .query() on a union whose members have diverged ClickHouseSettings types would be a compile error at the call site (line 380).

   2. Missing as ClickHouseSettings cast — processClickhouseSettings() is declared on BaseClickhouseClient in index.ts, returning Promise<ClickHouseSettings> where that ClickHouseSettings resolves to @clickhouse/client-common's copy. Here clickhouseSettings is typed against @clickhouse/client's ClickHouseSettings (line 358). Under 1.23, these are nominally distinct (each platform package bundles its own copy backed by a private SettingsMap), so the assignment at line 360 would be a type error — the same one node.ts fixes with (await this.processClickhouseSettings(...)) as ClickHouseSettings.

   The PR description claims "the actual upgrade can land later with no further code changes," but ProxyClickhouseClient would still require both of these fixes when 1.23 is bumped.

   

_{Reviews (1): Last reviewed commit: "Consolidate platform-client cast into a ..." | Re-trigger Greptile}

[peter-leonov-ch]

hat class will still produce the same nominal-type compile errors under 1.23 that motivated the PR, meaning the 1.23 bump will still require a follow-up fix to client.ts before CI passes.

The coding agent session tested the changes in this PR against the 1.23 here: https://github.com/hyperdxio/hyperdx/sessions/09fe9533-5802-414b-892d-0b6f057a7c20

If that's actually the case, I'll iterate on it until the gating PR turns green.

[github-actions]

E2E Test Results

✅ All tests passed • 217 passed • 3 skipped • 1502s

Status	Count
✅ Passed	217
❌ Failed	0
⚠️ Flaky	5
⏭️ Skipped	3

Tests ran across 4 shards in parallel.

View full report →

[github-actions]

🔵 Tier 2 — Low Risk

Small, isolated change with no API route or data model modifications.

Why this tier:

• Standard feature/fix — introduces new logic or modifies core functionality

Review process: AI review + quick human skim (target: 5–15 min). Reviewer validates AI assessment and checks for domain-specific concerns.
SLA: Resolve within 4 business hours.

Stats

• Production files changed: 4
• Production lines changed: 37 (+ 6 in test files, excluded from tier calculation)
• Branch: copilot/forward-compatible-clickhouse-client
• Author: Copilot

To override this classification, remove the review/tier-2 label and apply a different review/tier-* label. Manual overrides are preserved on subsequent pushes.