@housekit/orm 0.1.47 → 0.1.48

package/README.md

@@ -326,6 +326,40 @@ await db.select()
 
 ---
 
+## 📦 Bundle Size & Performance
+
+HouseKit is optimized for minimal bundle impact in your applications:
+
+| Metric | Value |
+|--------|-------|
+| **Tarball Size** | 96KB |
+| **Unpacked Size** | 644KB |
+| **Tree Shaking** | ✅ Enabled |
+| **Granular Exports** | 17 paths for precise imports |
+
+### Optimizations
+
+- **Modular Build**: 46 separate JS files vs 1 monolithic bundle
+- **Tree-Shakable**: Consumers can eliminate unused code automatically
+- **Granular Exports**: Import only what you need
+- **No Runtime Overhead**: Zero runtime dependency overhead
+
+### Import Examples
+
+```typescript
+// Import everything (full bundle)
+import { housekit, Engine, t } from '@housekit/orm';
+
+// Import specific modules only (recommended for tree-shaking)
+import { Engine } from '@housekit/orm/engines';
+import { defineTable, t } from '@housekit/orm/schema-builder';
+import { ClickHouseColumn } from '@housekit/orm/column';
+```
+
+**Note**: While HouseKit includes advanced features like binary serialization, engines, and relations (96KB), the modular structure ensures your bundle only includes what you actually use.
+
+---
+
 ## 🛠 SQL Utilities
 
 ### Dynamic Queries

package/dist/builders/delete.js

@@ -0,0 +1,112 @@
+import { eq } from '../expressions';
+import { and } from '../modules/conditional';
+export class ClickHouseDeleteBuilder {
+    client;
+    table;
+    _where = null;
+    _lastMutationId = null;
+    constructor(client, table) {
+        this.client = client;
+        this.table = table;
+    }
+    where(expression) {
+        if (!expression)
+            return this;
+        if (typeof expression === 'object' && 'toSQL' in expression) {
+            this._where = expression;
+            return this;
+        }
+        if (typeof expression === 'object') {
+            const chunks = [];
+            for (const [key, value] of Object.entries(expression)) {
+                const column = this.table.$columns[key];
+                if (column && value !== undefined) {
+                    chunks.push(eq(column, value));
+                }
+            }
+            if (chunks.length > 0) {
+                const combined = chunks.length === 1 ? chunks[0] : and(...chunks);
+                if (combined)
+                    this._where = combined;
+            }
+        }
+        return this;
+    }
+    toSQL() {
+        if (this.table.$options.appendOnly !== false) {
+            throw new Error(`DELETE is blocked for append-only table ${this.table.$table}. Set appendOnly: false to allow.`);
+        }
+        if (!this._where) {
+            throw new Error("❌ DELETE requires a WHERE clause in ClickHouse (safety first!)");
+        }
+        const { sql, params } = this._where.toSQL({ ignoreTablePrefix: true });
+        const tableName = this.table.$table;
+        return {
+            query: `ALTER TABLE \`${tableName}\` DELETE WHERE ${sql}`,
+            params
+        };
+    }
+    async execute() {
+        const { query, params } = this.toSQL();
+        await this.client.command({
+            query,
+            query_params: params,
+        });
+        this._lastMutationId = await fetchLatestMutationId(this.client, this.table.$table);
+    }
+    async wait(options) {
+        if (!this._lastMutationId) {
+            await this.execute();
+        }
+        if (!this._lastMutationId)
+            return;
+        await waitForMutationCompletion(this.client, this.table.$table, this._lastMutationId, options);
+    }
+    async then(onfulfilled, onrejected) {
+        try {
+            await this.execute();
+            if (onfulfilled) {
+                return Promise.resolve(onfulfilled());
+            }
+            return Promise.resolve();
+        }
+        catch (error) {
+            if (onrejected) {
+                return Promise.resolve(onrejected(error));
+            }
+            return Promise.reject(error);
+        }
+    }
+}
+async function fetchLatestMutationId(client, tableName) {
+    const result = await client.query({
+        query: `SELECT mutation_id FROM system.mutations WHERE database = currentDatabase() AND table = {table:String} ORDER BY create_time DESC LIMIT 1 FORMAT JSONEachRow`,
+        query_params: { table: tableName }
+    });
+    const rows = await result.json();
+    return rows[0]?.mutation_id ?? null;
+}
+async function waitForMutationCompletion(client, tableName, mutationId, options) {
+    const pollInterval = options?.pollIntervalMs ?? 500;
+    const timeout = options?.timeoutMs ?? 60_000;
+    const start = Date.now();
+    while (true) {
+        const result = await client.query({
+            query: `SELECT is_done, latest_failed_part, latest_fail_reason FROM system.mutations WHERE database = currentDatabase() AND table = {table:String} AND mutation_id = {mid:String} FORMAT JSONEachRow`,
+            query_params: { table: tableName, mid: mutationId }
+        });
+        const rows = await result.json();
+        const row = rows[0];
+        if (!row)
+            return;
+        if (row.latest_fail_reason) {
+            throw new Error(`Mutation ${mutationId} failed: ${row.latest_fail_reason}`);
+        }
+        if (row.is_done === 1)
+            return;
+        if (Date.now() - start > timeout) {
+            throw new Error(`Mutation ${mutationId} not completed after ${timeout}ms`);
+        }
+        await new Promise(res => setTimeout(res, pollInterval));
+    }
+}

package/dist/builders/insert.d.ts

@@ -8,7 +8,6 @@ export interface BinaryInsertConfig {
     username: string;
     password: string;
     database: string;
-    /** Skip validation for maximum performance */
     skipValidation?: boolean;
 }
 export declare class ClickHouseInsertBuilder<TTable extends TableRuntime<any, any>, TReturn = any> {
@@ -26,116 +25,26 @@ export declare class ClickHouseInsertBuilder<TTable extends TableRuntime<any, an
     private _isSingle;
     private _skipValidation;
     constructor(client: ClickHouseClient, table: TTable, connectionConfig?: BinaryInsertConfig | undefined);
-    /**
-     * Skip enum validation for maximum performance.
-     * Use in production when you trust your data source.
-     */
     skipValidation(): this;
     values(value: CleanInsert<TTable> | Array<CleanInsert<TTable>> | Iterable<CleanInsert<TTable>> | AsyncIterable<CleanInsert<TTable>> | Readable): ClickHouseInsertBuilder<TTable, TReturn>;
-    /** @template [T = CleanInsert<TTable>] */
     insert(data: CleanInsert<TTable> | CleanInsert<TTable>[]): Promise<TReturn>;
-    /**
-     * Return inserted data as an array.
-     * Use when inserting multiple rows.
-     */
     returning(): ClickHouseInsertBuilder<TTable, CleanSelect<TTable>[]>;
-    /**
-     * Return the single inserted row directly (not wrapped in array).
-     * Use when inserting a single value for cleaner syntax.
-     *
-     * @example
-     * const user = await db.insert(users).values({ email: 'a@b.com' }).returningOne();
-     */
     returningOne(): ClickHouseInsertBuilder<TTable, CleanSelect<TTable>>;
-    /**
-     * Disable the default returning() behavior.
-     * Useful when you don't need the inserted data back and want to avoid the overhead.
-     */
     noReturning(): ClickHouseInsertBuilder<TTable, void>;
-    /**
-     * Force synchronous insert (disables async_insert).
-     * This is already the default in HouseKit for best performance.
-     */
     syncInsert(): this;
-    /**
-     * Enable asynchronous inserts on the server (not the default).
-     * ClickHouse will batch multiple small inserts into a single disk operation.
-     *
-     * Note: Sync insert is faster for most use cases. Use async only when
-     * you need server-side batching for very high-frequency writes.
-     */
     asyncInsert(waitForCompletion?: boolean): this;
-    /**
-     * Activate Background Batching (Client-side buffering).
-     *
-     * Instead of sending request immediately, rows are buffered in memory
-     * and sent when limit is reached or interval passes.
-     *
-     * @param options Batch configuration
-     */
     batch(options?: Partial<BatchConfig>): this;
-    /** Configure batch processing options */
     batchOptions(options: BatchTransformOptions): this;
-    /**
-     * Set the batch size for streaming inserts.
-     * Larger batches = better throughput, higher memory usage.
-     * Default: 1000
-     */
     batchSize(size: number): this;
-    /**
-     * Add a row to the background batcher.
-     *
-     * If batching is not yet configured, it will use default settings
-     * (10,000 rows or 5 seconds).
-     *
-     * Note: This method is "fire-and-forget" and does not wait for
-     * the database to acknowledge the insert.
-     */
     append(row: CleanInsert<TTable>): Promise<void>;
-    /**
-     * Use JSON format explicitly (this is already the default).
-     *
-     * @example
-     * ```typescript
-     * await db.insert(events)
-     *   .values(rows)
-     *   .useJsonFormat()
-     *   .execute();
-     * ```
-     */
     useJsonFormat(): this;
-    /**
-     * Use JSONCompactEachRow format (smaller payload than JSON).
-     */
     useCompactFormat(): this;
-    /**
-     * Force RowBinary format.
-     * Uses direct HTTP request (bypasses official client).
-     */
     useBinaryFormat(): this;
-    /**
-     * Alias for useBinaryFormat().
-     * @deprecated Binary format is not faster than JSON with the official client.
-     */
     turbo(): this;
     execute(): Promise<TReturn>;
-    /**
-     * Resolve the actual format to use based on settings.
-     * Default is JSON (most reliable and well-optimized by the official client).
-     */
     private resolveFormat;
-    /**
-     * Execute insert using JSON format
-     */
     private executeJsonInsert;
-    /**
-     * Execute insert using RowBinary format (fastest)
-     * Uses direct HTTP request since the official client doesn't support RowBinary yet
-     */
     private executeBinaryInsert;
-    /**
-     * Process rows and yield them with column names mapped and defaults applied
-     */
     private processRows;
     private collectReturningRows;
     private assertReturningRow;

package/dist/builders/insert.js

@@ -0,0 +1,393 @@
+import { buildInsertPlan, processRowWithPlan } from '../utils/insert-processing';
+import { createBatchTransformStream } from '../utils/batch-transform';
+import { SyncBinarySerializer } from '../utils/binary-worker-pool';
+import { Readable } from 'stream';
+import { globalBatcher } from '../utils/background-batcher';
+import http from 'http';
+import https from 'https';
+let uuidv4Fn = null;
+let uuidv7Fn = null;
+let uuidv1 = null;
+let uuidv6 = null;
+const hasNativeUUID = typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function';
+function getUUIDv4() {
+    if (hasNativeUUID) {
+        return crypto.randomUUID();
+    }
+    if (uuidv4Fn)
+        return uuidv4Fn();
+    const uuid = require('uuid');
+    uuidv4Fn = uuid.v4;
+    return uuidv4Fn();
+}
+function getUUIDv7() {
+    if (uuidv7Fn)
+        return uuidv7Fn();
+    const uuid = require('uuid');
+    uuidv7Fn = uuid.v7;
+    return uuidv7Fn();
+}
+export class ClickHouseInsertBuilder {
+    client;
+    table;
+    connectionConfig;
+    _values = null;
+    _async = false;
+    _waitForAsync = true;
+    _batchOptions = {};
+    _format = 'auto';
+    _batchConfig = null;
+    _forceJson = false;
+    _returning = false;
+    _isSingle = false;
+    _skipValidation = false;
+    constructor(client, table, connectionConfig) {
+        this.client = client;
+        this.table = table;
+        this.connectionConfig = connectionConfig;
+        if (table.$options?.asyncInsert !== undefined) {
+            this._async = table.$options.asyncInsert;
+        }
+        if (connectionConfig?.skipValidation) {
+            this._skipValidation = true;
+        }
+    }
+    skipValidation() {
+        this._skipValidation = true;
+        return this;
+    }
+    values(value) {
+        this._values = value;
+        this._isSingle = !Array.isArray(value) && !isIterable(value) && !isAsyncIterable(value) && !(value instanceof Readable);
+        return this;
+    }
+    async insert(data) {
+        return this.values(data).execute();
+    }
+    returning() {
+        this._returning = true;
+        return this;
+    }
+    returningOne() {
+        this._returning = true;
+        this._isSingle = true;
+        return this;
+    }
+    noReturning() {
+        this._returning = false;
+        return this;
+    }
+    syncInsert() {
+        this._async = false;
+        return this;
+    }
+    asyncInsert(waitForCompletion = true) {
+        this._async = true;
+        this._waitForAsync = waitForCompletion;
+        return this;
+    }
+    batch(options = {}) {
+        this._batchConfig = {
+            maxRows: options.maxRows ?? 10000,
+            flushIntervalMs: options.flushIntervalMs ?? 5000,
+        };
+        return this;
+    }
+    batchOptions(options) {
+        this._batchOptions = options;
+        return this;
+    }
+    batchSize(size) {
+        this._batchOptions.batchSize = size;
+        return this;
+    }
+    async append(row) {
+        if (!this._batchConfig) {
+            this.batch();
+        }
+        const plan = buildInsertPlan(this.table, { skipValidation: this._skipValidation });
+        const batcher = globalBatcher(this.client);
+        const oldValues = this._values;
+        this._values = [row];
+        try {
+            const rowIterator = this.processRows(plan);
+            for await (const processedRow of rowIterator) {
+                batcher.add(this.table, processedRow, this._batchConfig);
+            }
+        }
+        finally {
+            this._values = oldValues;
+        }
+    }
+    useJsonFormat() {
+        this._format = 'json';
+        this._forceJson = true;
+        return this;
+    }
+    useCompactFormat() {
+        this._format = 'compact';
+        return this;
+    }
+    useBinaryFormat() {
+        this._format = 'binary';
+        return this;
+    }
+    turbo() {
+        return this.useBinaryFormat();
+    }
+    async execute() {
+        if (!this._values) {
+            throw new Error("❌ No values to insert");
+        }
+        if (Array.isArray(this._values) && this._values.length === 0) {
+            throw new Error("❌ No values to insert");
+        }
+        const plan = buildInsertPlan(this.table, { skipValidation: this._skipValidation });
+        if (this._returning) {
+            if (this._batchConfig) {
+                throw new Error('❌ returning() cannot be used with background batching');
+            }
+            const { processedRows, resultRows } = await this.collectReturningRows(plan);
+            const stream = Readable.from(processedRows, { objectMode: true });
+            await this.client.insert({
+                table: this.table.$table,
+                values: stream,
+                format: 'JSONEachRow',
+                clickhouse_settings: {
+                    async_insert: this._async ? 1 : 0,
+                    wait_for_async_insert: this._waitForAsync ? 1 : 0,
+                },
+            });
+            if (this._isSingle && resultRows.length > 0) {
+                return resultRows[0];
+            }
+            return resultRows;
+        }
+        if (this._batchConfig && !this._forceJson) {
+            const batcher = globalBatcher(this.client);
+            const rowIterator = this.processRows(plan);
+            for await (const row of rowIterator) {
+                batcher.add(this.table, row, this._batchConfig);
+            }
+            return undefined;
+        }
+        const tableName = this.table.$table;
+        const format = this.resolveFormat(plan);
+        if (format === 'binary') {
+            await this.executeBinaryInsert(plan, tableName);
+        }
+        else {
+            await this.executeJsonInsert(plan, tableName, format);
+        }
+        return undefined;
+    }
+    resolveFormat(plan) {
+        if (this._format !== 'auto') {
+            return this._format;
+        }
+        return plan.useCompact ? 'compact' : 'json';
+    }
+    async executeJsonInsert(plan, tableName, format) {
+        const mode = format === 'compact' ? 'compact' : 'json';
+        let stream;
+        if (this._values instanceof Readable) {
+            stream = this._values;
+        }
+        else {
+            const iterable = (Array.isArray(this._values) || isIterable(this._values) || isAsyncIterable(this._values))
+                ? this._values
+                : [this._values];
+            const sourceStream = Readable.from(iterable, { objectMode: true });
+            const batchTransform = createBatchTransformStream(plan, mode, this._batchOptions);
+            stream = sourceStream.pipe(batchTransform);
+        }
+        await this.client.insert({
+            table: tableName,
+            values: stream,
+            format: mode === 'compact' ? 'JSONCompactEachRow' : 'JSONEachRow',
+            columns: mode === 'compact' && plan.columnNames.length > 0 ? plan.columnNames : undefined,
+            clickhouse_settings: {
+                async_insert: this._async ? 1 : 0,
+                wait_for_async_insert: this._waitForAsync ? 1 : 0,
+            },
+        });
+    }
+    async executeBinaryInsert(plan, tableName) {
+        if (!this.connectionConfig) {
+            throw new Error('❌ Binary format requires connection configuration. This is an internal error - please report it.');
+        }
+        const columns = plan.columns.map((col) => ({
+            name: col.columnName,
+            type: col.column.type,
+            isNullable: col.column.isNull,
+            propKey: col.propKey,
+        }));
+        const serializer = new SyncBinarySerializer(columns);
+        const allRows = [];
+        if (this._values instanceof Readable) {
+            for await (const chunk of this._values) {
+                allRows.push(chunk);
+            }
+        }
+        else {
+            for await (const row of this.processRows(plan, true)) {
+                allRows.push(row);
+            }
+        }
+        if (allRows.length === 0) {
+            return;
+        }
+        const binaryData = serializer.serialize(allRows);
+        const { url: baseUrl, username, password, database } = this.connectionConfig;
+        const url = new URL(baseUrl);
+        const queryParams = new URLSearchParams({
+            query: `INSERT INTO ${tableName} FORMAT RowBinary`,
+            database: database,
+        });
+        if (this._async) {
+            queryParams.set('async_insert', '1');
+            queryParams.set('wait_for_async_insert', this._waitForAsync ? '1' : '0');
+        }
+        url.search = queryParams.toString();
+        const isHttps = url.protocol === 'https:';
+        const httpModule = isHttps ? https : http;
+        const authHeader = Buffer.from(`${username}:${password}`).toString('base64');
+        return new Promise((resolve, reject) => {
+            const req = httpModule.request(url, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/octet-stream',
+                    'Authorization': `Basic ${authHeader}`,
+                },
+            }, (res) => {
+                let body = '';
+                res.on('data', (chunk) => { body += chunk; });
+                res.on('end', () => {
+                    if (res.statusCode && res.statusCode >= 200 && res.statusCode < 300) {
+                        resolve();
+                    }
+                    else {
+                        reject(new Error(`ClickHouse error (${res.statusCode}): ${body}`));
+                    }
+                });
+            });
+            req.on('error', reject);
+            req.write(binaryData);
+            req.end();
+        });
+    }
+    async *processRows(plan, skipDateTransform = false) {
+        const values = this._values;
+        const iterable = Array.isArray(values) ? values :
+            isIterable(values) ? values :
+                isAsyncIterable(values) ? values :
+                    [values];
+        for await (const row of iterable) {
+            const processedRow = {};
+            for (const col of plan.columns) {
+                let value = row[col.propKey] !== undefined ? row[col.propKey] : row[col.columnName];
+                if (value === undefined) {
+                    if (col.defaultFn) {
+                        value = col.defaultFn(row);
+                    }
+                    else if (col.autoUUIDVersion !== null && !col.useServerUUID) {
+                        value = col.autoUUIDVersion === 7 ? getUUIDv7() : getUUIDv4();
+                    }
+                    else if (col.hasDefault) {
+                        value = col.defaultValue;
+                    }
+                }
+                if (value !== undefined && !skipDateTransform) {
+                    value = col.transform(value);
+                }
+                processedRow[col.columnName] = value;
+            }
+            yield processedRow;
+        }
+    }
+    async collectReturningRows(plan) {
+        const processedRows = [];
+        const resultRows = [];
+        const values = this._values;
+        const iterable = values instanceof Readable ? values :
+            Array.isArray(values) ? values :
+                isIterable(values) ? values :
+                    isAsyncIterable(values) ? values :
+                        [values];
+        for await (const row of iterable) {
+            const processed = processRowWithPlan(row, plan, 'json');
+            for (const col of plan.columns) {
+                if (processed[col.columnName] !== undefined)
+                    continue;
+                const expr = col.column.meta?.defaultExpr;
+                if (!expr)
+                    continue;
+                const resolved = this.resolveClientDefaultExpr(expr);
+                if (resolved !== undefined) {
+                    processed[col.columnName] = col.transform(resolved);
+                }
+            }
+            this.assertReturningRow(row, processed, plan);
+            processedRows.push(processed);
+            const resultRow = {};
+            for (const col of plan.columns) {
+                const value = processed[col.columnName];
+                resultRow[col.propKey] = value;
+            }
+            resultRows.push(resultRow);
+        }
+        return { processedRows, resultRows };
+    }
+    assertReturningRow(rawRow, processed, plan) {
+        for (const col of plan.columns) {
+            const hasValue = rawRow[col.propKey] !== undefined || rawRow[col.columnName] !== undefined;
+            if (hasValue)
+                continue;
+            if (processed[col.columnName] !== undefined) {
+                continue;
+            }
+            if (col.defaultFn || (col.autoUUIDVersion !== null && !col.useServerUUID) || col.hasDefault) {
+                continue;
+            }
+            if (col.useServerUUID || col.column.meta?.defaultExpr) {
+                throw new Error(`❌ returning() cannot infer column '${col.columnName}' because it uses a server-side default. Provide a value or remove the default expression.`);
+            }
+        }
+    }
+    resolveClientDefaultExpr(expr) {
+        const normalized = expr.replace(/\s+/g, '').toLowerCase();
+        if (normalized === 'now()' || normalized === 'now64()' || normalized.startsWith('now64(')) {
+            return new Date();
+        }
+        if (normalized === 'generateuuidv4()')
+            return getUUIDv4();
+        if (normalized === 'generateuuidv7()')
+            return getUUIDv7();
+        if (normalized === 'generateuuidv1()')
+            return uuidv1?.() ?? getUUIDv4();
+        if (normalized === 'generateuuidv6()')
+            return uuidv6?.() ?? getUUIDv7();
+        return undefined;
+    }
+    async then(onfulfilled, onrejected) {
+        try {
+            const result = await this.execute();
+            if (onfulfilled) {
+                return Promise.resolve(onfulfilled(result));
+            }
+            return Promise.resolve(result);
+        }
+        catch (error) {
+            if (onrejected) {
+                return Promise.resolve(onrejected(error));
+            }
+            return Promise.reject(error);
+        }
+    }
+}
+function isIterable(obj) {
+    return obj && typeof obj[Symbol.iterator] === 'function';
+}
+function isAsyncIterable(obj) {
+    return obj && typeof obj[Symbol.asyncIterator] === 'function';
+}

package/dist/builders/prepared.d.ts

@@ -5,7 +5,6 @@ export declare class PreparedQuery<TResult> {
     private querySuggestions;
     private columnNames;
     private columnTypes;
-    constructor(client: any, sql: string, paramKeys: string[], // The order of parameters (p_1, p_2...)
-    querySuggestions: string[], columnNames?: string[], columnTypes?: string[]);
+    constructor(client: any, sql: string, paramKeys: string[], querySuggestions: string[], columnNames?: string[], columnTypes?: string[]);
     execute(values: any[]): Promise<TResult[]>;
 }