@housekit/orm 0.1.25 → 0.1.27

package/README.md

@@ -14,10 +14,10 @@ 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.
-- **🏎️ Automatic Turbo Mode**: Native `RowBinary` serialization is used automatically when possible. Bypasses the overhead of JSON parsing for **5-10x faster inserts**.
+- **🏎️ Binary Inserts by Default**: Native `RowBinary` serialization is used automatically. **5-10x faster** than JSON.
 - **🏗️ 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 and keeping data transfer lean.
+- **🤝 Smart Relational API**: Query relations using `groupArray` internally, preventing row duplication.
 - **📦 Background Batching**: Built-in buffering to collect small inserts into high-performance batches automatically.
 
 ---
@@ -25,9 +25,6 @@ HouseKit ORM is a modern database toolkit designed specifically for ClickHouse.
 ## 📦 Installation
 
 ```bash
-# HouseKit requires the official ClickHouse client as a peer dependency
-npm install @housekit/orm @clickhouse/client
-# or
 bun add @housekit/orm @clickhouse/client
 ```
 
@@ -35,68 +32,199 @@ bun add @housekit/orm @clickhouse/client
 
 ## ⚡️ Quick Start
 
-### 1. Define your Table & Export Types
-Use the fluent `defineTable` API. You can export the inferred types directly from the schema definition thanks to **Phantom Types**.
+### 1. Define your Table
 
 ```typescript
 // schema.ts
-import { defineTable, t, Engine } from '@housekit/orm';
-
-export const webEvents = defineTable('web_events', {
-  id: t.uuid('id').primaryKey(),
-  eventType: t.string('event_type'),
-  url: t.string('url'),
-  revenue: t.decimal('revenue', 18, 4).default(0),
-  tags: t.array(t.string('tag')),
-  metadata: t.json('metadata'),
-  at: t.datetime('at').default('now()'),
+import { defineTable, t, Engine, relations } from '@housekit/orm';
+
+export const users = defineTable('users', {
+  id: t.uuid('id').autoGenerate({ version: 7 }).primaryKey().default('generateUUIDv7()'),
+  email: t.string('email'),
+  role: t.enum('role', ['admin', 'user']),
+  ...t.timestamps(),
 }, {
   engine: Engine.MergeTree(),
-  orderBy: 'at',
-  partitionBy: 'toYYYYMM(at)',
-  ttl: 'at + INTERVAL 1 MONTH'
+  orderBy: 'id'
 });
 
-// ✨ Export inferred types directly
-export type WebEvent = typeof webEvents.$inferSelect;
-export type NewWebEvent = typeof webEvents.$inferInsert;
+export const posts = defineTable('posts', {
+  id: t.uuid('id').autoGenerate({ version: 7 }).primaryKey().default('generateUUIDv7()'),
+  userId: t.uuid('user_id'),
+  title: t.string('title'),
+  createdAt: t.timestamp('created_at').default('now()'),
+}, {
+  engine: Engine.MergeTree(),
+  orderBy: 'createdAt'
+});
+
+relations(users, ({ many }) => ({
+  posts: many(posts, { fields: [users.id], references: [posts.userId] })
+}));
+
+export type User = typeof users.$type;
+export type NewUser = typeof users.$insert;
 ```
 
 ### 2. Connect and Query
-HouseKit automatically picks up configuration from your environment or `housekit.config.ts`.
 
 ```typescript
-import { createClient, sql } from '@housekit/orm';
-import { webEvents } from './schema';
-
-const db = await createClient();
-
-// Fully typed result inference.
-// No need to call .then() or .execute(), just await the builder!
-const results = await db.select({
-    id: webEvents.id,
-    path: webEvents.url,
-    total: sql<number>`sum(${webEvents.revenue})`
-  })
-  .from(webEvents)
-  .where({
-    // Object syntax implicitly uses AND operator
-    eventType: 'sale',
-    url: '/checkout'
-  })
-  .groupBy(webEvents.id, webEvents.url)
-  .limit(10);
+import { housekit } from '@housekit/orm';
+import * as schema from './schema';
+
+const db = housekit({ url: 'http://localhost:8123' }, { schema });
+
+// Binary insert (default, fastest)
+await db.insert(schema.users).values({ email: 'a@b.com', role: 'admin' });
+
+// JSON insert with returning data
+const [user] = await db
+  .insert(schema.users)
+  .values({ email: 'a@b.com', role: 'admin' })
+  .returning();
+```
+
+---
+
+## 🔍 Relational Query API
+
+### findMany / findFirst
+
+```typescript
+const users = await db.query.users.findMany({
+  where: { role: 'admin', active: true },
+  columns: { id: true, email: true },
+  orderBy: (cols, { desc }) => desc(cols.createdAt),
+  limit: 10,
+  with: {
+    posts: { limit: 5 }
+  }
+});
+```
+
+### findById
+
+```typescript
+// Simple lookup
+const user = await db.query.users.findById('uuid-here');
+
+// With relations
+const user = await db.query.users.findById('uuid-here', {
+  with: { posts: true }
+});
+```
+
+### where syntax
+
+```typescript
+// Object syntax (simplest)
+where: { email: 'a@b.com' }
+where: { role: 'admin', active: true }  // AND implícito
+
+// Direct expression
+where: eq(users.role, 'admin')
+
+// Callback for complex filters
+where: (cols, { and, gt, inArray }) => and(
+  gt(cols.age, 18),
+  inArray(cols.role, ['admin', 'moderator'])
+)
+```
+
+Available operators: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `inArray`, `notInArray`, `between`, `notBetween`, `has`, `hasAll`, `hasAny`, `and`, `or`, `not`, `isNull`, `isNotNull`
+
+### columns selection
+
+Select specific columns:
+
+```typescript
+const users = await db.query.users.findMany({
+  columns: { id: true, email: true }
+});
+// Returns: [{ id: '...', email: '...' }]
+```
+
+### orderBy
+
+```typescript
+// Callback (recommended)
+orderBy: (cols, { desc }) => desc(cols.createdAt)
+
+// Multiple columns
+orderBy: (cols, { desc, asc }) => [desc(cols.createdAt), asc(cols.name)]
+
+// Direct value
+orderBy: desc(users.createdAt)
+
+// Array
+orderBy: [desc(users.createdAt), asc(users.name)]
+```
+
+---
+
+## 🚀 High-Performance Inserts
+
+### Binary Insert (Default)
+
+Binary format is used by default for maximum performance:
+
+```typescript
+// Binary insert (no data returned)
+await db.insert(events).values([
+  { type: 'click', userId: '...' },
+  { type: 'view', userId: '...' },
+]);
+```
+
+### JSON Insert with Returning
+
+Use `.returningOne()` for single inserts or `.returning()` for multiple:
+
+```typescript
+// Single insert
+const user = await db
+  .insert(users)
+  .values({ email: 'a@b.com', role: 'admin' })
+  .returningOne();
+
+console.log(user.id); // Generated UUID
+
+// Multiple inserts
+const [user1, user2] = await db
+  .insert(users)
+  .values([{ email: 'a@b.com' }, { email: 'b@c.com' }])
+  .returning();
+```
+
+### Force JSON Format
+
+```typescript
+await db.insert(events).values(data).useJsonFormat();
+```
+
+### Background Batching
+
+Collect small writes into efficient batches:
+
+```typescript
+const builder = db.insert(events).batch({ 
+  maxRows: 10000, 
+  flushIntervalMs: 5000 
+});
+
+// Fire-and-forget
+await builder.append(event1);
+await builder.append(event2);
 ```
 
 ---
 
-## 🧠 Advanced Schema Definitions
+## 🧠 Advanced Schema
 
 ### Complex Engines
-HouseKit supports specialized ClickHouse engines with strict type checking for their parameters.
 
 ```typescript
-// SummingMergeTree: Automatically aggregates numeric columns
+// SummingMergeTree
 export const dailyRevenue = defineTable('daily_revenue', {
   day: t.date('day'),
   revenue: t.float64('revenue'),
@@ -105,23 +233,19 @@ export const dailyRevenue = defineTable('daily_revenue', {
   orderBy: 'day'
 });
 
-// ReplacingMergeTree: Deduplicates data by version
+// ReplacingMergeTree
 export const users = defineTable('users', {
   id: t.uint64('id'),
   email: t.string('email'),
   version: t.uint64('version'),
 }, {
   engine: Engine.ReplacingMergeTree('version'),
-  
-  // Portability: '{cluster}' references the server-side macro.
-  onCluster: '{cluster}', 
-  
+  onCluster: '{cluster}',
   orderBy: 'id'
 });
 ```
 
 ### Dictionaries
-Map external data or internal tables to fast in-memory dictionaries for ultra-low latency lookups.
 
 ```typescript
 import { defineDictionary } from '@housekit/orm';
@@ -138,130 +262,128 @@ export const userCache = defineDictionary('user_dict', {
 
 ---
 
-## 🚀 High-Performance Data Ingestion
+## 🔍 Specialized Joins
 
-### Automatic Turbo Mode (RowBinary)
-When you call `db.insert()`, HouseKit analyzes your schema. If types are compatible, it automatically switches to **Turbo Mode**, using native binary serialization instead of JSON.
+### ASOF JOIN
 
 ```typescript
-// Clean syntax: No .execute() needed. Just await.
-await db.insert(webEvents).values([
-  { id: '...', eventType: 'click', revenue: 0, metadata: { browser: 'chrome' } },
-  { id: '...', eventType: 'purchase', revenue: 99.90, metadata: { browser: 'safari' } },
-]);
-// Logic: Object -> Buffer (Binary) -> ClickHouse Stream (Zero-copy)
+const matched = await db.select()
+  .from(trades)
+  .asofJoin(quotes, sql`${trades.symbol} = ${quotes.symbol} AND ${trades.at} >= ${quotes.at}`)
+  .limit(100);
 ```
 
-### Background Batching
-Collect small, frequent writes into large batches to prevent the "too many parts" error in ClickHouse.
+### GLOBAL JOIN
 
 ```typescript
-const builder = db.insert(webEvents)
-  .batch({ 
-    maxRows: 10000, 
-    flushIntervalMs: 5000 
-  });
-
-// Add rows to the background queue.
-// Processing and flushing happen automatically.
-// Returns immediately (Fire-and-forget).
-await builder.append(row1);
-await builder.append(row2);
+await db.select()
+  .from(distributedTable)
+  .globalJoin(rightTable, condition);
 ```
 
 ---
 
-## 🛠️ Zero-Config Type Safety
-
-Because we use **Phantom Types**, you don't need to import generic helpers like `Infer<T>` in your application code. You can use `typeof table.$infer...` or the types you exported from your schema file.
+## 🛠 SQL Utilities
 
-### In Repository Functions
+### Dynamic Queries
 
 ```typescript
-import { webEvents, type NewWebEvent } from './schema';
+const conditions = [
+  eq(users.active, true),
+  gte(users.age, 18)
+];
 
-async function logEvents(events: NewWebEvent[]) {
-  // Types match automatically
-  return await db.insert(webEvents).values(events);
-}
+const query = await db.select()
+  .from(users)
+  .where(sql.join(conditions, sql` AND `));
 ```
 
 ---
 
-## 🤝 Smart Relational API
+## ⚡ Performance Optimizations
+
+HouseKit includes several optimizations for maximum throughput in production environments.
 
-Traditional ORMs produce "Flat Joins" that duplicate data (the Cartesian Product problem). HouseKit's Relational API uses ClickHouse's `groupArray` internally to fetch related data as nested arrays in a single, efficient query.
+### Connection Pooling
+
+Reuse HTTP connections across requests:
 
 ```typescript
-// Define relations in your schema first
-import { relations } from '@housekit/orm';
+const db = housekit({
+  url: 'http://localhost:8123',
+  pool: {
+    maxSockets: 200,      // Max concurrent connections
+    keepAlive: true,      // Reuse connections
+    timeout: 30000        // Socket timeout (ms)
+  }
+}, { schema });
+```
 
-relations(users, ({ many }) => ({
-  posts: many(posts, { fields: [users.id], references: [posts.userId] })
-}));
+### Skip Validation
 
-// Query with nested data
-const usersWithData = await db.query.users.findMany({
-  where: { country: 'US' }, // Object syntax
-  with: {
-    posts: {
-      limit: 5,
-      orderBy: { col: posts.createdAt, dir: 'DESC' }
-    }
-  },
-  limit: 10
-});
+Bypass enum validation in production when you trust your data source:
 
-// Result structure:
-// [{ id: 1, name: 'Alice', posts: [{ title: '...', ... }] }]
+```typescript
+// Global (all inserts)
+const db = housekit({
+  url: 'http://localhost:8123',
+  skipValidation: true
+}, { schema });
+
+// Per-insert
+await db.insert(events).values(data).skipValidation();
 ```
 
----
-
-## 🛠 SQL Utilities
+### Object Pooling
 
-### Dynamic Queries with `sql.join`
-Easily build complex queries by joining SQL fragments with separators.
+HouseKit automatically pools `BinaryWriter` instances to reduce GC pressure. For advanced use cases:
 
 ```typescript
-const conditions = [
-  eq(users.active, true),
-  gte(users.age, 18)
-];
+import { acquireWriter, releaseWriter } from '@housekit/orm';
 
-const query = await db.select()
-  .from(users)
-  .where(sql.join(conditions, sql` AND `));
+const writer = acquireWriter();
+try {
+  // Use writer for custom serialization
+} finally {
+  releaseWriter(writer);
+}
 ```
 
----
+### Optimized Serialization
 
-## 🔍 Specialized ClickHouse Joins
-
-### ASOF JOIN
-The industry standard for time-series matches (e.g., matching a trade with the closest price quote).
+For maximum performance with large batches:
 
 ```typescript
-const matched = await db.select()
-  .from(trades)
-  .asofJoin(quotes, sql`${trades.symbol} = ${quotes.symbol} AND ${trades.at} >= ${quotes.at}`)
-  .limit(100);
+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);
 ```
 
-### GLOBAL JOIN
-Essential for distributed setups to avoid local-data-only results on sharded clusters.
+### TypedArray for Numeric Data
+
+For schemas with mostly numeric columns:
 
 ```typescript
-await db.select()
-  .from(distributedTable)
-  .globalJoin(rightTable, condition);
+import { isNumericHeavySchema, serializeNumericBatch } from '@housekit/orm';
+
+if (isNumericHeavySchema(columns)) {
+  // Uses Float64Array for better memory layout
+  const { numericBuffer, otherData } = serializeNumericBatch(rows, config, numericIndices);
+}
 ```
 
 ---
 
-## 🛠 Observability & Logging
-
-Inject a custom logger to monitor query performance, throughput, and error rates.
+## 🛠 Observability
 
 ```typescript
 const db = await createClient({
@@ -278,4 +400,4 @@ const db = await createClient({
 
 ## License
 
-MIT © [Pablo Fernandez Ruiz](https://github.com/pablofdezr)
+MIT © [Pablo Fernandez Ruiz](https://github.com/pablofdezr)

package/dist/builders/insert.d.ts

@@ -3,40 +3,55 @@ import { type TableRuntime, type CleanInsert, type CleanSelect } from '../core';
 import { type BatchTransformOptions } from '../utils/batch-transform';
 import { Readable } from 'stream';
 import { type BatchConfig } from '../utils/background-batcher';
-/**
- * Insert format strategy:
- * - 'auto': Automatically choose best format (default - uses binary when possible)
- * - 'binary': Force RowBinary format (fastest)
- * - 'json': Force JSON format (for debugging/compatibility)
- * - 'compact': Force JSONCompactEachRow (smaller than JSON, faster than JSON)
- */
-type InsertFormat = 'auto' | 'binary' | 'json' | 'compact';
-export interface InsertOptions {
-    /**
-     * Format strategy for serialization.
-     * Default: 'auto' (uses RowBinary when possible, falls back to JSON)
-     */
-    format?: InsertFormat;
-    /** Rows per batch when streaming */
-    batchSize?: number;
+export interface BinaryInsertConfig {
+    url: string;
+    username: string;
+    password: string;
+    database: string;
+    /** Skip validation for maximum performance */
+    skipValidation?: boolean;
 }
-export declare class ClickHouseInsertBuilder<TTable extends TableRuntime<any, any>, TReturn = void> {
+export declare class ClickHouseInsertBuilder<TTable extends TableRuntime<any, any>, TReturn = any> {
     private client;
     private table;
+    private connectionConfig?;
     private _values;
     private _async;
     private _waitForAsync;
     private _batchOptions;
     private _format;
-    private _batchSize;
     private _batchConfig;
     private _forceJson;
     private _returning;
-    constructor(client: ClickHouseClient, table: TTable);
-    values(value: CleanInsert<TTable> | Array<CleanInsert<TTable>> | Iterable<CleanInsert<TTable>> | AsyncIterable<CleanInsert<TTable>> | Readable): this;
+    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<this>;
+    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).
      * Use when you need immediate durability guarantee.
@@ -131,6 +146,7 @@ export declare class ClickHouseInsertBuilder<TTable extends TableRuntime<any, an
     private executeJsonInsert;
     /**
      * Execute insert using RowBinary format (fastest)
+     * Uses direct HTTP request since the official client doesn't support RowBinary yet
      */
     private executeBinaryInsert;
     /**
@@ -142,4 +158,3 @@ export declare class ClickHouseInsertBuilder<TTable extends TableRuntime<any, an
     private resolveClientDefaultExpr;
     then<TResult1 = TReturn, TResult2 = never>(onfulfilled?: ((value: TReturn) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
 }
-export {};

package/dist/builders/select.d.ts

@@ -221,7 +221,9 @@ export declare class ClickHouseQueryBuilder<TTable extends TableDefinition<any>
             }>;
             readonly $inferSelect: { [K_2 in keyof (TSelection extends SelectionShape ? { [K in keyof (TSelection extends infer T_2 ? T_2 extends TSelection ? T_2 extends SelectionShape ? SelectResult<T_2> : Record<string, any> : never : never)]: ClickHouseColumn<(TSelection extends infer T_3 ? T_3 extends TSelection ? T_3 extends SelectionShape ? SelectResult<T_3> : Record<string, any> : never : never)[K], true, false>; } : Record<string, ClickHouseColumn<any, true, false>>)]: (TSelection extends SelectionShape ? { [K in keyof (TSelection extends infer T_3 ? T_3 extends TSelection ? T_3 extends SelectionShape ? SelectResult<T_3> : Record<string, any> : never : never)]: ClickHouseColumn<(TSelection extends infer T_4 ? T_4 extends TSelection ? T_4 extends SelectionShape ? SelectResult<T_4> : Record<string, any> : never : never)[K], true, false>; } : Record<string, ClickHouseColumn<any, true, false>>)[K_2] extends infer T_4 ? T_4 extends (TSelection extends SelectionShape ? { [K in keyof (TSelection extends infer T_5 ? T_5 extends TSelection ? T_5 extends SelectionShape ? SelectResult<T_5> : Record<string, any> : never : never)]: ClickHouseColumn<(TSelection extends infer T_6 ? T_6 extends TSelection ? T_6 extends SelectionShape ? SelectResult<T_6> : Record<string, any> : never : never)[K], true, false>; } : Record<string, ClickHouseColumn<any, true, false>>)[K_2] ? T_4 extends ClickHouseColumn<infer Type, infer IsNotNull extends boolean, any> ? IsNotNull extends true ? Type : Type | null : never : never : never; } extends infer T_1 ? { [K_1 in keyof T_1]: T_1[K_1]; } : never;
             readonly $inferInsert: import("..").TableInsert<TSelection extends SelectionShape ? { [K in keyof (TSelection extends infer T_4 ? T_4 extends TSelection ? T_4 extends SelectionShape ? SelectResult<T_4> : Record<string, any> : never : never)]: ClickHouseColumn<(TSelection extends infer T_5 ? T_5 extends TSelection ? T_5 extends SelectionShape ? SelectResult<T_5> : Record<string, any> : never : never)[K], true, false>; } : Record<string, ClickHouseColumn<any, true, false>>> extends infer T_3 ? { [K_3 in keyof T_3]: T_3[K_3]; } : never;
-        } & (TSelection extends SelectionShape ? { [K in keyof (TSelection extends infer T_5 ? T_5 extends TSelection ? T_5 extends SelectionShape ? SelectResult<T_5> : Record<string, any> : never : never)]: ClickHouseColumn<(TSelection extends infer T_6 ? T_6 extends TSelection ? T_6 extends SelectionShape ? SelectResult<T_6> : Record<string, any> : never : never)[K], true, false>; } : Record<string, ClickHouseColumn<any, true, false>>);
+            readonly $type: { [K_5 in keyof (TSelection extends SelectionShape ? { [K in keyof (TSelection extends infer T_6 ? T_6 extends TSelection ? T_6 extends SelectionShape ? SelectResult<T_6> : Record<string, any> : never : never)]: ClickHouseColumn<(TSelection extends infer T_7 ? T_7 extends TSelection ? T_7 extends SelectionShape ? SelectResult<T_7> : Record<string, any> : never : never)[K], true, false>; } : Record<string, ClickHouseColumn<any, true, false>>)]: (TSelection extends SelectionShape ? { [K in keyof (TSelection extends infer T_7 ? T_7 extends TSelection ? T_7 extends SelectionShape ? SelectResult<T_7> : Record<string, any> : never : never)]: ClickHouseColumn<(TSelection extends infer T_8 ? T_8 extends TSelection ? T_8 extends SelectionShape ? SelectResult<T_8> : Record<string, any> : never : never)[K], true, false>; } : Record<string, ClickHouseColumn<any, true, false>>)[K_5] extends infer T_8 ? T_8 extends (TSelection extends SelectionShape ? { [K in keyof (TSelection extends infer T_9 ? T_9 extends TSelection ? T_9 extends SelectionShape ? SelectResult<T_9> : Record<string, any> : never : never)]: ClickHouseColumn<(TSelection extends infer T_10 ? T_10 extends TSelection ? T_10 extends SelectionShape ? SelectResult<T_10> : Record<string, any> : never : never)[K], true, false>; } : Record<string, ClickHouseColumn<any, true, false>>)[K_5] ? T_8 extends ClickHouseColumn<infer Type, infer IsNotNull extends boolean, any> ? IsNotNull extends true ? Type : Type | null : never : never : never; } extends infer T_5 ? { [K_4 in keyof T_5]: T_5[K_4]; } : never;
+            readonly $insert: import("..").TableInsert<TSelection extends SelectionShape ? { [K in keyof (TSelection extends infer T_8 ? T_8 extends TSelection ? T_8 extends SelectionShape ? SelectResult<T_8> : Record<string, any> : never : never)]: ClickHouseColumn<(TSelection extends infer T_9 ? T_9 extends TSelection ? T_9 extends SelectionShape ? SelectResult<T_9> : Record<string, any> : never : never)[K], true, false>; } : Record<string, ClickHouseColumn<any, true, false>>> extends infer T_7 ? { [K_3 in keyof T_7]: T_7[K_3]; } : never;
+        } & (TSelection extends SelectionShape ? { [K in keyof (TSelection extends infer T_9 ? T_9 extends TSelection ? T_9 extends SelectionShape ? SelectResult<T_9> : Record<string, any> : never : never)]: ClickHouseColumn<(TSelection extends infer T_10 ? T_10 extends TSelection ? T_10 extends SelectionShape ? SelectResult<T_10> : Record<string, any> : never : never)[K], true, false>; } : Record<string, ClickHouseColumn<any, true, false>>);
         register: (mainQuery: ClickHouseQueryBuilder<any, any, any>) => ClickHouseQueryBuilder<any, any, any>;
     };
     final(): this;

package/dist/client.d.ts

@@ -6,9 +6,23 @@ import { ClickHouseUpdateBuilder } from './builders/update';
 import { type TableDefinition, type TableRuntime, type CleanInsert } from './core';
 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;
 export interface HousekitClient<TSchema extends Record<string, TableDefinition<any>> | undefined = any> {
@@ -45,3 +59,4 @@ export declare function createHousekitClient<TSchema extends Record<string, Tabl
     schema?: TSchema;
 }): HousekitClient<TSchema>;
 export declare const createClientFromConfigObject: typeof createHousekitClient;
+export {};

package/dist/column.d.ts

@@ -44,7 +44,7 @@ export declare class ClickHouseColumn<TType = any, TNotNull extends boolean = tr
      * Define a default value for the column.
      * Can be a static value or a SQL expression like 'now()'.
      */
-    default(value: any): ClickHouseColumn<TType, TNotNull, TAutoGenerated>;
+    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';
@@ -71,6 +71,6 @@ export declare class ClickHouseColumn<TType = any, TNotNull extends boolean = tr
      * 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, TAutoGenerated>;
+    $defaultFn(fn: (row: Record<string, any>) => any): ClickHouseColumn<TType, TNotNull, true>;
     toSQL(): string;
 }