@housekit/orm 0.1.28 → 0.1.29

package/README.md

@@ -14,7 +14,7 @@ HouseKit ORM is a modern database toolkit designed specifically for ClickHouse.
 ## 🚀 Key Features
 
 - **🛡️ First-Class TypeScript**: Full type inference for every query. Schema definition acts as the single source of truth.
-- **🏎️ Binary Inserts by Default**: Native `RowBinary` serialization is used automatically. **5-10x faster** than JSON.
+- **🏎️ High-Performance Inserts**: Optimized streaming with JSONCompact format and sync insert mode.
 - **🏗️ ClickHouse Native Engines**: Fluent DSL for `MergeTree`, `ReplacingMergeTree`, `SummingMergeTree`, `Distributed`, `Buffer`, and more.
 - **🔍 Advanced Analytics**: Specialized support for `ASOF JOIN`, `ARRAY JOIN`, `PREWHERE`, and complex Window Functions.
 - **🤝 Smart Relational API**: Query relations using `groupArray` internally, preventing row duplication.
@@ -74,7 +74,7 @@ import * as schema from './schema';
 
 const db = housekit({ url: 'http://localhost:8123' }, { schema });
 
-// Binary insert (default, fastest)
+// Standard insert (no data returned)
 await db.insert(schema.users).values({ email: 'a@b.com', role: 'admin' });
 
 // JSON insert with returning data
@@ -164,18 +164,32 @@ orderBy: [desc(users.createdAt), asc(users.name)]
 
 ## 🚀 High-Performance Inserts
 
-### Binary Insert (Default)
-
-Binary format is used by default for maximum performance:
+### Default Insert
 
 ```typescript
-// Binary insert (no data returned)
+// Standard insert (no data returned)
 await db.insert(events).values([
   { type: 'click', userId: '...' },
   { type: 'view', userId: '...' },
 ]);
 ```
 
+### Sync Insert (Fastest for Small Batches)
+
+Use `.syncInsert()` for maximum speed with batches under 5k rows:
+
+```typescript
+await db.insert(events).values(data).syncInsert();
+```
+
+### JSONCompact Format
+
+Use `.useCompactFormat()` for better performance with larger batches:
+
+```typescript
+await db.insert(events).values(data).useCompactFormat();
+```
+
 ### JSON Insert with Returning
 
 Use `.returningOne()` for single inserts or `.returning()` for multiple:
@@ -300,6 +314,32 @@ const query = await db.select()
 
 ---
 
+## 📊 Benchmarks
+
+Performance tested on local ClickHouse (Docker) with Bun runtime:
+
+| Rows | Method | Time | Throughput |
+|------|--------|------|------------|
+| 1,000 | JSON | 78ms | 12,821 rows/sec |
+| 1,000 | JSONCompact | 67ms | 14,925 rows/sec |
+| 1,000 | Sync Insert | 12ms | 83,333 rows/sec |
+| 5,000 | JSON | 108ms | 46,296 rows/sec |
+| 5,000 | JSONCompact | 56ms | 89,286 rows/sec |
+| 10,000 | JSON | 171ms | 58,480 rows/sec |
+| 10,000 | JSONCompact | 158ms | 63,291 rows/sec |
+
+Key findings:
+- **Sync insert** is fastest for small batches (<5k rows) - up to 6x faster
+- **JSONCompact** provides ~2x improvement for medium batches
+- For high-throughput scenarios, use `.syncInsert()` with batching
+
+Run the benchmark yourself:
+```bash
+bun run benchmark  # in app directory
+```
+
+---
+
 ## ⚡ Performance Optimizations
 
 HouseKit includes several optimizations for maximum throughput in production environments.

package/dist/builders/insert.d.ts

@@ -125,21 +125,10 @@ export declare class ClickHouseInsertBuilder<TTable extends TableRuntime<any, an
     turbo(): this;
     execute(): Promise<TReturn>;
     /**
-     * Resolve the actual format to use based on settings and table capabilities.
-     *
-     * Binary is preferred when:
-     * - No columns require server-side UUID generation
-     * - All column types are supported by our binary encoder
-     *
-     * Falls back to JSON when:
-     * - Columns use server-side defaults (e.g., generateUUIDv4())
-     * - Unsupported types are detected
+     * Resolve the actual format to use based on settings.
+     * Default is JSON (most reliable and well-optimized by the official client).
      */
     private resolveFormat;
-    /**
-     * Check if table and data are compatible with binary format
-     */
-    private canUseBinaryFormat;
     /**
      * Execute insert using JSON format
      */

package/dist/index.d.ts

@@ -1,6 +1,5 @@
-import type { ClickHouseClientConfigOptions } from '@clickhouse/client';
 import { type TableDefinition, type TableColumns } from './core';
-import { createClientFromConfigObject, type ClientConfigWithSchema, type HousekitClient as HousekitClientType } from './client';
+import { createClientFromConfigObject, type ClientConfigWithSchema, type HousekitClient as HousekitClientType, type HousekitClientConfig } from './client';
 import { generateSelectSchema, generateInsertSchema } from './codegen/zod';
 export { ClickHouseColumn } from './column';
 export { type TableDefinition, type TableColumns, type TableOptions, type IndexDefinition, type ProjectionDefinition, type InsertModel, type TableModel, type TableInsertArray, type TableRuntime, type TableInsert, index, projection, deriveTable, renderSchema } from './table';
@@ -67,7 +66,7 @@ export interface HouseKitConfig {
  * Load housekit.config.js/ts and create a client by name.
  */
 export declare function createClientFromConfig(databaseName?: string): Promise<HousekitClient>;
-export declare function housekit<TSchema extends Record<string, TableDefinition<any>> = Record<string, TableDefinition<any>>>(config: ClickHouseClientConfigOptions, options?: {
+export declare function housekit<TSchema extends Record<string, TableDefinition<any>> = Record<string, TableDefinition<any>>>(config: HousekitClientConfig, options?: {
     schema?: TSchema;
 }): HousekitClientType<TSchema>;
 export declare function createSchema<TCols extends TableColumns>(table: TableDefinition<TCols>): {

package/dist/index.js

@@ -4822,20 +4822,7 @@ class ClickHouseInsertBuilder {
     if (this._format !== "auto") {
       return this._format;
     }
-    const canUseBinary = this.canUseBinaryFormat(plan);
-    return canUseBinary ? "binary" : plan.useCompact ? "compact" : "json";
-  }
-  canUseBinaryFormat(plan) {
-    for (const col of plan.columns) {
-      if (col.useServerUUID) {
-        return false;
-      }
-      const type = col.column.type.toLowerCase();
-      if (type.includes("map(") || type.includes("tuple(") || type.includes("nested(") || type.includes("lowcardinality(")) {
-        return false;
-      }
-    }
-    return true;
+    return plan.useCompact ? "compact" : "json";
   }
   async executeJsonInsert(plan, tableName, format) {
     const mode = format === "compact" ? "compact" : "json";

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@housekit/orm",
-    "version": "0.1.28",
+    "version": "0.1.29",
     "description": "Type-safe ClickHouse ORM with modern DX and ClickHouse-specific optimizations. Features Turbo Mode (RowBinary), full engine support, and advanced query capabilities.",
     "type": "module",
     "main": "./dist/index.js",