@entrolytics/clickhouse-client 3.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Entrolytics <hey@entrolytics.click>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+import type { EventDBRow } from '@entrolytics/protocol';
+interface Logger {
+    info: (msg: string, ...args: unknown[]) => void;
+    warn: (msg: string, ...args: unknown[]) => void;
+    error: (msg: string, ...args: unknown[]) => void;
+}
+export declare function setClickHouseLogger(customLogger: Logger): void;
+export declare const clickhouse: import("@clickhouse/client").ClickHouseClient;
+export declare function testClickHouseConnection(): Promise<boolean>;
+/**
+ * Insert rows into a ClickHouse table with bounded retry and per-row error tolerance. Retries ONLY
+ * transient errors so a permanent bad-data error fails fast instead of being retried and amplifying
+ * duplicates (WP-6); per-row tolerance prevents one bad row from dropping the batch (WP-2). Used by
+ * every analytics ingest path (events, forms, vitals) so resilience is consistent.
+ */
+export declare function insertWithRetry(table: string, values: readonly unknown[], retries?: number): Promise<void>;
+/** Insert analytics events (events table) with retry + row tolerance. */
+export declare function insertEvents(events: EventDBRow[], retries?: number): Promise<void>;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAA;AAGvD,UAAU,MAAM;IACd,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAA;IAC/C,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAA;IAC/C,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAA;CACjD;AAsBD,wBAAgB,mBAAmB,CAAC,YAAY,EAAE,MAAM,QAEvD;AA+CD,eAAO,MAAM,UAAU,+CAAiC,CAAA;AAGxD,wBAAsB,wBAAwB,qBAW7C;AA6CD;;;;;GAKG;AACH,wBAAsB,eAAe,CACnC,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,SAAS,OAAO,EAAE,EAC1B,OAAO,SAAI,GACV,OAAO,CAAC,IAAI,CAAC,CA8Bf;AAED,yEAAyE;AACzE,wBAAsB,YAAY,CAAC,MAAM,EAAE,UAAU,EAAE,EAAE,OAAO,SAAI,iBAEnE"}

package/dist/index.js

@@ -0,0 +1,153 @@
+import { format } from 'node:util';
+import { createClient } from '@clickhouse/client';
+const defaultLogger = {
+    error: (msg, ...args) => {
+        process.stderr.write(`[clickhouse:error] ${msg}${args.length > 0 ? ` ${format(...args)}` : ''}\n`);
+    },
+    info: (msg, ...args) => {
+        process.stdout.write(`[clickhouse:info] ${msg}${args.length > 0 ? ` ${format(...args)}` : ''}\n`);
+    },
+    warn: (msg, ...args) => {
+        process.stdout.write(`[clickhouse:warn] ${msg}${args.length > 0 ? ` ${format(...args)}` : ''}\n`);
+    },
+};
+let logger = defaultLogger;
+export function setClickHouseLogger(customLogger) {
+    logger = customLogger;
+}
+const clickhouseSettings = {
+    // 30 seconds max execution time for queries
+    max_execution_time: 30,
+};
+/**
+ * Resolve the ClickHouse HTTP endpoint, supporting TLS (CBI-011). Precedence:
+ *
+ * 1. CLICKHOUSE_URL — a full URL (e.g. https://host:8443), used verbatim.
+ * 2. CLICKHOUSE_HOST that already includes a scheme — used verbatim.
+ * 3. Host + port, with the scheme chosen by CLICKHOUSE_SECURE (https on 8443). This lets
+ *    managed/TLS-only ClickHouse (e.g. ClickHouse Cloud) be configured purely through env instead
+ *    of being hardcoded to http://.
+ */
+function resolveClickHouseUrl() {
+    const fullUrl = process.env.CLICKHOUSE_URL;
+    if (fullUrl)
+        return fullUrl;
+    const host = process.env.CLICKHOUSE_HOST ?? 'localhost';
+    if (/^https?:\/\//i.test(host))
+        return host;
+    const secure = ['1', 'true', 'yes', 'on'].includes((process.env.CLICKHOUSE_SECURE ?? '').trim().toLowerCase());
+    const protocol = secure ? 'https' : 'http';
+    const port = process.env.CLICKHOUSE_PORT ?? (secure ? '8443' : '8123');
+    return `${protocol}://${host}:${port}`;
+}
+const clickhouseConfig = {
+    clickhouse_settings: clickhouseSettings,
+    compression: {
+        request: true,
+        response: true,
+    },
+    database: process.env.CLICKHOUSE_DATABASE ?? 'analytics',
+    keep_alive: {
+        enabled: true,
+    },
+    password: process.env.CLICKHOUSE_PASSWORD ?? '',
+    request_timeout: 30_000,
+    url: resolveClickHouseUrl(),
+    username: process.env.CLICKHOUSE_USER ?? 'default',
+};
+export const clickhouse = createClient(clickhouseConfig);
+// Test connection
+export async function testClickHouseConnection() {
+    try {
+        await clickhouse.query({
+            query: 'SELECT 1',
+        });
+        logger.info('✅ ClickHouse connection successful');
+        return true;
+    }
+    catch (err) {
+        logger.error('❌ ClickHouse connection failed:', err);
+        return false;
+    }
+}
+/**
+ * Per-row error tolerance for analytics inserts. ClickHouse rejects a JSONEachRow batch atomically
+ * by default, so a single malformed row would drop up to ~100 good events. These settings let the
+ * server skip a small number of broken rows (and unknown fields) instead of failing the whole batch
+ * (WP-2). The ratio cap keeps a genuinely corrupt batch from silently disappearing.
+ */
+const rowToleranceSettings = {
+    // Buffer small producer batches server-side while still acknowledging only after the flush
+    // succeeds. This reduces part creation without weakening delivery guarantees.
+    async_insert: 1,
+    // UInt64 settings are typed as strings, Float settings as numbers by the client.
+    input_format_allow_errors_num: '10',
+    input_format_allow_errors_ratio: 0.1,
+    input_format_skip_unknown_fields: 1,
+    wait_for_async_insert: 1,
+};
+/**
+ * Heuristic: is this ClickHouse error worth retrying? Connection/timeout/server (5xx-like) errors
+ * are transient; parse/type/syntax errors are permanent and retrying them only amplifies
+ * duplicate-insert risk (WP-6).
+ */
+function isRetryableClickHouseError(err) {
+    const message = (err instanceof Error ? err.message : typeof err === 'string' ? err : '').toLowerCase();
+    if (!message)
+        return true;
+    const permanentSignals = [
+        'cannot parse',
+        'type mismatch',
+        'unknown field',
+        'syntax error',
+        'cannot convert',
+        'value is too',
+        'illegal',
+        'bad request',
+    ];
+    if (permanentSignals.some((signal) => message.includes(signal)))
+        return false;
+    // Explicit 4xx status in the message → client error, do not retry.
+    if (/\b4\d{2}\b/.test(message))
+        return false;
+    return true;
+}
+/**
+ * Insert rows into a ClickHouse table with bounded retry and per-row error tolerance. Retries ONLY
+ * transient errors so a permanent bad-data error fails fast instead of being retried and amplifying
+ * duplicates (WP-6); per-row tolerance prevents one bad row from dropping the batch (WP-2). Used by
+ * every analytics ingest path (events, forms, vitals) so resilience is consistent.
+ */
+export async function insertWithRetry(table, values, retries = 3) {
+    if (values.length === 0)
+        return;
+    let lastError;
+    for (let i = 0; i < retries; i++) {
+        try {
+            await clickhouse.insert({
+                clickhouse_settings: rowToleranceSettings,
+                format: 'JSONEachRow',
+                table,
+                values: [...values],
+            });
+            return;
+        }
+        catch (err) {
+            lastError = err;
+            if (!isRetryableClickHouseError(err)) {
+                logger.error(`❌ ClickHouse insert into ${table} failed (non-retryable)`, err);
+                throw err;
+            }
+            logger.warn(`⚠️ ClickHouse insert into ${table} failed (attempt ${i + 1}/${retries}):`, err);
+            // Exponential backoff: 300ms, 600ms, 1200ms
+            await new Promise((resolve) => setTimeout(resolve, 300 * 2 ** i));
+        }
+    }
+    logger.error(`❌ ClickHouse insert into ${table} failed after retries`, lastError);
+    throw lastError;
+}
+/** Insert analytics events (events table) with retry + row tolerance. */
+export async function insertEvents(events, retries = 3) {
+    await insertWithRetry('analytics.events', events, retries);
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@entrolytics/clickhouse-client",
+  "version": "3.0.0",
+  "files": [
+    "dist",
+    "!dist/*.tsbuildinfo",
+    "package.json"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@clickhouse/client": "^1.24.0-head.443b2f0.1",
+    "@entrolytics/protocol": "^3.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.5.0",
+    "typescript": "next"
+  },
+  "scripts": {
+    "build": "tsc",
+    "check-types": "tsc -p tsconfig.check.json"
+  }
+}