@housekit/orm 0.1.18 → 0.1.21

package/dist/relational.d.ts

@@ -1,5 +1,13 @@
-import { type TableDefinition } from './core';
+import { type RelationDefinition, type TableDefinition, type CleanSelect } from './core';
 import type { SQLExpression } from './expressions';
+type Simplify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+type RelationsOf<TTable> = TTable extends {
+    $relations: infer R;
+} ? R : {};
+type NormalizedRelations<TTable> = RelationsOf<TTable> extends Record<string, RelationDefinition<any>> ? RelationsOf<TTable> : {};
+type RelationTarget<T> = T extends RelationDefinition<infer TTarget> ? TTarget : never;
 /**
  * Join strategy for relational queries.
  *
@@ -10,6 +18,23 @@ export type JoinStrategy = 'auto' | 'standard' | 'global' | 'any' | 'global_any'
 /**
  * Configuration options for the Relational Query API (`findMany`, `findFirst`).
  */
+export type RelationalWith<TTable> = [
+    keyof NormalizedRelations<TTable>
+] extends [never] ? Record<string, boolean | RelationalFindOptions<any>> : {
+    [K in keyof NormalizedRelations<TTable>]?: boolean | RelationalFindOptions<RelationTarget<NormalizedRelations<TTable>[K]>>;
+};
+type NestedWith<T> = T extends RelationalFindOptions<any> ? T['with'] : undefined;
+type RelationValue<TRel, TWith> = TRel extends {
+    relation: 'one';
+    table: infer TRelTable;
+} ? RelationalResult<TRelTable, TWith> | null : TRel extends {
+    relation: 'many';
+    table: infer TRelTable;
+} ? Array<RelationalResult<TRelTable, TWith>> : never;
+type RelationValueForKey<TTable, K, TWithValue> = K extends keyof NormalizedRelations<TTable> ? TWithValue extends boolean ? RelationValue<NormalizedRelations<TTable>[K], undefined> : TWithValue extends RelationalFindOptions<any> ? RelationValue<NormalizedRelations<TTable>[K], NestedWith<TWithValue>> : never : any;
+export type RelationalResult<TTable, TWith = undefined> = Simplify<CleanSelect<TTable> & (TWith extends RelationalWith<TTable> ? {
+    [K in keyof TWith]: RelationValueForKey<TTable, K, TWith[K]>;
+} : {})>;
 export type RelationalFindOptions<TTable = any> = {
     /**
      * Filter conditions for the main query.
@@ -32,7 +57,7 @@ export type RelationalFindOptions<TTable = any> = {
      *
      * @example with: { posts: { limit: 5 }, profile: true }
      */
-    with?: Record<string, boolean | RelationalFindOptions>;
+    with?: RelationalWith<TTable>;
     /**
      * Join strategy for related data.
      *
@@ -46,6 +71,12 @@ export type RelationalFindOptions<TTable = any> = {
      */
     joinStrategy?: JoinStrategy;
 };
+export type RelationalAPI<TSchema extends Record<string, TableDefinition<any>>> = {
+    [K in keyof TSchema]: {
+        findMany: <TOpts extends RelationalFindOptions<TSchema[K]> | undefined>(opts?: TOpts) => Promise<Array<RelationalResult<TSchema[K], TOpts extends RelationalFindOptions<TSchema[K]> ? TOpts['with'] : undefined>>>;
+        findFirst: <TOpts extends RelationalFindOptions<TSchema[K]> | undefined>(opts?: TOpts) => Promise<RelationalResult<TSchema[K], TOpts extends RelationalFindOptions<TSchema[K]> ? TOpts['with'] : undefined> | null>;
+    };
+};
 /**
  * Build a modern relational API with ClickHouse-specific optimizations.
  *
@@ -58,4 +89,5 @@ export type RelationalFindOptions<TTable = any> = {
  * @param client - The ClickHouse client instance.
  * @param schema - The shared schema definition containing all table and relation metadata.
  */
-export declare function buildRelationalAPI(client: any, schema?: Record<string, TableDefinition<any>>): Record<string, any> | undefined;
+export declare function buildRelationalAPI<TSchema extends Record<string, TableDefinition<any>>>(client: any, schema?: TSchema): RelationalAPI<TSchema> | undefined;
+export {};

package/dist/relations.d.ts

@@ -1,4 +1,4 @@
-import type { ClickHouseColumn, RelationDefinition, TableDefinition } from './core';
+import type { ClickHouseColumn, RelationDefinition, TableColumns, TableDefinition } from './core';
 type OneConfig = {
     fields: ClickHouseColumn[];
     references: ClickHouseColumn[];
@@ -8,8 +8,11 @@ type ManyConfig = {
     references?: ClickHouseColumn[];
 };
 type RelationBuilderHelpers = {
-    one: (table: TableDefinition<any>, config: OneConfig) => RelationDefinition;
-    many: (table: TableDefinition<any>, config?: ManyConfig) => RelationDefinition;
+    one: <TTarget extends TableDefinition<TableColumns>>(table: TTarget, config: OneConfig) => RelationDefinition<TTarget>;
+    many: <TTarget extends TableDefinition<TableColumns>>(table: TTarget, config?: ManyConfig) => RelationDefinition<TTarget>;
 };
-export declare function relations<TTable extends TableDefinition<any>, TRelations extends Record<string, RelationDefinition>>(table: TTable, callback: (helpers: RelationBuilderHelpers) => TRelations): TRelations;
+export declare function relations<TTable extends TableDefinition<TableColumns>, TRelations extends Record<string, RelationDefinition<any>>>(table: TTable, callback: (helpers: RelationBuilderHelpers) => TRelations): asserts table is TTable & {
+    $relations: TRelations;
+};
+export declare function relations<TTable extends TableDefinition<TableColumns>, TRelations extends Record<string, RelationDefinition<any>>>(table: TTable, callback: (helpers: RelationBuilderHelpers) => TRelations): TRelations;
 export {};

package/dist/schema-builder.d.ts

@@ -132,6 +132,24 @@ export declare const t: {
     polygon: (name: string) => ClickHouseColumn<[number, number][][], true, false>;
     multiPolygon: (name: string) => ClickHouseColumn<[number, number][][][], true, false>;
     enum: (name: string, values: readonly string[]) => ClickHouseColumn<string, false, false>;
+    /**
+     * Adds 'created_at' and 'updated_at' columns with default now().
+     */
+    timestamps: () => {
+        created_at: ClickHouseColumn<string | Date, true, false>;
+        updated_at: ClickHouseColumn<string | Date, true, false>;
+    };
+    /**
+     * Adds a standard UUID primary key column (default: 'id').
+     */
+    primaryUuid: <TName extends string = "id">(name?: TName) => { [K in TName]: ClickHouseColumn<string>; };
+    /**
+     * Adds 'is_deleted' and 'deleted_at' columns for soft deletes.
+     */
+    softDeletes: () => {
+        is_deleted: ClickHouseColumn<boolean, true, false>;
+        deleted_at: ClickHouseColumn<string | Date, false, false>;
+    };
 };
 export type ColumnBuilder = typeof t;
 /**
@@ -160,13 +178,25 @@ export { chProjection as defineProjection };
 /**
  * Define relations for a table using a callback pattern.
  */
-export declare function relations<TTable extends TableDefinition<any>>(table: TTable, relationsBuilder: (helpers: {
-    one: (table: TableDefinition<any>, config: {
+export declare function relations<TTable extends TableDefinition<any>, TRelations extends Record<string, RelationDefinition<any>>>(table: TTable, relationsBuilder: (helpers: {
+    one: <TTarget extends TableDefinition<any>>(table: TTarget, config: {
+        fields: ClickHouseColumn<any, any, any>[];
+        references: ClickHouseColumn<any, any, any>[];
+    }) => RelationDefinition<TTarget>;
+    many: <TTarget extends TableDefinition<any>>(table: TTarget, config?: {
+        fields?: ClickHouseColumn<any, any, any>[];
+        references?: ClickHouseColumn<any, any, any>[];
+    }) => RelationDefinition<TTarget>;
+}) => TRelations): asserts table is TTable & {
+    $relations: TRelations;
+};
+export declare function relations<TTable extends TableDefinition<any>, TRelations extends Record<string, RelationDefinition<any>>>(table: TTable, relationsBuilder: (helpers: {
+    one: <TTarget extends TableDefinition<any>>(table: TTarget, config: {
         fields: ClickHouseColumn<any, any, any>[];
         references: ClickHouseColumn<any, any, any>[];
-    }) => RelationDefinition;
-    many: (table: TableDefinition<any>, config?: {
+    }) => RelationDefinition<TTarget>;
+    many: <TTarget extends TableDefinition<any>>(table: TTarget, config?: {
         fields?: ClickHouseColumn<any, any, any>[];
         references?: ClickHouseColumn<any, any, any>[];
-    }) => RelationDefinition;
-}) => Record<string, RelationDefinition>): Record<string, RelationDefinition>;
+    }) => RelationDefinition<TTarget>;
+}) => TRelations): TRelations;

package/dist/table.d.ts

@@ -53,16 +53,16 @@ export declare const index: (name: string) => {
     };
 };
 export declare const projection: (name: string, query: string) => ProjectionDefinition;
-export type RelationDefinition = {
+export type RelationDefinition<TTarget extends TableDefinition<any> = TableDefinition<any>> = {
     relation: 'one';
     name: string;
-    table: TableDefinition<any>;
+    table: TTarget;
     fields: ClickHouseColumn[];
     references: ClickHouseColumn[];
 } | {
     relation: 'many';
     name: string;
-    table: TableDefinition<any>;
+    table: TTarget;
     fields?: ClickHouseColumn[];
     references?: ClickHouseColumn[];
 };
@@ -81,21 +81,21 @@ export type InferSelectModel<T extends {
 };
 export type InferInsertModel<T extends {
     $columns: TableColumns;
-}> = TableInsert<T['$columns']> & {
-    (): TableInsert<T['$columns']>;
-    (): TableInsert<T['$columns']>[];
-    (): TableInsert<T['$columns']>;
-};
-export type CleanInsert<T extends {
-    $inferInsert?: any;
-}> = T extends {
-    $inferInsert?: infer I;
-} ? I : never;
-export type CleanSelect<T extends {
-    $inferSelect?: any;
-}> = T extends {
-    $inferSelect?: infer S;
-} ? S : never;
+}> = TableInsert<T['$columns']>;
+type InferInsertFromColumns<T> = T extends {
+    $columns: infer TCols extends TableColumns;
+} ? TableInsert<TCols> : never;
+type InferSelectFromColumns<T> = T extends {
+    $columns: infer TCols extends TableColumns;
+} ? InferSelectModel<{
+    $columns: TCols;
+}> : never;
+export type CleanInsert<T> = T extends {
+    $inferInsert: infer I;
+} ? I : InferInsertFromColumns<T>;
+export type CleanSelect<T> = T extends {
+    $inferSelect: infer S;
+} ? S : InferSelectFromColumns<T>;
 export type InferInsertValue<TCols extends TableColumns, K extends keyof TCols> = TCols[K] extends ClickHouseColumn<infer Type, infer NotNull, any> ? NotNull extends true ? Type : Type | undefined | null : never;
 export type TableInsertArray<T extends TableDefinition<TableColumns>> = T['$inferInsert'][];
 export type TableModel<T extends TableDefinition<TableColumns>> = PublicSelectModel<T>;
@@ -112,13 +112,24 @@ export type TableDefinition<TCols extends TableColumns, TOptions = TableOptions>
     toSQL(): string;
     toSQLs?(): string[];
     as(alias: string): TableDefinition<TCols, TOptions>;
-    $inferSelect?: InferSelectModel<{
+    $inferSelect: InferSelectModel<{
         $columns: TCols;
     }>;
-    $inferInsert?: InferInsertModel<{
+    $inferInsert: InferInsertModel<{
         $columns: TCols;
     }>;
 } & TCols;
+export type TableRuntime<TInsert = any, TSelect = any, TOptions = TableOptions> = {
+    $table: string;
+    $columns: TableColumns;
+    $options: TOptions;
+    $relations?: Record<string, RelationDefinition>;
+    toSQL(): string;
+    toSQLs?(): string[];
+    as(alias: string): TableRuntime<TInsert, TSelect, TOptions>;
+    $inferSelect: TSelect;
+    $inferInsert: TInsert;
+};
 export interface VersionedMeta {
     baseName: string;
     version: string | number;

package/dist/utils/background-batcher.d.ts

@@ -1,5 +1,5 @@
 import type { ClickHouseClient } from '@clickhouse/client';
-import type { TableDefinition } from '../core';
+import type { TableRuntime } from '../core';
 export interface BatchConfig {
     maxRows: number;
     flushIntervalMs: number;
@@ -12,7 +12,7 @@ declare class BackgroundBatcher {
     private serializers;
     constructor(client: ClickHouseClient);
     private getSerializer;
-    add(table: TableDefinition<any>, row: any, config: BatchConfig): Promise<void>;
+    add(table: TableRuntime<any, any>, row: any, config: BatchConfig): Promise<void>;
     flush(tableName: string): Promise<void>;
     flushAll(): Promise<void>;
 }

package/dist/utils/insert-processing.d.ts

@@ -1,4 +1,4 @@
-import { ClickHouseColumn, type TableDefinition } from '../core';
+import { ClickHouseColumn, type TableRuntime } from '../core';
 type UUIDVersion = 1 | 3 | 4 | 5 | 6 | 7;
 type PreparedInsertColumn = {
     propKey: string;
@@ -17,7 +17,7 @@ export type InsertPlan = {
     columnNames: string[];
     useCompact: boolean;
 };
-export declare function buildInsertPlan(table: TableDefinition<any>): InsertPlan;
+export declare function buildInsertPlan(table: TableRuntime<any, any>): InsertPlan;
 export declare function processRowWithPlan(row: Record<string, any>, plan: InsertPlan, mode?: 'compact' | 'json'): Record<string, any> | any[];
 export declare function processRowsStream(rows: AsyncIterable<Record<string, any>> | Iterable<Record<string, any>>, plan: InsertPlan, mode?: 'compact' | 'json'): AsyncGenerator<any[] | Record<string, any>, void, unknown>;
 export {};

package/package.json

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