@hypequery/clickhouse 0.2.1

package/dist/core/query-builder.js

@@ -0,0 +1,372 @@
+import { ClickHouseConnection } from './connection';
+import { SQLFormatter } from './formatters/sql-formatter';
+import { AggregationFeature } from './features/aggregations';
+import { JoinFeature } from './features/joins';
+import { FilteringFeature } from './features/filtering';
+import { AnalyticsFeature } from './features/analytics';
+import { ExecutorFeature } from './features/executor';
+import { QueryModifiersFeature } from './features/query-modifiers';
+import { FilterValidator } from './validators/filter-validator';
+import { PaginationFeature } from './features/pagination';
+/**
+ * A type-safe query builder for ClickHouse databases.
+ * @template Schema - The full database schema
+ * @template T - The schema type of the current table
+ * @template HasSelect - Whether a SELECT clause has been applied
+ * @template Aggregations - The type of any aggregation functions applied
+ */
+export class QueryBuilder {
+    constructor(tableName, schema, originalSchema) {
+        this.config = {};
+        this.formatter = new SQLFormatter();
+        this.tableName = tableName;
+        this.schema = schema;
+        this.originalSchema = originalSchema;
+        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.pagination = new PaginationFeature(this);
+    }
+    debug() {
+        console.log('Current Type:', {
+            schema: this.schema,
+            originalSchema: this.originalSchema,
+            config: this.config
+        });
+        return this;
+    }
+    clone() {
+        const newBuilder = new QueryBuilder(this.tableName, this.schema, this.originalSchema);
+        newBuilder.config = { ...this.config };
+        // Initialize features with the new builder
+        newBuilder.aggregations = new AggregationFeature(newBuilder);
+        newBuilder.joins = new JoinFeature(newBuilder);
+        newBuilder.filtering = new FilteringFeature(newBuilder);
+        newBuilder.analytics = new AnalyticsFeature(newBuilder);
+        newBuilder.executor = new ExecutorFeature(newBuilder);
+        newBuilder.modifiers = new QueryModifiersFeature(newBuilder);
+        newBuilder.pagination = new PaginationFeature(newBuilder);
+        return newBuilder;
+    }
+    // --- Analytics Helper: Add a CTE.
+    withCTE(alias, subquery) {
+        this.config = this.analytics.addCTE(alias, subquery);
+        return this;
+    }
+    /**
+   * 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(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;
+    }
+    /**
+     * Applies a set of cross filters to the current query.
+     * All filter conditions from the provided CrossFilter are added to the query.
+     * @param crossFilter - An instance of CrossFilter containing shared filter conditions.
+     * @returns The current QueryBuilder instance.
+     */
+    applyCrossFilters(crossFilter) {
+        const filterGroup = crossFilter.getConditions();
+        filterGroup.conditions.forEach((item) => {
+            if ('column' in item) {
+                this.where(item.column, item.operator, item.value);
+            }
+        });
+        return this;
+    }
+    /**
+     * Selects specific columns from the table.
+     * @template K - The keys/columns to select
+     * @param {K[]} columns - Array of column names to select
+     * @returns {QueryBuilder} A new QueryBuilder instance with updated types
+     * @example
+     * ```ts
+     * builder.select(['id', 'name'])
+     * ```
+     */
+    select(columns) {
+        // Create a new builder with the appropriate type parameters
+        const newBuilder = new QueryBuilder(this.tableName, {
+            name: this.schema.name,
+            columns: {} // We need this cast because we only know the shape at runtime
+        }, this.originalSchema);
+        // Process columns array to handle SqlExpressions and convert to strings
+        const processedColumns = columns.map(col => {
+            if (typeof col === 'object' && col !== null && '__type' in col) {
+                return col.toSql();
+            }
+            return String(col);
+        });
+        newBuilder.config = {
+            ...this.config,
+            select: processedColumns,
+            orderBy: this.config.orderBy?.map(({ column, direction }) => ({
+                column: String(column),
+                direction
+            }))
+        };
+        return newBuilder;
+    }
+    sum(column, alias) {
+        const newBuilder = this.clone();
+        newBuilder.config = this.aggregations.sum(column, alias);
+        return newBuilder;
+    }
+    count(column, alias) {
+        const newBuilder = this.clone();
+        newBuilder.config = this.aggregations.count(column, alias);
+        return newBuilder;
+    }
+    avg(column, alias) {
+        const newBuilder = this.clone();
+        newBuilder.config = this.aggregations.avg(column, alias);
+        return newBuilder;
+    }
+    min(column, alias) {
+        const newBuilder = this.clone();
+        newBuilder.config = this.aggregations.min(column, alias);
+        return newBuilder;
+    }
+    max(column, alias) {
+        const newBuilder = this.clone();
+        newBuilder.config = this.aggregations.max(column, alias);
+        return newBuilder;
+    }
+    // Make needed properties accessible to features
+    getTableName() {
+        return this.tableName;
+    }
+    getFormatter() {
+        return this.formatter;
+    }
+    // Delegate execution methods to feature
+    toSQL() {
+        return this.executor.toSQL();
+    }
+    toSQLWithParams() {
+        return this.executor.toSQLWithParams();
+    }
+    execute() {
+        return this.executor.execute();
+    }
+    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) {
+        if (FilterValidator.validateJoinedColumn(String(column)))
+            return;
+        const columnType = this.schema.columns[column];
+        FilterValidator.validateFilterCondition({ column: String(column), operator, value }, columnType);
+    }
+    /**
+     * Adds a WHERE clause to filter results.
+     * @template K - The column key type
+     * @param {K} column - The column to filter on
+     * @param {FilterOperator} operator - The comparison operator
+     * @param {any} value - The value to compare against
+     * @returns {this} The current QueryBuilder instance
+     * @example
+     * ```ts
+     * builder.where('age', 'gt', 18)
+     * ```
+     */
+    where(column, operator, value) {
+        this.validateFilterValue(column, operator, value);
+        this.config = this.filtering.addCondition('AND', column, operator, value);
+        return this;
+    }
+    orWhere(column, operator, value) {
+        this.config = this.filtering.addCondition('OR', column, operator, value);
+        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) {
+        this.config = this.modifiers.addGroupBy(columns);
+        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(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) {
+        const newBuilder = this.clone();
+        newBuilder.config = this.joins.addJoin('INNER', table, leftColumn, rightColumn, alias);
+        return newBuilder;
+    }
+    leftJoin(table, leftColumn, rightColumn, alias) {
+        const newBuilder = this.clone();
+        newBuilder.config = this.joins.addJoin('LEFT', table, leftColumn, rightColumn, alias);
+        return newBuilder;
+    }
+    rightJoin(table, leftColumn, rightColumn, alias) {
+        const newBuilder = this.clone();
+        newBuilder.config = this.joins.addJoin('RIGHT', table, leftColumn, rightColumn, alias);
+        return newBuilder;
+    }
+    fullJoin(table, leftColumn, rightColumn, alias) {
+        const newBuilder = this.clone();
+        newBuilder.config = this.joins.addJoin('FULL', table, leftColumn, rightColumn, alias);
+        return newBuilder;
+    }
+    // Make config accessible to features
+    getConfig() {
+        return this.config;
+    }
+    /**
+     * Paginates the query results using cursor-based pagination
+     */
+    async paginate(options) {
+        return this.pagination.paginate(options);
+    }
+    /**
+     * Gets the first page of results
+     */
+    async firstPage(pageSize) {
+        return this.pagination.firstPage(pageSize);
+    }
+    /**
+     * Returns an async iterator that yields all pages
+     */
+    iteratePages(pageSize) {
+        return this.pagination.iteratePages(pageSize);
+    }
+    static setJoinRelationships(relationships) {
+        this.relationships = relationships;
+    }
+    /**
+     * Apply a predefined join relationship
+     */
+    withRelation(name, options) {
+        if (!QueryBuilder.relationships) {
+            throw new Error('Join relationships have not been initialized. Call QueryBuilder.setJoinRelationships first.');
+        }
+        const path = QueryBuilder.relationships.get(name);
+        if (!path) {
+            throw new Error(`Join relationship '${name}' not found`);
+        }
+        if (Array.isArray(path)) {
+            // Handle join chain
+            path.forEach(joinPath => {
+                const type = options?.type || joinPath.type || 'INNER';
+                const alias = options?.alias || joinPath.alias;
+                const table = String(joinPath.to);
+                this.config = this.joins.addJoin(type, table, joinPath.leftColumn, `${table}.${joinPath.rightColumn}`, alias);
+            });
+        }
+        else {
+            // Handle single join
+            const type = options?.type || path.type || 'INNER';
+            const alias = options?.alias || path.alias;
+            const table = String(path.to);
+            this.config = this.joins.addJoin(type, table, path.leftColumn, `${table}.${path.rightColumn}`, alias);
+        }
+        return this;
+    }
+}
+export function createQueryBuilder(config) {
+    ClickHouseConnection.initialize(config);
+    return {
+        table(tableName) {
+            return new QueryBuilder(tableName, {
+                name: tableName,
+                columns: {}
+            }, {});
+        }
+    };
+}

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,cAAc,CAAC"}

package/dist/core/tests/index.js

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

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":"AAmBA,MAAM,WAAW,UAAU;IACzB,UAAU,EAAE;QACV,EAAE,EAAE,OAAO,CAAC;QACZ,IAAI,EAAE,QAAQ,CAAC;QACf,KAAK,EAAE,SAAS,CAAC;QACjB,UAAU,EAAE,UAAU,CAAC;QACvB,QAAQ,EAAE,QAAQ,CAAC;QACnB,MAAM,EAAE,OAAO,CAAC;KACjB,CAAC;IACF,KAAK,EAAE;QACL,EAAE,EAAE,OAAO,CAAC;QACZ,SAAS,EAAE,QAAQ,CAAC;QACpB,KAAK,EAAE,QAAQ,CAAC;QAChB,UAAU,EAAE,UAAU,CAAC;QACvB,MAAM,EAAE,QAAQ,CAAC;KAClB,CAAC;IACF,MAAM,EAAE;QACN,EAAE,EAAE,OAAO,CAAC;QACZ,OAAO,EAAE,OAAO,CAAC;QACjB,UAAU,EAAE,OAAO,CAAC;QACpB,QAAQ,EAAE,OAAO,CAAC;QAClB,KAAK,EAAE,SAAS,CAAC;QACjB,MAAM,EAAE,QAAQ,CAAC;QACjB,UAAU,EAAE,UAAU,CAAC;KACxB,CAAC;IACF,QAAQ,EAAE;QACR,EAAE,EAAE,OAAO,CAAC;QACZ,IAAI,EAAE,QAAQ,CAAC;QACf,KAAK,EAAE,SAAS,CAAC;QACjB,QAAQ,EAAE,QAAQ,CAAC;QACnB,WAAW,EAAE,QAAQ,CAAC;KACvB,CAAC;CACH;AAGD,wBAAsB,wBAAwB;;GAwB7C;AAmDD,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAsCrB,CAAC;AAGF,wBAAsB,iBAAiB,kBAuFtC;AAGD,wBAAgB,iBAAiB,IAAI,OAAO,CAO3C;AAGD,wBAAgB,wBAAwB,SAsDvC;AAGD,wBAAgB,uBAAuB,SAYtC"}

package/dist/core/tests/integration/setup.js

@@ -0,0 +1,274 @@
+import { execSync } from 'child_process';
+import { createQueryBuilder } from '../../../index';
+import { ClickHouseConnection } from '../../connection';
+// Configuration for the test ClickHouse instance
+const CLICKHOUSE_HOST = process.env.CLICKHOUSE_TEST_HOST || 'http://localhost:8123';
+const CLICKHOUSE_USER = process.env.CLICKHOUSE_TEST_USER || 'hypequery';
+const CLICKHOUSE_PASSWORD = process.env.CLICKHOUSE_TEST_PASSWORD || 'hypequery_test';
+const CLICKHOUSE_DB = process.env.CLICKHOUSE_TEST_DB || 'test_db';
+// Log connection details for debugging
+console.log('Initializing ClickHouse connection with:', {
+    host: CLICKHOUSE_HOST,
+    user: CLICKHOUSE_USER,
+    password: CLICKHOUSE_PASSWORD ? 'PROVIDED' : 'NOT_PROVIDED',
+    database: CLICKHOUSE_DB
+});
+// Helper to initialize the connection
+export async function initializeTestConnection() {
+    try {
+        ClickHouseConnection.initialize({
+            host: CLICKHOUSE_HOST,
+            username: CLICKHOUSE_USER,
+            password: CLICKHOUSE_PASSWORD,
+            database: CLICKHOUSE_DB
+        });
+        // Test the connection
+        const client = ClickHouseConnection.getClient();
+        await client.ping();
+        console.log('ClickHouse connection successfully established');
+        return createQueryBuilder({
+            host: CLICKHOUSE_HOST,
+            username: CLICKHOUSE_USER,
+            password: CLICKHOUSE_PASSWORD,
+            database: CLICKHOUSE_DB
+        });
+    }
+    catch (error) {
+        console.error('Failed to initialize ClickHouse connection:', error);
+        throw error;
+    }
+}
+// SQL to create test tables
+const CREATE_TEST_TABLE = `
+CREATE TABLE IF NOT EXISTS test_table (
+  id Int32,
+  name String,
+  price Float64,
+  created_at DateTime,
+  category String,
+  active UInt8
+) ENGINE = MergeTree()
+ORDER BY id
+`;
+const CREATE_USERS_TABLE = `
+CREATE TABLE IF NOT EXISTS users (
+  id Int32,
+  user_name String,
+  email String,
+  created_at DateTime,
+  status String
+) ENGINE = MergeTree()
+ORDER BY id
+`;
+const CREATE_ORDERS_TABLE = `
+CREATE TABLE IF NOT EXISTS orders (
+  id Int32,
+  user_id Int32,
+  product_id Int32,
+  quantity Int32,
+  total Float64,
+  status String,
+  created_at DateTime
+) ENGINE = MergeTree()
+ORDER BY id
+`;
+const CREATE_PRODUCTS_TABLE = `
+CREATE TABLE IF NOT EXISTS products (
+  id Int32,
+  name String,
+  price Float64,
+  category String,
+  description String
+) ENGINE = MergeTree()
+ORDER BY id
+`;
+// Sample data for tests
+export const TEST_DATA = {
+    test_table: [
+        { id: 1, name: 'Product 1', price: 10.99, created_at: '2023-01-01 00:00:00', category: 'A', active: 1 },
+        { id: 2, name: 'Product 2', price: 20.50, created_at: '2023-01-02 00:00:00', category: 'B', active: 1 },
+        { id: 3, name: 'Product 3', price: 15.75, created_at: '2023-01-03 00:00:00', category: 'A', active: 0 },
+        { id: 4, name: 'Product 4', price: 25.00, created_at: '2023-01-04 00:00:00', category: 'C', active: 1 },
+        { id: 5, name: 'Product 5', price: 30.25, created_at: '2023-01-05 00:00:00', category: 'B', active: 0 },
+        { id: 6, name: 'Product 6', price: 12.99, created_at: '2023-01-06 00:00:00', category: 'A', active: 1 },
+        { id: 7, name: 'Product 7', price: 22.50, created_at: '2023-01-07 00:00:00', category: 'B', active: 1 },
+        { id: 8, name: 'Product 8', price: 18.75, created_at: '2023-01-08 00:00:00', category: 'C', active: 0 }
+    ],
+    users: [
+        { id: 1, user_name: 'user1', email: 'user1@example.com', created_at: '2023-01-01 00:00:00', status: 'active' },
+        { id: 2, user_name: 'user2', email: 'user2@example.com', created_at: '2023-01-02 00:00:00', status: 'active' },
+        { id: 3, user_name: 'user3', email: 'user3@example.com', created_at: '2023-01-03 00:00:00', status: 'inactive' },
+        { id: 4, user_name: 'user4', email: 'user4@example.com', created_at: '2023-01-04 00:00:00', status: 'active' },
+        { id: 5, user_name: 'user5', email: 'user5@example.com', created_at: '2023-01-05 00:00:00', status: 'pending' }
+    ],
+    orders: [
+        { id: 1, user_id: 1, product_id: 1, quantity: 2, total: 21.98, status: 'completed', created_at: '2023-01-10 10:00:00' },
+        { id: 2, user_id: 1, product_id: 3, quantity: 1, total: 15.75, status: 'completed', created_at: '2023-01-11 11:00:00' },
+        { id: 3, user_id: 2, product_id: 2, quantity: 3, total: 61.50, status: 'completed', created_at: '2023-01-12 12:00:00' },
+        { id: 4, user_id: 3, product_id: 5, quantity: 1, total: 30.25, status: 'pending', created_at: '2023-01-13 13:00:00' },
+        { id: 5, user_id: 4, product_id: 4, quantity: 2, total: 50.00, status: 'completed', created_at: '2023-01-14 14:00:00' },
+        { id: 6, user_id: 2, product_id: 6, quantity: 1, total: 12.99, status: 'cancelled', created_at: '2023-01-15 15:00:00' },
+        { id: 7, user_id: 5, product_id: 7, quantity: 4, total: 90.00, status: 'pending', created_at: '2023-01-16 16:00:00' },
+        { id: 8, user_id: 1, product_id: 8, quantity: 1, total: 18.75, status: 'completed', created_at: '2023-01-17 17:00:00' }
+    ],
+    products: [
+        { id: 1, name: 'Product A', price: 10.99, category: 'Electronics', description: 'A great electronic device' },
+        { id: 2, name: 'Product B', price: 20.50, category: 'Clothing', description: 'Comfortable clothing item' },
+        { id: 3, name: 'Product C', price: 15.75, category: 'Electronics', description: 'Another electronic gadget' },
+        { id: 4, name: 'Product D', price: 25.00, category: 'Home', description: 'Home decoration item' },
+        { id: 5, name: 'Product E', price: 30.25, category: 'Kitchen', description: 'Useful kitchen tool' },
+        { id: 6, name: 'Product F', price: 12.99, category: 'Office', description: 'Office supplies' },
+        { id: 7, name: 'Product G', price: 22.50, category: 'Electronics', description: 'Premium electronic device' },
+        { id: 8, name: 'Product H', price: 18.75, category: 'Clothing', description: 'Stylish clothing piece' }
+    ]
+};
+// Helper to set up the test database
+export async function setupTestDatabase() {
+    const client = ClickHouseConnection.getClient();
+    // Create database if it doesn't exist
+    await client.command({
+        query: `CREATE DATABASE IF NOT EXISTS ${CLICKHOUSE_DB}`
+    });
+    // Use the test database
+    await client.command({
+        query: `USE ${CLICKHOUSE_DB}`
+    });
+    // Create test tables
+    await client.command({
+        query: CREATE_TEST_TABLE
+    });
+    await client.command({
+        query: CREATE_USERS_TABLE
+    });
+    await client.command({
+        query: CREATE_ORDERS_TABLE
+    });
+    await client.command({
+        query: CREATE_PRODUCTS_TABLE
+    });
+    // Truncate tables if they exist
+    await client.command({
+        query: `TRUNCATE TABLE IF EXISTS test_table`
+    });
+    await client.command({
+        query: `TRUNCATE TABLE IF EXISTS users`
+    });
+    await client.command({
+        query: `TRUNCATE TABLE IF EXISTS orders`
+    });
+    await client.command({
+        query: `TRUNCATE TABLE IF EXISTS products`
+    });
+    // Insert test data
+    // For test_table
+    for (const item of TEST_DATA.test_table) {
+        await client.command({
+            query: `
+        INSERT INTO test_table (id, name, price, created_at, category, active)
+        VALUES (${item.id}, '${item.name}', ${item.price}, '${item.created_at}', '${item.category}', ${item.active})
+      `
+        });
+    }
+    // For users
+    for (const user of TEST_DATA.users) {
+        await client.command({
+            query: `
+        INSERT INTO users (id, user_name, email, created_at, status)
+        VALUES (${user.id}, '${user.user_name}', '${user.email}', '${user.created_at}', '${user.status}')
+      `
+        });
+    }
+    // For orders
+    for (const order of TEST_DATA.orders) {
+        await client.command({
+            query: `
+        INSERT INTO orders (id, user_id, product_id, quantity, total, status, created_at)
+        VALUES (${order.id}, ${order.user_id}, ${order.product_id}, ${order.quantity}, ${order.total}, '${order.status}', '${order.created_at}')
+      `
+        });
+    }
+    // For products
+    for (const product of TEST_DATA.products) {
+        await client.command({
+            query: `
+        INSERT INTO products (id, name, price, category, description)
+        VALUES (${product.id}, '${product.name}', ${product.price}, '${product.category}', '${product.description}')
+      `
+        });
+    }
+}
+// Helper to check if Docker is available
+export function isDockerAvailable() {
+    try {
+        execSync('docker --version', { stdio: 'ignore' });
+        return true;
+    }
+    catch (error) {
+        return false;
+    }
+}
+// Helper to start a ClickHouse Docker container for testing
+export function startClickHouseContainer() {
+    if (!isDockerAvailable()) {
+        console.warn('Docker is not available. Integration tests will use the configured ClickHouse instance.');
+        return;
+    }
+    try {
+        // Check if container is already running
+        const containerId = execSync('docker ps -q -f name=hypequery-test-clickhouse').toString().trim();
+        if (containerId) {
+            console.log('ClickHouse test container is already running.');
+            return;
+        }
+        // Start a new container with the hypequery user already configured
+        execSync(`docker run -d --name hypequery-test-clickhouse -p 8123:8123 -p 9000:9000 --ulimit nofile=262144:262144 -e CLICKHOUSE_USER=${CLICKHOUSE_USER} -e CLICKHOUSE_PASSWORD=${CLICKHOUSE_PASSWORD} -e CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT=1 clickhouse/clickhouse-server:latest`, { stdio: 'inherit' });
+        console.log('Started ClickHouse test container with user:', CLICKHOUSE_USER);
+        // Wait for ClickHouse to be ready
+        let attempts = 0;
+        const maxAttempts = 30;
+        while (attempts < maxAttempts) {
+            try {
+                execSync('curl -s http://localhost:8123/ping', { stdio: 'ignore' });
+                console.log('ClickHouse is ready.');
+                break;
+            }
+            catch (error) {
+                attempts++;
+                if (attempts >= maxAttempts) {
+                    throw new Error('ClickHouse failed to start in time.');
+                }
+                console.log(`Waiting for ClickHouse to be ready... (${attempts}/${maxAttempts})`);
+                execSync('sleep 1');
+            }
+        }
+        // Create the test database
+        try {
+            execSync(`
+        docker exec hypequery-test-clickhouse clickhouse-client -u ${CLICKHOUSE_USER} --password ${CLICKHOUSE_PASSWORD} --query "CREATE DATABASE IF NOT EXISTS ${CLICKHOUSE_DB}"
+      `, { stdio: 'inherit' });
+            console.log(`Created database '${CLICKHOUSE_DB}'.`);
+        }
+        catch (error) {
+            console.error('Failed to create database:', error);
+            throw error;
+        }
+    }
+    catch (error) {
+        console.error('Failed to start ClickHouse container:', error);
+        throw error;
+    }
+}
+// Helper to stop the ClickHouse Docker container
+export function stopClickHouseContainer() {
+    if (!isDockerAvailable()) {
+        return;
+    }
+    try {
+        execSync('docker stop hypequery-test-clickhouse', { stdio: 'ignore' });
+        execSync('docker rm hypequery-test-clickhouse', { stdio: 'ignore' });
+        console.log('Stopped and removed ClickHouse test container.');
+    }
+    catch (error) {
+        console.error('Failed to stop ClickHouse container:', error);
+    }
+}

package/dist/core/tests/test-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-utils.d.ts","sourceRoot":"","sources":["../../../src/core/tests/test-utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAEhD,KAAK,UAAU,GAAG,OAAO,GAAG,QAAQ,GAAG,SAAS,GAAG,MAAM,GAAG,OAAO,CAAA;AAEnE,MAAM,MAAM,eAAe,GAAG;IAC5B,EAAE,EAAE,OAAO,CAAC;IACZ,IAAI,EAAE,QAAQ,CAAC;IACf,KAAK,EAAE,SAAS,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,QAAQ,CAAC;IACnB,MAAM,EAAE,OAAO,CAAC;IAChB,UAAU,EAAE,OAAO,CAAC;IACpB,UAAU,EAAE,OAAO,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB,EAAE,EAAE,OAAO,CAAC;IACZ,SAAS,EAAE,QAAQ,CAAC;IACpB,KAAK,EAAE,QAAQ,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AAGF,MAAM,WAAW,UAAU;IACzB,UAAU,EAAE,eAAe,CAAC;IAC5B,KAAK,EAAE,WAAW,CAAC;IACnB,CAAC,SAAS,EAAE,MAAM,GAAG;QAAE,CAAC,UAAU,EAAE,MAAM,GAAG,UAAU,CAAA;KAAE,CAAC;CAC3D;AAGD,eAAO,MAAM,YAAY,EAAE,UAiB1B,CAAC;AAEF,wBAAgB,iBAAiB,IAAI,YAAY,CAAC,UAAU,EAAE,UAAU,CAAC,OAAO,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,UAAU,CAAC,OAAO,CAAC,CAAC,CASjH;AAED,wBAAgB,gBAAgB,IAAI,YAAY,CAAC,UAAU,EAAE,UAAU,CAAC,YAAY,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,UAAU,CAAC,YAAY,CAAC,CAAC,CAS1H"}

package/dist/core/tests/test-utils.js

@@ -0,0 +1,32 @@
+import { QueryBuilder } from '../query-builder';
+// Test data
+export const TEST_SCHEMAS = {
+    test_table: {
+        id: 'Int32',
+        name: 'String',
+        price: 'Float64',
+        created_at: 'Date',
+        category: 'String',
+        active: 'UInt8',
+        created_by: 'Int32',
+        updated_by: 'Int32'
+    },
+    users: {
+        id: 'Int32',
+        user_name: 'String',
+        email: 'String',
+        created_at: 'Date'
+    }
+};
+export function setupUsersBuilder() {
+    return new QueryBuilder('users', {
+        name: 'users',
+        columns: TEST_SCHEMAS.users
+    }, TEST_SCHEMAS);
+}
+export function setupTestBuilder() {
+    return new QueryBuilder('test_table', {
+        name: 'test_table',
+        columns: TEST_SCHEMAS.test_table
+    }, TEST_SCHEMAS);
+}