@housekit/orm 0.1.47 → 0.1.49

package/dist/client.d.ts

@@ -7,21 +7,15 @@ import { type TableDefinition, type TableRuntime, type CleanInsert } from './cor
 import { type HousekitLogger } from './logger';
 import { type RelationalAPI } from './relational';
 interface ConnectionPoolConfig {
-    /** Maximum concurrent sockets (default: 100) */
     maxSockets?: number;
-    /** Keep connections alive (default: true) */
     keepAlive?: boolean;
-    /** Keep-alive initial delay in ms (default: 1000) */
     keepAliveInitialDelay?: number;
-    /** Socket timeout in ms (default: 30000) */
     timeout?: number;
 }
 export type HousekitClientConfig = ClickHouseClientConfigOptions & {
     schema?: Record<string, TableDefinition<any>>;
     logger?: HousekitLogger;
-    /** Connection pool configuration */
     pool?: ConnectionPoolConfig;
-    /** Skip validation for maximum insert performance */
     skipValidation?: boolean;
 };
 export type ClientConfigWithSchema = HousekitClientConfig;

package/dist/client.js

@@ -0,0 +1,140 @@
+import { createClient as createChClient } from '@clickhouse/client';
+import { Readable } from 'stream';
+import http from 'http';
+import https from 'https';
+import { ClickHouseQueryBuilder } from './builders/select';
+import { ClickHouseInsertBuilder } from './builders/insert';
+import { ClickHouseDeleteBuilder } from './builders/delete';
+import { ClickHouseUpdateBuilder } from './builders/update';
+import { buildInsertPlan, processRowsStream } from './utils/insert-processing';
+import { wrapClientWithLogger } from './logger';
+import { buildRelationalAPI } from './relational';
+const agentPool = new Map();
+function getOrCreateAgent(url, config = {}) {
+    const isHttps = url.startsWith('https');
+    const key = `${url}-${config.maxSockets ?? 100}`;
+    let agent = agentPool.get(key);
+    if (agent)
+        return agent;
+    const agentConfig = {
+        keepAlive: config.keepAlive ?? true,
+        keepAliveMsecs: config.keepAliveInitialDelay ?? 1000,
+        maxSockets: config.maxSockets ?? 100,
+        maxFreeSockets: Math.floor((config.maxSockets ?? 100) / 2),
+        timeout: config.timeout ?? 30000,
+    };
+    agent = isHttps
+        ? new https.Agent(agentConfig)
+        : new http.Agent(agentConfig);
+    agentPool.set(key, agent);
+    return agent;
+}
+export function createHousekitClient(config) {
+    const { schema, logger, pool, skipValidation, ...configRest } = config;
+    const normalizedConfig = { ...configRest };
+    if ('host' in normalizedConfig && !('url' in normalizedConfig)) {
+        const host = normalizedConfig.host;
+        normalizedConfig.url = host.startsWith('http://') || host.startsWith('https://')
+            ? host
+            : `http://${host}`;
+        delete normalizedConfig.host;
+    }
+    const urlStr = normalizedConfig.url?.toString() ?? '';
+    const keepAliveAgent = getOrCreateAgent(urlStr, pool);
+    const clientConfig = {
+        ...normalizedConfig,
+        clickhouse_settings: {
+            enable_http_compression: 1,
+            ...normalizedConfig.clickhouse_settings
+        }
+    };
+    clientConfig.http_agent = keepAliveAgent;
+    const baseChClient = createChClient(clientConfig);
+    const client = wrapClientWithLogger(baseChClient, logger);
+    const tableExists = async (tableName) => {
+        const result = await client.query({
+            query: `EXISTS TABLE \`${tableName}\``,
+            format: 'JSONEachRow'
+        });
+        const rows = await result.json();
+        const exists = rows[0]?.result === 1 || rows[0]?.exists === 1;
+        return Boolean(exists);
+    };
+    const ensureTable = async (table) => {
+        const exists = await tableExists(table.$table);
+        if (!exists) {
+            await client.query({ query: table.toSQL() });
+        }
+    };
+    const dropTable = async (tableName, options) => {
+        const clause = options?.ifExists === false ? '' : ' IF EXISTS';
+        await client.query({ query: `DROP TABLE${clause} \`${tableName}\`` });
+    };
+    const binaryInsertConfig = {
+        url: normalizedConfig.url?.toString() || 'http://localhost:8123',
+        username: normalizedConfig.username || 'default',
+        password: normalizedConfig.password || '',
+        database: normalizedConfig.database || 'default',
+        skipValidation,
+    };
+    const baseClient = {
+        rawClient: client,
+        select: (fieldsOrTable) => {
+            const builder = new ClickHouseQueryBuilder(client);
+            if (!fieldsOrTable)
+                return builder.select();
+            if (typeof fieldsOrTable === 'object' && fieldsOrTable !== null && '$table' in fieldsOrTable) {
+                return builder.select().from(fieldsOrTable);
+            }
+            return builder.select(fieldsOrTable);
+        },
+        with: (name, query) => {
+            const builder = new ClickHouseQueryBuilder(client);
+            return builder.with(name, query);
+        },
+        insert: (table) => new ClickHouseInsertBuilder(client, table, binaryInsertConfig),
+        insertMany: async (table, values, opts) => {
+            const blockSize = Math.max(opts?.maxBlockSize || 10000, 1);
+            const plan = buildInsertPlan(table);
+            const mode = plan.useCompact ? 'compact' : 'json';
+            const processedRows = processRowsStream(values, plan, mode);
+            const stream = Readable.from(processedRows, { objectMode: true, highWaterMark: blockSize });
+            const clickhouse_settings = opts?.asyncInsertWait !== undefined
+                ? { async_insert: 1, wait_for_async_insert: opts.asyncInsertWait ? 1 : 0 }
+                : undefined;
+            await client.insert({
+                table: table.$table,
+                values: stream,
+                format: mode === 'compact' ? 'JSONCompactEachRow' : 'JSONEachRow',
+                columns: mode === 'compact' ? plan.columnNames : undefined,
+                ...(clickhouse_settings ? { clickhouse_settings } : {})
+            });
+        },
+        update: (table) => new ClickHouseUpdateBuilder(client, table),
+        delete: (table) => new ClickHouseDeleteBuilder(client, table),
+        command: async (params) => {
+            return client.query(params);
+        },
+        raw: async (query, params) => {
+            const resultSet = await client.query({
+                query,
+                query_params: params,
+                format: 'JSONEachRow'
+            });
+            return resultSet.json();
+        },
+        tableExists,
+        ensureTable,
+        dropTable,
+        close: () => client.close(),
+        schema: schema,
+        _config: config,
+        query: undefined
+    };
+    const relationalAPI = buildRelationalAPI(client, schema);
+    if (relationalAPI) {
+        baseClient.query = relationalAPI;
+    }
+    return baseClient;
+}
+export const createClientFromConfigObject = createHousekitClient;

package/dist/codegen/zod.js

@@ -0,0 +1,107 @@
+import { z } from 'zod';
+import { ClickHouseColumn } from '../column';
+function mapClickHouseTypeToZod(column) {
+    const type = column.type.toLowerCase();
+    let zodType;
+    if (type.startsWith('nullable(')) {
+        const innerType = column.type.slice('nullable('.length, -1);
+        const innerColumn = new ClickHouseColumn(column.name, innerType);
+        zodType = mapClickHouseTypeToZod(innerColumn).nullable();
+    }
+    else if (type.startsWith('array(')) {
+        const innerType = column.type.slice('array('.length, -1);
+        const innerColumn = new ClickHouseColumn(column.name, innerType);
+        zodType = z.array(mapClickHouseTypeToZod(innerColumn));
+    }
+    else if (type.startsWith('fixedstring')) {
+        zodType = z.string();
+    }
+    else if (type.startsWith('enum')) {
+        if (column.meta?.enumValues) {
+            zodType = z.enum(column.meta.enumValues);
+        }
+        else {
+            zodType = z.string();
+        }
+    }
+    else if (type.startsWith('datetime64')) {
+        zodType = z.date();
+    }
+    else if (type.startsWith('decimal')) {
+        zodType = z.string().refine((val) => !isNaN(parseFloat(val)), {
+            message: "Must be a valid decimal number string",
+        });
+    }
+    else {
+        switch (type) {
+            case 'uuid':
+            case 'string':
+            case 'json':
+            case 'ipv4':
+            case 'ipv6':
+                zodType = z.string();
+                break;
+            case 'int8':
+            case 'uint8':
+            case 'int16':
+            case 'uint16':
+            case 'int32':
+            case 'uint32':
+            case 'float32':
+            case 'float64':
+                zodType = z.number();
+                break;
+            case 'int64':
+            case 'uint64':
+            case 'int128':
+            case 'uint128':
+            case 'int256':
+            case 'uint256':
+                zodType = z.bigint();
+                break;
+            case 'boolean':
+            case 'bool':
+                zodType = z.boolean();
+                break;
+            case 'date':
+            case 'datetime':
+                zodType = z.date();
+                break;
+            default:
+                zodType = z.string();
+                break;
+        }
+    }
+    if (column.isNull && !type.startsWith('nullable(')) {
+        zodType = zodType.nullable();
+    }
+    return zodType;
+}
+export function generateSelectSchema(table) {
+    const shape = {};
+    for (const key in table.$columns) {
+        if (Object.prototype.hasOwnProperty.call(table.$columns, key)) {
+            const column = table.$columns[key];
+            shape[key] = mapClickHouseTypeToZod(column);
+        }
+    }
+    return z.object(shape);
+}
+export function generateInsertSchema(table) {
+    const shape = {};
+    for (const key in table.$columns) {
+        if (Object.prototype.hasOwnProperty.call(table.$columns, key)) {
+            const column = table.$columns[key];
+            let zodType = mapClickHouseTypeToZod(column);
+            const isOptionalBySchema = !column.isNull && (column.meta?.default !== undefined || column.meta?.defaultFn !== undefined || column.meta?.defaultExpr !== undefined || column.meta?.autoGenerate !== undefined);
+            const isOptionalByNullable = column.isNull;
+            if (isOptionalBySchema || isOptionalByNullable) {
+                zodType = zodType.optional();
+            }
+            else {
+            }
+            shape[key] = zodType;
+        }
+    }
+    return z.object(shape);
+}

package/dist/column.d.ts

@@ -26,8 +26,7 @@ export declare class ClickHouseColumn<TType = any, TNotNull extends boolean = tr
     isNull: boolean;
     meta?: ColumnMeta | undefined;
     tableName?: string;
-    constructor(name: string, type: string, isNull?: boolean, // Columns are NOT NULL by default (isNull = false)
-    meta?: ColumnMeta | undefined);
+    constructor(name: string, type: string, isNull?: boolean, meta?: ColumnMeta | undefined);
     clone<NTNotNull extends boolean = TNotNull, NAutoGenerated extends boolean = TAutoGenerated>(overrides?: {
         name?: string;
         type?: string;
@@ -40,37 +39,14 @@ export declare class ClickHouseColumn<TType = any, TNotNull extends boolean = tr
         version?: 1 | 3 | 4 | 5 | 6 | 7;
     }): ClickHouseColumn<TType, TNotNull, true>;
     primaryKey(): ClickHouseColumn<TType, true, TAutoGenerated>;
-    /**
-     * Define a default value for the column.
-     * Can be a static value or a SQL expression like 'now()'.
-     */
     default(value: any): ClickHouseColumn<TType, TNotNull, true>;
     references(getColumn: () => ClickHouseColumn, options?: {
         onDelete?: 'cascade' | 'set null' | 'restrict' | 'no action';
         onUpdate?: 'cascade' | 'set null' | 'restrict' | 'no action';
     }): ClickHouseColumn<TType, TNotNull, TAutoGenerated>;
-    /**
-     * Add a comment to the column in the database.
-     */
     comment(text: string): ClickHouseColumn<TType, TNotNull, TAutoGenerated>;
     alias(expression: string): ClickHouseColumn<TType, TNotNull, TAutoGenerated>;
-    /**
-     * Apply a compression codec to this column.
-     * Can be chained to apply multiple codecs (e.g., Delta then ZSTD).
-     *
-     * @example
-     * ```typescript
-     * // Optimize for time-series
-     * timestamp.codec('DoubleDelta').codec('ZSTD', 3)
-     * // Optimize for metrics
-     * value.codec('Gorilla')
-     * ```
-     */
     codec(type: 'ZSTD' | 'LZ4' | 'Delta' | 'DoubleDelta' | 'Gorilla' | 'None', level?: number): ClickHouseColumn<TType, TNotNull, TAutoGenerated>;
-    /**
-     * Calculates the column value on the client side before insertion.
-     * Useful for UUIDs, hashes, or computations based on other fields.
-     */
     $defaultFn(fn: (row: Record<string, any>) => any): ClickHouseColumn<TType, TNotNull, true>;
     toSQL(): string;
 }

package/dist/column.js

@@ -0,0 +1,133 @@
+export class ClickHouseColumn {
+    name;
+    type;
+    isNull;
+    meta;
+    tableName;
+    constructor(name, type, isNull = false, meta) {
+        this.name = name;
+        this.type = type;
+        this.isNull = isNull;
+        this.meta = meta;
+    }
+    clone(overrides = {}) {
+        const clonedMeta = overrides.meta ?? (this.meta ? { ...this.meta } : undefined);
+        const col = new ClickHouseColumn(overrides.name ?? this.name, overrides.type ?? this.type, overrides.isNull ?? this.isNull, clonedMeta);
+        col.tableName = this.tableName;
+        return col;
+    }
+    notNull() {
+        return this.clone({ isNull: false });
+    }
+    nullable() {
+        return this.clone({ isNull: true });
+    }
+    autoGenerate(options) {
+        if (this.type !== 'UUID') {
+            throw new Error('autoGenerate() can only be used with UUID columns');
+        }
+        const version = options?.version || 4;
+        const meta = { ...(this.meta ?? {}), autoGenerate: { type: 'uuid', version } };
+        return this.clone({ meta });
+    }
+    primaryKey() {
+        const meta = { ...(this.meta ?? {}), isPrimaryKey: true };
+        return this.clone({ isNull: false, meta });
+    }
+    default(value) {
+        const meta = { ...(this.meta ?? {}) };
+        if (typeof value === 'string') {
+            const trimmed = value.trim();
+            const isExpression = trimmed.includes('(') && trimmed.includes(')') ||
+                trimmed.match(/^[a-zA-Z_][a-zA-Z0-9_]*\s*\(/);
+            if (isExpression) {
+                meta.defaultExpr = trimmed;
+                delete meta.default;
+            }
+            else {
+                meta.default = value;
+                delete meta.defaultExpr;
+            }
+        }
+        else {
+            meta.default = value;
+            delete meta.defaultExpr;
+        }
+        return this.clone({ meta });
+    }
+    references(getColumn, options) {
+        const column = getColumn();
+        const meta = {
+            ...(this.meta ?? {}),
+            references: {
+                table: '',
+                column: column.name,
+                onDelete: options?.onDelete,
+                onUpdate: options?.onUpdate,
+            }
+        };
+        return this.clone({ meta });
+    }
+    comment(text) {
+        const meta = { ...(this.meta ?? {}), comment: text };
+        return this.clone({ meta });
+    }
+    alias(expression) {
+        const meta = { ...(this.meta ?? {}), alias: expression };
+        return this.clone({ meta });
+    }
+    codec(type, level) {
+        const codecStr = level ? `${type}(${level})` : type;
+        const meta = {
+            ...(this.meta ?? {}),
+            codec: this.meta?.codec ? `${this.meta.codec}, ${codecStr}` : codecStr
+        };
+        return this.clone({ meta });
+    }
+    $defaultFn(fn) {
+        const meta = { ...(this.meta ?? {}), defaultFn: fn };
+        return this.clone({ meta });
+    }
+    toSQL() {
+        const isComposite = this.type.startsWith('Array(') || this.type.startsWith('Map(') || this.type.startsWith('Tuple(');
+        const baseType = (this.isNull && !isComposite) ? `Nullable(${this.type})` : this.type;
+        const clauses = [baseType];
+        if (this.meta?.codec) {
+            clauses.push(`CODEC(${this.meta.codec})`);
+        }
+        if (this.meta?.defaultExpr) {
+            clauses.push(`DEFAULT ${this.meta.defaultExpr}`);
+        }
+        else if (this.meta?.default !== undefined) {
+            const defaultValue = this.meta.default;
+            let sqlValue;
+            if (typeof defaultValue === 'string') {
+                sqlValue = `'${defaultValue.replace(/'/g, "''")}'`;
+            }
+            else if (typeof defaultValue === 'number') {
+                sqlValue = String(defaultValue);
+            }
+            else if (typeof defaultValue === 'boolean') {
+                sqlValue = defaultValue ? '1' : '0';
+            }
+            else if (defaultValue === null) {
+                sqlValue = 'NULL';
+            }
+            else {
+                sqlValue = `'${String(defaultValue).replace(/'/g, "''")}'`;
+            }
+            clauses.push(`DEFAULT ${sqlValue}`);
+        }
+        if (this.meta?.materialized) {
+            clauses.push(`MATERIALIZED ${this.meta.materialized}`);
+        }
+        if (this.meta?.alias) {
+            clauses.push(`ALIAS ${this.meta.alias}`);
+        }
+        if (this.meta?.comment) {
+            const escapedComment = this.meta.comment.replace(/'/g, "''");
+            clauses.push(`COMMENT '${escapedComment}'`);
+        }
+        return clauses.join(' ');
+    }
+}

package/dist/compiler.d.ts

@@ -4,17 +4,10 @@ export declare class QueryCompiler {
     private paramCounter;
     reset(): void;
     private getNextParamName;
-    /**
-     * Compile with caching support.
-     * Returns a PreparedQuery ready for execution and the values to bind.
-     */
     compileWithCache(state: QueryBuilderState, client: any): {
         cachedQuery: PreparedQuery<any>;
         values: any[];
     };
-    /**
-     * Legacy/Internal method for getting SQL + Params directly (used by toSQL)
-     */
     compileSelect(state: QueryBuilderState): {
         sql: string;
         params: Record<string, unknown>;