@svadmin/clickhouse 0.0.0-stage → 0.2.1

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "@svadmin/clickhouse",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.1",
+  "description": "ClickHouse analytical DataProvider adapter for svadmin",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "src/**/*.ts",
+    "!src/**/*.test.*",
+    "!src/**/*.spec.*"
+  ],
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "peerDependencies": {
+    "@svadmin/core": "^0.79.0"
+  },
+  "keywords": [
+    "svadmin",
+    "clickhouse",
+    "analytics",
+    "data-provider",
+    "olap"
+  ],
+  "license": "MIT",
+  "author": "zuohuadong",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vibeunion/svadmin.git",
+    "directory": "packages/clickhouse"
+  },
+  "homepage": "https://github.com/vibeunion/svadmin#readme",
+  "bugs": {
+    "url": "https://github.com/vibeunion/svadmin/issues"
+  },
+  "svadmin": {
+    "capabilities": [
+      "data"
+    ],
+    "core": "^0.55.0",
+    "stability": "stable",
+    "migration": null
+  }
+}

package/src/clickhouse-data-provider.ts

@@ -0,0 +1,289 @@
+import type {
+  DataProvider,
+  GetListParams,
+  GetListResult,
+  GetOneParams,
+  GetOneResult,
+  CreateParams,
+  CreateResult,
+  UpdateParams,
+  UpdateResult,
+  DeleteParams,
+  DeleteResult,
+  CustomParams,
+  CustomResult,
+  BaseRecord,
+  Filter,
+  Sort,
+} from '@svadmin/core';
+
+export interface ClickHouseClientLike {
+  query: (params: { query: string; format?: string; query_params?: Record<string, unknown> }) => Promise<{
+    json: () => Promise<unknown>;
+  }>;
+}
+
+export interface ClickHouseOptions {
+  /** ClickHouse HTTP endpoint URL if no client is provided, e.g. 'http://localhost:8123' */
+  url?: string;
+  /** Optional database name */
+  database?: string;
+  /** Optional HTTP basic authorization header */
+  authorization?: string;
+  /** Custom fetch function */
+  fetch?: typeof fetch;
+}
+
+function sanitizeIdentifier(name: string): string {
+  if (!/^[a-zA-Z0-9_]+$/.test(name)) {
+    throw new Error(`Invalid ClickHouse table or column name: ${name}`);
+  }
+  return name;
+}
+
+function quoteString(value: string): string {
+  return `'${value.replaceAll('\\', '\\\\').replaceAll("'", "\\'")}'`;
+}
+
+function quoteValue(value: unknown): string {
+  if (typeof value === 'string') return quoteString(value);
+  if (typeof value === 'number') {
+    if (!Number.isFinite(value)) throw new Error('Unsupported ClickHouse filter value: expected a finite number');
+    return String(value);
+  }
+  if (typeof value === 'boolean') return value ? '1' : '0';
+  if (value === null) return 'NULL';
+  throw new Error(`Unsupported ClickHouse filter value: ${String(value)}`);
+}
+
+function quoteList(value: unknown, operator: string): string {
+  if (!Array.isArray(value) || value.length === 0) {
+    throw new Error(`Unsupported ClickHouse filter operator ${operator}: expected a non-empty array`);
+  }
+  return value.map(quoteValue).join(', ');
+}
+
+function escapedPattern(value: unknown): string {
+  return String(value).replaceAll('\\', '\\\\').replaceAll("'", "\\'");
+}
+
+function buildFilterClause(filter: Filter): string {
+  if ('field' in filter) {
+    const field = sanitizeIdentifier(filter.field);
+    const value = filter.value;
+    switch (filter.operator) {
+      case 'eq':
+      case 'eqs':
+        return `${field} = ${quoteValue(value)}`;
+      case 'ne':
+      case 'nes':
+        return `${field} != ${quoteValue(value)}`;
+      case 'lt':
+        return `${field} < ${quoteValue(value)}`;
+      case 'lte':
+        return `${field} <= ${quoteValue(value)}`;
+      case 'gt':
+        return `${field} > ${quoteValue(value)}`;
+      case 'gte':
+        return `${field} >= ${quoteValue(value)}`;
+      case 'in':
+        return `${field} IN (${quoteList(value, filter.operator)})`;
+      case 'nin':
+        return `${field} NOT IN (${quoteList(value, filter.operator)})`;
+      case 'ina':
+        return `hasAll(${field}, [${quoteList(value, filter.operator)}])`;
+      case 'nina':
+        return `NOT hasAll(${field}, [${quoteList(value, filter.operator)}])`;
+      case 'contains':
+      case 'containss':
+        return `${field} LIKE '%${escapedPattern(value)}%'`;
+      case 'ncontains':
+      case 'ncontainss':
+        return `${field} NOT LIKE '%${escapedPattern(value)}%'`;
+      case 'startswith':
+      case 'startswiths':
+        return `${field} LIKE '${escapedPattern(value)}%'`;
+      case 'nstartswith':
+      case 'nstartswiths':
+        return `${field} NOT LIKE '${escapedPattern(value)}%'`;
+      case 'endswith':
+      case 'endswiths':
+        return `${field} LIKE '%${escapedPattern(value)}'`;
+      case 'nendswith':
+      case 'nendswiths':
+        return `${field} NOT LIKE '%${escapedPattern(value)}'`;
+      case 'null':
+        return `${field} IS NULL`;
+      case 'nnull':
+        return `${field} IS NOT NULL`;
+      case 'between':
+      case 'nbetween': {
+        if (!Array.isArray(value) || value.length !== 2) {
+          throw new Error(`Unsupported ClickHouse filter operator ${filter.operator}: expected two values`);
+        }
+        const clause = `${field} BETWEEN ${quoteValue(value[0])} AND ${quoteValue(value[1])}`;
+        return filter.operator === 'between' ? clause : `NOT (${clause})`;
+      }
+      default:
+        throw new Error(`Unsupported ClickHouse filter operator: ${String((filter as { operator: unknown }).operator)}`);
+    }
+  }
+
+  if (!Array.isArray(filter.value) || filter.value.length === 0) {
+    throw new Error(`Unsupported ClickHouse logical operator ${filter.operator}: expected a non-empty filter group`);
+  }
+  const clauses = filter.value.map(buildFilterClause);
+  return `(${clauses.join(` ${filter.operator.toUpperCase()} `)})`;
+}
+
+function buildWhereClause(filters?: Filter[]): string {
+  if (!filters || filters.length === 0) return '';
+  return `WHERE ${filters.map(buildFilterClause).join(' AND ')}`;
+}
+
+function buildOrderBy(sorters?: Sort[]): string {
+  if (!sorters || sorters.length === 0) return '';
+  const parts = sorters.map((s: Sort) => `${sanitizeIdentifier(s.field)} ${s.order.toUpperCase()}`);
+  return `ORDER BY ${parts.join(', ')}`;
+}
+
+export function createClickHouseDataProvider(
+  clientOrOptions: ClickHouseClientLike | ClickHouseOptions,
+): DataProvider {
+  const isClient = 'query' in clientOrOptions && typeof clientOrOptions.query === 'function';
+  const customFetch = !isClient ? (clientOrOptions as ClickHouseOptions).fetch ?? fetch : fetch;
+  const baseUrl = !isClient ? (clientOrOptions as ClickHouseOptions).url ?? 'http://localhost:8123' : '';
+  const database = !isClient ? (clientOrOptions as ClickHouseOptions).database : undefined;
+  const authHeader = !isClient ? (clientOrOptions as ClickHouseOptions).authorization : undefined;
+
+  async function executeSql(sql: string): Promise<Record<string, unknown>[]> {
+    if (isClient) {
+      const res = await (clientOrOptions as ClickHouseClientLike).query({
+        query: sql,
+        format: 'JSON',
+      });
+      const data = (await res.json()) as { data?: Record<string, unknown>[] };
+      return data.data ?? [];
+    }
+
+    const headers: Record<string, string> = { 'Content-Type': 'text/plain' };
+    if (authHeader) headers['Authorization'] = authHeader;
+    if (database) headers['X-ClickHouse-Database'] = database;
+
+    const response = await customFetch(`${baseUrl}/?default_format=JSON`, {
+      method: 'POST',
+      headers,
+      body: sql,
+    });
+
+    if (!response.ok) {
+      const errText = await response.text();
+      throw new Error(`ClickHouse query failed (${response.status}): ${errText}`);
+    }
+
+    const body = (await response.json()) as { data?: Record<string, unknown>[] };
+    return body.data ?? [];
+  }
+
+  return {
+    getApiUrl: () => baseUrl,
+
+    async getList<TData extends BaseRecord = BaseRecord>(params: GetListParams): Promise<GetListResult<TData>> {
+      const table = sanitizeIdentifier(params.resource);
+      const where = buildWhereClause(params.filters);
+      const order = buildOrderBy(params.sorters);
+
+      const page = params.pagination?.current ?? 1;
+      const pageSize = params.pagination?.pageSize ?? 20;
+      const offset = (page - 1) * pageSize;
+
+      const dataQuery = `SELECT * FROM ${table} ${where} ${order} LIMIT ${pageSize} OFFSET ${offset} FORMAT JSON`;
+      const countQuery = `SELECT count() AS total FROM ${table} ${where} FORMAT JSON`;
+
+      const [data, countResult] = await Promise.all([
+        executeSql(dataQuery),
+        executeSql(countQuery),
+      ]);
+
+      const firstRow = countResult[0];
+      const countVal = firstRow ? firstRow['total'] : undefined;
+      const total = Number(countVal ?? data.length);
+
+      return {
+        data: data as unknown as TData[],
+        total,
+      };
+    },
+
+    async getOne<TData extends BaseRecord = BaseRecord>(params: GetOneParams): Promise<GetOneResult<TData>> {
+      const table = sanitizeIdentifier(params.resource);
+      const idStr = typeof params.id === 'string' ? quoteString(params.id) : quoteValue(params.id);
+      const sql = `SELECT * FROM ${table} WHERE id = ${idStr} LIMIT 1 FORMAT JSON`;
+      const rows = await executeSql(sql);
+
+      if (rows.length === 0) {
+        throw new Error(`Record with id ${params.id} not found in ${params.resource}`);
+      }
+
+      return {
+        data: rows[0] as unknown as TData,
+      };
+    },
+
+    async create<TData extends BaseRecord = BaseRecord>(params: CreateParams): Promise<CreateResult<TData>> {
+      const table = sanitizeIdentifier(params.resource);
+      const variables = params.variables as Record<string, unknown>;
+      const keys = Object.keys(variables).map(sanitizeIdentifier);
+      const values = Object.values(variables).map((val) =>
+        quoteValue(val),
+      );
+
+      const sql = `INSERT INTO ${table} (${keys.join(', ')}) VALUES (${values.join(', ')})`;
+      await executeSql(sql);
+
+      return {
+        data: variables as unknown as TData,
+      };
+    },
+
+    async update<TData extends BaseRecord = BaseRecord>(params: UpdateParams): Promise<UpdateResult<TData>> {
+      const table = sanitizeIdentifier(params.resource);
+      const idStr = typeof params.id === 'string' ? quoteString(params.id) : quoteValue(params.id);
+      const variables = params.variables as Record<string, unknown>;
+      const assignments = Object.entries(variables).map(([k, v]) => {
+        const val = quoteValue(v);
+        return `${sanitizeIdentifier(k)} = ${val}`;
+      });
+
+      const sql = `ALTER TABLE ${table} UPDATE ${assignments.join(', ')} WHERE id = ${idStr}`;
+      await executeSql(sql);
+
+      return {
+        data: { id: params.id, ...variables } as unknown as TData,
+      };
+    },
+
+    async deleteOne<TData extends BaseRecord = BaseRecord>(params: DeleteParams): Promise<DeleteResult<TData>> {
+      const table = sanitizeIdentifier(params.resource);
+      const idStr = typeof params.id === 'string' ? quoteString(params.id) : quoteValue(params.id);
+      const sql = `ALTER TABLE ${table} DELETE WHERE id = ${idStr}`;
+      await executeSql(sql);
+
+      return {
+        data: { id: params.id } as unknown as TData,
+      };
+    },
+
+    async custom<TData = unknown>(params: CustomParams): Promise<CustomResult<TData>> {
+      const metaQuery = params.meta && typeof params.meta['query'] === 'string' ? (params.meta['query'] as string) : undefined;
+      const sql = metaQuery ?? params.url;
+      if (!sql) {
+        throw new Error('ClickHouse custom query requires params.meta.query or params.url');
+      }
+      const data = await executeSql(sql);
+      return {
+        data: data as unknown as TData,
+      };
+    },
+  };
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export { createClickHouseDataProvider } from './clickhouse-data-provider.js';
+export type {
+  ClickHouseClientLike,
+  ClickHouseOptions,
+} from './clickhouse-data-provider.js';

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.