@housekit/orm 0.1.47 → 0.1.49

package/dist/engines.js

@@ -0,0 +1,292 @@
+export const Engine = {
+    MergeTree: (options) => ({
+        type: 'MergeTree',
+        ...options
+    }),
+    ReplacingMergeTree: (versionColumn, isDeletedColumn, options) => ({
+        type: 'ReplacingMergeTree',
+        versionColumn,
+        isDeletedColumn,
+        ...options
+    }),
+    SummingMergeTree: (columns, options) => ({
+        type: 'SummingMergeTree',
+        columns,
+        ...options
+    }),
+    AggregatingMergeTree: (options) => ({
+        type: 'AggregatingMergeTree',
+        ...options
+    }),
+    CollapsingMergeTree: (signColumn, options) => ({
+        type: 'CollapsingMergeTree',
+        signColumn,
+        ...options
+    }),
+    VersionedCollapsingMergeTree: (signColumn, versionColumn, options) => ({
+        type: 'VersionedCollapsingMergeTree',
+        signColumn,
+        versionColumn,
+        ...options
+    }),
+    GraphiteMergeTree: (configSection, options) => ({
+        type: 'GraphiteMergeTree',
+        configSection,
+        ...options
+    }),
+    ReplicatedMergeTree: (config) => ({
+        type: 'ReplicatedMergeTree',
+        zkPath: config?.zkPath ?? '/clickhouse/tables/{shard}/{database}/{table}',
+        replicaName: config?.replicaName ?? '{replica}',
+        baseEngine: config?.baseEngine,
+        versionColumn: config?.versionColumn,
+        isDeletedColumn: config?.isDeletedColumn,
+        sumColumns: config?.sumColumns,
+        signColumn: config?.signColumn,
+        enableLightweightDeletes: config?.enableLightweightDeletes
+    }),
+    Buffer: (targetTable, opts) => ({
+        type: 'Buffer',
+        database: 'currentDatabase()',
+        table: targetTable.$table,
+        layers: opts.layers ?? 16,
+        minTime: opts.minTime ?? 10,
+        maxTime: opts.maxTime ?? 100,
+        minRows: opts.minRows,
+        maxRows: opts.maxRows,
+        minBytes: opts.minBytes ?? 10_000_000,
+        maxBytes: opts.maxBytes ?? 100_000_000
+    }),
+    BufferExplicit: (config) => ({
+        type: 'Buffer',
+        ...config
+    }),
+    Distributed: (config) => ({
+        type: 'Distributed',
+        shardingKey: config.shardingKey ?? 'rand()',
+        ...config
+    }),
+    Null: () => ({
+        type: 'Null'
+    }),
+    Log: () => ({
+        type: 'Log'
+    }),
+    TinyLog: () => ({
+        type: 'TinyLog'
+    }),
+    Memory: (config) => ({
+        type: 'Memory',
+        ...config
+    }),
+    Join: (strictness, joinType, keys) => ({
+        type: 'Join',
+        strictness,
+        joinType,
+        keys
+    }),
+    Dictionary: (dictionaryName) => ({
+        type: 'Dictionary',
+        dictionaryName
+    }),
+    File: (format, compression) => ({
+        type: 'File',
+        format,
+        compression
+    }),
+    URL: (url, format, compression) => ({
+        type: 'URL',
+        url,
+        format,
+        compression
+    }),
+    S3: (config) => ({
+        type: 'S3',
+        ...config
+    }),
+    Kafka: (config) => ({
+        type: 'Kafka',
+        ...config
+    }),
+    PostgreSQL: (config) => ({
+        type: 'PostgreSQL',
+        ...config
+    }),
+    MySQL: (config) => ({
+        type: 'MySQL',
+        ...config
+    })
+};
+export function renderEngineSQL(engine) {
+    if (!engine)
+        return 'MergeTree()';
+    switch (engine.type) {
+        case 'MergeTree':
+            return 'MergeTree()';
+        case 'ReplacingMergeTree': {
+            const args = [];
+            if (engine.versionColumn)
+                args.push(engine.versionColumn);
+            if (engine.isDeletedColumn)
+                args.push(engine.isDeletedColumn);
+            return `ReplacingMergeTree(${args.join(', ')})`;
+        }
+        case 'SummingMergeTree':
+            if (engine.columns && engine.columns.length > 0) {
+                return `SummingMergeTree(${engine.columns.join(', ')})`;
+            }
+            return 'SummingMergeTree()';
+        case 'AggregatingMergeTree':
+            return 'AggregatingMergeTree()';
+        case 'CollapsingMergeTree':
+            return `CollapsingMergeTree(${engine.signColumn})`;
+        case 'VersionedCollapsingMergeTree':
+            return `VersionedCollapsingMergeTree(${engine.signColumn}, ${engine.versionColumn})`;
+        case 'GraphiteMergeTree':
+            return `GraphiteMergeTree('${engine.configSection}')`;
+        case 'ReplicatedMergeTree': {
+            const zkPath = engine.zkPath ?? '/clickhouse/tables/{shard}/{database}/{table}';
+            const replicaName = engine.replicaName ?? '{replica}';
+            let baseName = 'ReplicatedMergeTree';
+            if (engine.baseEngine) {
+                baseName = `Replicated${engine.baseEngine}`;
+            }
+            const args = [`'${zkPath}'`, `'${replicaName}'`];
+            switch (engine.baseEngine) {
+                case 'ReplacingMergeTree':
+                    if (engine.versionColumn)
+                        args.push(engine.versionColumn);
+                    if (engine.isDeletedColumn)
+                        args.push(engine.isDeletedColumn);
+                    break;
+                case 'SummingMergeTree':
+                    if (engine.sumColumns && engine.sumColumns.length > 0) {
+                        args.push(`(${engine.sumColumns.join(', ')})`);
+                    }
+                    break;
+                case 'CollapsingMergeTree':
+                case 'VersionedCollapsingMergeTree':
+                    if (engine.signColumn)
+                        args.push(engine.signColumn);
+                    break;
+            }
+            if (engine.baseEngine === 'VersionedCollapsingMergeTree' && engine.versionColumn) {
+                args.push(engine.versionColumn);
+            }
+            return `${baseName}(${args.join(', ')})`;
+        }
+        case 'Buffer':
+            return `Buffer(${engine.database}, ${engine.table}, ${engine.layers}, ${engine.minTime}, ${engine.maxTime}, ${engine.minRows}, ${engine.maxRows}, ${engine.minBytes}, ${engine.maxBytes})`;
+        case 'Distributed': {
+            const shardKey = engine.shardingKey ?? 'rand()';
+            if (engine.policyName) {
+                return `Distributed('${engine.cluster}', '${engine.database}', '${engine.table}', ${shardKey}, '${engine.policyName}')`;
+            }
+            return `Distributed('${engine.cluster}', '${engine.database}', '${engine.table}', ${shardKey})`;
+        }
+        case 'Null':
+            return 'Null()';
+        case 'Log':
+            return 'Log()';
+        case 'TinyLog':
+            return 'TinyLog()';
+        case 'Memory': {
+            const args = [];
+            if (engine.maxRows !== undefined)
+                args.push(`max_rows = ${engine.maxRows}`);
+            if (engine.maxBytes !== undefined)
+                args.push(`max_bytes = ${engine.maxBytes}`);
+            if (engine.compress !== undefined)
+                args.push(`compress = ${engine.compress ? 1 : 0}`);
+            if (args.length > 0) {
+                return `Memory(${args.join(', ')})`;
+            }
+            return 'Memory()';
+        }
+        case 'Join':
+            return `Join(${engine.strictness}, ${engine.joinType}, ${engine.keys.join(', ')})`;
+        case 'Dictionary':
+            return `Dictionary('${engine.dictionaryName}')`;
+        case 'File': {
+            if (engine.compression && engine.compression !== 'none') {
+                return `File('${engine.format}', '${engine.compression}')`;
+            }
+            return `File('${engine.format}')`;
+        }
+        case 'URL': {
+            if (engine.compression && engine.compression !== 'none') {
+                return `URL('${engine.url}', '${engine.format}', '${engine.compression}')`;
+            }
+            return `URL('${engine.url}', '${engine.format}')`;
+        }
+        case 'S3': {
+            const args = [`'${engine.path}'`];
+            if (engine.accessKeyId && engine.secretAccessKey) {
+                args.push(`'${engine.accessKeyId}'`, `'${engine.secretAccessKey}'`);
+            }
+            args.push(`'${engine.format}'`);
+            if (engine.compression && engine.compression !== 'none') {
+                args.push(`'${engine.compression}'`);
+            }
+            return `S3(${args.join(', ')})`;
+        }
+        case 'Kafka': {
+            const topics = Array.isArray(engine.topicList) ? engine.topicList.join(', ') : engine.topicList;
+            let sql = `Kafka() SETTINGS kafka_broker_list = '${engine.brokerList}', kafka_topic_list = '${topics}', kafka_group_name = '${engine.groupName}', kafka_format = '${engine.format}'`;
+            if (engine.numConsumers !== undefined) {
+                sql += `, kafka_num_consumers = ${engine.numConsumers}`;
+            }
+            if (engine.maxBlockSize !== undefined) {
+                sql += `, kafka_max_block_size = ${engine.maxBlockSize}`;
+            }
+            if (engine.skipBroken !== undefined) {
+                sql += `, kafka_skip_broken_messages = ${engine.skipBroken}`;
+            }
+            return sql;
+        }
+        case 'PostgreSQL':
+            return `PostgreSQL('${engine.host}:${engine.port}', '${engine.database}', '${engine.table}', '${engine.user}', '${engine.password}'${engine.schema ? `, '${engine.schema}'` : ''})`;
+        case 'MySQL':
+            return `MySQL('${engine.host}:${engine.port}', '${engine.database}', '${engine.table}', '${engine.user}', '${engine.password}')`;
+        default:
+            const _exhaustive = engine;
+            return 'MergeTree()';
+    }
+}
+export function isMergeTreeFamily(engine) {
+    if (!engine)
+        return true;
+    if (typeof engine === 'string')
+        return /MergeTree/i.test(engine);
+    return [
+        'MergeTree',
+        'ReplacingMergeTree',
+        'SummingMergeTree',
+        'AggregatingMergeTree',
+        'CollapsingMergeTree',
+        'VersionedCollapsingMergeTree',
+        'GraphiteMergeTree',
+        'ReplicatedMergeTree'
+    ].includes(engine.type);
+}
+export function isReplicatedEngine(engine) {
+    if (!engine)
+        return false;
+    if (typeof engine === 'string')
+        return /Replicated/i.test(engine);
+    return engine.type === 'ReplicatedMergeTree';
+}
+export function getVersionColumn(engine) {
+    if (!engine || typeof engine === 'string')
+        return undefined;
+    if (engine.type === 'ReplacingMergeTree') {
+        return engine.versionColumn;
+    }
+    if (engine.type === 'ReplicatedMergeTree' && engine.baseEngine === 'ReplacingMergeTree') {
+        return engine.versionColumn;
+    }
+    if (engine.type === 'VersionedCollapsingMergeTree') {
+        return engine.versionColumn;
+    }
+    return undefined;
+}

package/dist/expressions.d.ts

@@ -37,17 +37,7 @@ export declare namespace sql {
     var raw: (rawSql: string) => SQLExpression;
     var join: (expressions: (SQLExpression | ClickHouseColumn | SQLValue)[], separator?: SQLExpression | string) => SQLExpression;
 }
-/**
- * Typed SQL helper that preserves types for columns from a table definition.
- */
 export declare function typedSQL<T extends Record<string, ClickHouseColumn>>(strings: TemplateStringsArray, ...args: Array<SQLValue | SQLExpression | T[keyof T]>): SQL<any>;
-/**
- * Generic function call helper for any ClickHouse function
- * @param name Function name
- * @param args Function arguments
- * @example fn('hex', md5(users.email))
- * @example fn('length', users.interests)
- */
 export declare function fn(name: string, ...args: (ClickHouseColumn | SQLExpression | SQLValue)[]): SQLExpression;
 export declare function eq<T>(col: ClickHouseColumn<T, any, any> | SQLExpression, val: T | SQLValue | ClickHouseColumn | SQLExpression): SQLExpression<any>;
 export declare function ne<T>(col: ClickHouseColumn<T, any, any> | SQLExpression, val: T | SQLValue | ClickHouseColumn | SQLExpression): SQLExpression<any>;

package/dist/expressions.js

@@ -0,0 +1,268 @@
+import { ClickHouseColumn } from './core';
+const UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function inferType(val, contextCol) {
+    if (contextCol) {
+        if (contextCol.type === 'UUID')
+            return 'UUID';
+        if (contextCol.type.startsWith('Int') || contextCol.type.startsWith('UInt'))
+            return contextCol.type;
+        if (contextCol.type.startsWith('Float') || contextCol.type.startsWith('Decimal'))
+            return contextCol.type;
+    }
+    if (val === null)
+        return 'String';
+    if (typeof val === 'number')
+        return Number.isInteger(val) ? 'Int32' : 'Float64';
+    if (typeof val === 'boolean')
+        return 'Bool';
+    if (val instanceof Date)
+        return 'DateTime';
+    if (Array.isArray(val)) {
+        if (val.length > 0)
+            return `Array(${inferType(val[0])})`;
+        return 'Array(String)';
+    }
+    if (typeof val === 'string' && val.length === 36 && UUID_REGEX.test(val)) {
+        return 'UUID';
+    }
+    if (typeof val === 'object')
+        return 'String';
+    return 'String';
+}
+export class SQL {
+    queryChunks;
+    params;
+    _type;
+    constructor(queryChunks, params) {
+        this.queryChunks = queryChunks;
+        this.params = params;
+    }
+    as(alias) {
+        const cloned = new SQL([...this.queryChunks], [...this.params]);
+        cloned._alias = alias;
+        return cloned;
+    }
+    walk(visitor) {
+        let structure = '';
+        let lastColumn = null;
+        for (let i = 0; i < this.queryChunks.length; i++) {
+            structure += this.queryChunks[i];
+            if (i < this.params.length) {
+                const param = this.params[i];
+                const isColumnByInstanceof = param instanceof ClickHouseColumn;
+                const isColumnByProperties = param && typeof param === 'object' &&
+                    'name' in param && 'type' in param && 'toSQL' in param;
+                if (isColumnByInstanceof || isColumnByProperties) {
+                    const col = param;
+                    lastColumn = col;
+                    structure += col.tableName ? `${col.tableName}.${col.name}` : col.name;
+                }
+                else if (typeof param === 'object' && param !== null && 'walk' in param) {
+                    structure += param.walk(visitor);
+                    lastColumn = null;
+                }
+                else {
+                    if (param !== undefined) {
+                        const type = inferType(param, lastColumn || undefined);
+                        visitor(param, type);
+                        structure += `{:${type}}`;
+                    }
+                    lastColumn = null;
+                }
+            }
+        }
+        return structure;
+    }
+    formatColumn(col, options) {
+        if (options?.ignoreTablePrefix) {
+            return `\`${col.name}\``;
+        }
+        return col.tableName ? `\`${col.tableName}\`.\`${col.name}\`` : `\`${col.name}\``;
+    }
+    toSQL(options) {
+        const finalParams = {};
+        let sql = '';
+        let lastColumn = null;
+        for (let i = 0; i < this.queryChunks.length; i++) {
+            sql += this.queryChunks[i];
+            if (i < this.params.length) {
+                const param = this.params[i];
+                const isColumnByInstanceof = param instanceof ClickHouseColumn;
+                const isColumnByProperties = param && typeof param === 'object' &&
+                    'name' in param &&
+                    'type' in param &&
+                    'toSQL' in param &&
+                    typeof param.name === 'string' &&
+                    typeof param.type === 'string' &&
+                    typeof param.toSQL === 'function';
+                const isColumn = isColumnByInstanceof || isColumnByProperties;
+                if (isColumn) {
+                    lastColumn = param;
+                    sql += this.formatColumn(lastColumn, options);
+                }
+                else if (typeof param === 'object' && param !== null && 'toSQL' in param) {
+                    const res = param.toSQL(options);
+                    sql += res.sql;
+                    Object.assign(finalParams, res.params);
+                    lastColumn = null;
+                }
+                else {
+                    if (param === undefined) {
+                        if (options?.table?.$columns) {
+                            const paramIndex = i;
+                            const context = paramIndex > 0 ? ` (parameter ${paramIndex} in expression)` : '';
+                            const sqlContext = sql.substring(Math.max(0, sql.length - 50));
+                            const possibleColumnNames = Object.keys(options.table.$columns);
+                            const availableColumns = possibleColumnNames.slice(0, 10).join(', ');
+                            const commonNames = ['name', 'email', 'id', 'userId', 'firstName', 'lastName'];
+                            const suggestedColumns = commonNames
+                                .filter(name => possibleColumnNames.includes(name))
+                                .slice(0, 3)
+                                .join(', ');
+                            throw new Error(`Cannot use undefined value in SQL expression${context}. ` +
+                                `A table column is undefined (e.g., users.name is undefined when calling concat(users.name, ...)).\n\n` +
+                                `This usually happens when:\n` +
+                                `  1. The Proxy didn't resolve the column correctly\n` +
+                                `  2. The column name doesn't match (check camelCase vs snake_case)\n` +
+                                `  3. The column doesn't exist on the table\n\n` +
+                                `Make sure you're accessing columns correctly: table.columnName (e.g., users.email)\n` +
+                                (suggestedColumns ? `Suggested columns: ${suggestedColumns}\n` : '') +
+                                `Available columns: ${availableColumns}${possibleColumnNames.length > 10 ? '...' : ''}\n` +
+                                `SQL context: ...${sqlContext}`);
+                        }
+                        else {
+                            const paramIndex = i;
+                            const context = paramIndex > 0 ? ` (parameter ${paramIndex} in expression)` : '';
+                            const sqlContext = sql.substring(Math.max(0, sql.length - 50));
+                            throw new Error(`Cannot use undefined value in SQL expression${context}. ` +
+                                `This usually means:\n` +
+                                `  1. A table column is undefined (e.g., users.name is undefined when calling concat(users.name, ...))\n` +
+                                `  2. A property wasn't returned from a previous query\n` +
+                                `  3. The column doesn't exist on the table\n\n` +
+                                `Make sure you're accessing columns correctly: table.columnName (e.g., users.email)\n` +
+                                `SQL context: ...${sqlContext}`);
+                        }
+                    }
+                    const paramName = `p_${Object.keys(finalParams).length + 1}`;
+                    let finalVal = param;
+                    if (param instanceof Date) {
+                        const iso = param.toISOString();
+                        const [datePart, timePart] = iso.split('T');
+                        const [time] = timePart.split('.');
+                        finalVal = `${datePart} ${time}`;
+                    }
+                    else if (typeof param === 'object' && param !== null && !Array.isArray(param)) {
+                        finalVal = JSON.stringify(param);
+                    }
+                    finalParams[paramName] = finalVal;
+                    const type = inferType(param, lastColumn || undefined);
+                    sql += `{${paramName}:${type}}`;
+                    lastColumn = null;
+                }
+            }
+        }
+        return { sql, params: finalParams };
+    }
+}
+export function sql(strings, ...args) {
+    return new SQL([...strings], args);
+}
+sql.raw = function (rawSql) {
+    return {
+        _type: undefined,
+        toSQL: () => ({ sql: rawSql, params: {} }),
+        walk: () => rawSql,
+        as: function (alias) {
+            return {
+                ...this,
+                _alias: alias
+            };
+        }
+    };
+};
+sql.join = function (expressions, separator = sql `, `) {
+    if (expressions.length === 0)
+        return sql ``;
+    const chunks = [''];
+    const params = [];
+    const sep = typeof separator === 'string' ? sql.raw(separator) : separator;
+    expressions.forEach((expr, i) => {
+        params.push(expr);
+        if (i < expressions.length - 1) {
+            params.push(sep);
+            chunks.push('', '');
+        }
+        else {
+            chunks.push('');
+        }
+    });
+    return new SQL(chunks, params);
+};
+export function typedSQL(strings, ...args) {
+    return new SQL([...strings], args);
+}
+export function fn(name, ...args) {
+    const chunks = [`${name}(`];
+    const params = [];
+    args.forEach((arg, i) => {
+        params.push(arg);
+        if (i < args.length - 1) {
+            chunks.push(', ');
+        }
+    });
+    chunks.push(')');
+    return new SQL(chunks, params);
+}
+export function eq(col, val) {
+    return sql `${col} = ${val}`;
+}
+export function ne(col, val) {
+    return sql `${col} != ${val}`;
+}
+export function gt(col, val) {
+    return sql `${col} > ${val}`;
+}
+export function gte(col, val) {
+    return sql `${col} >= ${val}`;
+}
+export function lt(col, val) {
+    return sql `${col} < ${val}`;
+}
+export function lte(col, val) {
+    return sql `${col} <= ${val}`;
+}
+export function inArray(col, values) {
+    if (Array.isArray(values)) {
+        if (values.length === 0)
+            return sql `1=0`;
+    }
+    return sql `${col} IN ${values}`;
+}
+export function notInArray(col, values) {
+    if (Array.isArray(values)) {
+        if (values.length === 0)
+            return sql `1=1`;
+    }
+    return sql `${col} NOT IN ${values}`;
+}
+export function between(col, min, max) {
+    return sql `${col} BETWEEN ${min} AND ${max}`;
+}
+export function notBetween(col, min, max) {
+    return sql `${col} NOT BETWEEN ${min} AND ${max}`;
+}
+export function has(col, value) {
+    return sql `has(${col}, ${value})`;
+}
+export function hasAll(col, values) {
+    return sql `hasAll(${col}, ${values})`;
+}
+export function hasAny(col, values) {
+    return sql `hasAny(${col}, ${values})`;
+}
+export function asc(col) {
+    return { col, dir: 'ASC' };
+}
+export function desc(col) {
+    return { col, dir: 'DESC' };
+}