@clickhouse/client-web 1.18.1 → 1.18.2-head.59c3f62.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/utils/stream.js

@@ -8,22 +8,33 @@ function isStream(obj) {
     return (obj !== null && obj !== undefined && typeof obj.pipeThrough === 'function');
 }
 async function getAsText(stream) {
-    let result = '';
-    let isDone = false;
+    let text = '';
     const textDecoder = new TextDecoder();
     const reader = stream.getReader();
-    while (!isDone) {
+    while (true) {
         const { done, value } = await reader.read();
         const decoded = textDecoder.decode(value, { stream: true });
-        if (decoded.length + result.length > MaxStringLength) {
+        if (decoded.length + text.length > MaxStringLength) {
+            // The error message is crafted to be similar to the one thrown by Node's implementation.
+            // A simple try/catch block around the concatenation of the decoded chunk would not work
+            // as different browsers throw profoundly different errors including "out of memory"
+            // in tests. Somehow using manual length checks seems to be the only way to reliably
+            // detect this condition across browsers.
+            // Also, Vitest crashes while running the try/catch implementatioin in Firefox.
             throw new Error('The response length exceeds the maximum allowed size of V8 String: ' +
                 `${MaxStringLength}; consider limiting the amount of requested rows.`);
         }
-        result += decoded;
-        isDone = done;
+        text += decoded;
+        if (done)
+            break;
     }
-    // flush
-    result += textDecoder.decode();
-    return result;
+    // flush unfinished multi-byte characters
+    const decoded = textDecoder.decode();
+    if (decoded.length + text.length > MaxStringLength) {
+        throw new Error('The response length exceeds the maximum allowed size of V8 String: ' +
+            `${MaxStringLength}; consider limiting the amount of requested rows.`);
+    }
+    text += decoded;
+    return text;
 }
 //# sourceMappingURL=stream.js.map

package/dist/utils/stream.js.map

@@ -1 +1 @@
-{"version":3,"file":"stream.js","sourceRoot":"","sources":["../../src/utils/stream.ts"],"names":[],"mappings":";;AAGA,4BAIC;AAED,8BAuBC;AAhCD,+EAA+E;AAC/E,MAAM,eAAe,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,EAAE,CAAA;AAE5C,SAAgB,QAAQ,CAAC,GAAQ;IAC/B,OAAO,CACL,GAAG,KAAK,IAAI,IAAI,GAAG,KAAK,SAAS,IAAI,OAAO,GAAG,CAAC,WAAW,KAAK,UAAU,CAC3E,CAAA;AACH,CAAC;AAEM,KAAK,UAAU,SAAS,CAAC,MAAsB;IACpD,IAAI,MAAM,GAAG,EAAE,CAAA;IACf,IAAI,MAAM,GAAG,KAAK,CAAA;IAElB,MAAM,WAAW,GAAG,IAAI,WAAW,EAAE,CAAA;IACrC,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS,EAAE,CAAA;IAEjC,OAAO,CAAC,MAAM,EAAE,CAAC;QACf,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,MAAM,MAAM,CAAC,IAAI,EAAE,CAAA;QAC3C,MAAM,OAAO,GAAG,WAAW,CAAC,MAAM,CAAC,KAAK,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAA;QAC3D,IAAI,OAAO,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,GAAG,eAAe,EAAE,CAAC;YACrD,MAAM,IAAI,KAAK,CACb,qEAAqE;gBACnE,GAAG,eAAe,mDAAmD,CACxE,CAAA;QACH,CAAC;QACD,MAAM,IAAI,OAAO,CAAA;QACjB,MAAM,GAAG,IAAI,CAAA;IACf,CAAC;IAED,QAAQ;IACR,MAAM,IAAI,WAAW,CAAC,MAAM,EAAE,CAAA;IAC9B,OAAO,MAAM,CAAA;AACf,CAAC"}
+{"version":3,"file":"stream.js","sourceRoot":"","sources":["../../src/utils/stream.ts"],"names":[],"mappings":";;AAGA,4BAIC;AAED,8BAoCC;AA7CD,+EAA+E;AAC/E,MAAM,eAAe,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,EAAE,CAAA;AAE5C,SAAgB,QAAQ,CAAC,GAAQ;IAC/B,OAAO,CACL,GAAG,KAAK,IAAI,IAAI,GAAG,KAAK,SAAS,IAAI,OAAO,GAAG,CAAC,WAAW,KAAK,UAAU,CAC3E,CAAA;AACH,CAAC;AAEM,KAAK,UAAU,SAAS,CAAC,MAAsB;IACpD,IAAI,IAAI,GAAG,EAAE,CAAA;IAEb,MAAM,WAAW,GAAG,IAAI,WAAW,EAAE,CAAA;IACrC,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS,EAAE,CAAA;IAEjC,OAAO,IAAI,EAAE,CAAC;QACZ,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,MAAM,MAAM,CAAC,IAAI,EAAE,CAAA;QAC3C,MAAM,OAAO,GAAG,WAAW,CAAC,MAAM,CAAC,KAAK,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAA;QAC3D,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,GAAG,eAAe,EAAE,CAAC;YACnD,yFAAyF;YACzF,wFAAwF;YACxF,oFAAoF;YACpF,oFAAoF;YACpF,yCAAyC;YACzC,+EAA+E;YAC/E,MAAM,IAAI,KAAK,CACb,qEAAqE;gBACnE,GAAG,eAAe,mDAAmD,CACxE,CAAA;QACH,CAAC;QACD,IAAI,IAAI,OAAO,CAAA;QACf,IAAI,IAAI;YAAE,MAAK;IACjB,CAAC;IAED,yCAAyC;IACzC,MAAM,OAAO,GAAG,WAAW,CAAC,MAAM,EAAE,CAAA;IACpC,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,GAAG,eAAe,EAAE,CAAC;QACnD,MAAM,IAAI,KAAK,CACb,qEAAqE;YACnE,GAAG,eAAe,mDAAmD,CACxE,CAAA;IACH,CAAC;IACD,IAAI,IAAI,OAAO,CAAA;IAEf,OAAO,IAAI,CAAA;AACb,CAAC"}

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-declare const _default: "1.18.1";
+declare const _default: "1.18.2-head.59c3f62.1";
 export default _default;

package/dist/version.js

@@ -1,4 +1,4 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.default = '1.18.1';
+exports.default = '1.18.2-head.59c3f62.1';
 //# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -1 +1 @@
-{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":";;AAAA,kBAAe,QAAQ,CAAA"}
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":";;AAAA,kBAAe,uBAAuB,CAAA"}

package/package.json

@@ -2,7 +2,7 @@
   "name": "@clickhouse/client-web",
   "description": "Official JS client for ClickHouse DB - Web API implementation",
   "homepage": "https://clickhouse.com",
-  "version": "1.18.1",
+  "version": "1.18.2-head.59c3f62.1",
   "license": "Apache-2.0",
   "keywords": [
     "clickhouse",
@@ -30,6 +30,6 @@
     "build": "rm -rf dist; tsc"
   },
   "dependencies": {
-    "@clickhouse/client-common": "1.18.1"
+    "@clickhouse/client-common": "1.18.2-head.59c3f62.1"
   }
 }