@clickhouse/client-common 0.3.1 → 1.0.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,21 @@
 </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>
+
+<img src="https://sonarcloud.io/api/project_badges/measure?project=ClickHouse_clickhouse-js&metric=alert_status">
+
+<img src="https://sonarcloud.io/api/project_badges/measure?project=ClickHouse_clickhouse-js&metric=coverage">
 </p>
 
 ## About

package/dist/client.d.ts

@@ -1,68 +1,9 @@
-import type { ClickHouseLogLevel, ClickHouseSettings, Connection, ConnectionParams, ConnExecResult, Logger, WithClickHouseSummary } from '@clickhouse/client-common';
+import type { BaseClickHouseClientConfigOptions, ClickHouseSettings, ConnExecResult, IsSame, WithClickHouseSummary } from '@clickhouse/client-common';
 import { type DataFormat } from '@clickhouse/client-common';
 import type { InputJSON, InputJSONObjectEachRow } 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;
@@ -81,6 +22,14 @@ export interface QueryParams extends BaseQueryParams {
     /** Format of the resulting dataset. */
     format?: DataFormat;
 }
+/** 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 interface ExecParams extends BaseQueryParams {
     /** Statement to execute. */
     query: string;
@@ -133,21 +82,21 @@ export interface InsertParams<Stream = unknown, T = unknown> extends BaseQueryPa
     columns?: NonEmptyArray<string> | InsertColumnsExcept;
 }
 export declare class ClickHouseClient<Stream = unknown> {
-    private readonly connectionParams;
+    private readonly clientClickHouseSettings;
     private readonly connection;
     private readonly makeResultSet;
     private readonly valuesEncoder;
     private readonly closeStream;
     private readonly sessionId?;
-    constructor(config: ClickHouseClientConfigOptions<Stream>);
-    private getQueryParams;
+    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.
+     * Returns an implementation of {@link BaseResultSet}.
      */
-    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.
@@ -181,5 +130,6 @@ export declare class ClickHouseClient<Stream = unknown> {
      * for example, during the graceful shutdown phase.
      */
     close(): Promise<void>;
+    private withClientQueryParams;
 }
 export {};

package/dist/client.js

@@ -2,9 +2,10 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ClickHouseClient = void 0;
 const client_common_1 = require("@clickhouse/client-common");
+const config_1 = require("./config");
 class ClickHouseClient {
     constructor(config) {
-        Object.defineProperty(this, "connectionParams", {
+        Object.defineProperty(this, "clientClickHouseSettings", {
             enumerable: true,
             configurable: true,
             writable: true,
@@ -40,38 +41,31 @@ class ClickHouseClient {
             writable: true,
             value: void 0
         });
-        this.connectionParams = getConnectionParams(config);
+        const logger = config?.log?.LoggerClass
+            ? new config.log.LoggerClass()
+            : new client_common_1.DefaultLogger();
+        const configWithURL = (0, config_1.prepareConfigWithURL)(config, logger, config.impl.handle_specific_url_params ?? null);
+        const connectionParams = (0, config_1.getConnectionParams)(configWithURL, logger);
+        this.clientClickHouseSettings = connectionParams.clickhouse_settings;
         this.sessionId = config.session_id;
-        validateConnectionParams(this.connectionParams);
-        this.connection = config.impl.make_connection(this.connectionParams);
+        this.connection = config.impl.make_connection(configWithURL, connectionParams);
         this.makeResultSet = config.impl.make_result_set;
         this.valuesEncoder = config.impl.values_encoder;
         this.closeStream = config.impl.close_stream;
     }
-    getQueryParams(params) {
-        return {
-            clickhouse_settings: {
-                ...this.connectionParams.clickhouse_settings,
-                ...params.clickhouse_settings,
-            },
-            query_params: params.query_params,
-            abort_signal: params.abort_signal,
-            query_id: params.query_id,
-            session_id: this.sessionId,
-        };
-    }
     /**
      * 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}.
      */
     async query(params) {
         const format = params.format ?? 'JSON';
         const query = formatQuery(params.query, format);
         const { stream, query_id } = await this.connection.query({
             query,
-            ...this.getQueryParams(params),
+            ...this.withClientQueryParams(params),
         });
         return this.makeResultSet(stream, format, query_id);
     }
@@ -96,7 +90,7 @@ class ClickHouseClient {
         const query = removeTrailingSemi(params.query.trim());
         return await this.connection.exec({
             query,
-            ...this.getQueryParams(params),
+            ...this.withClientQueryParams(params),
         });
     }
     /**
@@ -116,7 +110,7 @@ class ClickHouseClient {
         const result = await this.connection.insert({
             query,
             values: this.valuesEncoder.encodeValues(params.values, format),
-            ...this.getQueryParams(params),
+            ...this.withClientQueryParams(params),
         });
         return { ...result, executed: true };
     }
@@ -135,6 +129,18 @@ class ClickHouseClient {
     async close() {
         return await this.connection.close();
     }
+    withClientQueryParams(params) {
+        return {
+            clickhouse_settings: {
+                ...this.clientClickHouseSettings,
+                ...params.clickhouse_settings,
+            },
+            query_params: params.query_params,
+            abort_signal: params.abort_signal,
+            query_id: params.query_id,
+            session_id: this.sessionId,
+        };
+    }
 }
 exports.ClickHouseClient = ClickHouseClient;
 function formatQuery(query, format) {
@@ -155,39 +161,6 @@ function removeTrailingSemi(query) {
     }
     return query;
 }
-function validateConnectionParams({ url }) {
-    if (url.protocol !== 'http:' && url.protocol !== 'https:') {
-        throw new Error(`Only http(s) protocol is supported, but given: [${url.protocol}]`);
-    }
-}
-function createUrl(host) {
-    try {
-        return new URL(host);
-    }
-    catch (err) {
-        throw new Error('Configuration parameter "host" contains malformed url.');
-    }
-}
-function getConnectionParams(config) {
-    return {
-        application_id: config.application,
-        url: createUrl(config.host ?? 'http://localhost:8123'),
-        request_timeout: config.request_timeout ?? 30000,
-        max_open_connections: config.max_open_connections ?? 10,
-        compression: {
-            decompress_response: config.compression?.response ?? true,
-            compress_request: config.compression?.request ?? false,
-        },
-        username: config.username ?? 'default',
-        password: config.password ?? '',
-        database: config.database ?? 'default',
-        clickhouse_settings: config.clickhouse_settings ?? {},
-        log_writer: new client_common_1.LogWriter(config?.log?.LoggerClass
-            ? new config.log.LoggerClass()
-            : new client_common_1.DefaultLogger(), 'Connection', config.log?.level),
-        additional_headers: config.additional_headers,
-    };
-}
 function isInsertColumnsExcept(obj) {
     return (obj !== undefined &&
         obj !== null &&

package/dist/client.js.map

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

package/dist/config.d.ts

@@ -0,0 +1,159 @@
+import type { InsertValues } from './client';
+import type { Connection, ConnectionParams } from './connection';
+import type { DataFormat } from './data_formatter';
+import type { Logger } from './logger';
+import { ClickHouseLogLevel } from './logger';
+import type { BaseResultSet } from './result';
+import type { ClickHouseSettings } from './settings';
+export interface BaseClickHouseClientConfigOptions {
+    /** @deprecated since version 1.0.0. Use {@link url} instead. <br/>
+     *  A ClickHouse instance URL.
+     *  @default http://localhost:8123 */
+    host?: string;
+    /** A ClickHouse instance URL.
+     *  @default http://localhost:8123 */
+    url?: string | URL;
+    /** An optional pathname to add to the ClickHouse URL after it is parsed by the client.
+     *  For example, if you use a proxy, and your ClickHouse instance can be accessed as http://proxy:8123/clickhouse_server,
+     *  specify `clickhouse_server` here (with or without a leading slash);
+     *  otherwise, if provided directly in the {@link url}, it will be considered as the `database` option.<br/>
+     *  Multiple segments are supported, e.g. `/my_proxy/db`.
+     *  @default empty string */
+    pathname?: string;
+    /** The request timeout in milliseconds.
+     *  @default 30_000 */
+    request_timeout?: number;
+    /** Maximum number of sockets to allow per host.
+     *  @default 10 */
+    max_open_connections?: number;
+    /** Request and response compression settings. */
+    compression?: {
+        /** `response: true` instructs ClickHouse server to respond with compressed response body. <br/>
+         *  This will add `Accept-Encoding: gzip` header in the request and `enable_http_compression=1` ClickHouse HTTP setting.
+         *  <p><b>Warning</b>: Response compression can't be enabled for a user with readonly=1, as ClickHouse will not allow settings modifications for such user.</p>
+         *  @default false */
+        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 empty string */
+    password?: string;
+    /** The name of the application using the JS client.
+     *  @default empty string */
+    application?: string;
+    /** Database name to use.
+     * @default default */
+    database?: string;
+    /** ClickHouse settings to apply to all requests.
+     *  @default empty object */
+    clickhouse_settings?: ClickHouseSettings;
+    log?: {
+        /** A class to instantiate a custom logger implementation.
+         *  @default see {@link DefaultLogger} */
+        LoggerClass?: new () => Logger;
+        /** @default set to {@link ClickHouseLogLevel.OFF} */
+        level?: ClickHouseLogLevel;
+    };
+    /** ClickHouse Session id to attach to the outgoing requests.
+     *  @default empty string */
+    session_id?: string;
+    /** @deprecated since version 1.0.0. Use {@link http_headers} instead. <br/>
+     *  Additional HTTP headers to attach to the outgoing requests.
+     *  @default empty object */
+    additional_headers?: Record<string, string>;
+    /** Additional HTTP headers to attach to the outgoing requests.
+     *  @default empty object */
+    http_headers?: Record<string, string>;
+    /** HTTP Keep-Alive related settings. */
+    keep_alive?: {
+        /** Enable or disable HTTP Keep-Alive mechanism.
+         *  @default true */
+        enabled?: boolean;
+    };
+}
+export type MakeConnection<Stream, Config = BaseClickHouseClientConfigOptionsWithURL> = (config: Config, params: ConnectionParams) => Connection<Stream>;
+export type MakeResultSet<Stream> = <Format extends DataFormat, ResultSet extends BaseResultSet<Stream, Format>>(stream: Stream, format: Format, query_id: string) => ResultSet;
+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>;
+/**
+ * An implementation might have extra config parameters that we can parse from the connection URL.
+ * These are supposed to be processed after we finish parsing the base configuration.
+ * URL params handled in the common package will be deleted from the URL object.
+ * This way we ensure that only implementation-specific params are passed there,
+ * so we can indicate which URL parameters are unknown by both common and implementation packages.
+ */
+export type HandleImplSpecificURLParams = (config: BaseClickHouseClientConfigOptions, url: URL) => {
+    config: BaseClickHouseClientConfigOptions;
+    handled_params: Set<string>;
+    unknown_params: Set<string>;
+};
+/** Things that may vary between Web/Node.js/etc client implementations. */
+export interface ImplementationDetails<Stream> {
+    impl: {
+        make_connection: MakeConnection<Stream>;
+        make_result_set: MakeResultSet<Stream>;
+        values_encoder: ValuesEncoder<Stream>;
+        close_stream: CloseStream<Stream>;
+        handle_specific_url_params?: HandleImplSpecificURLParams;
+    };
+}
+export type BaseClickHouseClientConfigOptionsWithURL = Omit<BaseClickHouseClientConfigOptions, 'url'> & {
+    url: URL;
+};
+/**
+ * Validates and normalizes the provided "base" config.
+ * Warns about deprecated configuration parameters usage.
+ * Parses the common URL parameters into the configuration parameters (these are the same for all implementations).
+ * Parses implementation-specific URL parameters using the handler provided by that implementation.
+ * Merges these parameters with the base config and implementation-specific defaults.
+ * Enforces certain defaults in case of deprecated keys or readonly mode.
+ */
+export declare function prepareConfigWithURL(baseConfigOptions: BaseClickHouseClientConfigOptions, logger: Logger, handleImplURLParams: HandleImplSpecificURLParams | null): BaseClickHouseClientConfigOptionsWithURL;
+export declare function getConnectionParams(config: BaseClickHouseClientConfigOptionsWithURL, logger: Logger): ConnectionParams;
+/**
+ * Merge two versions of the config: base (hardcoded) from the instance creation and the URL parsed one.
+ * URL config takes priority and overrides the base config parameters.
+ * If a value is overridden, then a warning will be logged (even if the log level is OFF).
+ */
+export declare function mergeConfigs(baseConfig: BaseClickHouseClientConfigOptions, configFromURL: BaseClickHouseClientConfigOptions, logger: Logger): BaseClickHouseClientConfigOptions;
+export declare function createUrl(configURL: string | URL | undefined): URL;
+/**
+ * @param url potentially contains auth, database and URL params to parse the configuration from
+ * @param handleExtraURLParams some platform-specific URL params might be unknown by the common package;
+ * use this function defined in the implementation to handle them. Logs warnings in case of hardcode overrides.
+ */
+export declare function loadConfigOptionsFromURL(url: URL, handleExtraURLParams: HandleImplSpecificURLParams | null): [URL, BaseClickHouseClientConfigOptions];
+export declare function booleanConfigURLValue({ key, value, }: {
+    key: string;
+    value: string;
+}): boolean;
+export declare function numberConfigURLValue({ key, value, min, max, }: {
+    key: string;
+    value: string;
+    min?: number;
+    max?: number;
+}): number;
+export declare function enumConfigURLValue<Enum, Key extends string>({ key, value, enumObject, }: {
+    key: string;
+    value: string;
+    enumObject: {
+        [k in Key]: Enum;
+    };
+}): Enum;