@hypequery/clickhouse 0.2.1 → 0.2.2-beta.0

package/dist/core/connection.js

@@ -1,34 +1,157 @@
-import { createClient } from '@clickhouse/client-web';
+import { isClientConfig } from './query-builder.js';
+// Function to synchronously get the appropriate client
+function getClickHouseClientSync() {
+    const isDev = process.env.NODE_ENV === 'development';
+    const isNode = typeof process !== 'undefined' && process.versions && process.versions.node;
+    // In Node.js environment, use Node.js client only
+    if (isNode) {
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-var-requires
+            const clientNode = require('@clickhouse/client');
+            if (isDev) {
+                console.log('hypequery: Using @clickhouse/client for Node.js environment');
+            }
+            return {
+                createClient: clientNode.createClient,
+                ClickHouseSettings: clientNode.ClickHouseSettings || {}
+            };
+        }
+        catch (error) {
+            throw new Error('@clickhouse/client is required for Node.js environments.\n\n' +
+                'Install with: npm install @clickhouse/client\n\n' +
+                'Alternatively, you can provide a client instance directly in the config.client option.');
+        }
+    }
+    // For browser environments, require() doesn't work, so we can't auto-detect
+    // Users must use manual injection in browser environments
+    throw new Error('Unable to auto-detect ClickHouse client in browser environment. ' +
+        'Please use manual injection by providing a client instance:\n\n' +
+        '```typescript\n' +
+        'import { createClient } from \'@clickhouse/client-web\';\n' +
+        'const client = createClient({ host: \'http://localhost:8123\' });\n' +
+        'ClickHouseConnection.initialize({ host: \'http://localhost:8123\', client });\n' +
+        '```\n\n' +
+        'This is required because browser environments cannot use require() to load modules.');
+}
+/**
+ * The main entry point for connecting to a ClickHouse database.
+ * Provides static methods to initialize the connection and retrieve the client.
+ *
+ * Supports two modes of operation:
+ * 1. **Manual injection**: Provide a client instance via `config.client` (required for browser environments)
+ * 2. **Auto-detection**: Automatically uses @clickhouse/client for Node.js environments
+ *
+ * @category Core
+ * @example
+ * ```typescript
+ * // Method 1: Manual injection (required for browser environments)
+ * import { createClient } from '@clickhouse/client-web';
+ * const client = createClient({
+ *   host: 'http://localhost:8123',
+ *   username: 'default',
+ *   password: 'password'
+ * });
+ *
+ * ClickHouseConnection.initialize({
+ *   host: 'http://localhost:8123',
+ *   database: 'my_database',
+ *   client // Explicitly provide the client
+ * });
+ *
+ * // Method 2: Auto-detection (Node.js environments only)
+ * ClickHouseConnection.initialize({
+ *   host: 'http://localhost:8123',
+ *   username: 'default',
+ *   password: 'password',
+ *   database: 'my_database'
+ * });
+ *
+ * // Get the client to execute queries directly
+ * const client = ClickHouseConnection.getClient();
+ * const result = await client.query({
+ *   query: 'SELECT * FROM my_table',
+ *   format: 'JSONEachRow'
+ * });
+ * ```
+ *
+ * @note This library requires one of the following peer dependencies:
+ * - @clickhouse/client (for Node.js environments)
+ * - @clickhouse/client-web (for browser environments)
+ *
+ * **Important**: Browser environments require manual injection because `require()` calls don't work in browsers.
+ */
 export class ClickHouseConnection {
+    /**
+     * Initializes the ClickHouse connection with the provided configuration.
+     * This method must be called before any queries can be executed.
+     *
+     * **Priority order:**
+     * 1. If `config.client` is provided, use it directly (manual injection)
+     * 2. Otherwise, auto-detect @clickhouse/client for Node.js environments
+     *
+     * **Note**: Browser environments require manual injection because `require()` calls don't work in browsers.
+     *
+     * @param config - The connection configuration options
+     * @returns The ClickHouseConnection class for method chaining
+     * @throws Will throw an error if no ClickHouse client is available
+     *
+     * @example
+     * ```typescript
+     * // Manual injection (required for browser environments)
+     * import { createClient } from '@clickhouse/client-web';
+     * const client = createClient({ host: 'http://localhost:8123' });
+     * ClickHouseConnection.initialize({ host: 'http://localhost:8123', client });
+     *
+     * // Auto-detection (Node.js environments only)
+     * ClickHouseConnection.initialize({
+     *   host: 'http://localhost:8123',
+     *   username: 'default',
+     *   password: 'password',
+     *   database: 'my_database'
+     * });
+     * ```
+     */
     static initialize(config) {
-        // Create a client config object with only the standard options
-        const clientConfig = {
-            host: config.host,
-            username: config.username,
-            password: config.password,
-            database: config.database,
-        };
-        // Add the extended options if provided
-        if (config.http_headers)
-            clientConfig.http_headers = config.http_headers;
-        if (config.request_timeout)
-            clientConfig.request_timeout = config.request_timeout;
-        if (config.compression)
-            clientConfig.compression = config.compression;
-        if (config.application)
-            clientConfig.application = config.application;
-        if (config.keep_alive)
-            clientConfig.keep_alive = config.keep_alive;
-        if (config.log)
-            clientConfig.log = config.log;
-        if (config.clickhouse_settings)
-            clientConfig.clickhouse_settings = config.clickhouse_settings;
-        this.instance = createClient(clientConfig);
+        // If a client is explicitly provided, use it directly
+        if (isClientConfig(config)) {
+            this.instance = config.client;
+            return ClickHouseConnection;
+        }
+        // Otherwise, auto-detect the client (we know we have a host-based config)
+        this.clientModule = getClickHouseClientSync();
+        this.instance = this.clientModule.createClient(config);
+        return ClickHouseConnection;
     }
+    /**
+     * Retrieves the ClickHouse client instance for direct query execution.
+     *
+     * @returns The ClickHouse client instance
+     * @throws Will throw an error if the connection has not been initialized
+     *
+     * @example
+     * ```typescript
+     * const client = ClickHouseConnection.getClient();
+     * const result = await client.query({
+     *   query: 'SELECT * FROM my_table',
+     *   format: 'JSONEachRow'
+     * });
+     * ```
+     */
     static getClient() {
         if (!this.instance) {
-            throw new Error('ClickHouse connection not initialized');
+            throw new Error('ClickHouse connection not initialized. Call ClickHouseConnection.initialize() first.');
         }
         return this.instance;
     }
+    /**
+     * Gets the ClickHouseSettings type from the loaded client module.
+     * Only available when using auto-detection (not manual injection).
+     *
+     * @returns The ClickHouseSettings type or an empty object if not available
+     */
+    static getClickHouseSettings() {
+        return this.clientModule?.ClickHouseSettings || {};
+    }
 }
+ClickHouseConnection.instance = null;
+ClickHouseConnection.clientModule = null;

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

@@ -0,0 +1,69 @@
+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';
+    };
+}
+/**
+ * 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;
+    /**
+     * 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/cross-filter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cross-filter.d.ts","sourceRoot":"","sources":["../../src/core/cross-filter.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,UAAU,EACV,cAAc,EACd,eAAe,EACf,gBAAgB,EAChB,oBAAoB,EACrB,MAAM,UAAU,CAAC;AAIlB,MAAM,WAAW,WAAW,CAC1B,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,GAAG,GAAG,EACxD,SAAS,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,GAAG;IAE3C,QAAQ,EAAE,KAAK,GAAG,IAAI,CAAC;IACvB,UAAU,EAAE,KAAK,CACf,oBAAoB,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,CAAC,GAAG,WAAW,CAAC,MAAM,EAAE,SAAS,CAAC,CAC9E,CAAC;IACF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE;QACR,MAAM,EAAE,MAAM,SAAS,CAAC;QACxB,SAAS,EAAE,KAAK,GAAG,MAAM,CAAC;KAC3B,CAAC;CACH;AAED,eAAO,MAAM,SAAS;;;;;;;;;CASZ,CAAC;AAEX,MAAM,MAAM,aAAa,GAAG,OAAO,SAAS,CAAC,MAAM,OAAO,SAAS,CAAC,CAAC;AAErE;;;;GAIG;AACH,qBAAa,WAAW,CACtB,MAAM,SAAS;IAAE,CAAC,SAAS,EAAE,MAAM,GAAG;QAAE,CAAC,UAAU,EAAE,MAAM,GAAG,UAAU,CAAA;KAAE,CAAA;CAAE,GAAG,GAAG,EAClF,SAAS,SAAS,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,MAAM,EAAE,MAAM,CAAC;IAMlD,OAAO,CAAC,MAAM,CAAC;IAH3B,OAAO,CAAC,SAAS,CAAyC;gBAGtC,MAAM,CAAC,EAAE,MAAM,YAAA;IAInC;;;OAGG;IACH,GAAG,CACD,UAAU,SAAS,OAAO,CAAC,MAAM,MAAM,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC,EAC3D,EAAE,SAAS,cAAc,EAEzB,SAAS,EAAE,oBAAoB,CAC7B,gBAAgB,CAAC,eAAe,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,EACpE,MAAM,EACN,MAAM,CAAC,SAAS,CAAC,CAClB,GACA,IAAI;IA0BP;;OAEG;IACH,WAAW,CACT,UAAU,EAAE,KAAK,CAAC,oBAAoB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,GACtE,IAAI;IAQP;;;;OAIG;IACH,QAAQ,CACN,eAAe,EAAE,KAAK,CACpB,oBAAoB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,SAAS,CAAC,CAAC,GAAG,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,SAAS,CAAC,CAAC,CAC9F,EACD,QAAQ,EAAE,KAAK,GAAG,IAAI,GACrB,IAAI;IAYP;;OAEG;IACH,aAAa,IAAI,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,SAAS,CAAC,CAAC;IAIvD;;;;OAIG;IACH,OAAO,CAAC,aAAa;IAarB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAazB;;OAEG;IACH,OAAO,CAAC,aAAa;IAqBrB;;OAEG;IACH,OAAO,CAAC,OAAO;IAMf,OAAO,CAAC,gBAAgB;IAYxB,YAAY,CAAC,CAAC,SAAS,MAAM,MAAM,CAAC,SAAS,CAAC,EAC5C,MAAM,EAAE,CAAC,SAAS,MAAM,MAAM,CAAC,SAAS,CAAC,GACrC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,MAAM,GAAG,UAAU,GAChD,CAAC,GACD,KAAK,GACL,KAAK,EACT,KAAK,EAAE,aAAa,GACnB,IAAI;IAgDP,SAAS,CAAC,CAAC,SAAS,MAAM,MAAM,CAAC,SAAS,CAAC,EACzC,MAAM,EAAE,CAAC,SAAS,MAAM,MAAM,CAAC,SAAS,CAAC,GACrC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,MAAM,GAAG,UAAU,GAChD,CAAC,GACD,KAAK,GACL,KAAK,EACT,IAAI,EAAE,MAAM,GACX,IAAI;IAQP,mBAAmB,CAAC,CAAC,SAAS,MAAM,MAAM,CAAC,SAAS,CAAC,EACnD,MAAM,EAAE,CAAC,SAAS,MAAM,MAAM,CAAC,SAAS,CAAC,GACrC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,MAAM,GAAG,UAAU,GAChD,CAAC,GACD,KAAK,GACL,KAAK,EACT,YAAY,EAAE,CAAC,IAAI,EAAE,IAAI,CAAC,GACzB,IAAI;IAQP,eAAe,CAAC,CAAC,SAAS,MAAM,MAAM,CAAC,SAAS,CAAC,EAC/C,MAAM,EAAE,CAAC,SAAS,MAAM,MAAM,CAAC,SAAS,CAAC,GACrC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,MAAM,GAAG,UAAU,GAChD,CAAC,GACD,KAAK,GACL,KAAK,EACT,YAAY,EAAE,CAAC,IAAI,EAAE,IAAI,CAAC,GACzB,IAAI;IASP;;;;;OAKG;IACH,IAAI,CAAC,CAAC,SAAS,MAAM,MAAM,CAAC,SAAS,CAAC,EACpC,WAAW,EAAE,CAAC,EACd,CAAC,EAAE,MAAM,EACT,OAAO,GAAE,MAAM,GAAG,KAAc,GAC/B,IAAI;CAmBR"}
+{"version":3,"file":"cross-filter.d.ts","sourceRoot":"","sources":["../../src/core/cross-filter.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,UAAU,EACV,cAAc,EACd,eAAe,EACf,gBAAgB,EAChB,oBAAoB,EACrB,MAAM,UAAU,CAAC;AAIlB,MAAM,WAAW,WAAW,CAC1B,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,GAAG,GAAG,EACxD,SAAS,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,GAAG;IAE3C,QAAQ,EAAE,KAAK,GAAG,IAAI,CAAC;IACvB,UAAU,EAAE,KAAK,CACf,oBAAoB,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,CAAC,GAAG,WAAW,CAAC,MAAM,EAAE,SAAS,CAAC,CAC9E,CAAC;IACF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE;QACR,MAAM,EAAE,MAAM,SAAS,CAAC;QACxB,SAAS,EAAE,KAAK,GAAG,MAAM,CAAC;KAC3B,CAAC;CACH;AAED;;;;GAIG;AACH,qBAAa,WAAW,CACtB,MAAM,SAAS;IAAE,CAAC,SAAS,EAAE,MAAM,GAAG;QAAE,CAAC,UAAU,EAAE,MAAM,GAAG,UAAU,CAAA;KAAE,CAAA;CAAE,GAAG,GAAG,EAClF,SAAS,SAAS,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,MAAM,EAAE,MAAM,CAAC;IAMlD,OAAO,CAAC,MAAM,CAAC;IAH3B,OAAO,CAAC,SAAS,CAAyC;gBAGtC,MAAM,CAAC,EAAE,MAAM,YAAA;IAInC;;;OAGG;IACH,GAAG,CACD,UAAU,SAAS,OAAO,CAAC,MAAM,MAAM,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC,EAC3D,EAAE,SAAS,cAAc,EAEzB,SAAS,EAAE,oBAAoB,CAC7B,gBAAgB,CAAC,eAAe,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,EACpE,MAAM,EACN,MAAM,CAAC,SAAS,CAAC,CAClB,GACA,IAAI;IA0BP;;OAEG;IACH,WAAW,CACT,UAAU,EAAE,KAAK,CAAC,oBAAoB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,GACtE,IAAI;IAQP;;;;OAIG;IACH,QAAQ,CACN,eAAe,EAAE,KAAK,CACpB,oBAAoB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,SAAS,CAAC,CAAC,GAAG,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,SAAS,CAAC,CAAC,CAC9F,EACD,QAAQ,EAAE,KAAK,GAAG,IAAI,GACrB,IAAI;IAYP;;OAEG;IACH,aAAa,IAAI,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,SAAS,CAAC,CAAC;IAIvD;;;;OAIG;IACH,OAAO,CAAC,aAAa;IAarB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAazB;;OAEG;IACH,OAAO,CAAC,aAAa;IAqBrB;;OAEG;IACH,OAAO,CAAC,OAAO;IAMf;;;;;OAKG;IACH,IAAI,CAAC,CAAC,SAAS,MAAM,MAAM,CAAC,SAAS,CAAC,EACpC,WAAW,EAAE,CAAC,EACd,CAAC,EAAE,MAAM,EACT,OAAO,GAAE,MAAM,GAAG,KAAc,GAC/B,IAAI;CAmBR"}

package/dist/core/cross-filter.js

@@ -1,14 +1,4 @@
-import { FilterValidator } from './validators/filter-validator';
-export const DateRange = {
-    TODAY: 'today',
-    YESTERDAY: 'yesterday',
-    LAST_7_DAYS: 'last_7_days',
-    LAST_30_DAYS: 'last_30_days',
-    THIS_MONTH: 'this_month',
-    LAST_MONTH: 'last_month',
-    THIS_QUARTER: 'this_quarter',
-    YEAR_TO_DATE: 'year_to_date'
-};
+import { FilterValidator } from './validators/filter-validator.js';
 /**
  * A type-safe filter builder supporting both simple conditions and complex nested groups.
  * @template Schema - The full database schema type
@@ -120,78 +110,6 @@ export class CrossFilter {
     isGroup(item) {
         return typeof item.conditions !== 'undefined';
     }
-    addDateCondition(column, value) {
-        this.rootGroup.conditions.push({
-            column,
-            operator: 'between',
-            value: [value[0].toISOString(), value[1].toISOString()]
-        });
-        return this;
-    }
-    addDateRange(column, range) {
-        const now = new Date();
-        let start;
-        let end;
-        switch (range) {
-            case 'today':
-                start = new Date(now.setHours(0, 0, 0, 0));
-                end = new Date(now.setHours(23, 59, 59, 999));
-                break;
-            case 'yesterday':
-                start = new Date(now.setDate(now.getDate() - 1));
-                start.setHours(0, 0, 0, 0);
-                end = new Date(start);
-                end.setHours(23, 59, 59, 999);
-                break;
-            case 'last_7_days':
-                end = new Date(now);
-                start = new Date(now.setDate(now.getDate() - 7));
-                break;
-            case 'last_30_days':
-                end = new Date(now);
-                start = new Date(now.setDate(now.getDate() - 30));
-                break;
-            case 'this_month':
-                start = new Date(now.getFullYear(), now.getMonth(), 1);
-                end = new Date(now.getFullYear(), now.getMonth() + 1, 0);
-                break;
-            case 'last_month':
-                start = new Date(now.getFullYear(), now.getMonth() - 1, 1);
-                end = new Date(now.getFullYear(), now.getMonth(), 0);
-                break;
-            case 'this_quarter':
-                const quarter = Math.floor(now.getMonth() / 3);
-                start = new Date(now.getFullYear(), quarter * 3, 1);
-                end = new Date(now.getFullYear(), (quarter + 1) * 3, 0);
-                break;
-            case 'year_to_date':
-                start = new Date(now.getFullYear(), 0, 1);
-                end = new Date(now);
-                break;
-            default:
-                throw new Error(`Unsupported date range: ${range}`);
-        }
-        return this.addDateCondition(column, [start, end]);
-    }
-    lastNDays(column, days) {
-        const end = new Date();
-        const start = new Date();
-        start.setDate(start.getDate() - days);
-        return this.addDateCondition(column, [start, end]);
-    }
-    addComparisonPeriod(column, currentRange) {
-        const periodLength = currentRange[1].getTime() - currentRange[0].getTime();
-        const previousStart = new Date(currentRange[0].getTime() - periodLength);
-        const previousEnd = new Date(currentRange[1].getTime() - periodLength);
-        return this.addDateCondition(column, [previousStart, previousEnd]);
-    }
-    addYearOverYear(column, currentRange) {
-        const previousStart = new Date(currentRange[0]);
-        previousStart.setFullYear(previousStart.getFullYear() - 1);
-        const previousEnd = new Date(currentRange[1]);
-        previousEnd.setFullYear(previousEnd.getFullYear() - 1);
-        return this.addDateCondition(column, [previousStart, previousEnd]);
-    }
     /**
      * Creates a filter for top N records by a value column
      * @param valueColumn - The column to filter and order by

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-common';
+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/analytics.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"analytics.d.ts","sourceRoot":"","sources":["../../../src/core/features/analytics.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAChD,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAE5D,qBAAa,gBAAgB,CAC3B,MAAM,SAAS;IAAE,CAAC,SAAS,EAAE,MAAM,GAAG;QAAE,CAAC,UAAU,EAAE,MAAM,GAAG,UAAU,CAAA;KAAE,CAAA;CAAE,EAC5E,CAAC,EACD,SAAS,SAAS,OAAO,GAAG,KAAK,EACjC,YAAY,GAAG,EAAE,EACjB,SAAS,GAAG,CAAC;IAED,OAAO,CAAC,OAAO;gBAAP,OAAO,EAAE,YAAY,CAAC,MAAM,EAAE,CAAC,EAAE,SAAS,EAAE,YAAY,EAAE,SAAS,CAAC;IAExF,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,YAAY,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,MAAM;;;;;;;;;;;;;;;;;;IAS/D,eAAe,CACb,MAAM,EAAE,MAAM,CAAC,GAAG,WAAW,CAAC,MAAM,CAAC,EACrC,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,mBAAmB,GAAG,iBAAiB,GAAG,eAAe,GAAG,cAAc,GAAG,eAAe,GAAG,gBAAgB,GAAG,kBAAkB,GAAG,eAAe;;;;;;;;;;;;;;;;;;IAiBhK,WAAW,CAAC,IAAI,EAAE,kBAAkB;;;;;;;;;;;;;;;;;;CAQrC"}
+{"version":3,"file":"analytics.d.ts","sourceRoot":"","sources":["../../../src/core/features/analytics.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAChD,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAA;AAE9D,qBAAa,gBAAgB,CAC3B,MAAM,SAAS;IAAE,CAAC,SAAS,EAAE,MAAM,GAAG;QAAE,CAAC,UAAU,EAAE,MAAM,GAAG,UAAU,CAAA;KAAE,CAAA;CAAE,EAC5E,CAAC,EACD,SAAS,SAAS,OAAO,GAAG,KAAK,EACjC,YAAY,GAAG,EAAE,EACjB,SAAS,GAAG,CAAC;IAED,OAAO,CAAC,OAAO;gBAAP,OAAO,EAAE,YAAY,CAAC,MAAM,EAAE,CAAC,EAAE,SAAS,EAAE,YAAY,EAAE,SAAS,CAAC;IAExF,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,YAAY,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,MAAM;;;;;;;;;;;;;;;;;;IAS/D,eAAe,CACb,MAAM,EAAE,MAAM,CAAC,GAAG,WAAW,CAAC,MAAM,CAAC,EACrC,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,mBAAmB,GAAG,iBAAiB,GAAG,eAAe,GAAG,cAAc,GAAG,eAAe,GAAG,gBAAgB,GAAG,kBAAkB,GAAG,eAAe;;;;;;;;;;;;;;;;;;IAiBhK,WAAW,CAAC,IAAI,EAAE,kBAAkB;;;;;;;;;;;;;;;;;;CAQrC"}

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

@@ -0,0 +1,31 @@
+import { QueryBuilder } from '../query-builder';
+import { CrossFilter } from '../cross-filter';
+import { ColumnType } from '../../types';
+/**
+ * Feature for handling cross-filter operations on queries
+ */
+export declare class CrossFilteringFeature<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>);
+    /**
+     * Applies a set of cross filters to the query
+     * @param crossFilter - An instance of CrossFilter containing shared filter conditions
+     * @returns Updated query config
+     */
+    applyCrossFilters(crossFilter: CrossFilter<Schema, keyof Schema>): import("../../types").QueryConfig<T, Schema>;
+    /**
+     * Apply AND conditions - each condition is applied with WHERE
+     */
+    private applyAndConditions;
+    /**
+     * Apply direct OR conditions without adding extra conjunctions
+     * @param conditions The conditions to apply
+     * @param builder The builder to apply conditions to, defaults to this.builder
+     */
+    private applyOrConditions;
+}
+//# sourceMappingURL=cross-filtering.d.ts.map

package/dist/core/features/cross-filtering.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cross-filtering.d.ts","sourceRoot":"","sources":["../../../src/core/features/cross-filtering.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAChD,OAAO,EAAE,WAAW,EAAe,MAAM,iBAAiB,CAAC;AAC3D,OAAO,EAAwB,UAAU,EAAe,MAAM,aAAa,CAAC;AAgB5E;;GAEG;AACH,qBAAa,qBAAqB,CAChC,MAAM,SAAS;IAAE,CAAC,SAAS,EAAE,MAAM,GAAG;QAAE,CAAC,UAAU,EAAE,MAAM,GAAG,UAAU,CAAA;KAAE,CAAA;CAAE,EAC5E,CAAC,EACD,SAAS,SAAS,OAAO,GAAG,KAAK,EACjC,YAAY,GAAG,EAAE,EACjB,SAAS,GAAG,CAAC;IAED,OAAO,CAAC,OAAO;gBAAP,OAAO,EAAE,YAAY,CAAC,MAAM,EAAE,CAAC,EAAE,SAAS,EAAE,YAAY,EAAE,SAAS,CAAC;IAExF;;;;OAIG;IACH,iBAAiB,CAAC,WAAW,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,MAAM,CAAC;IAsBhE;;OAEG;IACH,OAAO,CAAC,kBAAkB;IA4B1B;;;;OAIG;IACH,OAAO,CAAC,iBAAiB;CAqD1B"}