@housekit/orm 0.1.14 → 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/builders/select.d.ts

@@ -217,7 +217,9 @@ export declare class ClickHouseQueryBuilder<TTable extends TableDefinition<any>
             $inferSelect?: import("../table").InferSelectModel<{
                 $columns: TSelection extends SelectionShape ? { [K in keyof (TSelection extends infer T_1 ? T_1 extends TSelection ? T_1 extends SelectionShape ? SelectResult<T_1> : Record<string, any> : never : never)]: ClickHouseColumn<(TSelection extends infer T_2 ? T_2 extends TSelection ? T_2 extends SelectionShape ? SelectResult<T_2> : Record<string, any> : never : never)[K], true, false>; } : Record<string, ClickHouseColumn<any, true, false>>;
             }> | undefined;
-            $inferInsert?: import("../table").TableInsert<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>>> | undefined;
+            $inferInsert?: import("../table").InferInsertModel<{
+                $columns: 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>>;
+            }> | undefined;
         } & (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>>);
         register: (mainQuery: ClickHouseQueryBuilder<any, any, any>) => ClickHouseQueryBuilder<any, any, any>;
     };

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

@@ -81,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.14",
+    "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",
@@ -65,4 +65,4 @@
     "engines": {
         "node": ">=18.0.0"
     }
-}
+}