@hypequery/clickhouse 0.2.1 → 0.2.2

package/dist/core/query-builder.d.ts

@@ -0,0 +1,197 @@
+import { CrossFilter } from './cross-filter';
+import { ColumnType, FilterOperator, OrderDirection, TableColumn, AggregationType, QueryConfig, OperatorValueMap, InferColumnType, PaginationOptions, PaginatedResult } from '../types';
+import { ClickHouseSettings } from '@clickhouse/client-web';
+import { SQLFormatter } from './formatters/sql-formatter';
+import { JoinRelationships, JoinPathOptions } from './join-relationships';
+import { SqlExpression } from './utils/sql-expressions';
+/**
+ * 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 declare class QueryBuilder<Schema extends {
+    [tableName: string]: {
+        [columnName: string]: ColumnType;
+    };
+}, T, HasSelect extends boolean = false, Aggregations = {}, OriginalT = T> {
+    private static relationships;
+    private config;
+    private tableName;
+    private schema;
+    private originalSchema;
+    private formatter;
+    private aggregations;
+    private joins;
+    private filtering;
+    private analytics;
+    private executor;
+    private modifiers;
+    private pagination;
+    constructor(tableName: string, schema: {
+        name: string;
+        columns: T;
+    }, originalSchema: Schema);
+    debug(): this;
+    private clone;
+    withCTE(alias: string, subquery: QueryBuilder<any, any> | string): 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: keyof T | TableColumn<Schema>, interval: string, method?: 'toStartOfInterval' | 'toStartOfMinute' | 'toStartOfHour' | 'toStartOfDay' | 'toStartOfWeek' | 'toStartOfMonth' | 'toStartOfQuarter' | 'toStartOfYear'): this;
+    raw(sql: string): this;
+    settings(opts: ClickHouseSettings): 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: CrossFilter<Schema, keyof Schema>): 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<K extends keyof T | TableColumn<Schema> | SqlExpression>(columns: K[]): QueryBuilder<Schema, {
+        [P in Extract<K, keyof T | TableColumn<Schema>> as P extends `${string}.${infer C}` ? C : P]: P extends keyof T ? (T[P] extends "String" ? string : T[P] extends "Date" ? Date : T[P] extends "Float64" | "Int32" | "Int64" ? number : never) : string;
+    }, true, Aggregations, OriginalT>;
+    sum<Column extends keyof OriginalT, Alias extends string = `${Column & string}_sum`>(column: Column, alias?: Alias): QueryBuilder<Schema, AggregationType<T, Aggregations, Column, Alias, 'sum', HasSelect>, true, {}, OriginalT>;
+    count<Column extends keyof OriginalT, Alias extends string = `${Column & string}_count`>(column: Column, alias?: Alias): QueryBuilder<Schema, AggregationType<T, Aggregations, Column, Alias, 'count', HasSelect>, true, {}, OriginalT>;
+    avg<Column extends keyof OriginalT, Alias extends string = `${Column & string}_avg`>(column: Column, alias?: Alias): QueryBuilder<Schema, AggregationType<T, Aggregations, Column, Alias, 'avg', HasSelect>, true, {}, OriginalT>;
+    min<Column extends keyof OriginalT, Alias extends string = `${Column & string}_min`>(column: Column, alias?: Alias): QueryBuilder<Schema, AggregationType<T, Aggregations, Column, Alias, 'min', HasSelect>, true, {}, OriginalT>;
+    max<Column extends keyof OriginalT, Alias extends string = `${Column & string}_max`>(column: Column, alias?: Alias): QueryBuilder<Schema, AggregationType<T, Aggregations, Column, Alias, 'max', HasSelect>, true, {}, OriginalT>;
+    getTableName(): string;
+    getFormatter(): SQLFormatter;
+    toSQL(): string;
+    toSQLWithParams(): {
+        sql: string;
+        parameters: any[];
+    };
+    execute(): Promise<T[]>;
+    stream(): Promise<ReadableStream<T[]>>;
+    /**
+     * Processes each row in a stream with the provided callback function
+     * @param callback Function to call for each row in the stream
+     */
+    streamForEach<R = void>(callback: (row: T) => R | Promise<R>): Promise<void>;
+    private validateFilterValue;
+    /**
+     * 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<K extends keyof OriginalT | TableColumn<Schema>, Op extends keyof OperatorValueMap<any>>(column: K, operator: Op, value: K extends keyof OriginalT ? OperatorValueMap<OriginalT[K] extends ColumnType ? InferColumnType<OriginalT[K]> : never>[Op] : any): this;
+    orWhere<K extends keyof OriginalT | TableColumn<Schema>>(column: K, operator: FilterOperator, value: any): 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: (keyof T | TableColumn<Schema>) | Array<keyof T | TableColumn<Schema>>): this;
+    limit(count: number): this;
+    offset(count: number): 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<K extends keyof T | TableColumn<Schema>>(column: K, direction?: OrderDirection): 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: string, parameters?: any[]): this;
+    distinct(): this;
+    whereBetween<K extends keyof OriginalT>(column: K, [min, max]: [
+        OriginalT[K] extends ColumnType ? InferColumnType<OriginalT[K]> : never,
+        OriginalT[K] extends ColumnType ? InferColumnType<OriginalT[K]> : never
+    ]): this;
+    innerJoin<TableName extends keyof Schema>(table: TableName, leftColumn: keyof OriginalT, rightColumn: `${TableName & string}.${keyof Schema[TableName] & string}`, alias?: string): QueryBuilder<Schema, T, HasSelect, Aggregations, OriginalT>;
+    leftJoin<TableName extends keyof Schema>(table: TableName, leftColumn: keyof OriginalT, rightColumn: `${TableName & string}.${keyof Schema[TableName] & string}`, alias?: string): QueryBuilder<Schema, T, HasSelect, Aggregations, OriginalT>;
+    rightJoin<TableName extends keyof Schema>(table: TableName, leftColumn: keyof OriginalT, rightColumn: `${TableName & string}.${keyof Schema[TableName] & string}`, alias?: string): QueryBuilder<Schema, T, HasSelect, Aggregations, OriginalT>;
+    fullJoin<TableName extends keyof Schema>(table: TableName, leftColumn: keyof OriginalT, rightColumn: `${TableName & string}.${keyof Schema[TableName] & string}`, alias?: string): QueryBuilder<Schema, T, HasSelect, Aggregations, OriginalT>;
+    getConfig(): QueryConfig<T, Schema>;
+    /**
+     * Paginates the query results using cursor-based pagination
+     */
+    paginate(options: PaginationOptions<T>): Promise<PaginatedResult<T>>;
+    /**
+     * Gets the first page of results
+     */
+    firstPage(pageSize: number): Promise<PaginatedResult<T>>;
+    /**
+     * Returns an async iterator that yields all pages
+     */
+    iteratePages(pageSize: number): AsyncGenerator<PaginatedResult<T>>;
+    static setJoinRelationships<S extends {
+        [tableName: string]: {
+            [columnName: string]: ColumnType;
+        };
+    }>(relationships: JoinRelationships<S>): void;
+    /**
+     * Apply a predefined join relationship
+     */
+    withRelation(name: string, options?: JoinPathOptions): this;
+}
+export declare function createQueryBuilder<Schema extends {
+    [K in keyof Schema]: {
+        [columnName: string]: ColumnType;
+    };
+}>(config: {
+    host: string;
+    username?: string;
+    password?: string;
+    database?: string;
+    http_headers?: Record<string, string>;
+    request_timeout?: number;
+    compression?: {
+        response?: boolean;
+        request?: boolean;
+    };
+    application?: string;
+    keep_alive?: {
+        enabled: boolean;
+    };
+    log?: any;
+    clickhouse_settings?: ClickHouseSettings;
+}): {
+    table<TableName extends keyof Schema>(tableName: TableName): QueryBuilder<Schema, Schema[TableName], false, {}>;
+};
+//# sourceMappingURL=query-builder.d.ts.map

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

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

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

@@ -0,0 +1,40 @@
+export declare const initializeTestConnection: () => Promise<{
+    table<TableName extends never>(tableName: TableName): import("../../query-builder").QueryBuilder<{}, {}[TableName], false, {}, {}[TableName]>;
+}>;
+export declare const ensureConnectionInitialized: () => import("@clickhouse/client-web/dist/client").WebClickHouseClient;
+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 TestSchema {
+    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: TestSchema;
+export declare const setupTestDatabase: () => Promise<void>;
+//# sourceMappingURL=setup.d.ts.map

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

@@ -1 +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"}
+{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../../../../src/core/tests/integration/setup.ts"],"names":[],"mappings":"AA8CA,eAAO,MAAM,wBAAwB;;EAyBpC,CAAC;AAGF,eAAO,MAAM,2BAA2B,wEAevC,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,UAAU;IACzB,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;AAGD,eAAO,MAAM,SAAS,EAAE,UAoBvB,CAAC;AAGF,eAAO,MAAM,iBAAiB,QAAa,OAAO,CAAC,IAAI,CAuFtD,CAAC"}