@housekit/orm 0.1.28 → 0.1.30

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,26 @@ orderBy: [desc(users.createdAt), asc(users.name)]
 
 ## 🚀 High-Performance Inserts
 
-### Binary Insert (Default)
+### Default Insert (Sync Mode)
 
-Binary format is used by default for maximum performance:
+HouseKit uses synchronous inserts by default for maximum speed:
 
 ```typescript
-// Binary insert (no data returned)
+// Standard insert - uses sync mode automatically
 await db.insert(events).values([
   { type: 'click', userId: '...' },
   { type: 'view', userId: '...' },
 ]);
 ```
 
+### Async Insert (Server-Side Batching)
+
+Use `.asyncInsert()` when you want ClickHouse to batch writes internally:
+
+```typescript
+await db.insert(events).values(data).asyncInsert();
+```
+
 ### JSON Insert with Returning
 
 Use `.returningOne()` for single inserts or `.returning()` for multiple:
@@ -196,12 +204,6 @@ const [user1, user2] = await db
   .returning();
 ```
 
-### Force JSON Format
-
-```typescript
-await db.insert(events).values(data).useJsonFormat();
-```
-
 ### Background Batching
 
 Collect small writes into efficient batches:
@@ -300,6 +302,32 @@ const query = await db.select()
 
 ---
 
+## 📊 Benchmarks
+
+Performance tested on local ClickHouse (Docker) with Bun runtime:
+
+| Rows | Method | Time | Throughput |
+|------|--------|------|------------|
+| 1,000 | JSON | 19ms | 52,632 rows/sec |
+| 1,000 | JSON Sync | 13ms | 76,923 rows/sec |
+| 5,000 | JSON | 118ms | 42,373 rows/sec |
+| 5,000 | JSON Sync | 54ms | 92,593 rows/sec |
+| 10,000 | JSON | 159ms | 62,893 rows/sec |
+| 10,000 | JSON Sync | 161ms | 62,112 rows/sec |
+
+Key findings:
+- **Sync insert is the default** - fastest for most use cases
+- For batches <5k rows, sync is up to **2x faster**
+- For larger batches (10k+), performance is similar
+- Use `.asyncInsert()` only when you need server-side batching
+
+Run the benchmark yourself:
+```bash
+bun run benchmark  # in app directory
+```
+
+---
+
 ## ⚡ Performance Optimizations
 
 HouseKit includes several optimizations for maximum throughput in production environments.
@@ -334,53 +362,6 @@ const db = housekit({
 await db.insert(events).values(data).skipValidation();
 ```
 
-### Object Pooling
-
-HouseKit automatically pools `BinaryWriter` instances to reduce GC pressure. For advanced use cases:
-
-```typescript
-import { acquireWriter, releaseWriter } from '@housekit/orm';
-
-const writer = acquireWriter();
-try {
-  // Use writer for custom serialization
-} finally {
-  releaseWriter(writer);
-}
-```
-
-### Optimized Serialization
-
-For maximum performance with large batches:
-
-```typescript
-import { 
-  buildOptimizedBinaryConfig, 
-  serializeRowsOptimized 
-} from '@housekit/orm';
-
-// Pre-compile accessors once
-const config = buildOptimizedBinaryConfig(columns, { 
-  skipValidation: true 
-});
-
-// Serialize batches with pooled writer + pre-compiled accessors
-const buffer = serializeRowsOptimized(rows, config);
-```
-
-### TypedArray for Numeric Data
-
-For schemas with mostly numeric columns:
-
-```typescript
-import { isNumericHeavySchema, serializeNumericBatch } from '@housekit/orm';
-
-if (isNumericHeavySchema(columns)) {
-  // Uses Float64Array for better memory layout
-  const { numericBuffer, otherData } = serializeNumericBatch(rows, config, numericIndices);
-}
-```
-
 ---
 
 ## 🛠 Observability

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

@@ -4671,7 +4671,7 @@ class ClickHouseInsertBuilder {
   table;
   connectionConfig;
   _values = null;
-  _async = true;
+  _async = false;
   _waitForAsync = true;
   _batchOptions = {};
   _format = "auto";
@@ -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.30",
     "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",