@hypequery/clickhouse 0.2.1 → 0.2.2

package/dist/core/cross-filter.d.ts

@@ -0,0 +1,85 @@
+import { ColumnType, FilterOperator, InferColumnType, OperatorValueMap, FilterConditionInput } from '../types';
+export interface FilterGroup<Schema extends Record<string, Record<string, any>> = any, OriginalT extends Record<string, any> = any> {
+    operator: 'AND' | 'OR';
+    conditions: Array<FilterConditionInput<any, Schema, OriginalT> | FilterGroup<Schema, OriginalT>>;
+    limit?: number;
+    orderBy?: {
+        column: keyof OriginalT;
+        direction: 'ASC' | 'DESC';
+    };
+}
+export declare const DateRange: {
+    readonly TODAY: "today";
+    readonly YESTERDAY: "yesterday";
+    readonly LAST_7_DAYS: "last_7_days";
+    readonly LAST_30_DAYS: "last_30_days";
+    readonly THIS_MONTH: "this_month";
+    readonly LAST_MONTH: "last_month";
+    readonly THIS_QUARTER: "this_quarter";
+    readonly YEAR_TO_DATE: "year_to_date";
+};
+export type DateRangeType = typeof DateRange[keyof typeof DateRange];
+/**
+ * A type-safe filter builder supporting both simple conditions and complex nested groups.
+ * @template Schema - The full database schema type
+ * @template TableName - The specific table being filtered
+ */
+export declare class CrossFilter<Schema extends {
+    [tableName: string]: {
+        [columnName: string]: ColumnType;
+    };
+} = any, TableName extends keyof Schema = Extract<keyof Schema, string>> {
+    private schema?;
+    private rootGroup;
+    constructor(schema?: Schema | undefined);
+    /**
+     * Adds a single filter condition to the root group with an implicit AND conjunction.
+     * Performs type-safe validation if a schema is provided.
+     */
+    add<ColumnName extends Extract<keyof Schema[TableName], string>, Op extends FilterOperator>(condition: FilterConditionInput<OperatorValueMap<InferColumnType<Schema[TableName][ColumnName]>>[Op], Schema, Schema[TableName]>): this;
+    /**
+     * Adds multiple filter conditions to the root group.
+     */
+    addMultiple(conditions: Array<FilterConditionInput<any, Schema, Schema[TableName]>>): this;
+    /**
+     * Adds a nested group of filter conditions to the root group using the specified logical operator.
+     * @param groupConditions - Array of filter conditions or nested groups to be grouped together.
+     * @param operator - Logical operator ('AND' or 'OR') to combine the conditions in the group.
+     */
+    addGroup(groupConditions: Array<FilterConditionInput<any, Schema, Schema[TableName]> | FilterGroup<Schema, Schema[TableName]>>, operator: 'AND' | 'OR'): this;
+    /**
+     * Returns the current filter tree representing all conditions and groups.
+     */
+    getConditions(): FilterGroup<Schema, Schema[TableName]>;
+    /**
+     * Looks up a column's type from the schema.
+     * Defaults to 'String' if no schema is provided.
+     * @param column - The column name as a string.
+     */
+    private getColumnType;
+    /**
+     * Validates the value of a filter condition against its expected column type.
+     */
+    private validateValueType;
+    /**
+     * Recursively validates an array of filter conditions and nested groups.
+     */
+    private validateGroup;
+    /**
+     * Type guard to check if an item is a FilterGroup.
+     */
+    private isGroup;
+    private addDateCondition;
+    addDateRange<K extends keyof Schema[TableName]>(column: K extends keyof Schema[TableName] ? Schema[TableName][K] extends 'Date' | 'DateTime' ? K : never : never, range: DateRangeType): this;
+    lastNDays<K extends keyof Schema[TableName]>(column: K extends keyof Schema[TableName] ? Schema[TableName][K] extends 'Date' | 'DateTime' ? K : never : never, days: number): this;
+    addComparisonPeriod<K extends keyof Schema[TableName]>(column: K extends keyof Schema[TableName] ? Schema[TableName][K] extends 'Date' | 'DateTime' ? K : never : never, currentRange: [Date, Date]): this;
+    addYearOverYear<K extends keyof Schema[TableName]>(column: K extends keyof Schema[TableName] ? Schema[TableName][K] extends 'Date' | 'DateTime' ? K : never : never, currentRange: [Date, Date]): this;
+    /**
+     * Creates a filter for top N records by a value column
+     * @param valueColumn - The column to filter and order by
+     * @param n - Number of records to return
+     * @param orderBy - Sort direction, defaults to 'desc'
+     */
+    topN<K extends keyof Schema[TableName]>(valueColumn: K, n: number, orderBy?: 'desc' | 'asc'): this;
+}
+//# sourceMappingURL=cross-filter.d.ts.map

package/dist/core/features/aggregations.d.ts

@@ -0,0 +1,102 @@
+import { QueryBuilder } from '../query-builder';
+import { ColumnType } from '../../types';
+export declare class AggregationFeature<Schema extends {
+    [tableName: string]: {
+        [columnName: string]: ColumnType;
+    };
+}, T, HasSelect extends boolean = false, Aggregations = {}, OriginalT = T> {
+    private builder;
+    constructor(builder: QueryBuilder<Schema, T, HasSelect, Aggregations, OriginalT>);
+    private createAggregation;
+    sum<Column extends keyof OriginalT, Alias extends string = `${Column & string}_sum`>(column: Column, alias?: Alias): {
+        select: string[];
+        where?: import("../../types").WhereCondition[];
+        groupBy?: string[];
+        having?: string[];
+        limit?: number;
+        offset?: number;
+        distinct?: boolean;
+        orderBy?: {
+            column: keyof T | import("../../types").TableColumn<Schema>;
+            direction: import("../../types").OrderDirection;
+        }[] | undefined;
+        joins?: import("../../types").JoinClause[];
+        parameters?: any[];
+        ctes?: string[];
+        unionQueries?: string[];
+        settings?: string;
+    };
+    count<Column extends keyof OriginalT, Alias extends string = `${Column & string}_count`>(column: Column, alias?: Alias): {
+        select: string[];
+        where?: import("../../types").WhereCondition[];
+        groupBy?: string[];
+        having?: string[];
+        limit?: number;
+        offset?: number;
+        distinct?: boolean;
+        orderBy?: {
+            column: keyof T | import("../../types").TableColumn<Schema>;
+            direction: import("../../types").OrderDirection;
+        }[] | undefined;
+        joins?: import("../../types").JoinClause[];
+        parameters?: any[];
+        ctes?: string[];
+        unionQueries?: string[];
+        settings?: string;
+    };
+    avg<Column extends keyof OriginalT, Alias extends string = `${Column & string}_avg`>(column: Column, alias?: Alias): {
+        select: string[];
+        where?: import("../../types").WhereCondition[];
+        groupBy?: string[];
+        having?: string[];
+        limit?: number;
+        offset?: number;
+        distinct?: boolean;
+        orderBy?: {
+            column: keyof T | import("../../types").TableColumn<Schema>;
+            direction: import("../../types").OrderDirection;
+        }[] | undefined;
+        joins?: import("../../types").JoinClause[];
+        parameters?: any[];
+        ctes?: string[];
+        unionQueries?: string[];
+        settings?: string;
+    };
+    min<Column extends keyof OriginalT, Alias extends string = `${Column & string}_min`>(column: Column, alias?: Alias): {
+        select: string[];
+        where?: import("../../types").WhereCondition[];
+        groupBy?: string[];
+        having?: string[];
+        limit?: number;
+        offset?: number;
+        distinct?: boolean;
+        orderBy?: {
+            column: keyof T | import("../../types").TableColumn<Schema>;
+            direction: import("../../types").OrderDirection;
+        }[] | undefined;
+        joins?: import("../../types").JoinClause[];
+        parameters?: any[];
+        ctes?: string[];
+        unionQueries?: string[];
+        settings?: string;
+    };
+    max<Column extends keyof OriginalT, Alias extends string = `${Column & string}_max`>(column: Column, alias?: Alias): {
+        select: string[];
+        where?: import("../../types").WhereCondition[];
+        groupBy?: string[];
+        having?: string[];
+        limit?: number;
+        offset?: number;
+        distinct?: boolean;
+        orderBy?: {
+            column: keyof T | import("../../types").TableColumn<Schema>;
+            direction: import("../../types").OrderDirection;
+        }[] | undefined;
+        joins?: import("../../types").JoinClause[];
+        parameters?: any[];
+        ctes?: string[];
+        unionQueries?: string[];
+        settings?: string;
+    };
+}
+//# sourceMappingURL=aggregations.d.ts.map

package/dist/core/features/analytics.d.ts

@@ -0,0 +1,66 @@
+import { QueryBuilder } from '../query-builder';
+import { ColumnType, TableColumn } from '../../types';
+import { ClickHouseSettings } from '@clickhouse/client-web';
+export declare class AnalyticsFeature<Schema extends {
+    [tableName: string]: {
+        [columnName: string]: ColumnType;
+    };
+}, T, HasSelect extends boolean = false, Aggregations = {}, OriginalT = T> {
+    private builder;
+    constructor(builder: QueryBuilder<Schema, T, HasSelect, Aggregations, OriginalT>);
+    addCTE(alias: string, subquery: QueryBuilder<any, any> | string): {
+        ctes: string[];
+        select?: (string | keyof T)[] | undefined;
+        where?: import("../../types").WhereCondition[];
+        groupBy?: string[];
+        having?: string[];
+        limit?: number;
+        offset?: number;
+        distinct?: boolean;
+        orderBy?: {
+            column: keyof T | TableColumn<Schema>;
+            direction: import("../../types").OrderDirection;
+        }[] | undefined;
+        joins?: import("../../types").JoinClause[];
+        parameters?: any[];
+        unionQueries?: string[];
+        settings?: string;
+    };
+    addTimeInterval(column: keyof T | TableColumn<Schema>, interval: string, method: 'toStartOfInterval' | 'toStartOfMinute' | 'toStartOfHour' | 'toStartOfDay' | 'toStartOfWeek' | 'toStartOfMonth' | 'toStartOfQuarter' | 'toStartOfYear'): {
+        groupBy: string[];
+        select?: (string | keyof T)[] | undefined;
+        where?: import("../../types").WhereCondition[];
+        having?: string[];
+        limit?: number;
+        offset?: number;
+        distinct?: boolean;
+        orderBy?: {
+            column: keyof T | TableColumn<Schema>;
+            direction: import("../../types").OrderDirection;
+        }[] | undefined;
+        joins?: import("../../types").JoinClause[];
+        parameters?: any[];
+        ctes?: string[];
+        unionQueries?: string[];
+        settings?: string;
+    };
+    addSettings(opts: ClickHouseSettings): {
+        settings: string;
+        select?: (string | keyof T)[] | undefined;
+        where?: import("../../types").WhereCondition[];
+        groupBy?: string[];
+        having?: string[];
+        limit?: number;
+        offset?: number;
+        distinct?: boolean;
+        orderBy?: {
+            column: keyof T | TableColumn<Schema>;
+            direction: import("../../types").OrderDirection;
+        }[] | undefined;
+        joins?: import("../../types").JoinClause[];
+        parameters?: any[];
+        ctes?: string[];
+        unionQueries?: string[];
+    };
+}
+//# sourceMappingURL=analytics.d.ts.map

package/dist/core/features/executor.d.ts

@@ -0,0 +1,19 @@
+import { QueryBuilder } from '../query-builder';
+import { ColumnType } from '../../types';
+export declare class ExecutorFeature<Schema extends {
+    [tableName: string]: {
+        [columnName: string]: ColumnType;
+    };
+}, T, HasSelect extends boolean = false, Aggregations = {}, OriginalT = T> {
+    private builder;
+    constructor(builder: QueryBuilder<Schema, T, HasSelect, Aggregations, OriginalT>);
+    toSQLWithParams(): {
+        sql: string;
+        parameters: any[];
+    };
+    toSQL(): string;
+    execute(): Promise<T[]>;
+    stream(): Promise<ReadableStream<T[]>>;
+    private toSQLWithoutParameters;
+}
+//# sourceMappingURL=executor.d.ts.map

package/dist/core/features/filtering.d.ts

@@ -0,0 +1,29 @@
+import { QueryBuilder } from '../query-builder';
+import { ColumnType, FilterOperator, TableColumn } from '../../types';
+export declare class FilteringFeature<Schema extends {
+    [tableName: string]: {
+        [columnName: string]: ColumnType;
+    };
+}, T, HasSelect extends boolean = false, Aggregations = {}, OriginalT = T> {
+    private builder;
+    constructor(builder: QueryBuilder<Schema, T, HasSelect, Aggregations, OriginalT>);
+    addCondition<K extends keyof OriginalT | TableColumn<Schema>>(conjunction: 'AND' | 'OR', column: K, operator: FilterOperator, value: any): {
+        where: import("../../types").WhereCondition[];
+        parameters: any[];
+        select?: (string | keyof T)[] | undefined;
+        groupBy?: string[];
+        having?: string[];
+        limit?: number;
+        offset?: number;
+        distinct?: boolean;
+        orderBy?: {
+            column: TableColumn<Schema> | keyof T;
+            direction: import("../../types").OrderDirection;
+        }[] | undefined;
+        joins?: import("../../types").JoinClause[];
+        ctes?: string[];
+        unionQueries?: string[];
+        settings?: string;
+    };
+}
+//# sourceMappingURL=filtering.d.ts.map

package/dist/core/features/joins.d.ts

@@ -0,0 +1,29 @@
+import { QueryBuilder } from '../query-builder';
+import { ColumnType, JoinType } from '../../types';
+export declare class JoinFeature<Schema extends {
+    [tableName: string]: {
+        [columnName: string]: ColumnType;
+    };
+}, T, HasSelect extends boolean = false, Aggregations = {}, OriginalT = T> {
+    private builder;
+    constructor(builder: QueryBuilder<Schema, T, HasSelect, Aggregations, OriginalT>);
+    addJoin<TableName extends keyof Schema>(type: JoinType, table: TableName, leftColumn: keyof OriginalT, rightColumn: `${TableName & string}.${keyof Schema[TableName] & string}`, alias?: string): {
+        joins: import("../../types").JoinClause[];
+        select?: (string | keyof T)[] | undefined;
+        where?: import("../../types").WhereCondition[];
+        groupBy?: string[];
+        having?: string[];
+        limit?: number;
+        offset?: number;
+        distinct?: boolean;
+        orderBy?: {
+            column: keyof T | import("../../types").TableColumn<Schema>;
+            direction: import("../../types").OrderDirection;
+        }[] | undefined;
+        parameters?: any[];
+        ctes?: string[];
+        unionQueries?: string[];
+        settings?: string;
+    };
+}
+//# sourceMappingURL=joins.d.ts.map

package/dist/core/features/pagination.d.ts

@@ -0,0 +1,23 @@
+import { QueryBuilder } from '../query-builder';
+import { ColumnType, PaginationOptions, PaginatedResult } from '../../types';
+export declare class PaginationFeature<Schema extends {
+    [tableName: string]: {
+        [columnName: string]: ColumnType;
+    };
+}, T, HasSelect extends boolean = false, Aggregations = {}, OriginalT = T> {
+    private builder;
+    private static cursorStacks;
+    private stackKey;
+    constructor(builder: QueryBuilder<Schema, T, HasSelect, Aggregations, OriginalT>);
+    private get cursorStack();
+    private set cursorStack(value);
+    private get currentPosition();
+    private set currentPosition(value);
+    private encodeCursor;
+    private decodeCursor;
+    paginate(options: PaginationOptions<T>): Promise<PaginatedResult<T>>;
+    private generateCursor;
+    firstPage(pageSize: number): Promise<PaginatedResult<T>>;
+    iteratePages(pageSize: number): AsyncGenerator<PaginatedResult<T>>;
+}
+//# sourceMappingURL=pagination.d.ts.map

package/dist/core/features/query-modifiers.d.ts

@@ -0,0 +1,119 @@
+import { QueryBuilder } from '../query-builder';
+import { ColumnType, OrderDirection, TableColumn } from '../../types';
+export declare class QueryModifiersFeature<Schema extends {
+    [tableName: string]: {
+        [columnName: string]: ColumnType;
+    };
+}, T, HasSelect extends boolean = false, Aggregations = {}, OriginalT = T> {
+    private builder;
+    constructor(builder: QueryBuilder<Schema, T, HasSelect, Aggregations, OriginalT>);
+    addGroupBy(columns: (keyof T | TableColumn<Schema>) | Array<keyof T | TableColumn<Schema>>): {
+        groupBy: string[];
+        select?: (string | keyof T)[] | undefined;
+        where?: import("../../types").WhereCondition[];
+        having?: string[];
+        limit?: number;
+        offset?: number;
+        distinct?: boolean;
+        orderBy?: {
+            column: TableColumn<Schema> | keyof T;
+            direction: OrderDirection;
+        }[] | undefined;
+        joins?: import("../../types").JoinClause[];
+        parameters?: any[];
+        ctes?: string[];
+        unionQueries?: string[];
+        settings?: string;
+    };
+    addLimit(count: number): {
+        limit: number;
+        select?: (string | keyof T)[] | undefined;
+        where?: import("../../types").WhereCondition[];
+        groupBy?: string[];
+        having?: string[];
+        offset?: number;
+        distinct?: boolean;
+        orderBy?: {
+            column: TableColumn<Schema> | keyof T;
+            direction: OrderDirection;
+        }[] | undefined;
+        joins?: import("../../types").JoinClause[];
+        parameters?: any[];
+        ctes?: string[];
+        unionQueries?: string[];
+        settings?: string;
+    };
+    addOffset(count: number): {
+        offset: number;
+        select?: (string | keyof T)[] | undefined;
+        where?: import("../../types").WhereCondition[];
+        groupBy?: string[];
+        having?: string[];
+        limit?: number;
+        distinct?: boolean;
+        orderBy?: {
+            column: TableColumn<Schema> | keyof T;
+            direction: OrderDirection;
+        }[] | undefined;
+        joins?: import("../../types").JoinClause[];
+        parameters?: any[];
+        ctes?: string[];
+        unionQueries?: string[];
+        settings?: string;
+    };
+    addOrderBy<K extends keyof T | TableColumn<Schema>>(column: K, direction?: OrderDirection): {
+        orderBy: {
+            column: TableColumn<Schema> | keyof T;
+            direction: OrderDirection;
+        }[];
+        select?: (string | keyof T)[] | undefined;
+        where?: import("../../types").WhereCondition[];
+        groupBy?: string[];
+        having?: string[];
+        limit?: number;
+        offset?: number;
+        distinct?: boolean;
+        joins?: import("../../types").JoinClause[];
+        parameters?: any[];
+        ctes?: string[];
+        unionQueries?: string[];
+        settings?: string;
+    };
+    addHaving(condition: string, parameters?: any[]): {
+        having: string[];
+        parameters: any[] | undefined;
+        select?: (string | keyof T)[] | undefined;
+        where?: import("../../types").WhereCondition[];
+        groupBy?: string[];
+        limit?: number;
+        offset?: number;
+        distinct?: boolean;
+        orderBy?: {
+            column: TableColumn<Schema> | keyof T;
+            direction: OrderDirection;
+        }[] | undefined;
+        joins?: import("../../types").JoinClause[];
+        ctes?: string[];
+        unionQueries?: string[];
+        settings?: string;
+    };
+    setDistinct(): {
+        distinct: boolean;
+        select?: (string | keyof T)[] | undefined;
+        where?: import("../../types").WhereCondition[];
+        groupBy?: string[];
+        having?: string[];
+        limit?: number;
+        offset?: number;
+        orderBy?: {
+            column: TableColumn<Schema> | keyof T;
+            direction: OrderDirection;
+        }[] | undefined;
+        joins?: import("../../types").JoinClause[];
+        parameters?: any[];
+        ctes?: string[];
+        unionQueries?: string[];
+        settings?: string;
+    };
+}
+//# sourceMappingURL=query-modifiers.d.ts.map

package/dist/core/formatters/sql-formatter.d.ts

@@ -0,0 +1,9 @@
+import { QueryConfig } from '../../types';
+export declare class SQLFormatter {
+    formatSelect(config: QueryConfig<any, any>): string;
+    formatGroupBy(config: QueryConfig<any, any>): string;
+    formatWhere(config: QueryConfig<any, any>): string;
+    private getSqlOperator;
+    formatJoins(config: QueryConfig<any, any>): string;
+}
+//# sourceMappingURL=sql-formatter.d.ts.map

package/dist/core/join-relationships.d.ts

@@ -0,0 +1,50 @@
+import { ColumnType, JoinType } from '../types';
+export interface JoinPath<Schema> {
+    from: keyof Schema;
+    to: keyof Schema;
+    leftColumn: string;
+    rightColumn: string;
+    type?: JoinType;
+    alias?: string;
+}
+export interface JoinPathOptions {
+    type?: JoinType;
+    alias?: string;
+    context?: Record<string, any>;
+}
+export declare class JoinRelationships<Schema extends {
+    [tableName: string]: {
+        [columnName: string]: ColumnType;
+    };
+}> {
+    private paths;
+    /**
+     * Define a single join relationship
+     */
+    define(name: string, path: JoinPath<Schema>): void;
+    /**
+     * Define a chain of join relationships
+     */
+    defineChain(name: string, paths: JoinPath<Schema>[]): void;
+    /**
+     * Get a join relationship by name
+     */
+    get(name: string): JoinPath<Schema> | JoinPath<Schema>[] | undefined;
+    /**
+     * Check if a join relationship exists
+     */
+    has(name: string): boolean;
+    /**
+     * Remove a join relationship
+     */
+    remove(name: string): boolean;
+    /**
+     * Clear all join relationships
+     */
+    clear(): void;
+    /**
+     * Get all defined relationship names
+     */
+    getDefinedRelationships(): string[];
+}
+//# sourceMappingURL=join-relationships.d.ts.map