@housekit/orm 0.1.13 → 0.1.16

package/README.md

@@ -162,6 +162,46 @@ await builder.append(row2);
 
 ---
 
+## 🛠️ Type-Safe Inserts
+
+### Simple Repository Pattern
+
+```typescript
+async insertEvents(events: auditEvents[]) {
+  return await db.insert(auditEvents).values(events);
+}
+
+// Usage
+await repository.insertEvents([
+  { venueId: 'venue-1', ingredientId: 'ing-1', type: 'restock', quantity: 100, at: new Date() },
+  { venueId: 'venue-2', ingredientId: 'ing-2', type: 'sale', quantity: -50, at: new Date(), referenceId: null }
+]);
+```
+
+### How It Works
+
+When you write `table.$inferInsert`, it includes a callable signature. TypeScript interprets `table[]` as invoking that callable and applying the array type, giving you `TableInsert<T>[]` automatically.
+
+### Alternative Approaches
+
+```typescript
+import { TableInsertArray } from '@housekit/orm';
+
+// Using explicit type helper
+async insertEvents(events: TableInsertArray<typeof salesEvents>) {
+  return await db.insert(salesEvents).values(events);
+}
+
+// Using $inferInsert directly
+async insertEvents(events: typeof salesEvents.$inferInsert[]) {
+  return await db.insert(salesEvents).values(events);
+}
+```
+
+**Recommended**: Use `table[]` for the cleanest, most ergonomic DX.
+
+---
+
 ## 🤝 Smart Relational API
 
 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.

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { type TableDefinition, type TableColumns } from './core';
 import { createClientFromConfigObject, type ClientConfigWithSchema } from './client';
 export { ClickHouseColumn } from './column';
-export { type TableDefinition, type TableColumns, type TableOptions, type IndexDefinition, type ProjectionDefinition, index, projection, deriveTable, renderSchema } from './table';
+export { type TableDefinition, type TableColumns, type TableOptions, type IndexDefinition, type ProjectionDefinition, type TableInsert, index, projection, deriveTable, renderSchema } from './table';
 export { Engine, type EngineConfiguration } from './engines';
 export * from './external';
 export * from './expressions';

package/dist/table.d.ts

@@ -71,10 +71,8 @@ export type TableRow<TCols extends TableColumns> = {
     [K in keyof TCols]: TCols[K] extends ClickHouseColumn<infer T, infer NotNull, any> ? NotNull extends true ? T : T | null : never;
 };
 export type TableInsert<TCols extends TableColumns> = {
-    [K in keyof TCols as TCols[K] extends ClickHouseColumn<any, infer NotNull, infer Auto> ? NotNull extends true ? Auto extends true ? never : K : never : never]: TCols[K] extends ClickHouseColumn<infer T, any, any> ? T : never;
-} & Partial<{
-    [K in keyof TCols as TCols[K] extends ClickHouseColumn<any, infer NotNull, infer Auto> ? NotNull extends true ? Auto extends true ? K : never : K : never]: TCols[K] extends ClickHouseColumn<infer T, any, any> ? T : never;
-}>;
+    [K in keyof TCols as TCols[K] extends ClickHouseColumn<any, infer NotNull, infer Auto> ? NotNull extends true ? Auto extends true ? never : K : K : never]: TCols[K] extends ClickHouseColumn<infer T, any, any> ? T : never;
+};
 type GetColumnType<T extends ClickHouseColumn> = T extends ClickHouseColumn<infer Type, infer IsNotNull, any> ? IsNotNull extends true ? Type : Type | null : never;
 export type InferSelectModel<T extends {
     $columns: TableColumns;
@@ -83,7 +81,9 @@ export type InferSelectModel<T extends {
 };
 export type InferInsertModel<T extends {
     $columns: TableColumns;
-}> = TableInsert<T['$columns']>;
+}> = TableInsert<T['$columns']> & {
+    (): TableInsert<T['$columns']>;
+};
 export type TableDefinition<TCols extends TableColumns, TOptions = TableOptions> = {
     $table: string;
     $columns: TCols;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@housekit/orm",
-    "version": "0.1.13",
+    "version": "0.1.16",
     "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",