@clickhouse/client-common 0.3.0 → 0.4.0

package/LICENSE

@@ -1,4 +1,4 @@
-Copyright 2016-2023 ClickHouse, Inc.
+Copyright 2016-2024 ClickHouse, Inc.
 
                                  Apache License
                            Version 2.0, January 2004
@@ -188,7 +188,7 @@ Copyright 2016-2023 ClickHouse, Inc.
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright 2016-2023 ClickHouse, Inc.
+   Copyright 2016-2024 ClickHouse, Inc.
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

package/README.md

@@ -4,9 +4,23 @@
 </p>
 <br/>
 <p align="center">
+<a href="https://www.npmjs.com/package/@clickhouse/client">
+<img alt="NPM Version" src="https://img.shields.io/npm/v/%40clickhouse%2Fclient?color=%233178C6&logo=npm">
+</a>
+
+<a href="https://www.npmjs.com/package/@clickhouse/client">
+<img alt="NPM Downloads" src="https://img.shields.io/npm/dw/%40clickhouse%2Fclient?color=%233178C6&logo=npm">
+</a>
+
 <a href="https://github.com/ClickHouse/clickhouse-js/actions/workflows/tests.yml">
 <img src="https://github.com/ClickHouse/clickhouse-js/actions/workflows/tests.yml/badge.svg?branch=main">
 </a>
+
+<a href="https://codecov.io/gh/ClickHouse/clickhouse-js">
+<img src="https://codecov.io/gh/ClickHouse/clickhouse-js/graph/badge.svg?token=B832WB00WJ">
+</a>
+
+<img src="https://api.scorecard.dev/projects/github.com/ClickHouse/clickhouse-js/badge">
 </p>
 
 ## About

package/dist/clickhouse_types.d.ts

@@ -1,7 +1,7 @@
 export interface ResponseJSON<T = unknown> {
     data: Array<T>;
     query_id?: string;
-    totals?: Record<string, number>;
+    totals?: T;
     extremes?: Record<string, any>;
     meta?: Array<{
         name: string;
@@ -13,6 +13,7 @@ export interface ResponseJSON<T = unknown> {
         bytes_read: number;
     };
     rows?: number;
+    rows_before_limit_at_least?: number;
 }
 export interface InputJSON<T = unknown> {
     meta: {
@@ -31,7 +32,64 @@ export interface ClickHouseSummary {
     result_rows: string;
     result_bytes: string;
     elapsed_ns: string;
+    /** Available only after ClickHouse 24.9 */
+    real_time_microseconds?: string;
 }
+export type ResponseHeaders = Record<string, string | string[] | undefined>;
 export interface WithClickHouseSummary {
     summary?: ClickHouseSummary;
 }
+export interface WithResponseHeaders {
+    response_headers: ResponseHeaders;
+}
+export interface ClickHouseProgress {
+    read_rows: string;
+    read_bytes: string;
+    elapsed_ns: string;
+    total_rows_to_read?: string;
+}
+export interface ProgressRow {
+    progress: ClickHouseProgress;
+}
+export type SpecialEventRow<T> = {
+    meta: Array<{
+        name: string;
+        type: string;
+    }>;
+} | {
+    totals: T;
+} | {
+    min: T;
+} | {
+    max: T;
+} | {
+    rows_before_limit_at_least: number | string;
+} | {
+    rows_before_aggregation: number | string;
+} | {
+    exception: string;
+};
+export type InsertValues<Stream, T = unknown> = ReadonlyArray<T> | Stream | InputJSON<T> | InputJSONObjectEachRow<T>;
+export type NonEmptyArray<T> = [T, ...T[]];
+export interface ClickHouseCredentialsAuth {
+    username?: string;
+    password?: string;
+}
+/** Supported in ClickHouse Cloud only */
+export interface ClickHouseJWTAuth {
+    access_token: string;
+}
+export type ClickHouseAuth = ClickHouseCredentialsAuth | ClickHouseJWTAuth;
+/** Type guard to use with `JSONEachRowWithProgress`, checking if the emitted row is a progress row.
+ *  @see https://clickhouse.com/docs/interfaces/formats/JSONEachRowWithProgress */
+export declare function isProgressRow(row: unknown): row is ProgressRow;
+/** Type guard to use with `JSONEachRowWithProgress`, checking if the emitted row is a row with data.
+ *  @see https://clickhouse.com/docs/interfaces/formats/JSONEachRowWithProgress */
+export declare function isRow<T>(row: unknown): row is {
+    row: T;
+};
+/** Type guard to use with `JSONEachRowWithProgress`, checking if the row contains an exception.
+ *  @see https://clickhouse.com/docs/interfaces/formats/JSONEachRowWithProgress */
+export declare function isException(row: unknown): row is {
+    exception: string;
+};

package/dist/clickhouse_types.js

@@ -1,3 +1,30 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.isProgressRow = isProgressRow;
+exports.isRow = isRow;
+exports.isException = isException;
+/** Type guard to use with `JSONEachRowWithProgress`, checking if the emitted row is a progress row.
+ *  @see https://clickhouse.com/docs/interfaces/formats/JSONEachRowWithProgress */
+function isProgressRow(row) {
+    return (row !== null &&
+        typeof row === 'object' &&
+        'progress' in row &&
+        Object.keys(row).length === 1);
+}
+/** Type guard to use with `JSONEachRowWithProgress`, checking if the emitted row is a row with data.
+ *  @see https://clickhouse.com/docs/interfaces/formats/JSONEachRowWithProgress */
+function isRow(row) {
+    return (row !== null &&
+        typeof row === 'object' &&
+        'row' in row &&
+        Object.keys(row).length === 1);
+}
+/** Type guard to use with `JSONEachRowWithProgress`, checking if the row contains an exception.
+ *  @see https://clickhouse.com/docs/interfaces/formats/JSONEachRowWithProgress */
+function isException(row) {
+    return (row !== null &&
+        typeof row === 'object' &&
+        'exception' in row &&
+        Object.keys(row).length === 1);
+}
 //# sourceMappingURL=clickhouse_types.js.map

package/dist/clickhouse_types.js.map

@@ -1 +1 @@
-{"version":3,"file":"clickhouse_types.js","sourceRoot":"","sources":["../../../packages/client-common/src/clickhouse_types.ts"],"names":[],"mappings":""}
+{"version":3,"file":"clickhouse_types.js","sourceRoot":"","sources":["../src/clickhouse_types.ts"],"names":[],"mappings":";;AAqFA,sCAOC;AAID,sBAOC;AAID,kCAOC;AA/BD;kFACkF;AAClF,SAAgB,aAAa,CAAC,GAAY;IACxC,OAAO,CACL,GAAG,KAAK,IAAI;QACZ,OAAO,GAAG,KAAK,QAAQ;QACvB,UAAU,IAAI,GAAG;QACjB,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,MAAM,KAAK,CAAC,CAC9B,CAAA;AACH,CAAC;AAED;kFACkF;AAClF,SAAgB,KAAK,CAAI,GAAY;IACnC,OAAO,CACL,GAAG,KAAK,IAAI;QACZ,OAAO,GAAG,KAAK,QAAQ;QACvB,KAAK,IAAI,GAAG;QACZ,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,MAAM,KAAK,CAAC,CAC9B,CAAA;AACH,CAAC;AAED;kFACkF;AAClF,SAAgB,WAAW,CAAC,GAAY;IACtC,OAAO,CACL,GAAG,KAAK,IAAI;QACZ,OAAO,GAAG,KAAK,QAAQ;QACvB,WAAW,IAAI,GAAG;QAClB,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,MAAM,KAAK,CAAC,CAC9B,CAAA;AACH,CAAC"}

package/dist/client.d.ts

@@ -1,68 +1,9 @@
-import type { ClickHouseLogLevel, ClickHouseSettings, Connection, ConnectionParams, ConnExecResult, Logger, WithClickHouseSummary } from '@clickhouse/client-common';
-import { type DataFormat } from '@clickhouse/client-common';
-import type { InputJSON, InputJSONObjectEachRow } from './clickhouse_types';
+import type { BaseClickHouseClientConfigOptions, ClickHouseSettings, ConnExecResult, IsSame, WithClickHouseSummary, WithResponseHeaders } from './index';
+import { type DataFormat } from './index';
+import type { InsertValues, NonEmptyArray } from './clickhouse_types';
+import type { ImplementationDetails } from './config';
 import type { ConnPingResult } from './connection';
 import type { BaseResultSet } from './result';
-export type MakeConnection<Stream> = (params: ConnectionParams) => Connection<Stream>;
-export type MakeResultSet<Stream> = (stream: Stream, format: DataFormat, session_id: string) => BaseResultSet<Stream>;
-export interface ValuesEncoder<Stream> {
-    validateInsertValues<T = unknown>(values: InsertValues<Stream, T>, format: DataFormat): void;
-    /**
-     * A function encodes an array or a stream of JSON objects to a format compatible with ClickHouse.
-     * If values are provided as an array of JSON objects, the function encodes it in place.
-     * If values are provided as a stream of JSON objects, the function sets up the encoding of each chunk.
-     * If values are provided as a raw non-object stream, the function does nothing.
-     *
-     * @param values a set of values to send to ClickHouse.
-     * @param format a format to encode value to.
-     */
-    encodeValues<T = unknown>(values: InsertValues<Stream, T>, format: DataFormat): string | Stream;
-}
-export type CloseStream<Stream> = (stream: Stream) => Promise<void>;
-export interface ClickHouseClientConfigOptions<Stream> {
-    impl: {
-        make_connection: MakeConnection<Stream>;
-        make_result_set: MakeResultSet<Stream>;
-        values_encoder: ValuesEncoder<Stream>;
-        close_stream: CloseStream<Stream>;
-    };
-    /** A ClickHouse instance URL. Default value: `http://localhost:8123`. */
-    host?: string;
-    /** The request timeout in milliseconds. Default value: `30_000`. */
-    request_timeout?: number;
-    /** Maximum number of sockets to allow per host. Default value: `10`. */
-    max_open_connections?: number;
-    compression?: {
-        /** `response: true` instructs ClickHouse server to respond with
-         * compressed response body. Default: true. */
-        response?: boolean;
-        /** `request: true` enabled compression on the client request body.
-         * Default: false. */
-        request?: boolean;
-    };
-    /** The name of the user on whose behalf requests are made.
-     * Default: 'default'. */
-    username?: string;
-    /** The user password. Default: ''. */
-    password?: string;
-    /** The name of the application using the JS client.
-     * Default: empty. */
-    application?: string;
-    /** Database name to use. Default value: `default`. */
-    database?: string;
-    /** ClickHouse settings to apply to all requests. Default value: {} */
-    clickhouse_settings?: ClickHouseSettings;
-    log?: {
-        /** A class to instantiate a custom logger implementation.
-         * Default: {@link DefaultLogger} */
-        LoggerClass?: new () => Logger;
-        /** Default: OFF */
-        level?: ClickHouseLogLevel;
-    };
-    session_id?: string;
-    additional_headers?: Record<string, string>;
-}
-export type BaseClickHouseClientConfigOptions<Stream> = Omit<ClickHouseClientConfigOptions<Stream>, 'impl'>;
 export interface BaseQueryParams {
     /** ClickHouse's settings that can be applied on query level. */
     clickhouse_settings?: ClickHouseSettings;
@@ -71,9 +12,28 @@ export interface BaseQueryParams {
     /** AbortSignal instance to cancel a request in progress. */
     abort_signal?: AbortSignal;
     /** A specific `query_id` that will be sent with this request.
-     * If it is not set, a random identifier will be generated automatically by the client. */
+     *  If it is not set, a random identifier will be generated automatically by the client. */
     query_id?: string;
+    /** A specific ClickHouse Session id for this query.
+     *  If it is not set, {@link BaseClickHouseClientConfigOptions.session_id} will be used.
+     *  @default undefined (no override) */
     session_id?: string;
+    /** A specific list of roles to use for this query.
+     *  If it is not set, {@link BaseClickHouseClientConfigOptions.role} will be used.
+     *  @default undefined (no override) */
+    role?: string | Array<string>;
+    /** When defined, overrides {@link BaseClickHouseClientConfigOptions.auth} for this particular request.
+     *  @default undefined (no override) */
+    auth?: {
+        username: string;
+        password: string;
+    } | {
+        access_token: string;
+    };
+    /** Additional HTTP headers to attach to this particular request.
+     *  Overrides the headers set in {@link BaseClickHouseClientConfigOptions.http_headers}.
+     *  @default empty object */
+    http_headers?: Record<string, string>;
 }
 export interface QueryParams extends BaseQueryParams {
     /** Statement to execute. */
@@ -81,20 +41,56 @@ export interface QueryParams extends BaseQueryParams {
     /** Format of the resulting dataset. */
     format?: DataFormat;
 }
-export interface ExecParams extends BaseQueryParams {
-    /** Statement to execute. */
+/** Same parameters as {@link QueryParams}, but with `format` field as a type */
+export type QueryParamsWithFormat<Format extends DataFormat> = Omit<QueryParams, 'format'> & {
+    format?: Format;
+};
+/** If the Format is not a literal type, fall back to the default behavior of the ResultSet,
+ *  allowing to call all methods with all data shapes variants,
+ *  and avoiding generated types that include all possible DataFormat literal values. */
+export type QueryResult<Stream, Format extends DataFormat> = IsSame<Format, DataFormat> extends true ? BaseResultSet<Stream, unknown> : BaseResultSet<Stream, Format>;
+export type ExecParams = BaseQueryParams & {
+    /** Statement to execute (including the FORMAT clause). By default, the query will be sent in the request body;
+     *  If {@link ExecParamsWithValues.values} are defined, the query is sent as a request parameter,
+     *  and the values are sent in the request body instead. */
     query: string;
-}
+    /** If set to `false`, the client _will not_ decompress the response stream, even if the response compression
+     *  was requested by the client via the {@link BaseClickHouseClientConfigOptions.compression.response } setting.
+     *  This could be useful if the response stream is passed to another application as-is,
+     *  and the decompression is handled there.
+     *  @note 1) Node.js only. This setting will have no effect on the Web version.
+     *  @note 2) In case of an error, the stream will be decompressed anyway, regardless of this setting.
+     *  @default true */
+    decompress_response_stream?: boolean;
+    /**
+     * If set to `true`, the client will ignore error responses from the server and return them as-is in the response stream.
+     * This could be useful if you want to handle error responses manually.
+     * @note 1) Node.js only. This setting will have no effect on the Web version.
+     * @note 2) Default behavior is to not ignore error responses, and throw an error when an error response
+     *          is received. This includes decompressing the error response stream if it is compressed.
+     * @default false
+     */
+    ignore_error_response?: boolean;
+};
+export type ExecParamsWithValues<Stream> = ExecParams & {
+    /** If you have a custom INSERT statement to run with `exec`, the data from this stream will be inserted.
+     *
+     *  NB: the data in the stream is expected to be serialized accordingly to the FORMAT clause
+     *  used in {@link ExecParams.query} in this case.
+     *
+     *  @see https://clickhouse.com/docs/en/interfaces/formats */
+    values: Stream;
+};
 export type CommandParams = ExecParams;
 export type CommandResult = {
     query_id: string;
-} & WithClickHouseSummary;
+} & WithClickHouseSummary & WithResponseHeaders;
 export type InsertResult = {
     /**
      * Indicates whether the INSERT statement was executed on the server.
      * Will be `false` if there was no data to insert.
-     * For example: if {@link InsertParams.values} was an empty array,
-     * the client does not any requests to the server, and {@link executed} is false.
+     * For example, if {@link InsertParams.values} was an empty array,
+     * the client does not send any requests to the server, and {@link executed} is false.
      */
     executed: boolean;
     /**
@@ -102,11 +98,8 @@ export type InsertResult = {
      * Otherwise, either {@link InsertParams.query_id} if it was set, or the id that was generated by the client.
      */
     query_id: string;
-} & WithClickHouseSummary;
+} & WithClickHouseSummary & WithResponseHeaders;
 export type ExecResult<Stream> = ConnExecResult<Stream>;
-export type PingResult = ConnPingResult;
-export type InsertValues<Stream, T = unknown> = ReadonlyArray<T> | Stream | InputJSON<T> | InputJSONObjectEachRow<T>;
-type NonEmptyArray<T> = [T, ...T[]];
 /** {@link except} field contains a non-empty list of columns to exclude when generating `(* EXCEPT (...))` clause */
 export interface InsertColumnsExcept {
     except: NonEmptyArray<string>;
@@ -119,7 +112,7 @@ export interface InsertParams<Stream = unknown, T = unknown> extends BaseQueryPa
     /** Format of the dataset to insert. Default: `JSONCompactEachRow` */
     format?: DataFormat;
     /**
-     * Allows to specify which columns the data will be inserted into.
+     * Allows specifying which columns the data will be inserted into.
      * Accepts either an array of strings (column names) or an object of {@link InsertColumnsExcept} type.
      * Examples of generated queries:
      *
@@ -132,54 +125,92 @@ export interface InsertParams<Stream = unknown, T = unknown> extends BaseQueryPa
      * See also: https://clickhouse.com/docs/en/sql-reference/statements/insert-into */
     columns?: NonEmptyArray<string> | InsertColumnsExcept;
 }
+/** Parameters for the health-check request - using the built-in `/ping` endpoint.
+ *  This is the default behavior for the Node.js version. */
+export type PingParamsWithEndpoint = {
+    select: false;
+} & Pick<BaseQueryParams, 'abort_signal' | 'http_headers'>;
+/** Parameters for the health-check request - using a SELECT query.
+ *  This is the default behavior for the Web version, as the `/ping` endpoint does not support CORS.
+ *  Most of the standard `query` method params, e.g., `query_id`, `abort_signal`, `http_headers`, etc. will work,
+ *  except for `query_params`, which does not make sense to allow in this method. */
+export type PingParamsWithSelectQuery = {
+    select: true;
+} & Omit<BaseQueryParams, 'query_params'>;
+export type PingParams = PingParamsWithEndpoint | PingParamsWithSelectQuery;
+export type PingResult = ConnPingResult;
 export declare class ClickHouseClient<Stream = unknown> {
+    private readonly clientClickHouseSettings;
     private readonly connectionParams;
     private readonly connection;
     private readonly makeResultSet;
     private readonly valuesEncoder;
-    private readonly closeStream;
     private readonly sessionId?;
-    constructor(config: ClickHouseClientConfigOptions<Stream>);
-    private getQueryParams;
+    private readonly role?;
+    private readonly logWriter;
+    private readonly jsonHandling;
+    constructor(config: BaseClickHouseClientConfigOptions & ImplementationDetails<Stream>);
     /**
-     * Used for most statements that can have a response, such as SELECT.
-     * FORMAT clause should be specified separately via {@link QueryParams.format} (default is JSON)
-     * Consider using {@link ClickHouseClient.insert} for data insertion,
-     * or {@link ClickHouseClient.command} for DDLs.
+     * Used for most statements that can have a response, such as `SELECT`.
+     * FORMAT clause should be specified separately via {@link QueryParams.format} (default is `JSON`).
+     * Consider using {@link ClickHouseClient.insert} for data insertion, or {@link ClickHouseClient.command} for DDLs.
+     * Returns an implementation of {@link BaseResultSet}.
+     *
+     * See {@link DataFormat} for the formats supported by the client.
      */
-    query(params: QueryParams): Promise<BaseResultSet<Stream>>;
+    query<Format extends DataFormat = 'JSON'>(params: QueryParamsWithFormat<Format>): Promise<QueryResult<Stream, Format>>;
     /**
      * It should be used for statements that do not have any output,
      * when the format clause is not applicable, or when you are not interested in the response at all.
-     * Response stream is destroyed immediately as we do not expect useful information there.
+     * The response stream is destroyed immediately as we do not expect useful information there.
      * Examples of such statements are DDLs or custom inserts.
-     * If you are interested in the response data, consider using {@link ClickHouseClient.exec}
+     *
+     * @note if you have a custom query that does not work with {@link ClickHouseClient.query},
+     * and you are interested in the response data, consider using {@link ClickHouseClient.exec}.
      */
     command(params: CommandParams): Promise<CommandResult>;
     /**
-     * Similar to {@link ClickHouseClient.command}, but for the cases where the output is expected,
-     * but format clause is not applicable. The caller of this method is expected to consume the stream,
-     * otherwise, the request will eventually be timed out.
+     * Similar to {@link ClickHouseClient.command}, but for the cases where the output _is expected_,
+     * but format clause is not applicable. The caller of this method _must_ consume the stream,
+     * as the underlying socket will not be released until then, and the request will eventually be timed out.
+     *
+     * @note it is not intended to use this method to execute the DDLs, such as `CREATE TABLE` or similar;
+     * use {@link ClickHouseClient.command} instead.
      */
-    exec(params: ExecParams): Promise<ExecResult<Stream>>;
+    exec(params: ExecParams | ExecParamsWithValues<Stream>): Promise<ExecResult<Stream>>;
     /**
      * The primary method for data insertion. It is recommended to avoid arrays in case of large inserts
      * to reduce application memory consumption and consider streaming for most of such use cases.
      * As the insert operation does not provide any output, the response stream is immediately destroyed.
-     * In case of a custom insert operation, such as, for example, INSERT FROM SELECT,
-     * consider using {@link ClickHouseClient.command}, passing the entire raw query there (including FORMAT clause).
+     *
+     * @note in case of a custom insert operation (e.g., `INSERT FROM SELECT`),
+     * consider using {@link ClickHouseClient.command}, passing the entire raw query there
+     * (including the `FORMAT` clause).
      */
     insert<T>(params: InsertParams<Stream, T>): Promise<InsertResult>;
     /**
-     * Health-check request. It does not throw if an error occurs -
-     * the error is returned inside the result object.
+     * A health-check request. It does not throw if an error occurs - the error is returned inside the result object.
+     *
+     * By default, Node.js version uses the built-in `/ping` endpoint, which does not verify credentials.
+     * Optionally, it can be switched to a `SELECT` query (see {@link PingParamsWithSelectQuery}).
+     * In that case, the server will verify the credentials.
+     *
+     * **NOTE**: Since the `/ping` endpoint does not support CORS, the Web version always uses a `SELECT` query.
      */
-    ping(): Promise<PingResult>;
+    ping(params?: PingParams): Promise<PingResult>;
     /**
      * Shuts down the underlying connection.
      * This method should ideally be called only once per application lifecycle,
      * for example, during the graceful shutdown phase.
      */
     close(): Promise<void>;
+    /**
+     * Closes the client connection.
+     *
+     * Automatically called when using `using` statement in supported environments.
+     * @see {@link ClickHouseClient.close}
+     * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/using
+     */
+    [Symbol.asyncDispose](): Promise<void>;
+    private withClientQueryParams;
 }
-export {};