@simplysm/orm-common 13.0.98 → 13.0.99

package/docs/schema-builders.md

@@ -1,27 +1,30 @@
 # Schema Builders
 
-Fluent API builders for defining tables, views, procedures, columns, indexes, and relations.
+## `Table`
 
-Source: `src/schema/table-builder.ts`, `src/schema/view-builder.ts`, `src/schema/procedure-builder.ts`, `src/schema/factory/column-builder.ts`, `src/schema/factory/index-builder.ts`, `src/schema/factory/relation-builder.ts`, `src/models/system-migration.ts`
-
-## Table / TableBuilder
-
-### Table (factory function)
+Table builder factory function. Creates a `TableBuilder` for defining table schema via fluent API.
 
 ```typescript
 function Table(name: string): TableBuilder<{}, {}>;
 ```
 
-### TableBuilder
+## `TableBuilder`
 
-Immutable fluent builder. Each method returns a new instance.
+Database table definition builder. Define columns, PK, indexes, and relations via fluent API.
 
 ```typescript
 class TableBuilder<
   TColumns extends ColumnBuilderRecord,
   TRelations extends RelationBuilderRecord,
 > {
-  readonly meta: {
+  readonly $columns!: TColumns;
+  readonly $relations!: TRelations;
+  readonly $inferSelect!: InferColumns<TColumns> & InferDeepRelations<TRelations>;
+  readonly $inferColumns!: InferColumns<TColumns>;
+  readonly $inferInsert!: InferInsertColumns<TColumns>;
+  readonly $inferUpdate!: InferUpdateColumns<TColumns>;
+
+  constructor(readonly meta: {
     name: string;
     description?: string;
     database?: string;
@@ -30,60 +33,41 @@ class TableBuilder<
     primaryKey?: (keyof TColumns & string)[];
     relations?: TRelations;
     indexes?: IndexBuilder<(keyof TColumns & string)[]>[];
-  };
-
-  // Type inference helpers
-  readonly $inferSelect: InferColumns<TColumns> & InferDeepRelations<TRelations>;
-  readonly $inferColumns: InferColumns<TColumns>;
-  readonly $inferInsert: InferInsertColumns<TColumns>;
-  readonly $inferUpdate: InferUpdateColumns<TColumns>;
+  });
 
   description(desc: string): TableBuilder<TColumns, TRelations>;
   database(db: string): TableBuilder<TColumns, TRelations>;
   schema(schema: string): TableBuilder<TColumns, TRelations>;
-  columns<T extends ColumnBuilderRecord>(
-    fn: (c: ReturnType<typeof createColumnFactory>) => T,
-  ): TableBuilder<T, TRelations>;
+  columns<TNewColumnDefs extends ColumnBuilderRecord>(
+    fn: (c: ReturnType<typeof createColumnFactory>) => TNewColumnDefs,
+  ): TableBuilder<TNewColumnDefs, TRelations>;
   primaryKey(...columns: (keyof TColumns & string)[]): TableBuilder<TColumns, TRelations>;
-  indexes(
-    fn: (i: ReturnType<typeof createIndexFactory<keyof TColumns & string>>) => IndexBuilder<string[]>[],
-  ): TableBuilder<TColumns, TRelations>;
-  relations<T extends RelationBuilderRecord>(
-    fn: (r: RelationFactory) => T,
-  ): TableBuilder<TColumns, T>;
+  indexes(fn: (i: ...) => IndexBuilder<string[]>[]): TableBuilder<TColumns, TRelations>;
+  relations<T extends RelationBuilderRecord>(fn: (r: ...) => T): TableBuilder<TColumns, T>;
 }
 ```
 
-**Example:**
+| Method | Description |
+|--------|-------------|
+| `description()` | Set table description (DDL comment) |
+| `database()` | Set database name |
+| `schema()` | Set schema name (MSSQL/PostgreSQL) |
+| `columns()` | Define columns using the column factory |
+| `primaryKey()` | Set primary key columns (composite PK supported) |
+| `indexes()` | Define indexes using the index factory |
+| `relations()` | Define relations using the relation factory |
 
-```typescript
-const User = Table("User")
-  .database("mydb")
-  .columns((c) => ({
-    id: c.bigint().autoIncrement(),
-    name: c.varchar(100),
-    email: c.varchar(200).nullable(),
-    status: c.varchar(20).default("active"),
-    createdAt: c.datetime(),
-  }))
-  .primaryKey("id")
-  .indexes((i) => [i.index("email").unique()])
-  .relations((r) => ({
-    posts: r.foreignKeyTarget(() => Post, "author"),
-  }));
-```
+## `View`
 
----
-
-## View / ViewBuilder
-
-### View (factory function)
+View builder factory function. Creates a `ViewBuilder` for defining view schema via fluent API.
 
 ```typescript
 function View(name: string): ViewBuilder<any, any, {}>;
 ```
 
-### ViewBuilder
+## `ViewBuilder`
+
+Database view definition builder. Define view query and relations via fluent API.
 
 ```typescript
 class ViewBuilder<
@@ -91,16 +75,17 @@ class ViewBuilder<
   TData extends DataRecord,
   TRelations extends RelationBuilderRecord,
 > {
-  readonly meta: {
+  readonly $relations!: TRelations;
+  readonly $inferSelect!: TData;
+
+  constructor(readonly meta: {
     name: string;
     description?: string;
     database?: string;
     schema?: string;
     viewFn?: (db: TDbContext) => Queryable<TData, any>;
     relations?: TRelations;
-  };
-
-  readonly $inferSelect: TData;
+  });
 
   description(desc: string): ViewBuilder<TDbContext, TData, TRelations>;
   database(db: string): ViewBuilder<TDbContext, TData, TRelations>;
@@ -108,42 +93,39 @@ class ViewBuilder<
   query<TViewData extends DataRecord, TDb extends DbContextBase>(
     viewFn: (db: TDb) => Queryable<TViewData, any>,
   ): ViewBuilder<TDb, TViewData, TRelations>;
-  relations<T extends RelationBuilderRecord>(
-    fn: (r: RelationFactory) => T,
-  ): ViewBuilder<TDbContext, TData & InferDeepRelations<T>, TRelations>;
+  relations<T extends RelationBuilderRecord>(fn: (r: ...) => T): ViewBuilder<TDbContext, TData & InferDeepRelations<T>, TRelations>;
 }
 ```
 
-**Example:**
-
-```typescript
-const ActiveUsers = View("ActiveUsers")
-  .database("mydb")
-  .query((db: MyDb) =>
-    db.user()
-      .where((u) => [expr.eq(u.status, "active")])
-      .select((u) => ({ id: u.id, name: u.name, email: u.email }))
-  );
-```
-
----
+| Method | Description |
+|--------|-------------|
+| `description()` | Set view description (DDL comment) |
+| `database()` | Set database name |
+| `schema()` | Set schema name |
+| `query()` | Define the view's SELECT query |
+| `relations()` | Define relations with other tables/views |
 
-## Procedure / ProcedureBuilder
+## `Procedure`
 
-### Procedure (factory function)
+Procedure builder factory function. Creates a `ProcedureBuilder` for defining stored procedure schema via fluent API.
 
 ```typescript
 function Procedure(name: string): ProcedureBuilder<never, never>;
 ```
 
-### ProcedureBuilder
+## `ProcedureBuilder`
+
+Stored procedure definition builder. Define parameters, return type, and body via fluent API.
 
 ```typescript
 class ProcedureBuilder<
   TParams extends ColumnBuilderRecord,
   TReturns extends ColumnBuilderRecord,
 > {
-  readonly meta: {
+  readonly $params!: TParams;
+  readonly $returns!: TReturns;
+
+  constructor(readonly meta: {
     name: string;
     description?: string;
     database?: string;
@@ -151,51 +133,51 @@ class ProcedureBuilder<
     params?: TParams;
     returns?: TReturns;
     query?: string;
-  };
+  });
 
   description(desc: string): ProcedureBuilder<TParams, TReturns>;
   database(db: string): ProcedureBuilder<TParams, TReturns>;
   schema(schema: string): ProcedureBuilder<TParams, TReturns>;
-  params<T extends ColumnBuilderRecord>(
-    fn: (c: ReturnType<typeof createColumnFactory>) => T,
-  ): ProcedureBuilder<T, TReturns>;
-  returns<T extends ColumnBuilderRecord>(
-    fn: (c: ReturnType<typeof createColumnFactory>) => T,
-  ): ProcedureBuilder<TParams, T>;
+  params<T extends ColumnBuilderRecord>(fn: (c: ...) => T): ProcedureBuilder<T, TReturns>;
+  returns<T extends ColumnBuilderRecord>(fn: (c: ...) => T): ProcedureBuilder<TParams, T>;
   body(sql: string): ProcedureBuilder<TParams, TReturns>;
 }
 ```
 
-**Example:**
+| Method | Description |
+|--------|-------------|
+| `description()` | Set procedure description |
+| `database()` | Set database name |
+| `schema()` | Set schema name |
+| `params()` | Define input parameters |
+| `returns()` | Define return type columns |
+| `body()` | Set procedure body SQL |
 
-```typescript
-const GetUserById = Procedure("GetUserById")
-  .database("mydb")
-  .params((c) => ({ userId: c.bigint() }))
-  .returns((c) => ({ id: c.bigint(), name: c.varchar(100) }))
-  .body("SELECT id, name FROM User WHERE id = userId");
-```
+## `ColumnBuilder`
 
----
-
-## ColumnBuilder
-
-Column definition builder used within `TableBuilder.columns()`.
+Column definition builder. Define column type, nullable, autoIncrement, default, and description via fluent API.
 
 ```typescript
 class ColumnBuilder<TValue extends ColumnPrimitive, TMeta extends ColumnMeta> {
-  readonly meta: TMeta;
+  constructor(readonly meta: TMeta);
 
-  autoIncrement(): ColumnBuilder<TValue, TMeta & { autoIncrement: true }>;
-  nullable(): ColumnBuilder<TValue | undefined, TMeta & { nullable: true }>;
-  default(value: TValue): ColumnBuilder<TValue, TMeta & { default: typeof value }>;
+  autoIncrement(): ColumnBuilder<TValue, Omit<TMeta, "autoIncrement"> & { autoIncrement: true }>;
+  nullable(): ColumnBuilder<TValue | undefined, Omit<TMeta, "nullable"> & { nullable: true }>;
+  default(value: TValue): ColumnBuilder<TValue, Omit<TMeta, "default"> & { default: typeof value }>;
   description(desc: string): ColumnBuilder<TValue, TMeta & { description: string }>;
 }
 ```
 
-## createColumnFactory
+| Method | Description |
+|--------|-------------|
+| `autoIncrement()` | Set auto increment (optional in INSERT) |
+| `nullable()` | Allow NULL (adds `undefined` to type) |
+| `default()` | Set default value (optional in INSERT) |
+| `description()` | Set column description (DDL comment) |
+
+## `createColumnFactory`
 
-Returns an object with methods for all column types.
+Column builder factory. Provides builder creation methods for all basic data types.
 
 ```typescript
 function createColumnFactory(): {
@@ -216,34 +198,36 @@ function createColumnFactory(): {
 };
 ```
 
-**Example:**
-
-```typescript
-Table("Product").columns((c) => ({
-  id: c.bigint().autoIncrement(),
-  name: c.varchar(100),
-  price: c.decimal(10, 2),
-  description: c.text().nullable(),
-  isActive: c.boolean().default(true),
-  createdAt: c.datetime(),
-}))
-```
-
----
-
-## IndexBuilder
-
-Index definition builder used within `TableBuilder.indexes()`.
+| Method | SQL Type | TypeScript Type |
+|--------|----------|-----------------|
+| `int()` | INT (4 bytes) | `number` |
+| `bigint()` | BIGINT (8 bytes) | `number` |
+| `float()` | FLOAT (4 bytes) | `number` |
+| `double()` | DOUBLE (8 bytes) | `number` |
+| `decimal()` | DECIMAL(p, s) | `number` |
+| `varchar()` | VARCHAR(n) | `string` |
+| `char()` | CHAR(n) | `string` |
+| `text()` | TEXT | `string` |
+| `binary()` | LONGBLOB/VARBINARY(MAX)/BYTEA | `Bytes` |
+| `boolean()` | TINYINT(1)/BIT/BOOLEAN | `boolean` |
+| `datetime()` | DATETIME | `DateTime` |
+| `date()` | DATE | `DateOnly` |
+| `time()` | TIME | `Time` |
+| `uuid()` | BINARY(16)/UNIQUEIDENTIFIER/UUID | `Uuid` |
+
+## `IndexBuilder`
+
+Index definition builder. Define index columns, uniqueness, and sort order via fluent API.
 
 ```typescript
 class IndexBuilder<TKeys extends string[]> {
-  readonly meta: {
+  constructor(readonly meta: {
     columns: TKeys;
     name?: string;
     unique?: boolean;
     orderBy?: { [K in keyof TKeys]: "ASC" | "DESC" };
     description?: string;
-  };
+  });
 
   name(name: string): IndexBuilder<TKeys>;
   unique(): IndexBuilder<TKeys>;
@@ -252,7 +236,9 @@ class IndexBuilder<TKeys extends string[]> {
 }
 ```
 
-## createIndexFactory
+## `createIndexFactory`
+
+Index builder factory. Used in `TableBuilder.indexes()`.
 
 ```typescript
 function createIndexFactory<TColumnKey extends string>(): {
@@ -260,156 +246,218 @@ function createIndexFactory<TColumnKey extends string>(): {
 };
 ```
 
-**Example:**
-
-```typescript
-Table("User")
-  .columns((c) => ({ id: c.bigint(), email: c.varchar(200), name: c.varchar(100) }))
-  .indexes((i) => [
-    i.index("email").unique(),
-    i.index("name", "email").orderBy("ASC", "DESC"),
-    i.index("email").name("IX_User_Email"),
-  ]);
-```
+## `ForeignKeyBuilder`
 
----
-
-## Relation Builders
-
-### ForeignKeyBuilder
-
-N:1 FK relation that creates a DB constraint.
+Foreign key relation builder (N:1). Creates actual FK constraints in the DB.
 
 ```typescript
-class ForeignKeyBuilder<TOwner extends TableBuilder<any, any>, TTargetFn extends () => TableBuilder<any, any>> {
-  readonly meta: {
+class ForeignKeyBuilder<
+  TOwner extends TableBuilder<any, any>,
+  TTargetFn extends () => TableBuilder<any, any>,
+> {
+  constructor(readonly meta: {
     ownerFn: () => TOwner;
     columns: string[];
     targetFn: TTargetFn;
     description?: string;
-  };
+  });
 
   description(desc: string): ForeignKeyBuilder<TOwner, TTargetFn>;
 }
 ```
 
-### ForeignKeyTargetBuilder
+## `ForeignKeyTargetBuilder`
 
-1:N FK reverse-reference. Loaded as array by default; call `.single()` for 1:1.
+Foreign key reverse-reference builder (1:N). Loaded as array on `include()` (single object when `.single()` is called).
 
 ```typescript
-class ForeignKeyTargetBuilder<TTargetTableFn extends () => TableBuilder<any, any>, TIsSingle extends boolean> {
-  readonly meta: {
+class ForeignKeyTargetBuilder<
+  TTargetTableFn extends () => TableBuilder<any, any>,
+  TIsSingle extends boolean,
+> {
+  constructor(readonly meta: {
     targetTableFn: TTargetTableFn;
     relationName: string;
     description?: string;
     isSingle?: TIsSingle;
-  };
+  });
 
   description(desc: string): ForeignKeyTargetBuilder<TTargetTableFn, TIsSingle>;
   single(): ForeignKeyTargetBuilder<TTargetTableFn, true>;
 }
 ```
 
-### RelationKeyBuilder
+## `RelationKeyBuilder`
 
-N:1 logical relation (no DB FK constraint). Can be used in Views.
+Logical relation builder (N:1). Same as `ForeignKeyBuilder` but does not create FK constraints in the DB. Can be used in views.
 
 ```typescript
 class RelationKeyBuilder<
   TOwner extends TableBuilder<any, any> | ViewBuilder<any, any, any>,
   TTargetFn extends () => TableBuilder<any, any> | ViewBuilder<any, any, any>,
 > {
-  readonly meta: {
+  constructor(readonly meta: {
     ownerFn: () => TOwner;
     columns: string[];
     targetFn: TTargetFn;
     description?: string;
-  };
+  });
 
   description(desc: string): RelationKeyBuilder<TOwner, TTargetFn>;
 }
 ```
 
-### RelationKeyTargetBuilder
+## `RelationKeyTargetBuilder`
 
-1:N logical reverse-reference (no DB FK constraint). Can be used in Views.
+Logical relation reverse-reference builder (1:N). Same as `ForeignKeyTargetBuilder` but without DB FK constraints. Can be used in views.
 
 ```typescript
 class RelationKeyTargetBuilder<
   TTargetTableFn extends () => TableBuilder<any, any> | ViewBuilder<any, any, any>,
   TIsSingle extends boolean,
 > {
-  readonly meta: {
+  constructor(readonly meta: {
     targetTableFn: TTargetTableFn;
     relationName: string;
     description?: string;
     isSingle?: TIsSingle;
-  };
+  });
 
   description(desc: string): RelationKeyTargetBuilder<TTargetTableFn, TIsSingle>;
   single(): RelationKeyTargetBuilder<TTargetTableFn, true>;
 }
 ```
 
-### createRelationFactory
+## `createRelationFactory`
+
+Relation builder factory. Used in `TableBuilder.relations()` and `ViewBuilder.relations()`. Tables can use both FK + RelationKey; views can only use RelationKey.
 
 ```typescript
-function createRelationFactory<TOwner, TColumnKey extends string>(
-  ownerFn: () => TOwner,
-): TOwner extends TableBuilder<any, any>
-  ? RelationFkFactory & RelationRkFactory   // Tables get both FK and RK
-  : RelationRkFactory;                      // Views get only RK
+function createRelationFactory<
+  TOwner extends TableBuilder<any, any> | ViewBuilder<any, any, any>,
+  TColumnKey extends string,
+>(ownerFn: () => TOwner): TOwner extends TableBuilder<any, any>
+  ? RelationFkFactory<TOwner, TColumnKey> & RelationRkFactory<TOwner, TColumnKey>
+  : RelationRkFactory<TOwner, TColumnKey>;
 ```
 
-Factory methods:
-- `foreignKey(columns, targetFn)` -- N:1 FK (table only)
-- `foreignKeyTarget(targetTableFn, relationName)` -- 1:N FK reverse-reference (table only)
-- `relationKey(columns, targetFn)` -- N:1 logical relation
-- `relationKeyTarget(targetTableFn, relationName)` -- 1:N logical reverse-reference
+## `ColumnBuilderRecord`
 
-**Example:**
+Column builder record type. Used as the return type of `TableBuilder.columns()`.
 
 ```typescript
-const Post = Table("Post")
-  .columns((c) => ({ id: c.bigint().autoIncrement(), authorId: c.bigint() }))
-  .primaryKey("id")
-  .relations((r) => ({
-    author: r.foreignKey(["authorId"], () => User),
-  }));
-
-const User = Table("User")
-  .columns((c) => ({ id: c.bigint().autoIncrement(), name: c.varchar(100) }))
-  .primaryKey("id")
-  .relations((r) => ({
-    posts: r.foreignKeyTarget(() => Post, "author"),
-    profile: r.foreignKeyTarget(() => Profile, "user").single(),
-  }));
+type ColumnBuilderRecord = Record<string, ColumnBuilder<ColumnPrimitive, ColumnMeta>>;
 ```
 
----
+## `RelationBuilderRecord`
 
-## _Migration
+Relation builder record type. Return type of `TableBuilder.relations()` and `ViewBuilder.relations()`.
 
-Built-in system migration table. Automatically included by `defineDbContext`.
+```typescript
+type RelationBuilderRecord = Record<
+  string,
+  ForeignKeyBuilder<any, any> | ForeignKeyTargetBuilder<any, any> | RelationKeyBuilder<any, any> | RelationKeyTargetBuilder<any, any>
+>;
+```
+
+## `InferColumns`
+
+Infer actual value types from a column builder record.
 
 ```typescript
-const _Migration = Table("_migration")
-  .columns((c) => ({ code: c.varchar(255) }))
-  .description("System Migration Table")
-  .primaryKey("code");
+type InferColumns<TBuilders extends ColumnBuilderRecord> = {
+  [K in keyof TBuilders]: TBuilders[K] extends ColumnBuilder<infer V, any> ? V : never;
+};
 ```
 
----
+## `InferColumnExprs`
 
-## Type Inference Utilities
+Infer expression input types from a column builder record.
 
-| Type | Description |
-|------|-------------|
-| `ColumnBuilderRecord` | `Record<string, ColumnBuilder<ColumnPrimitive, ColumnMeta>>` |
-| `InferColumns<T>` | Map column builders to value types (`{ id: number; name: string; ... }`) |
-| `InferInsertColumns<T>` | Required columns + Partial optional columns (autoIncrement/nullable/default are optional) |
-| `InferUpdateColumns<T>` | All columns Partial |
-| `InferColumnExprs<T>` | Map column builders to `ExprInput` types |
-| `RelationBuilderRecord` | Record of FK/FKT/RK/RKT builders |
-| `InferDeepRelations<T>` | Deep relation type inference (all relations optional) |
+```typescript
+type InferColumnExprs<TBuilders extends ColumnBuilderRecord> = {
+  [K in keyof TBuilders]: TBuilders[K] extends ColumnBuilder<infer V, any> ? ExprInput<V> : never;
+};
+```
+
+## `InferInsertColumns`
+
+INSERT type inference. Required columns are required, optional columns (autoIncrement, nullable, default) are `Partial`.
+
+```typescript
+type InferInsertColumns<TBuilders extends ColumnBuilderRecord> = Pick<
+  InferColumns<TBuilders>,
+  RequiredInsertKeys<TBuilders>
+> & Partial<Pick<InferColumns<TBuilders>, OptionalInsertKeys<TBuilders>>>;
+```
+
+## `InferUpdateColumns`
+
+UPDATE type inference. All columns are optional.
+
+```typescript
+type InferUpdateColumns<TBuilders extends ColumnBuilderRecord> = Partial<InferColumns<TBuilders>>;
+```
+
+## `RequiredInsertKeys`
+
+Extract required column keys for INSERT (columns without autoIncrement, nullable, or default).
+
+```typescript
+type RequiredInsertKeys<TBuilders extends ColumnBuilderRecord> = { ... }[keyof TBuilders];
+```
+
+## `OptionalInsertKeys`
+
+Extract optional column keys for INSERT.
+
+```typescript
+type OptionalInsertKeys<TBuilders extends ColumnBuilderRecord> = Exclude<keyof TBuilders, RequiredInsertKeys<TBuilders>>;
+```
+
+## `DataToColumnBuilderRecord`
+
+Transform from data record to column builder record.
+
+```typescript
+type DataToColumnBuilderRecord<TData extends DataRecord> = { ... };
+```
+
+## `InferDeepRelations`
+
+Deep relation type inference from relation definitions. Makes all relations optional.
+
+```typescript
+type InferDeepRelations<TRelations extends RelationBuilderRecord> = {
+  [K in keyof TRelations]?: ExtractRelationTarget<TRelations[K]> | ExtractRelationTargetResult<TRelations[K]>;
+};
+```
+
+## `ExtractRelationTarget`
+
+Extract target type from FK/RelationKey (single object, N:1 relation).
+
+```typescript
+type ExtractRelationTarget<TRelation> = ...;
+```
+
+## `ExtractRelationTargetResult`
+
+Extract target type from FKTarget/RelationKeyTarget (array or single object, 1:N relation).
+
+```typescript
+type ExtractRelationTargetResult<TRelation> = ...;
+```
+
+## `_Migration`
+
+Built-in system migration table. Automatically included in every `DbContextDef`.
+
+```typescript
+const _Migration = Table("_migration")
+  .columns((c) => ({
+    code: c.varchar(255),
+  }))
+  .description("System Migration Table")
+  .primaryKey("code");
+```