@housekit/orm 0.1.17 → 0.1.21

package/README.md

@@ -167,7 +167,9 @@ await builder.append(row2);
 ### Simple Repository Pattern
 
 ```typescript
-async insertEvents(events: auditEvents[]) {
+import type { InferInsert } from '@housekit/orm';
+
+async insertEvents(events: InferInsert<typeof auditEvents>[]) {
   return await db.insert(auditEvents).values(events);
 }
 
@@ -178,27 +180,34 @@ await repository.insertEvents([
 ]);
 ```
 
-### 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
+### Type Helpers
 
 ```typescript
-import { TableInsertArray } from '@housekit/orm';
+import type { TableInsertArray, InferInsert } from '@housekit/orm';
+
+// Using the direct helper
+async insertEvents(events: InferInsert<typeof salesEvents>[]) {
+  return await db.insert(salesEvents).values(events);
+}
 
 // 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);
+### Inline Types (No Extra Exports)
+
+```typescript
+import { users } from './schema';
+import type { Infer } from '@housekit/orm';
+
+function UserCard({ user }: { user: Infer<typeof users> }) {
+  return <div>{user.email}</div>;
 }
 ```
 
-**Recommended**: Use `table[]` for the cleanest, most ergonomic DX.
+**Note**: Autocomplete shows clean data types by default without exposing internal types.
 
 ---
 
@@ -288,4 +297,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/delete.d.ts

@@ -1,7 +1,7 @@
 import type { ClickHouseClient } from '@clickhouse/client';
 import type { SQLExpression } from '../expressions';
-import type { TableDefinition, TableColumns } from '../core';
-export declare class ClickHouseDeleteBuilder<TTable extends TableDefinition<TableColumns>> {
+import type { TableRuntime } from '../core';
+export declare class ClickHouseDeleteBuilder<TTable extends TableRuntime<any, any>> {
     private client;
     private table;
     private _where;

package/dist/builders/insert.d.ts

@@ -1,5 +1,5 @@
 import type { ClickHouseClient } from '@clickhouse/client';
-import { type TableDefinition, type TableInsert, type TableColumns } from '../core';
+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';
@@ -20,7 +20,7 @@ export interface InsertOptions {
     /** Rows per batch when streaming */
     batchSize?: number;
 }
-export declare class ClickHouseInsertBuilder<TTable extends TableDefinition<TableColumns>> {
+export declare class ClickHouseInsertBuilder<TTable extends TableRuntime<any, any>, TReturn = void> {
     private client;
     private table;
     private _values;
@@ -31,8 +31,12 @@ export declare class ClickHouseInsertBuilder<TTable extends TableDefinition<Tabl
     private _batchSize;
     private _batchConfig;
     private _forceJson;
+    private _returning;
     constructor(client: ClickHouseClient, table: TTable);
-    values(value: TableInsert<TTable['$columns']> | Array<TableInsert<TTable['$columns']>> | Iterable<TableInsert<TTable['$columns']>> | AsyncIterable<TableInsert<TTable['$columns']>> | Readable): this;
+    values(value: CleanInsert<TTable> | Array<CleanInsert<TTable>> | Iterable<CleanInsert<TTable>> | AsyncIterable<CleanInsert<TTable>> | Readable): this;
+    /** @template [T = CleanInsert<TTable>] */
+    insert(data: CleanInsert<TTable> | CleanInsert<TTable>[]): Promise<this>;
+    returning(): ClickHouseInsertBuilder<TTable, CleanSelect<TTable>[]>;
     /**
      * Force synchronous insert (disables async_insert).
      * Use when you need immediate durability guarantee.
@@ -73,7 +77,7 @@ export declare class ClickHouseInsertBuilder<TTable extends TableDefinition<Tabl
      * Note: This method is "fire-and-forget" and does not wait for
      * the database to acknowledge the insert.
      */
-    append(row: TableInsert<TTable['$columns']>): Promise<void>;
+    append(row: CleanInsert<TTable>): Promise<void>;
     /**
      * Force JSON format (useful for debugging or compatibility).
      *
@@ -104,7 +108,7 @@ export declare class ClickHouseInsertBuilder<TTable extends TableDefinition<Tabl
      * Up to 5x faster than normal insertion.
      */
     turbo(): this;
-    execute(): Promise<void>;
+    execute(): Promise<TReturn>;
     /**
      * Resolve the actual format to use based on settings and table capabilities.
      *
@@ -133,6 +137,9 @@ export declare class ClickHouseInsertBuilder<TTable extends TableDefinition<Tabl
      * Process rows and yield them with column names mapped and defaults applied
      */
     private processRows;
-    then<TResult1 = void, TResult2 = never>(onfulfilled?: ((value: void) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
+    private collectReturningRows;
+    private assertReturningRow;
+    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

@@ -1,5 +1,5 @@
 import type { ClickHouseClient } from '@clickhouse/client';
-import { ClickHouseColumn, type TableDefinition, type TableOptions } from '../core';
+import { ClickHouseColumn, type TableDefinition, type TableOptions, type InferSelectModel } from '../core';
 import { type SQLExpression } from '../expressions';
 import { type QueryBuilderState, type SelectionShape, type SelectResult, type ResultWithArrayJoin, type InferQueryResult } from './select.types';
 export type { QueryBuilderState, SelectionShape, SelectResult } from './select.types';
@@ -8,6 +8,7 @@ type StandardJoinType = 'INNER' | 'LEFT' | 'RIGHT' | 'FULL' | 'CROSS';
 export declare class ClickHouseQueryBuilder<TTable extends TableDefinition<any> | null = null, TSelection extends SelectionShape | null = null, TResult = InferQueryResult<TTable, TSelection>> {
     private client;
     private _select;
+    private _selectResolver;
     private _table;
     private _prewhere;
     private _sample;
@@ -27,11 +28,15 @@ export declare class ClickHouseQueryBuilder<TTable extends TableDefinition<any>
     private _suggestions;
     constructor(client: ClickHouseClient);
     select<TNewSelection extends SelectionShape>(fields: TNewSelection): ClickHouseQueryBuilder<TTable, TNewSelection, InferQueryResult<TTable, TNewSelection>>;
+    select<TNewSelection extends SelectionShape>(fields: (cols: TTable extends TableDefinition<infer TCols> ? TCols : any) => TNewSelection): ClickHouseQueryBuilder<TTable, TNewSelection, InferQueryResult<TTable, TNewSelection>>;
     select(): ClickHouseQueryBuilder<TTable, null, InferQueryResult<TTable, null>>;
     from<TNewTable extends TableDefinition<any>>(table: TNewTable): ClickHouseQueryBuilder<TNewTable, TSelection, InferQueryResult<TNewTable, TSelection>>;
     from<TSubQuery extends ClickHouseQueryBuilder<any, any, any>>(subquery: TSubQuery, alias?: string): ClickHouseQueryBuilder<any, TSelection, any>;
     private fromSubquery;
-    where(expression: SQLExpression | undefined | null): this;
+    private resolveSelect;
+    where(expression: SQLExpression | (TTable extends TableDefinition<infer TCols> ? Partial<InferSelectModel<{
+        $columns: TCols;
+    }>> : Record<string, any>) | undefined | null): this;
     orderBy(col: ClickHouseColumn | SQLExpression | {
         col: ClickHouseColumn | SQLExpression;
         dir: 'ASC' | 'DESC';
@@ -214,12 +219,10 @@ export declare class ClickHouseQueryBuilder<TTable extends TableDefinition<any>
                 kind: "cte";
                 query?: string;
             }>;
-            $inferSelect?: import("../table").InferSelectModel<{
+            $inferSelect: 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").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;
+            }>;
+            $inferInsert: import("..").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>>>;
         } & (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/builders/update.d.ts

@@ -1,7 +1,7 @@
 import type { ClickHouseClient } from '@clickhouse/client';
 import type { SQLExpression } from '../expressions';
-import { type TableDefinition, type TableColumns } from '../core';
-export declare class ClickHouseUpdateBuilder<TTable extends TableDefinition<TableColumns>> {
+import { type TableRuntime } from '../core';
+export declare class ClickHouseUpdateBuilder<TTable extends TableRuntime<any, any>> {
     private client;
     private table;
     private _set;

package/dist/client.d.ts

@@ -3,9 +3,9 @@ import { ClickHouseQueryBuilder } from './builders/select';
 import { ClickHouseInsertBuilder } from './builders/insert';
 import { ClickHouseDeleteBuilder } from './builders/delete';
 import { ClickHouseUpdateBuilder } from './builders/update';
-import { type TableDefinition, type TableColumns, type TableInsert } from './core';
+import { type TableDefinition, type TableRuntime, type CleanInsert } from './core';
 import { type HousekitLogger } from './logger';
-import { type RelationalFindOptions } from './relational';
+import { type RelationalAPI } from './relational';
 export type HousekitClientConfig = ClickHouseClientConfigOptions & {
     schema?: Record<string, TableDefinition<any>>;
     logger?: HousekitLogger;
@@ -15,13 +15,13 @@ export interface HousekitClient<TSchema extends Record<string, TableDefinition<a
     rawClient: ClickHouseClient;
     select: <T extends Record<string, any> | TableDefinition<any>>(fieldsOrTable?: T) => any;
     with: (name: string, query: ClickHouseQueryBuilder<any>) => ClickHouseQueryBuilder<any>;
-    insert: <TCols extends TableColumns>(table: TableDefinition<TCols>) => ClickHouseInsertBuilder<any>;
-    insertMany: <TCols extends TableColumns>(table: TableDefinition<TCols>, values: Array<TableInsert<TCols>> | Iterable<TableInsert<TCols>> | AsyncIterable<TableInsert<TCols>>, opts?: {
+    insert: <TTable extends TableRuntime<any, any>>(table: TTable) => ClickHouseInsertBuilder<TTable>;
+    insertMany: <TTable extends TableRuntime<any, any>>(table: TTable, values: Array<CleanInsert<TTable>> | Iterable<CleanInsert<TTable>> | AsyncIterable<CleanInsert<TTable>>, opts?: {
         maxBlockSize?: number;
         asyncInsertWait?: boolean;
     }) => Promise<void>;
-    update: <TCols extends TableColumns>(table: TableDefinition<TCols>) => ClickHouseUpdateBuilder<any>;
-    delete: <TCols extends TableColumns>(table: TableDefinition<TCols>) => ClickHouseDeleteBuilder<any>;
+    update: <TTable extends TableRuntime<any, any>>(table: TTable) => ClickHouseUpdateBuilder<TTable>;
+    delete: <TTable extends TableRuntime<any, any>>(table: TTable) => ClickHouseDeleteBuilder<TTable>;
     command: (params: {
         query: string;
         query_params?: Record<string, unknown>;
@@ -39,12 +39,7 @@ export interface HousekitClient<TSchema extends Record<string, TableDefinition<a
     close: () => Promise<void>;
     schema: TSchema;
     _config: HousekitClientConfig;
-    query: TSchema extends Record<string, TableDefinition<any>> ? {
-        [K in keyof TSchema]: {
-            findMany: (opts?: RelationalFindOptions) => Promise<any[]>;
-            findFirst: (opts?: RelationalFindOptions) => Promise<any | null>;
-        };
-    } : undefined;
+    query: TSchema extends Record<string, TableDefinition<any>> ? RelationalAPI<TSchema> : undefined;
 }
 export declare function createHousekitClient<TSchema extends Record<string, TableDefinition<any>> | undefined = any>(config: HousekitClientConfig & {
     schema?: TSchema;

package/dist/index.d.ts

@@ -1,7 +1,21 @@
+import type { ClickHouseClientConfigOptions } from '@clickhouse/client';
 import { type TableDefinition, type TableColumns } from './core';
-import { createClientFromConfigObject, type ClientConfigWithSchema } from './client';
+import { createClientFromConfigObject, type ClientConfigWithSchema, type HousekitClient as HousekitClientType } from './client';
+import { generateSelectSchema, generateInsertSchema } from './codegen/zod';
 export { ClickHouseColumn } from './column';
-export { type TableDefinition, type TableColumns, type TableOptions, type IndexDefinition, type ProjectionDefinition, type TableInsert, index, projection, deriveTable, renderSchema } from './table';
+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';
+/**
+ * Infer the SELECT type (result) from a table definition.
+ */
+export type Infer<T> = T extends {
+    $inferSelect: infer U;
+} ? U : never;
+/**
+ * Infer the INSERT type (input) from a table definition.
+ */
+export type InferInsert<T> = T extends {
+    $inferInsert: infer U;
+} ? U : never;
 export { Engine, type EngineConfiguration } from './engines';
 export * from './external';
 export * from './expressions';
@@ -25,6 +39,13 @@ export { SyncBinarySerializer, BinaryWorkerPool, type BinaryWorkerPoolOptions, }
  * 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?: {
+    schema?: TSchema;
+}): HousekitClientType<TSchema>;
+export declare function createSchema<TCols extends TableColumns>(table: TableDefinition<TCols>): {
+    select: import("zod").ZodObject<any, import("zod/v4/core").$strip>;
+    insert: import("zod").ZodObject<any, import("zod/v4/core").$strip>;
+};
 export type HousekitClient = ReturnType<typeof createClientFromConfigObject>;
 export declare function createClient(): Promise<HousekitClient>;
 export declare function createClient(config: ClientConfigWithSchema): HousekitClient;
@@ -53,7 +74,6 @@ export declare function closeAllClients(clients: Record<string, HousekitClient>)
 import { defineTable, defineProjection, detectMaterializedViewDrift, extractMVQuery, createMigrationBridge, generateBlueGreenMigration, relations } from './schema-builder';
 import { sql } from './expressions';
 import { deriveTable } from './table';
-import { generateSelectSchema, generateInsertSchema } from './codegen/zod';
 /**
  * Optional default export for users who prefer this style.
  * Named exports are recommended for better tree-shaking.
@@ -122,6 +142,15 @@ declare const _default: {
         polygon: (name: string) => import("./column").ClickHouseColumn<[number, number][][], true, false>;
         multiPolygon: (name: string) => import("./column").ClickHouseColumn<[number, number][][][], true, false>;
         enum: (name: string, values: readonly string[]) => import("./column").ClickHouseColumn<string, false, false>;
+        timestamps: () => {
+            created_at: import("./column").ClickHouseColumn<string | Date, true, false>;
+            updated_at: import("./column").ClickHouseColumn<string | Date, true, false>;
+        };
+        primaryUuid: <TName extends string = "id">(name?: TName) => { [K in TName]: import("./column").ClickHouseColumn<string>; };
+        softDeletes: () => {
+            is_deleted: import("./column").ClickHouseColumn<boolean, true, false>;
+            deleted_at: import("./column").ClickHouseColumn<string | Date, false, false>;
+        };
     };
     table: typeof defineTable;
     defineTable: typeof defineTable;