@hypequery/clickhouse 0.0.0-canary-20260306132943

package/dist/core/query-builder.js

@@ -0,0 +1,495 @@
+import { ClickHouseConnection } from './connection.js';
+import { SQLFormatter } from './formatters/sql-formatter.js';
+import { AggregationFeature } from './features/aggregations.js';
+import { JoinFeature } from './features/joins.js';
+import { FilteringFeature } from './features/filtering.js';
+import { AnalyticsFeature } from './features/analytics.js';
+import { ExecutorFeature } from './features/executor.js';
+import { QueryModifiersFeature } from './features/query-modifiers.js';
+import { FilterValidator } from './validators/filter-validator.js';
+import { createPredicateBuilder, } from './utils/predicate-builder.js';
+import { CrossFilteringFeature } from './features/cross-filtering.js';
+import { executeWithCache } from './cache/cache-manager.js';
+import { substituteParameters } from './utils.js';
+import { mergeCacheOptionsPartial, initializeCacheRuntime } from './cache/utils.js';
+/**
+ * Type guard to check if a config is a client-based configuration.
+ */
+export function isClientConfig(config) {
+    return 'client' in config && config.client !== undefined;
+}
+/**
+ * A type-safe query builder for ClickHouse databases.
+ * The builder carries a single state object that encodes scope, output, and schema metadata.
+ */
+export class QueryBuilder {
+    static relationships;
+    config = {};
+    tableName;
+    state;
+    formatter = new SQLFormatter();
+    aggregations;
+    joins;
+    filtering;
+    analytics;
+    executor;
+    modifiers;
+    crossFiltering;
+    runtime;
+    cacheOptions;
+    constructor(tableName, state, runtime) {
+        this.tableName = tableName;
+        this.state = state;
+        this.runtime = runtime;
+        this.aggregations = new AggregationFeature(this);
+        this.joins = new JoinFeature(this);
+        this.filtering = new FilteringFeature(this);
+        this.analytics = new AnalyticsFeature(this);
+        this.executor = new ExecutorFeature(this);
+        this.modifiers = new QueryModifiersFeature(this);
+        this.crossFiltering = new CrossFilteringFeature(this);
+    }
+    fork(state, config) {
+        const builder = new QueryBuilder(this.tableName, state, this.runtime);
+        builder.config = { ...config };
+        builder.cacheOptions = this.cacheOptions;
+        return builder;
+    }
+    debug() {
+        console.log('Current Type:', {
+            state: this.state,
+            config: this.config
+        });
+        return this;
+    }
+    cache(options) {
+        if (options === false) {
+            this.cacheOptions = { mode: 'no-store', ttlMs: 0, staleTtlMs: 0, cacheTimeMs: 0 };
+            return this;
+        }
+        this.cacheOptions = mergeCacheOptionsPartial(this.cacheOptions, options);
+        return this;
+    }
+    // --- Analytics Helper: Add a CTE.
+    withCTE(alias, subquery) {
+        this.config = this.analytics.addCTE(alias, subquery);
+        return this;
+    }
+    // --- Analytics Helper: Add a scalar WITH alias.
+    withScalar(alias, expressionBuilder) {
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(alias)) {
+            throw new Error(`Invalid scalar alias "${alias}". Use an unquoted SQL identifier (letters, numbers, underscore; cannot start with a number).`);
+        }
+        const expression = expressionBuilder(createPredicateBuilder());
+        const nextConfig = this.analytics.addScalar(alias, expression);
+        const nextState = {
+            ...this.state,
+            scalars: {
+                ...this.state.scalars,
+                [alias]: undefined,
+            },
+        };
+        const builder = new QueryBuilder(this.tableName, nextState, this.runtime);
+        builder.config = { ...nextConfig };
+        builder.cacheOptions = this.cacheOptions;
+        return builder;
+    }
+    /**
+   * Groups results by a time interval using a specified ClickHouse function.
+   *
+   * @param column - The column containing the date or timestamp.
+   * @param interval - The interval value. For example, "1 day" or "15 minute".
+   *                   This is only used when the method is 'toStartOfInterval'.
+   * @param method - The time bucketing function to use.
+   *                 Defaults to 'toStartOfInterval'.
+   *                 Other valid values include 'toStartOfMinute', 'toStartOfHour',
+   *                 'toStartOfDay', 'toStartOfWeek', 'toStartOfMonth', 'toStartOfQuarter', and 'toStartOfYear'.
+   * @returns The current QueryBuilder instance.
+   */
+    groupByTimeInterval(column, interval, method = 'toStartOfInterval') {
+        this.config = this.analytics.addTimeInterval(String(column), interval, method);
+        return this;
+    }
+    // --- Analytics Helper: Add a raw SQL fragment.
+    raw(sql) {
+        // Use raw() to inject SQL that isn't supported by the builder.
+        // Use with caution.
+        this.config.having = this.config.having || [];
+        this.config.having.push(sql);
+        return this;
+    }
+    // --- Analytics Helper: Add query settings.
+    settings(opts) {
+        this.config = this.analytics.addSettings(opts);
+        return this;
+    }
+    applyCrossFilters(crossFilter) {
+        const normalized = crossFilter;
+        this.config = this.crossFiltering.applyCrossFilters(normalized);
+        return this;
+    }
+    select(columnsOrAsterisk) {
+        if (columnsOrAsterisk === '*') {
+            const nextState = {
+                ...this.state,
+                output: {}
+            };
+            const nextConfig = {
+                ...this.config,
+                select: ['*'],
+                orderBy: this.config.orderBy?.map(({ column, direction }) => ({
+                    column: String(column),
+                    direction
+                }))
+            };
+            return this.fork(nextState, nextConfig);
+        }
+        const columns = columnsOrAsterisk;
+        const processedColumns = columns.map(col => {
+            if (typeof col === 'object' && col !== null && '__type' in col) {
+                return col.toSql();
+            }
+            return String(col);
+        });
+        const nextState = {
+            ...this.state,
+            output: {}
+        };
+        const nextConfig = {
+            ...this.config,
+            select: processedColumns,
+            orderBy: this.config.orderBy?.map(({ column, direction }) => ({
+                column: String(column),
+                direction
+            }))
+        };
+        return this.fork(nextState, nextConfig);
+    }
+    selectConst(...columns) {
+        return this.select(columns);
+    }
+    sum(column, alias) {
+        return this.applyAggregation(column, alias, 'sum', (col, finalAlias) => this.aggregations.sum(col, finalAlias));
+    }
+    count(column, alias) {
+        return this.applyAggregation(column, alias, 'count', (col, finalAlias) => this.aggregations.count(col, finalAlias));
+    }
+    avg(column, alias) {
+        return this.applyAggregation(column, alias, 'avg', (col, finalAlias) => this.aggregations.avg(col, finalAlias));
+    }
+    min(column, alias) {
+        return this.applyAggregation(column, alias, 'min', (col, finalAlias) => this.aggregations.min(col, finalAlias));
+    }
+    max(column, alias) {
+        return this.applyAggregation(column, alias, 'max', (col, finalAlias) => this.aggregations.max(col, finalAlias));
+    }
+    applyAggregation(column, alias, suffix, updater) {
+        const columnName = String(column);
+        const finalAlias = (alias || `${columnName}_${suffix}`);
+        const nextState = {
+            ...this.state,
+            output: {}
+        };
+        const nextConfig = updater(columnName, finalAlias);
+        return this.fork(nextState, nextConfig);
+    }
+    // Make needed properties accessible to features
+    getTableName() {
+        return this.tableName;
+    }
+    getFormatter() {
+        return this.formatter;
+    }
+    getRuntimeContext() {
+        return this.runtime;
+    }
+    getCacheOptions() {
+        return this.cacheOptions;
+    }
+    getExecutor() {
+        return this.executor;
+    }
+    // Delegate execution methods to feature
+    toSQL() {
+        return this.executor.toSQL();
+    }
+    toSQLWithParams() {
+        return this.executor.toSQLWithParams();
+    }
+    execute(options) {
+        return executeWithCache(this, options);
+    }
+    async stream() {
+        return this.executor.stream();
+    }
+    /**
+     * Processes each row in a stream with the provided callback function
+     * @param callback Function to call for each row in the stream
+     */
+    async streamForEach(callback) {
+        const stream = await this.stream();
+        const reader = stream.getReader();
+        try {
+            while (true) {
+                const { done, value: rows } = await reader.read();
+                if (done)
+                    break;
+                for (const row of rows) {
+                    await callback(row);
+                }
+            }
+        }
+        finally {
+            reader.releaseLock();
+        }
+    }
+    validateFilterValue(column, operator, value) {
+        // Handle tuple columns
+        if (Array.isArray(column)) {
+            // For tuple operations, we don't validate individual column types
+            // as they might be cross-table references
+            return;
+        }
+        // Skip validation for advanced IN operators - they handle their own validation
+        const advancedInOperators = [
+            'globalIn', 'globalNotIn', 'inSubquery', 'globalInSubquery',
+            'inTable', 'globalInTable', 'inTuple', 'globalInTuple'
+        ];
+        if (advancedInOperators.includes(operator)) {
+            return;
+        }
+        const columnName = String(column);
+        if (FilterValidator.validateJoinedColumn(columnName))
+            return;
+        const baseColumns = this.state.base;
+        const columnType = baseColumns[columnName];
+        FilterValidator.validateFilterCondition({ column: columnName, operator, value }, columnType);
+    }
+    where(columnOrColumns, operator, value) {
+        if (typeof columnOrColumns === 'function') {
+            const expression = columnOrColumns(createPredicateBuilder());
+            this.config = this.filtering.addExpressionCondition('AND', expression);
+            return this;
+        }
+        if (operator === undefined) {
+            throw new Error('Operator is required when specifying a column for where()');
+        }
+        // Handle tuple operations
+        if (Array.isArray(columnOrColumns) && (operator === 'inTuple' || operator === 'globalInTuple')) {
+            const columns = columnOrColumns;
+            this.validateFilterValue(columns, operator, value);
+            this.config = this.filtering.addCondition('AND', columns.map(String), operator, value);
+            return this;
+        }
+        const column = columnOrColumns;
+        this.validateFilterValue(column, operator, value);
+        this.config = this.filtering.addCondition('AND', String(column), operator, value);
+        return this;
+    }
+    orWhere(columnOrColumns, operator, value) {
+        if (typeof columnOrColumns === 'function') {
+            const expression = columnOrColumns(createPredicateBuilder());
+            this.config = this.filtering.addExpressionCondition('OR', expression);
+            return this;
+        }
+        if (operator === undefined) {
+            throw new Error('Operator is required when specifying a column for orWhere()');
+        }
+        if (Array.isArray(columnOrColumns) && (operator === 'inTuple' || operator === 'globalInTuple')) {
+            const columns = columnOrColumns;
+            this.validateFilterValue(columns, operator, value);
+            this.config = this.filtering.addCondition('OR', columns.map(String), operator, value);
+            return this;
+        }
+        const column = columnOrColumns;
+        this.validateFilterValue(column, operator, value);
+        this.config = this.filtering.addCondition('OR', String(column), operator, value);
+        return this;
+    }
+    /**
+     * Creates a parenthesized group of WHERE conditions joined with AND/OR operators.
+     * @param {Function} callback - Function that builds the conditions within the group
+     * @returns {this} The current QueryBuilder instance
+     * @example
+     * ```ts
+     * builder.whereGroup(qb => {
+     *   qb.where('status', 'eq', 'active').orWhere('status', 'eq', 'pending');
+     * })
+     * ```
+     */
+    whereGroup(callback) {
+        this.config = this.filtering.startWhereGroup();
+        callback(this);
+        this.config = this.filtering.endWhereGroup();
+        return this;
+    }
+    /**
+     * Creates a parenthesized group of WHERE conditions joined with OR operator.
+     * @param {Function} callback - Function that builds the conditions within the group
+     * @returns {this} The current QueryBuilder instance
+     * @example
+     * ```ts
+     * builder.orWhereGroup(qb => {
+     *   qb.where('status', 'eq', 'active').orWhere('status', 'eq', 'pending');
+     * })
+     * ```
+     */
+    orWhereGroup(callback) {
+        this.config = this.filtering.startOrWhereGroup();
+        callback(this);
+        this.config = this.filtering.endWhereGroup();
+        return this;
+    }
+    /**
+     * Adds a GROUP BY clause.
+     * @param {keyof T | Array<keyof T>} columns - Column(s) to group by
+     * @returns {this} The current QueryBuilder instance
+     * @example
+     * ```ts
+     * builder.groupBy(['category', 'status'])
+     * ```
+     */
+    groupBy(columns) {
+        const normalized = Array.isArray(columns) ? columns.map(String) : String(columns);
+        this.config = this.modifiers.addGroupBy(normalized);
+        return this;
+    }
+    limit(count) {
+        this.config = this.modifiers.addLimit(count);
+        return this;
+    }
+    offset(count) {
+        this.config = this.modifiers.addOffset(count);
+        return this;
+    }
+    /**
+     * Adds an ORDER BY clause.
+     * @param {keyof T} column - The column to order by
+     * @param {OrderDirection} [direction='ASC'] - The sort direction
+     * @returns {this} The current QueryBuilder instance
+     * @example
+     * ```ts
+     * builder.orderBy('created_at', 'DESC')
+     * ```
+     */
+    orderBy(column, direction = 'ASC') {
+        this.config = this.modifiers.addOrderBy(String(column), direction);
+        return this;
+    }
+    /**
+     * Adds a HAVING clause for filtering grouped results.
+     * @param {string} condition - The HAVING condition
+     * @returns {this} The current QueryBuilder instance
+     * @example
+     * ```ts
+     * builder.having('COUNT(*) > 5')
+     * ```
+     */
+    having(condition, parameters) {
+        this.config = this.modifiers.addHaving(condition, parameters);
+        return this;
+    }
+    distinct() {
+        this.config = this.modifiers.setDistinct();
+        return this;
+    }
+    whereBetween(column, [min, max]) {
+        if (min === null || max === null) {
+            throw new Error('BETWEEN values cannot be null');
+        }
+        return this.where(column, 'between', [min, max]);
+    }
+    innerJoin(table, leftColumn, rightColumn, alias) {
+        return this.applyJoin('INNER', table, leftColumn, rightColumn, alias);
+    }
+    leftJoin(table, leftColumn, rightColumn, alias) {
+        return this.applyJoin('LEFT', table, leftColumn, rightColumn, alias);
+    }
+    rightJoin(table, leftColumn, rightColumn, alias) {
+        return this.applyJoin('RIGHT', table, leftColumn, rightColumn, alias);
+    }
+    fullJoin(table, leftColumn, rightColumn, alias) {
+        return this.applyJoin('FULL', table, leftColumn, rightColumn, alias);
+    }
+    applyJoin(type, table, leftColumn, rightColumn, alias) {
+        const nextState = {
+            ...this.state,
+            aliases: alias ? { ...this.state.aliases, [alias]: table } : this.state.aliases
+        };
+        const nextConfig = this.joins.addJoin(type, table, String(leftColumn), rightColumn, alias);
+        return this.fork(nextState, nextConfig);
+    }
+    // Make config accessible to features
+    getConfig() {
+        return this.config;
+    }
+    static setJoinRelationships(relationships) {
+        this.relationships = relationships;
+    }
+    /**
+     * Apply a predefined join relationship
+     */
+    withRelation(name, options) {
+        const relationships = QueryBuilder.relationships;
+        if (!relationships) {
+            throw new Error('Join relationships have not been initialized. Call QueryBuilder.setJoinRelationships first.');
+        }
+        const path = relationships.get(name);
+        if (!path) {
+            throw new Error(`Join relationship '${name}' not found`);
+        }
+        const applyJoin = (joinPath) => {
+            const type = options?.type || joinPath.type || 'INNER';
+            const alias = options?.alias || joinPath.alias;
+            const table = String(joinPath.to);
+            const rightColumn = `${table}.${joinPath.rightColumn}`;
+            this.config = this.joins.addJoin(type, table, joinPath.leftColumn, rightColumn, alias);
+        };
+        if (Array.isArray(path)) {
+            path.forEach(applyJoin);
+        }
+        else {
+            applyJoin(path);
+        }
+        return this;
+    }
+}
+function deriveNamespace(config) {
+    if (isClientConfig(config)) {
+        return 'client';
+    }
+    const host = 'host' in config ? config.host : 'unknown-host';
+    const database = 'database' in config ? config.database : 'default';
+    const username = 'username' in config ? config.username : 'default';
+    return `${host || 'unknown-host'}|${database || 'default'}|${username || 'default'}`;
+}
+export function createQueryBuilder(config) {
+    const { cache: cacheConfig, ...connectionConfig } = config;
+    ClickHouseConnection.initialize(connectionConfig);
+    const namespace = cacheConfig?.namespace || deriveNamespace(connectionConfig);
+    const { runtime, cacheController } = initializeCacheRuntime(cacheConfig, namespace);
+    return {
+        cache: cacheController,
+        async rawQuery(sql, params = []) {
+            const client = ClickHouseConnection.getClient();
+            const finalSQL = substituteParameters(sql, params);
+            const result = await client.query({
+                query: finalSQL,
+                format: 'JSONEachRow'
+            });
+            return result.json();
+        },
+        table(tableName) {
+            const state = {
+                schema: {},
+                tables: tableName,
+                output: {},
+                baseTable: tableName,
+                base: {},
+                aliases: {},
+                scalars: {}
+            };
+            return new QueryBuilder(tableName, state, runtime);
+        }
+    };
+}

package/dist/core/tests/index.d.ts

@@ -0,0 +1,2 @@
+export * from './test-utils.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/core/tests/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/tests/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC"}

package/dist/core/tests/index.js

@@ -0,0 +1 @@
+export * from './test-utils.js';

package/dist/core/tests/integration/setup.d.ts

@@ -0,0 +1,48 @@
+export declare const TEST_CONNECTION_CONFIG: {
+    host: string;
+    user: string;
+    password: string;
+    database: string;
+};
+export declare const initializeTestConnection: () => Promise<{
+    cache: import("../../cache/controller.js").CacheController;
+    rawQuery<TResult = any>(sql: string, params?: unknown[]): Promise<TResult[][]>;
+    table<TableName extends never>(tableName: TableName): import("../../query-builder.js").SelectQB<import("../../types/builder-state.js").SchemaDefinition<unknown>, TableName, import("../../../index.js").TableRecord<import("../../types/builder-state.js").SchemaDefinition<unknown>[TableName]>, TableName>;
+}>;
+export declare const ensureConnectionInitialized: () => import("@clickhouse/client").ClickHouseClient | import("@clickhouse/client-web").ClickHouseClient;
+export declare const isDockerAvailable: () => Promise<boolean>;
+export declare const isDockerComposeAvailable: () => Promise<boolean>;
+export declare const isContainerRunning: (containerName: string) => Promise<boolean>;
+export declare const isClickHouseReady: () => Promise<boolean>;
+export declare const startClickHouseContainer: () => Promise<void>;
+export declare const waitForClickHouse: (maxAttempts?: number, retryInterval?: number) => Promise<void>;
+export declare const stopClickHouseContainer: () => Promise<void>;
+export interface TestSchemaType {
+    test_table: Array<{
+        id: number;
+        name: string;
+        category: string;
+        price: number;
+        created_at: string;
+        is_active: boolean;
+    }>;
+    users: Array<{
+        id: number;
+        user_name: string;
+        email: string;
+        status: string;
+        created_at: string;
+    }>;
+    orders: Array<{
+        id: number;
+        user_id: number;
+        product_id: number;
+        quantity: number;
+        total: number;
+        status: string;
+        created_at: string;
+    }>;
+}
+export declare const TEST_DATA: TestSchemaType;
+export declare const setupTestDatabase: () => Promise<void>;
+//# sourceMappingURL=setup.d.ts.map

package/dist/core/tests/integration/setup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../../../../src/core/tests/integration/setup.ts"],"names":[],"mappings":"AAgDA,eAAO,MAAM,sBAAsB;;;;;CAAS,CAAC;AAG7C,eAAO,MAAM,wBAAwB;;;;EAyBpC,CAAC;AAGF,eAAO,MAAM,2BAA2B,yGAevC,CAAC;AAGF,eAAO,MAAM,iBAAiB,QAAa,OAAO,CAAC,OAAO,CAOzD,CAAC;AAGF,eAAO,MAAM,wBAAwB,QAAa,OAAO,CAAC,OAAO,CAahE,CAAC;AAGF,eAAO,MAAM,kBAAkB,GAAU,eAAe,MAAM,KAAG,OAAO,CAAC,OAAO,CAO/E,CAAC;AAGF,eAAO,MAAM,iBAAiB,QAAa,OAAO,CAAC,OAAO,CAQzD,CAAC;AAGF,eAAO,MAAM,wBAAwB,QAAa,OAAO,CAAC,IAAI,CAwC7D,CAAC;AAGF,eAAO,MAAM,iBAAiB,GAC5B,oBAAgB,EAChB,sBAAoB,KACnB,OAAO,CAAC,IAAI,CAad,CAAC;AAGF,eAAO,MAAM,uBAAuB,QAAa,OAAO,CAAC,IAAI,CA0B5D,CAAC;AAGF,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,KAAK,CAAC;QAChB,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;QACb,QAAQ,EAAE,MAAM,CAAC;QACjB,KAAK,EAAE,MAAM,CAAC;QACd,UAAU,EAAE,MAAM,CAAC;QACnB,SAAS,EAAE,OAAO,CAAC;KACpB,CAAC,CAAC;IACH,KAAK,EAAE,KAAK,CAAC;QACX,EAAE,EAAE,MAAM,CAAC;QACX,SAAS,EAAE,MAAM,CAAC;QAClB,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,MAAM,CAAC;QACf,UAAU,EAAE,MAAM,CAAC;KACpB,CAAC,CAAC;IACH,MAAM,EAAE,KAAK,CAAC;QACZ,EAAE,EAAE,MAAM,CAAC;QACX,OAAO,EAAE,MAAM,CAAC;QAChB,UAAU,EAAE,MAAM,CAAC;QACnB,QAAQ,EAAE,MAAM,CAAC;QACjB,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,MAAM,CAAC;QACf,UAAU,EAAE,MAAM,CAAC;KACpB,CAAC,CAAC;CACJ;AAkDD,eAAO,MAAM,SAAS,EAAE,cAAoC,CAAC;AAK7D,eAAO,MAAM,iBAAiB,QAAa,OAAO,CAAC,IAAI,CAkGtD,CAAC"}