@clickhouse/client 1.18.1 → 1.18.2-head.9835b07.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,8 +11,9 @@ 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;

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/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;
@@ -24,35 +25,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 +46,6 @@ export declare abstract class NodeBaseConnection implements Connection<Stream.Re
     private getAbortController;
     private logRequestError;
     private httpRequestErrorMessage;
-    private parseSummary;
     private runExec;
     private request;
 }