@clickhouse/client 1.18.1 → 1.18.2-head.084b623.1

package/README.md

@@ -27,18 +27,83 @@
 
 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 three 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.
+  Compatible with Chrome/Firefox browsers and Cloudflare workers.
 - `@clickhouse/client-common` - shared common types and the base framework for building a custom client implementation.
 
+## 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 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 |
+
+### 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).
+
+## Compatibility with ClickHouse
+
+| Client version | ClickHouse |
+| -------------- | ---------- |
+| 1.12.0+        | 24.8+      |
+
+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'
+
+const client = createClient({
+  url: process.env.CLICKHOUSE_URL ?? 'http://localhost:8123',
+  username: process.env.CLICKHOUSE_USER ?? 'default',
+  password: process.env.CLICKHOUSE_PASSWORD ?? '',
+})
+
+const resultSet = await client.query({
+  query: 'SELECT * FROM system.tables',
+  format: 'JSONEachRow',
+})
+
+const tables = await resultSet.json()
+console.log(tables)
+
+await client.close()
+```
+
+See more examples in the [examples directory](./examples).
+
 ## Documentation
 
-See the [ClickHouse website](https://clickhouse.com/docs/en/integrations/language-clients/javascript) for the full documentation entry.
+See the [ClickHouse website](https://clickhouse.com/docs/integrations/javascript) for the full documentation.
 
 ## Usage examples
 

package/dist/config.d.ts

@@ -11,11 +11,17 @@ export type NodeClickHouseClientConfigOptions = BaseClickHouseClientConfigOption
          *  @default true */
         enabled?: boolean;
         /** For how long keep a particular idle socket alive on the client side (in milliseconds).
-         *  It is supposed to be a fair bit less that the ClickHouse server KeepAlive timeout,
-         *  which is by default 3000 ms for pre-23.11 versions. <br/>
+         *  It is supposed to be at least a second less than the ClickHouse server KeepAlive timeout,
+         *  which is by default `3000` ms for pre-23.11 versions.
+         *
          *  When set to `0`, the idle socket management feature is disabled.
          *  @default 2500 */
         idle_socket_ttl?: number;
+        /** Eagerly destroy the sockets that are considered stale (idle for more than `idle_socket_ttl`),
+         *  without waiting for the timeout to trigger. This allows freeing up stale sockets
+         *  in case of longer event loop delays.
+         *  @default false */
+        eagerly_destroy_stale_sockets?: boolean;
     };
     /** Custom HTTP agent to use for the outgoing HTTP(s) requests.
      *  If set, {@link BaseClickHouseClientConfigOptions.max_open_connections}, {@link tls} and {@link keep_alive}

package/dist/config.js

@@ -62,6 +62,7 @@ exports.NodeConfigImpl = {
             connection_params: params,
             set_basic_auth_header: nodeConfig.set_basic_auth_header ?? true,
             capture_enhanced_stack_trace: nodeConfig.capture_enhanced_stack_trace ?? false,
+            eagerly_destroy_stale_sockets: nodeConfig.keep_alive?.eagerly_destroy_stale_sockets ?? false,
             http_agent: nodeConfig.http_agent,
             keep_alive,
             tls,

package/dist/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

package/dist/connection/create_connection.d.ts

@@ -9,8 +9,9 @@ export interface CreateConnectionParams {
     http_agent: http.Agent | https.Agent | undefined;
     set_basic_auth_header: boolean;
     capture_enhanced_stack_trace: boolean;
+    eagerly_destroy_stale_sockets?: boolean;
 }
 /** A factory for easier mocking after Node.js 22.18 */
 export declare class NodeConnectionFactory {
-    static create({ connection_params, tls, keep_alive, http_agent, set_basic_auth_header, capture_enhanced_stack_trace, }: CreateConnectionParams): NodeBaseConnection;
+    static create({ connection_params, tls, keep_alive, http_agent, set_basic_auth_header, capture_enhanced_stack_trace, eagerly_destroy_stale_sockets, }: CreateConnectionParams): NodeBaseConnection;
 }

package/dist/connection/create_connection.js

@@ -7,7 +7,7 @@ const node_https_connection_1 = require("./node_https_connection");
 /** A factory for easier mocking after Node.js 22.18 */
 // eslint-disable-next-line @typescript-eslint/no-extraneous-class
 class NodeConnectionFactory {
-    static create({ connection_params, tls, keep_alive, http_agent, set_basic_auth_header, capture_enhanced_stack_trace, }) {
+    static create({ connection_params, tls, keep_alive, http_agent, set_basic_auth_header, capture_enhanced_stack_trace, eagerly_destroy_stale_sockets = false, }) {
         if (http_agent !== undefined) {
             return new node_custom_agent_connection_1.NodeCustomAgentConnection({
                 ...connection_params,
@@ -15,6 +15,7 @@ class NodeConnectionFactory {
                 capture_enhanced_stack_trace,
                 keep_alive, // only used to enforce proper KeepAlive headers
                 http_agent,
+                eagerly_destroy_stale_sockets,
             });
         }
         switch (connection_params.url.protocol) {
@@ -24,6 +25,7 @@ class NodeConnectionFactory {
                     set_basic_auth_header,
                     capture_enhanced_stack_trace,
                     keep_alive,
+                    eagerly_destroy_stale_sockets,
                 });
             case 'https:':
                 return new node_https_connection_1.NodeHttpsConnection({
@@ -32,6 +34,7 @@ class NodeConnectionFactory {
                     capture_enhanced_stack_trace,
                     keep_alive,
                     tls,
+                    eagerly_destroy_stale_sockets,
                 });
             default:
                 throw new Error('Only HTTP and HTTPS protocols are supported');

package/dist/connection/create_connection.js.map

@@ -1 +1 @@
-{"version":3,"file":"create_connection.js","sourceRoot":"","sources":["../../src/connection/create_connection.ts"],"names":[],"mappings":";;;AAOA,iFAA0E;AAC1E,iEAA2D;AAC3D,mEAA6D;AAW7D,uDAAuD;AACvD,kEAAkE;AAClE,MAAa,qBAAqB;IAChC,MAAM,CAAC,MAAM,CAAC,EACZ,iBAAiB,EACjB,GAAG,EACH,UAAU,EACV,UAAU,EACV,qBAAqB,EACrB,4BAA4B,GACL;QACvB,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;YAC7B,OAAO,IAAI,wDAAyB,CAAC;gBACnC,GAAG,iBAAiB;gBACpB,qBAAqB;gBACrB,4BAA4B;gBAC5B,UAAU,EAAE,gDAAgD;gBAC5D,UAAU;aACX,CAAC,CAAA;QACJ,CAAC;QACD,QAAQ,iBAAiB,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC;YACvC,KAAK,OAAO;gBACV,OAAO,IAAI,yCAAkB,CAAC;oBAC5B,GAAG,iBAAiB;oBACpB,qBAAqB;oBACrB,4BAA4B;oBAC5B,UAAU;iBACX,CAAC,CAAA;YACJ,KAAK,QAAQ;gBACX,OAAO,IAAI,2CAAmB,CAAC;oBAC7B,GAAG,iBAAiB;oBACpB,qBAAqB;oBACrB,4BAA4B;oBAC5B,UAAU;oBACV,GAAG;iBACJ,CAAC,CAAA;YACJ;gBACE,MAAM,IAAI,KAAK,CAAC,6CAA6C,CAAC,CAAA;QAClE,CAAC;IACH,CAAC;CACF;AAtCD,sDAsCC"}
+{"version":3,"file":"create_connection.js","sourceRoot":"","sources":["../../src/connection/create_connection.ts"],"names":[],"mappings":";;;AAOA,iFAA0E;AAC1E,iEAA2D;AAC3D,mEAA6D;AAY7D,uDAAuD;AACvD,kEAAkE;AAClE,MAAa,qBAAqB;IAChC,MAAM,CAAC,MAAM,CAAC,EACZ,iBAAiB,EACjB,GAAG,EACH,UAAU,EACV,UAAU,EACV,qBAAqB,EACrB,4BAA4B,EAC5B,6BAA6B,GAAG,KAAK,GACd;QACvB,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;YAC7B,OAAO,IAAI,wDAAyB,CAAC;gBACnC,GAAG,iBAAiB;gBACpB,qBAAqB;gBACrB,4BAA4B;gBAC5B,UAAU,EAAE,gDAAgD;gBAC5D,UAAU;gBACV,6BAA6B;aAC9B,CAAC,CAAA;QACJ,CAAC;QACD,QAAQ,iBAAiB,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC;YACvC,KAAK,OAAO;gBACV,OAAO,IAAI,yCAAkB,CAAC;oBAC5B,GAAG,iBAAiB;oBACpB,qBAAqB;oBACrB,4BAA4B;oBAC5B,UAAU;oBACV,6BAA6B;iBAC9B,CAAC,CAAA;YACJ,KAAK,QAAQ;gBACX,OAAO,IAAI,2CAAmB,CAAC;oBAC7B,GAAG,iBAAiB;oBACpB,qBAAqB;oBACrB,4BAA4B;oBAC5B,UAAU;oBACV,GAAG;oBACH,6BAA6B;iBAC9B,CAAC,CAAA;YACJ;gBACE,MAAM,IAAI,KAAK,CAAC,6CAA6C,CAAC,CAAA;QAClE,CAAC;IACH,CAAC;CACF;AA1CD,sDA0CC"}

package/dist/connection/node_base_connection.d.ts

@@ -1,9 +1,10 @@
-import type { ConnBaseQueryParams, ConnCommandResult, Connection, ConnectionParams, ConnExecParams, ConnExecResult, ConnInsertParams, ConnInsertResult, ConnPingResult, ConnQueryResult, LogWriter } from '@clickhouse/client-common';
+import type { ConnBaseQueryParams, ConnCommandResult, Connection, ConnectionParams, ConnExecParams, ConnExecResult, ConnInsertParams, ConnInsertResult, ConnPingResult, ConnQueryResult } from '@clickhouse/client-common';
 import { ClickHouseLogLevel } from '@clickhouse/client-common';
 import { type ConnPingParams } from '@clickhouse/client-common';
 import type Http from 'http';
 import type Https from 'node:https';
-import Stream from 'stream';
+import type Stream from 'stream';
+import { type RequestParams } from './socket_pool';
 export type NodeConnectionParams = ConnectionParams & {
     tls?: TLSParams;
     http_agent?: Http.Agent | Https.Agent;
@@ -14,6 +15,10 @@ export type NodeConnectionParams = ConnectionParams & {
         idle_socket_ttl: number;
     };
     log_level: ClickHouseLogLevel;
+    /**
+     * Eagerly destroy the sockets that are considered stale (idle for more than `idle_socket_ttl`), without waiting for the timeout to trigger. This allows to free up the stale sockets in case of longer event loop delays.
+     */
+    eagerly_destroy_stale_sockets: boolean;
 };
 export type TLSParams = {
     ca_cert: Buffer;
@@ -24,35 +29,13 @@ export type TLSParams = {
     key: Buffer;
     type: 'Mutual';
 };
-export interface RequestParams {
-    method: 'GET' | 'POST';
-    url: URL;
-    headers: Http.OutgoingHttpHeaders;
-    body?: string | Stream.Readable;
-    abort_signal: AbortSignal;
-    enable_response_compression?: boolean;
-    enable_request_compression?: boolean;
-    try_decompress_response_stream?: boolean;
-    ignore_error_response?: boolean;
-    parse_summary?: boolean;
-    query: string;
-    query_id: string;
-    log_writer: LogWriter;
-    log_level: ClickHouseLogLevel;
-}
 export declare abstract class NodeBaseConnection implements Connection<Stream.Readable> {
     protected readonly params: NodeConnectionParams;
     protected readonly agent: Http.Agent;
     protected readonly defaultAuthHeader: string;
     protected readonly defaultHeaders: Http.OutgoingHttpHeaders;
-    private readonly jsonHandling;
-    private readonly knownSockets;
-    private readonly idleSocketTTL;
     private readonly connectionId;
-    private socketCounter;
-    private requestCounter;
-    private getNewSocketId;
-    private getNewRequestId;
+    private readonly socketPool;
     protected constructor(params: NodeConnectionParams, agent: Http.Agent);
     ping(params: ConnPingParams): Promise<ConnPingResult>;
     query(params: ConnBaseQueryParams): Promise<ConnQueryResult<Stream.Readable>>;
@@ -67,7 +50,6 @@ export declare abstract class NodeBaseConnection implements Connection<Stream.Re
     private getAbortController;
     private logRequestError;
     private httpRequestErrorMessage;
-    private parseSummary;
     private runExec;
     private request;
 }