@housekit/orm 0.1.47 → 0.1.49

package/README.md

@@ -2,16 +2,17 @@
 
 **The high-performance, type-safe ClickHouse ORM for Node.js and Bun.**
 
-> ⚠️ **Public Beta**: This package is currently in public beta. Feedback is highly appreciated as we polish the API for v1.0.
+> ⚠️ **Public Beta**: This package is currently in public beta. Feedback is highly appreciated as we polish API for v1.0.
 
-> 💡 **Interactive Docs**: Use [RepoGrep](https://app.ami.dev/repogrep?repo=https://github.com/pablofdezr/housekit) to search and query the entire codebase and documentation for free (Updated instantly).
+> 💡 **Interactive Docs**: Use [RepoGrep](https://app.ami.dev/repogrep?repo=https://github.com/pablofdezr/housekit) to search and query entire codebase and documentation for free (Updated instantly).
 
-> 💡 **Ask ZRead**: Need deep insights? [Ask ZRead](https://zread.ai/pablofdezr/housekit) for AI-powered understanding of the codebase (Updated weekly).
+> 💡 **Ask ZRead**: Need deep insights? [Ask ZRead](https://zread.ai/pablofdezr/housekit) for AI-powered understanding of codebase (Updated weekly).
 
-> 💡 **Ask Devin AI**: Have questions about integrating HouseKit? [Ask the Wiki](https://deepwiki.com/pablofdezr/housekit) for AI-powered assistance (Updated weekly).
+> 💡 **Ask Devin AI**: Have questions about integrating HouseKit? [Ask Wiki](https://deepwiki.com/pablofdezr/housekit) for AI-powered assistance (Updated weekly).
 
-HouseKit ORM is a modern database toolkit designed specifically for ClickHouse. It bridges the gap between ergonomic developer experiences and the extreme performance requirements of high-volume OLAP workloads.
+HouseKit ORM is a modern database toolkit designed specifically for ClickHouse. It bridges gap between ergonomic developer experiences and extreme performance requirements of high-volume OLAP workloads.
 
+[![npm](https://nodei.co/npm/@housekit/orm.png)](https://www.npmjs.com/package/@housekit/orm)
 [![npm version](https://img.shields.io/npm/v/@housekit/orm.svg)](https://www.npmjs.com/package/@housekit/orm)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Documentation](https://img.shields.io/badge/Docs-RepoGrep-teal?style=flat-square)](https://app.ami.dev/repogrep?repo=https://github.com/pablofdezr/housekit)
@@ -127,6 +128,86 @@ const [user] = await db
 
 ---
 
+## 🎯 The `housekit()` Client
+
+The `housekit()` function creates a fully-featured ClickHouse client with query builders for all operations.
+
+### Client Methods
+
+| Method | Description |
+|--------|-------------|
+| **`db.select()`** | Creates a SELECT query builder |
+| **`db.insert(table)`** | Inserts data into a table |
+| **`db.insertMany(table, data, opts)`** | Bulk inserts with configuration |
+| **`db.update(table)`** | Updates rows in a table |
+| **`db.delete(table)`** | Deletes rows from a table |
+| **`db.raw(sql, params)`** | Executes raw SQL queries |
+| **`db.command({query, query_params})`** | Executes ClickHouse commands |
+| **`db.close()`** | Closes the connection |
+
+### Client Properties
+
+| Property | Description |
+|----------|-------------|
+| **`db.rawClient`** | Raw `@clickhouse/client` instance (direct access) |
+| **`db.query`** ⭐ | **Relational API** - only available if `{ schema }` is passed |
+| **`db.schema`** | Your defined table schema |
+
+### ⭐ The Relational API (`db.query`)
+
+**Only available when you pass a schema:**
+
+```typescript
+const db = housekit({ url: 'http://localhost:8123' }, { 
+  schema: { users, events } 
+});
+```
+
+Then you can query using ORM-style methods:
+
+```typescript
+// Find by ID
+db.query.users.findById('uuid-here');
+
+// Find many with conditions
+db.query.users.findMany({ where: { role: 'admin' } });
+
+// Find first with columns
+db.query.users.findFirst({ columns: { id: true, email: true } });
+
+// Find with relations (automatic JOIN)
+db.query.users.findMany({ 
+  with: { posts: true } 
+});
+```
+
+### Complete Example
+
+```typescript
+const db = housekit({ url: 'http://localhost:8123' }, { schema });
+
+// 1. Insert using builder
+await db.insert(schema.users).values({ email: 'a@b.com', role: 'admin' });
+
+// 2. Regular SELECT
+const result = await db.select().from(schema.users).where(eq(schema.users.role, 'admin'));
+
+// 3. Relational query (automatic JOIN)
+const user = await db.query.users.findById('uuid-here', {
+  with: { posts: true }
+});
+
+// 4. Raw SQL
+const data = await db.raw('SELECT * FROM users LIMIT 10');
+
+// 5. Close connection
+await db.close();
+```
+
+---
+
+---
+
 ## 🔍 Relational Query API
 
 ### findMany / findFirst
@@ -326,6 +407,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;