@housekit/orm 0.1.47 → 0.1.49

package/dist/compiler.js

@@ -0,0 +1,513 @@
+import { ClickHouseColumn } from './core';
+import { LRUCache } from './utils/lru-cache';
+import { PreparedQuery } from './builders/prepared';
+const queryCache = new LRUCache({ max: 1000 });
+export class QueryCompiler {
+    paramCounter = 0;
+    reset() {
+        this.paramCounter = 0;
+    }
+    getNextParamName() {
+        return `p_${++this.paramCounter}`;
+    }
+    compileWithCache(state, client) {
+        const { key, values } = this.generateFingerprint(state);
+        let template = queryCache.get(key);
+        if (!template) {
+            const result = this.performFullCompilation(state);
+            const paramCount = Object.keys(result.params).length;
+            const paramKeys = Array.from({ length: paramCount }, (_, i) => `p_${i + 1}`);
+            template = {
+                sql: result.sql,
+                paramKeys,
+                suggestions: result.suggestions,
+                columnNames: result.columnNames,
+                columnTypes: result.columnTypes
+            };
+            queryCache.set(key, template);
+        }
+        const cachedQuery = new PreparedQuery(client, template.sql, template.paramKeys, template.suggestions, template.columnNames, template.columnTypes);
+        return { cachedQuery, values };
+    }
+    compileSelect(state) {
+        const { key, values } = this.generateFingerprint(state);
+        let template = queryCache.get(key);
+        if (!template) {
+            const result = this.performFullCompilation(state);
+            const paramCount = Object.keys(result.params).length;
+            const paramKeys = Array.from({ length: paramCount }, (_, i) => `p_${i + 1}`);
+            template = {
+                sql: result.sql,
+                paramKeys,
+                suggestions: result.suggestions,
+                columnNames: result.columnNames,
+                columnTypes: result.columnTypes
+            };
+            queryCache.set(key, template);
+        }
+        const params = {};
+        for (let i = 0; i < template.paramKeys.length; i++) {
+            if (i < values.length) {
+                params[template.paramKeys[i]] = values[i];
+            }
+        }
+        return {
+            sql: template.sql,
+            params,
+            suggestions: template.suggestions
+        };
+    }
+    generateFingerprint(state) {
+        const values = [];
+        const visitor = (val, type) => values.push(val);
+        let key = 'SELECT';
+        if (state.ctes.length > 0) {
+            key += '|CTES:';
+            for (const cte of state.ctes) {
+                if (cte.query && typeof cte.query.toSQL === 'function') {
+                    const { sql, params } = cte.query.toSQL();
+                    key += `(${cte.name}:${sql})`;
+                    if (params) {
+                        for (const [, val] of Object.entries(params)) {
+                            values.push(val);
+                        }
+                    }
+                }
+                else {
+                    key += `(${cte.name}:unknown)`;
+                }
+            }
+        }
+        if (state.select) {
+            key += '|SEL:';
+            if (state.distinct)
+                key += 'DISTINCT:';
+            const keys = Object.keys(state.select);
+            for (const alias of keys) {
+                const item = state.select[alias];
+                key += `${alias}=`;
+                if (item instanceof ClickHouseColumn) {
+                    key += `COL:${item.tableName}.${item.name}`;
+                }
+                else if (item && typeof item === 'object' && 'walk' in item) {
+                    key += `EXPR:${item.walk(visitor)}`;
+                }
+                else {
+                    key += `RAW:${String(item)}`;
+                }
+                key += ';';
+            }
+        }
+        else {
+            key += '|SEL:*';
+        }
+        if (state.table) {
+            const t = state.table;
+            if (t.$options?.kind === 'subquery' && t.$options?.subquery) {
+                const { sql, params } = t.$options.subquery.toSQL();
+                key += `|FROM:SUB(${sql})`;
+                if (params) {
+                    for (const [, val] of Object.entries(params)) {
+                        values.push(val);
+                    }
+                }
+            }
+            else {
+                key += `|FROM:${state.table.$table}`;
+                if (state.final)
+                    key += ':FINAL';
+            }
+        }
+        if (state.joins.length > 0) {
+            key += '|JOINS:';
+            for (const join of state.joins) {
+                key += `${join.type}:${join.table}`;
+                if (join.on) {
+                    key += `ON:${join.on.walk(visitor)}`;
+                }
+                key += ';';
+            }
+        }
+        if (state.arrayJoins.length > 0) {
+            key += '|AJOINS:';
+            for (const aj of state.arrayJoins) {
+                if (aj.column instanceof ClickHouseColumn) {
+                    key += `COL:${aj.column.tableName}.${aj.column.name}`;
+                }
+                else {
+                    key += `EXPR:${aj.column.walk(visitor)}`;
+                }
+                if (aj.alias)
+                    key += `AS:${aj.alias}`;
+                key += ';';
+            }
+        }
+        if (state.prewhere) {
+            key += `|PREWHERE:${state.prewhere.walk(visitor)}`;
+        }
+        if (state.where) {
+            key += `|WHERE:${state.where.walk(visitor)}`;
+        }
+        if (state.groupBy.length > 0) {
+            key += '|GROUP:';
+            for (const g of state.groupBy) {
+                if (g instanceof ClickHouseColumn) {
+                    key += `COL:${g.tableName}.${g.name}`;
+                }
+                else {
+                    key += `EXPR:${g.walk(visitor)}`;
+                }
+                key += ';';
+            }
+        }
+        if (state.having) {
+            key += `|HAVING:${state.having.walk(visitor)}`;
+        }
+        if (state.orderBy.length > 0) {
+            key += '|ORDER:';
+            for (const o of state.orderBy) {
+                if (o.col instanceof ClickHouseColumn) {
+                    key += `COL:${o.col.tableName}.${o.col.name}`;
+                }
+                else {
+                    key += `EXPR:${o.col.walk(visitor)}`;
+                }
+                key += `:${o.dir};`;
+            }
+        }
+        if (state.limit !== null)
+            key += `|LIMIT:${state.limit}`;
+        if (state.offset !== null)
+            key += `|OFFSET:${state.offset}`;
+        if (state.sample !== null) {
+            key += `|SAMPLE:${state.sample.ratio}:${state.sample.offset}`;
+        }
+        if (state.settings) {
+            key += '|SETTINGS:';
+            const sortedKeys = Object.keys(state.settings).sort();
+            for (const k of sortedKeys) {
+                key += `${k}=${state.settings[k]};`;
+            }
+        }
+        if (Object.keys(state.windows).length > 0) {
+            key += '|WINDOWS:';
+            const sortedKeys = Object.keys(state.windows).sort();
+            for (const k of sortedKeys) {
+                key += `${k}=${state.windows[k]};`;
+            }
+        }
+        return { key, values };
+    }
+    performFullCompilation(state) {
+        const table = state.table;
+        if (!table)
+            throw new Error('❌ .from() is required');
+        const getAlias = (fallback, item) => {
+            if (item && typeof item === 'object' && typeof item._alias === 'string') {
+                return item._alias;
+            }
+            return fallback;
+        };
+        this.reset();
+        const params = {};
+        let withSql = '';
+        if (state.ctes.length > 0) {
+            const cteParts = state.ctes.map(cte => {
+                const { query: originalQuery, params: cteParams } = cte.query.toSQL();
+                const renamedParams = {};
+                let query = originalQuery;
+                for (const [key, value] of Object.entries(cteParams)) {
+                    const newKey = this.getNextParamName();
+                    renamedParams[newKey] = value;
+                    query = query.replace(new RegExp(`\\{${key}:`, 'g'), `{${newKey}:`);
+                }
+                Object.assign(params, renamedParams);
+                return `${cte.name} AS (${query})`;
+            });
+            withSql = `WITH ${cteParts.join(', ')}`;
+        }
+        const distinctKeyword = state.distinct ? 'DISTINCT ' : '';
+        let selectSql = '*';
+        const columnNames = [];
+        const columnTypes = [];
+        if (state.select) {
+            selectSql = Object.keys(state.select)
+                .map(alias => {
+                let item = state.select[alias];
+                const targetAlias = getAlias(alias, item);
+                const isColumnByInstanceof = item instanceof ClickHouseColumn;
+                const isColumnByProperties = item && typeof item === 'object' &&
+                    'name' in item && 'type' in item && 'toSQL' in item &&
+                    typeof item.name === 'string' && typeof item.type === 'string';
+                const isColumn = isColumnByInstanceof || isColumnByProperties;
+                const isExpression = item && typeof item === 'object' && 'toSQL' in item && !isColumn;
+                if (!isColumn && !isExpression) {
+                    const resolved = this.resolveColumn(item, alias, table);
+                    if (resolved) {
+                        item = resolved;
+                    }
+                }
+                if (item === undefined || item === null) {
+                    const availableColumns = Object.keys(table.$columns).map(key => {
+                        const col = table.$columns[key];
+                        return `${key} (column: ${col.name})`;
+                    }).join(', ');
+                    const directProps = Object.keys(table).filter(k => !k.startsWith('$')).join(', ');
+                    throw new Error(`Field "${alias}" in SELECT is undefined. ` +
+                        `The value you passed for "${alias}" is undefined. ` +
+                        `Make sure you're accessing the column correctly:\n` +
+                        `  - Use table.columnName (e.g., myTable.columnName)\n` +
+                        `  - Or use table.$columns.columnName (e.g., myTable.$columns.columnName)\n` +
+                        `  - Available column properties: ${directProps}\n` +
+                        `  - Available columns (property -> column): ${availableColumns}\n` +
+                        `  - Example: client.select({ my_column: myTable.columnName }).from(myTable)`);
+                }
+                columnNames.push(targetAlias);
+                if (item instanceof ClickHouseColumn || isColumnByProperties) {
+                    const col = item;
+                    columnTypes.push(col.type);
+                    const colSql = this.formatColumn(col);
+                    return `${colSql} AS \`${targetAlias}\``;
+                }
+                else if (item && typeof item === 'object' && 'toSQL' in item) {
+                    const res = item.toSQL({ table });
+                    Object.assign(params, res.params);
+                    columnTypes.push(item.type || 'String');
+                    return `${res.sql} AS \`${targetAlias}\``;
+                }
+                else {
+                    throw new Error(`Field "${alias}" in SELECT must be a ClickHouseColumn or SQLExpression, ` +
+                        `but got ${typeof item}. ` +
+                        `Make sure you're using table.columnName (e.g., myTable.columnName) correctly.`);
+                }
+            })
+                .join(', ');
+        }
+        else if (table) {
+            for (const [key, col] of Object.entries(table.$columns)) {
+                const column = col;
+                columnNames.push(column.name);
+                columnTypes.push(column.type);
+            }
+        }
+        const isSubquery = table?.$options?.kind === 'subquery' && table?.$options?.subquery;
+        const tableName = table.$table;
+        let fromSql;
+        if (isSubquery) {
+            const { sql: subSql, params: subParams } = table.$options.subquery.toSQL();
+            Object.assign(params, subParams);
+            fromSql = `(${subSql}) AS \`${tableName}\``;
+        }
+        else {
+            fromSql = `\`${tableName}\``;
+            if (state.final) {
+                fromSql += ' FINAL';
+            }
+        }
+        if (state.joins.length > 0) {
+            const joinParts = state.joins.map(join => {
+                if (join.type === 'CROSS' || !join.on) {
+                    return `${join.type} JOIN \`${join.table}\``;
+                }
+                const onRes = join.on.toSQL({ table });
+                Object.assign(params, onRes.params);
+                return `${join.type} JOIN \`${join.table}\` ON ${onRes.sql}`;
+            });
+            fromSql += ' ' + joinParts.join(' ');
+        }
+        if (state.arrayJoins.length > 0) {
+            const arrayJoinParts = state.arrayJoins.map(aj => {
+                const isColumn = aj.column instanceof ClickHouseColumn ||
+                    (aj.column && typeof aj.column === 'object' && 'name' in aj.column && 'type' in aj.column);
+                let columnSql;
+                if (isColumn) {
+                    columnSql = this.formatColumn(aj.column);
+                }
+                else {
+                    const res = aj.column.toSQL({ table });
+                    Object.assign(params, res.params);
+                    columnSql = res.sql;
+                }
+                return aj.alias ? `${columnSql} AS \`${aj.alias}\`` : columnSql;
+            });
+            fromSql += ' ARRAY JOIN ' + arrayJoinParts.join(', ');
+        }
+        let prewhereSql = '';
+        if (state.prewhere) {
+            const res = state.prewhere.toSQL({ table });
+            prewhereSql = `PREWHERE ${res.sql}`;
+            Object.assign(params, res.params);
+        }
+        let whereSql = '';
+        if (state.where) {
+            const res = state.where.toSQL({ table });
+            whereSql = `WHERE ${res.sql}`;
+            Object.assign(params, res.params);
+        }
+        let groupBySql = '';
+        if (state.groupBy.length > 0) {
+            const parts = state.groupBy.map(c => {
+                const isColumn = c instanceof ClickHouseColumn ||
+                    (c && typeof c === 'object' && 'name' in c && 'type' in c);
+                if (isColumn) {
+                    return this.formatColumn(c);
+                }
+                else {
+                    const res = c.toSQL({ table });
+                    Object.assign(params, res.params);
+                    return res.sql;
+                }
+            });
+            groupBySql = `GROUP BY ${parts.join(', ')}`;
+        }
+        let havingSql = '';
+        if (state.having) {
+            const res = state.having.toSQL({ table });
+            havingSql = `HAVING ${res.sql}`;
+            Object.assign(params, res.params);
+        }
+        let orderSql = '';
+        if (state.orderBy.length > 0) {
+            const parts = state.orderBy.map(o => {
+                let colSql;
+                const isColumn = o.col instanceof ClickHouseColumn ||
+                    (o.col && typeof o.col === 'object' && 'name' in o.col && 'type' in o.col);
+                if (isColumn) {
+                    colSql = this.formatColumn(o.col);
+                }
+                else {
+                    const res = o.col.toSQL({ table });
+                    Object.assign(params, res.params);
+                    colSql = res.sql;
+                }
+                const sqlUpper = colSql.trim().toUpperCase();
+                const alreadyHasDirection = sqlUpper.endsWith(' ASC') || sqlUpper.endsWith(' DESC');
+                if (alreadyHasDirection) {
+                    return colSql;
+                }
+                return `${colSql} ${o.dir}`;
+            });
+            orderSql = `ORDER BY ${parts.join(', ')}`;
+        }
+        let limitSql = '';
+        if (state.limit !== null) {
+            limitSql = `LIMIT ${state.limit}`;
+            if (state.offset !== null) {
+                limitSql += ` OFFSET ${state.offset}`;
+            }
+        }
+        let sampleSql = '';
+        if (state.sample !== null) {
+            sampleSql = `SAMPLE ${state.sample.ratio}`;
+            if (state.sample.offset !== undefined) {
+                sampleSql += ` OFFSET ${state.sample.offset}`;
+            }
+        }
+        let settingsSql = '';
+        const finalSettings = { ...(state.settings || {}) };
+        if (table.$options?.projections && table.$options.projections.length > 0) {
+            if (finalSettings.use_projection === undefined) {
+                finalSettings.use_projection = 1;
+                state.suggestions.push(`💡 This table has projections. Automatically enabled 'use_projection = 1' for potentially faster execution.`);
+            }
+        }
+        if (Object.keys(finalSettings).length > 0) {
+            const parts = Object.entries(finalSettings).map(([k, v]) => `${k} = ${v}`);
+            settingsSql = `SETTINGS ${parts.join(', ')}`;
+        }
+        let windowSql = '';
+        if (Object.keys(state.windows).length > 0) {
+            const parts = Object.entries(state.windows).map(([name, def]) => `${name} AS (${def})`);
+            windowSql = `WINDOW ${parts.join(', ')}`;
+        }
+        const queryParts = [
+            withSql,
+            `SELECT ${distinctKeyword}${selectSql}`,
+            `FROM ${fromSql}`,
+            prewhereSql,
+            whereSql,
+            groupBySql,
+            havingSql,
+            orderSql,
+            limitSql,
+            sampleSql,
+            windowSql,
+            settingsSql
+        ].filter(part => part !== '');
+        return {
+            sql: queryParts.join(' '),
+            params,
+            suggestions: state.suggestions,
+            columnNames,
+            columnTypes
+        };
+    }
+    formatColumn(col) {
+        const colName = 'name' in col ? col.name : col.name;
+        const tableName = 'tableName' in col ? col.tableName : col.tableName;
+        return tableName ? `\`${tableName}\`.\`${colName}\`` : `\`${colName}\``;
+    }
+    resolveColumn(value, alias, table) {
+        if (value instanceof ClickHouseColumn) {
+            return value;
+        }
+        if (value && typeof value === 'object' && 'toSQL' in value) {
+            return value;
+        }
+        if (table) {
+            if (table.$columns[alias]) {
+                const col = table.$columns[alias];
+                if (col instanceof ClickHouseColumn) {
+                    return col;
+                }
+            }
+            try {
+                const tableProp = table[alias];
+                if (tableProp instanceof ClickHouseColumn) {
+                    return tableProp;
+                }
+            }
+            catch (e) { }
+            const aliasCamelCase = alias.replace(/_([a-z])/g, (_, letter) => letter.toUpperCase());
+            if (aliasCamelCase !== alias) {
+                if (table.$columns[aliasCamelCase]) {
+                    return table.$columns[aliasCamelCase];
+                }
+                try {
+                    const tableProp = table[aliasCamelCase];
+                    if (tableProp instanceof ClickHouseColumn) {
+                        return tableProp;
+                    }
+                }
+                catch (e) { }
+            }
+            const aliasSnakeCase = alias.replace(/([A-Z])/g, '_$1').toLowerCase();
+            if (aliasSnakeCase !== alias && aliasSnakeCase !== aliasCamelCase) {
+                if (table.$columns[aliasSnakeCase]) {
+                    return table.$columns[aliasSnakeCase];
+                }
+                try {
+                    const tableProp = table[aliasSnakeCase];
+                    if (tableProp instanceof ClickHouseColumn) {
+                        return tableProp;
+                    }
+                }
+                catch (e) { }
+            }
+            for (const [, col] of Object.entries(table.$columns)) {
+                const column = col;
+                if (column.name === alias || column.name === aliasCamelCase || column.name === aliasSnakeCase) {
+                    return column;
+                }
+            }
+            const aliasLower = alias.toLowerCase();
+            for (const [key, col] of Object.entries(table.$columns)) {
+                const column = col;
+                if (key.toLowerCase() === aliasLower || column.name.toLowerCase() === aliasLower) {
+                    return column;
+                }
+            }
+        }
+        return null;
+    }
+}

package/dist/core.js

@@ -0,0 +1,6 @@
+export * from './column';
+export * from './table';
+export * from './engines';
+export * from './materialized-views';
+export * from './dictionary';
+export * from './external';

package/dist/data-types.d.ts

@@ -5,55 +5,22 @@ export declare const int16: (name: string) => ClickHouseColumn<number, true, fal
 export declare const integer: (name: string) => ClickHouseColumn<number, true, false>;
 export declare const int32: (name: string) => ClickHouseColumn<number, true, false>;
 export declare const int64: (name: string) => ClickHouseColumn<number, true, false>;
-/**
- * ⚠️ Advanced: Very wide integer type (128-bit).
- * Use only if you need to store numbers larger than 2^63-1.
- * For most cases, `int64` is sufficient.
- */
 export declare const int128: (name: string) => ClickHouseColumn<number, true, false>;
-/**
- * ⚠️ Advanced: Extremely wide integer type (256-bit).
- * Use only if you need to store numbers larger than 2^127-1.
- * For most cases, `int64` is sufficient.
- */
 export declare const int256: (name: string) => ClickHouseColumn<number, true, false>;
 export declare const uint8: (name: string) => ClickHouseColumn<number, true, false>;
 export declare const uint16: (name: string) => ClickHouseColumn<number, true, false>;
 export declare const uint32: (name: string) => ClickHouseColumn<number, true, false>;
 export declare const uint64: (name: string) => ClickHouseColumn<number, true, false>;
-/**
- * ⚠️ Advanced: Very wide unsigned integer type (128-bit).
- * Use only if you need to store numbers larger than 2^64-1.
- * For most cases, `uint64` is sufficient.
- */
 export declare const uint128: (name: string) => ClickHouseColumn<number, true, false>;
-/**
- * ⚠️ Advanced: Extremely wide unsigned integer type (256-bit).
- * Use only if you need to store numbers larger than 2^128-1.
- * For most cases, `uint64` is sufficient.
- */
 export declare const uint256: (name: string) => ClickHouseColumn<number, true, false>;
 export declare const float32: (name: string) => ClickHouseColumn<number, true, false>;
 export declare const float: (name: string) => ClickHouseColumn<number, true, false>;
 export declare const float64: (name: string) => ClickHouseColumn<number, true, false>;
-/**
- * ⚠️ Advanced: Brain Floating Point (16-bit).
- * Primarily used for machine learning applications.
- * Lower precision than `float32`. Use only if you know exactly why.
- */
 export declare const bfloat16: (name: string) => ClickHouseColumn<number, true, false>;
 export declare const decimal: (name: string, precision?: number, scale?: number) => ClickHouseColumn<number, true, false>;
 export declare const decimal32: (name: string, scale?: number) => ClickHouseColumn<number, true, false>;
 export declare const decimal64: (name: string, scale?: number) => ClickHouseColumn<number, true, false>;
-/**
- * ⚠️ Advanced: High precision decimal.
- * Use only if you need more precision than `decimal64`.
- */
 export declare const decimal128: (name: string, scale?: number) => ClickHouseColumn<number, true, false>;
-/**
- * ⚠️ Advanced: Extreme precision decimal.
- * Use only if you need more precision than `decimal128`.
- */
 export declare const decimal256: (name: string, scale?: number) => ClickHouseColumn<number, true, false>;
 export declare const text: (name: string) => ClickHouseColumn<string, true, false>;
 export declare const string: (name: string) => ClickHouseColumn<string, true, false>;
@@ -75,11 +42,6 @@ export declare const nested: (name: string, fields: Record<string, string>) => C
 export declare const nullable: <T, TNotNull extends boolean, TAutoGenerated extends boolean>(col: ClickHouseColumn<T, TNotNull, TAutoGenerated>) => ClickHouseColumn<T, false, TAutoGenerated>;
 export declare const lowCardinality: <T, TNotNull extends boolean, TAutoGenerated extends boolean>(col: ClickHouseColumn<T, TNotNull, TAutoGenerated>) => ClickHouseColumn<T, TNotNull, TAutoGenerated>;
 export declare const json: <TSchema = JsonValue>(name: string) => ClickHouseColumn<TSchema, false, false>;
-/**
- * ⚠️ Advanced: Dynamic typing (experimental/niche).
- * Allows storing values of different types in the same column.
- * This is still evolving in ClickHouse. Use with caution.
- */
 export declare const dynamic: (name: string, maxTypes?: number) => ClickHouseColumn<any, true, false>;
 export declare const aggregateFunction: (name: string, funcName: string, ...argTypes: string[]) => ClickHouseColumn<any, true, false>;
 export declare const simpleAggregateFunction: (name: string, funcName: string, argType: string) => ClickHouseColumn<any, true, false>;
@@ -97,48 +59,25 @@ export interface TTLRule {
     target?: string;
 }
 export declare const ttl: {
-    /**
-     * Delete rows after a time interval
-     * @example ttl.delete(events.timestamp, { days: 30 })
-     */
     delete: (column: ClickHouseColumn, interval: {
         days?: number;
         hours?: number;
         months?: number;
         years?: number;
     }) => TTLRule;
-    /**
-     * Move rows to cold storage after a time interval
-     * @example ttl.toDisk(events.timestamp, { days: 7 }, 'cold_storage')
-     */
     toDisk: (column: ClickHouseColumn, interval: {
         days?: number;
         hours?: number;
         months?: number;
         years?: number;
     }, disk: string) => TTLRule;
-    /**
-     * Move rows to a volume after a time interval
-     * @example ttl.toVolume(events.timestamp, { days: 30 }, 'archive')
-     */
     toVolume: (column: ClickHouseColumn, interval: {
         days?: number;
         hours?: number;
         months?: number;
         years?: number;
     }, volume: string) => TTLRule;
-    /**
-     * Custom TTL expression
-     * @example ttl.custom('created_at + INTERVAL 1 YEAR')
-     */
     custom: (expression: string) => TTLRule;
-    /**
-     * Combine multiple TTL rules (tiered storage)
-     * @example ttl.tiered(events.timestamp, [
-     *   { days: 7, action: 'toDisk', target: 'cold' },
-     *   { days: 30, action: 'delete' }
-     * ])
-     */
     tiered: (column: ClickHouseColumn, tiers: Array<{
         days?: number;
         hours?: number;