@simplysm/orm-common 14.0.4 → 14.0.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (8) hide show
  1. package/README.md +127 -99
  2. package/docs/core.md +88 -137
  3. package/docs/expression.md +177 -174
  4. package/docs/query-builder.md +95 -71
  5. package/docs/queryable.md +160 -135
  6. package/docs/schema-builders.md +151 -209
  7. package/docs/types.md +273 -254
  8. package/package.json +2 -2
package/docs/schema-builders.md CHANGED
@@ -4,213 +4,172 @@ Fluent API builders for defining tables, views, procedures, columns, indexes, an
4
4
 
5
5
  ## Table (function)
6
6
 
7
- Factory function that creates a `TableBuilder`.
8
-
9
7
  ```typescript
10
- function Table(name: string): TableBuilder<{}, {}>;
8
+ function Table(name: string): TableBuilder<{}, {}>
11
9
  ```
12
10
 
13
- ## TableBuilder
11
+ Creates a new TableBuilder with the given table name.
14
12
 
15
- Database table definition builder with fluent API for columns, primary keys, indexes, and relations.
13
+ ## TableBuilder
16
14
 
17
15
  ```typescript
18
- class TableBuilder<TColumns extends ColumnBuilderRecord, TRelations extends RelationBuilderRecord> {
19
- readonly $columns: TColumns;
20
- readonly $relations: TRelations;
21
- readonly $inferSelect: InferColumns<TColumns> & InferDeepRelations<TRelations>;
22
- readonly $inferColumns: InferColumns<TColumns>;
23
- readonly $inferInsert: InferInsertColumns<TColumns>;
24
- readonly $inferUpdate: InferUpdateColumns<TColumns>;
16
+ class TableBuilder<TColumns extends ColumnBuilderRecord, TRelations extends RelationBuilderRecord>
17
+ ```
25
18
 
26
- constructor(readonly meta: {
27
- name: string;
28
- description?: string;
29
- database?: string;
30
- schema?: string;
31
- columns?: TColumns;
32
- primaryKey?: (keyof TColumns & string)[];
33
- relations?: TRelations;
34
- indexes?: IndexBuilder<(keyof TColumns & string)[]>[];
35
- });
36
- }
19
+ Fluent API for defining database table schema including columns, primary key, indexes, and relations.
20
+
21
+ ### Phantom Type Fields
22
+
23
+ | Field | Type | Description |
24
+ |-------|------|-------------|
25
+ | `$columns` | `TColumns` | Column definitions (type inference) |
26
+ | `$relations` | `TRelations` | Relation definitions (type inference) |
27
+ | `$inferSelect` | `InferColumns<TColumns> & InferDeepRelations<TRelations>` | Full SELECT type |
28
+ | `$inferColumns` | `InferColumns<TColumns>` | Column-only type |
29
+ | `$inferInsert` | `InferInsertColumns<TColumns>` | INSERT type (AI/nullable/default optional) |
30
+ | `$inferUpdate` | `InferUpdateColumns<TColumns>` | UPDATE type (all optional) |
31
+
32
+ ### Constructor
33
+
34
+ ```typescript
35
+ constructor(readonly meta: {
36
+ name: string;
37
+ description?: string;
38
+ database?: string;
39
+ schema?: string;
40
+ columns?: TColumns;
41
+ primaryKey?: (keyof TColumns & string)[];
42
+ relations?: TRelations;
43
+ indexes?: IndexBuilder<(keyof TColumns & string)[]>[];
44
+ })
37
45
  ```
38
46
 
39
47
  ### Methods
40
48
 
41
49
  | Method | Signature | Description |
42
- |---|---|---|
50
+ |--------|-----------|-------------|
43
51
  | `description` | `(desc: string) => TableBuilder` | Set table description (DDL comment) |
44
52
  | `database` | `(db: string) => TableBuilder` | Set database name |
45
53
  | `schema` | `(schema: string) => TableBuilder` | Set schema name (MSSQL/PostgreSQL) |
46
- | `columns` | `(fn: (c: ColumnFactory) => TNewCols) => TableBuilder<TNewCols, TRelations>` | Define columns using the column factory |
47
- | `primaryKey` | `(...columns: string[]) => TableBuilder` | Set primary key (composite supported) |
54
+ | `columns` | `<T>(fn: (c: ColumnFactory) => T) => TableBuilder<T, TRelations>` | Define columns via column factory |
55
+ | `primaryKey` | `(...columns: (keyof TColumns & string)[]) => TableBuilder` | Set primary key (single or composite) |
48
56
  | `indexes` | `(fn: (i: IndexFactory) => IndexBuilder[]) => TableBuilder` | Define indexes |
49
- | `relations` | `(fn: (r: RelationFactory) => T) => TableBuilder<TColumns, T>` | Define relationships |
57
+ | `relations` | `<T>(fn: (r: RelationFactory) => T) => TableBuilder<TColumns, T>` | Define FK and relation mappings |
50
58
 
51
- **Example:**
59
+ ## View (function)
52
60
 
53
61
  ```typescript
54
- const User = Table("User")
55
- .database("mydb")
56
- .columns((c) => ({
57
- id: c.bigint().autoIncrement(),
58
- name: c.varchar(100),
59
- email: c.varchar(200).nullable(),
60
- status: c.varchar(20).default("active"),
61
- }))
62
- .primaryKey("id")
63
- .indexes((i) => [i.index("email").unique()])
64
- .relations((r) => ({
65
- posts: r.foreignKeyTarget(() => Post, "author"),
66
- }));
62
+ function View(name: string): ViewBuilder<any, any, {}>
67
63
  ```
68
64
 
69
- ## View (function)
65
+ Creates a new ViewBuilder with the given view name.
70
66
 
71
- Factory function that creates a `ViewBuilder`.
67
+ ## ViewBuilder
72
68
 
73
69
  ```typescript
74
- function View(name: string): ViewBuilder<any, {}, {}>;
70
+ class ViewBuilder<TDbContext extends DbContextBase, TData extends DataRecord, TRelations extends RelationBuilderRecord>
75
71
  ```
76
72
 
77
- ## ViewBuilder
73
+ Fluent API for defining database view schema.
78
74
 
79
- Database view definition builder.
75
+ ### Phantom Type Fields
80
76
 
81
- ```typescript
82
- class ViewBuilder<TDbContext, TData extends DataRecord, TRelations extends RelationBuilderRecord> {
83
- readonly $relations: TRelations;
84
- readonly $inferSelect: TData;
85
-
86
- constructor(readonly meta: {
87
- name: string;
88
- description?: string;
89
- database?: string;
90
- schema?: string;
91
- viewFn?: (db: TDbContext) => Queryable<TData, any>;
92
- relations?: TRelations;
93
- });
94
- }
95
- ```
77
+ | Field | Type | Description |
78
+ |-------|------|-------------|
79
+ | `$relations` | `TRelations` | Relation definitions |
80
+ | `$inferSelect` | `TData` | Full SELECT type |
96
81
 
97
82
  ### Methods
98
83
 
99
84
  | Method | Signature | Description |
100
- |---|---|---|
85
+ |--------|-----------|-------------|
101
86
  | `description` | `(desc: string) => ViewBuilder` | Set view description |
102
87
  | `database` | `(db: string) => ViewBuilder` | Set database name |
103
88
  | `schema` | `(schema: string) => ViewBuilder` | Set schema name |
104
- | `query` | `(viewFn: (db: TDb) => Queryable) => ViewBuilder` | Define view query |
105
- | `relations` | `(fn: (r: RelationFactory) => T) => ViewBuilder` | Define relationships |
89
+ | `query` | `<TViewData, TDb>(viewFn: (db: TDb) => Queryable<TViewData, any>) => ViewBuilder<TDb, TViewData, TRelations>` | Define the view's SELECT query |
90
+ | `relations` | `<T>(fn: (r: RelationFactory) => T) => ViewBuilder` | Define relations (RelationKey only, no FK) |
106
91
 
107
- **Example:**
92
+ ## Procedure (function)
108
93
 
109
94
  ```typescript
110
- const ActiveUsers = View("ActiveUsers")
111
- .database("mydb")
112
- .query((db: MyDb) =>
113
- db.user()
114
- .where((u) => [expr.eq(u.status, "active")])
115
- .select((u) => ({ id: u.id, name: u.name }))
116
- );
95
+ function Procedure(name: string): ProcedureBuilder<never, never>
117
96
  ```
118
97
 
119
- ## Procedure (function)
98
+ Creates a new ProcedureBuilder with the given procedure name.
120
99
 
121
- Factory function that creates a `ProcedureBuilder`.
100
+ ## ProcedureBuilder
122
101
 
123
102
  ```typescript
124
- function Procedure(name: string): ProcedureBuilder<never, never>;
103
+ class ProcedureBuilder<TParams extends ColumnBuilderRecord, TReturns extends ColumnBuilderRecord>
125
104
  ```
126
105
 
127
- ## ProcedureBuilder
106
+ Fluent API for defining stored procedure schema.
128
107
 
129
- Stored procedure definition builder.
108
+ ### Phantom Type Fields
130
109
 
131
- ```typescript
132
- class ProcedureBuilder<TParams extends ColumnBuilderRecord, TReturns extends ColumnBuilderRecord> {
133
- readonly $params: TParams;
134
- readonly $returns: TReturns;
135
-
136
- constructor(readonly meta: {
137
- name: string;
138
- description?: string;
139
- database?: string;
140
- schema?: string;
141
- params?: TParams;
142
- returns?: TReturns;
143
- query?: string;
144
- });
145
- }
146
- ```
110
+ | Field | Type | Description |
111
+ |-------|------|-------------|
112
+ | `$params` | `TParams` | Parameter definitions |
113
+ | `$returns` | `TReturns` | Return type definitions |
147
114
 
148
115
  ### Methods
149
116
 
150
117
  | Method | Signature | Description |
151
- |---|---|---|
118
+ |--------|-----------|-------------|
152
119
  | `description` | `(desc: string) => ProcedureBuilder` | Set procedure description |
153
120
  | `database` | `(db: string) => ProcedureBuilder` | Set database name |
154
121
  | `schema` | `(schema: string) => ProcedureBuilder` | Set schema name |
155
- | `params` | `(fn: (c: ColumnFactory) => T) => ProcedureBuilder<T, TReturns>` | Define input parameters |
156
- | `returns` | `(fn: (c: ColumnFactory) => T) => ProcedureBuilder<TParams, T>` | Define return columns |
122
+ | `params` | `<T>(fn: (c: ColumnFactory) => T) => ProcedureBuilder<T, TReturns>` | Define input parameters |
123
+ | `returns` | `<T>(fn: (c: ColumnFactory) => T) => ProcedureBuilder<TParams, T>` | Define return columns |
157
124
  | `body` | `(sql: string) => ProcedureBuilder` | Set procedure body SQL |
158
125
 
159
- **Example:**
160
-
161
- ```typescript
162
- const GetUserById = Procedure("GetUserById")
163
- .database("mydb")
164
- .params((c) => ({ userId: c.bigint() }))
165
- .returns((c) => ({ id: c.bigint(), name: c.varchar(100) }))
166
- .body("SELECT id, name FROM User WHERE id = userId");
167
- ```
168
-
169
126
  ## ColumnBuilder
170
127
 
171
- Column definition builder used inside `TableBuilder.columns()`.
172
-
173
128
  ```typescript
174
129
  class ColumnBuilder<TValue extends ColumnPrimitive, TMeta extends ColumnMeta> {
175
130
  constructor(readonly meta: TMeta);
176
131
  }
177
132
  ```
178
133
 
134
+ Column definition builder with fluent API for type modifiers.
135
+
179
136
  ### Methods
180
137
 
181
138
  | Method | Signature | Description |
182
- |---|---|---|
183
- | `autoIncrement` | `() => ColumnBuilder` | Set auto-increment. Makes column optional in INSERT. |
184
- | `nullable` | `() => ColumnBuilder<TValue \| undefined, ...>` | Allow NULL. Adds `undefined` to value type. |
185
- | `default` | `(value: TValue) => ColumnBuilder` | Set default value. Makes column optional in INSERT. |
186
- | `description` | `(desc: string) => ColumnBuilder` | Set column description (DDL comment) |
139
+ |--------|-----------|-------------|
140
+ | `autoIncrement` | `() => ColumnBuilder<TValue, TMeta & { autoIncrement: true }>` | Set auto-increment (INSERT optional) |
141
+ | `nullable` | `() => ColumnBuilder<TValue \| undefined, TMeta & { nullable: true }>` | Allow NULL values |
142
+ | `default` | `(value: TValue) => ColumnBuilder<TValue, TMeta & { default: TValue }>` | Set default value (INSERT optional) |
143
+ | `description` | `(desc: string) => ColumnBuilder<TValue, TMeta & { description: string }>` | Set column description (DDL comment) |
187
144
 
188
145
  ## createColumnFactory
189
146
 
190
- Returns a column factory object with methods for all supported data types.
191
-
192
147
  ```typescript
193
- function createColumnFactory(): {
194
- int(): ColumnBuilder<number, ...>;
195
- bigint(): ColumnBuilder<number, ...>;
196
- float(): ColumnBuilder<number, ...>;
197
- double(): ColumnBuilder<number, ...>;
198
- decimal(precision: number, scale?: number): ColumnBuilder<number, ...>;
199
- varchar(length: number): ColumnBuilder<string, ...>;
200
- char(length: number): ColumnBuilder<string, ...>;
201
- text(): ColumnBuilder<string, ...>;
202
- binary(): ColumnBuilder<Bytes, ...>;
203
- boolean(): ColumnBuilder<boolean, ...>;
204
- datetime(): ColumnBuilder<DateTime, ...>;
205
- date(): ColumnBuilder<DateOnly, ...>;
206
- time(): ColumnBuilder<Time, ...>;
207
- uuid(): ColumnBuilder<Uuid, ...>;
208
- };
148
+ function createColumnFactory(): ColumnFactory
209
149
  ```
210
150
 
211
- ## IndexBuilder
151
+ Returns a column type factory object. Used inside `TableBuilder.columns()` and `ProcedureBuilder.params()/returns()`.
152
+
153
+ ### Factory Methods
154
+
155
+ | Method | Signature | SQL Type | TypeScript Type |
156
+ |--------|-----------|----------|-----------------|
157
+ | `int` | `() => ColumnBuilder<number, ...>` | `INT` | `number` |
158
+ | `bigint` | `() => ColumnBuilder<number, ...>` | `BIGINT` | `number` |
159
+ | `float` | `() => ColumnBuilder<number, ...>` | `FLOAT` | `number` |
160
+ | `double` | `() => ColumnBuilder<number, ...>` | `DOUBLE` | `number` |
161
+ | `decimal` | `(precision, scale?) => ColumnBuilder<number, ...>` | `DECIMAL(p,s)` | `number` |
162
+ | `varchar` | `(length) => ColumnBuilder<string, ...>` | `VARCHAR(n)` | `string` |
163
+ | `char` | `(length) => ColumnBuilder<string, ...>` | `CHAR(n)` | `string` |
164
+ | `text` | `() => ColumnBuilder<string, ...>` | `TEXT` | `string` |
165
+ | `binary` | `() => ColumnBuilder<Bytes, ...>` | `LONGBLOB`/`BYTEA` | `Bytes` |
166
+ | `boolean` | `() => ColumnBuilder<boolean, ...>` | `TINYINT(1)`/`BIT`/`BOOLEAN` | `boolean` |
167
+ | `datetime` | `() => ColumnBuilder<DateTime, ...>` | `DATETIME` | `DateTime` |
168
+ | `date` | `() => ColumnBuilder<DateOnly, ...>` | `DATE` | `DateOnly` |
169
+ | `time` | `() => ColumnBuilder<Time, ...>` | `TIME` | `Time` |
170
+ | `uuid` | `() => ColumnBuilder<Uuid, ...>` | `BINARY(16)`/`UNIQUEIDENTIFIER`/`UUID` | `Uuid` |
212
171
 
213
- Index definition builder used inside `TableBuilder.indexes()`.
172
+ ## IndexBuilder
214
173
 
215
174
  ```typescript
216
175
  class IndexBuilder<TKeys extends string[]> {
@@ -227,126 +186,109 @@ class IndexBuilder<TKeys extends string[]> {
227
186
  ### Methods
228
187
 
229
188
  | Method | Signature | Description |
230
- |---|---|---|
231
- | `name` | `(name: string) => IndexBuilder` | Set custom index name |
232
- | `unique` | `() => IndexBuilder` | Mark as unique index |
233
- | `orderBy` | `(...orderBy: ("ASC" \| "DESC")[]) => IndexBuilder` | Set column sort order |
234
- | `description` | `(description: string) => IndexBuilder` | Set index description |
189
+ |--------|-----------|-------------|
190
+ | `name` | `(name: string) => IndexBuilder<TKeys>` | Set custom index name |
191
+ | `unique` | `() => IndexBuilder<TKeys>` | Mark as unique index |
192
+ | `orderBy` | `(...orderBy: ("ASC" \| "DESC")[]) => IndexBuilder<TKeys>` | Set sort order per column |
193
+ | `description` | `(desc: string) => IndexBuilder<TKeys>` | Set index description |
235
194
 
236
195
  ## createIndexFactory
237
196
 
238
- Returns an index factory with the `index(...columns)` method.
239
-
240
197
  ```typescript
241
- function createIndexFactory<TColumnKey extends string>(): {
242
- index<TKeys extends TColumnKey[]>(...columns: TKeys): IndexBuilder<TKeys>;
243
- };
198
+ function createIndexFactory<TColumnKey extends string>(): { index: (...columns: TColumnKey[]) => IndexBuilder }
244
199
  ```
245
200
 
246
- ## ForeignKeyBuilder
201
+ Returns an index factory. Used inside `TableBuilder.indexes()`.
247
202
 
248
- Foreign key relation builder (N:1). Creates a real FK constraint in the database.
203
+ ## ForeignKeyBuilder
249
204
 
250
205
  ```typescript
251
- class ForeignKeyBuilder<TOwner extends TableBuilder, TTargetFn extends () => TableBuilder> {
206
+ class ForeignKeyBuilder<TOwner extends TableBuilder<any, any>, TTargetFn extends () => TableBuilder<any, any>> {
252
207
  constructor(readonly meta: {
253
208
  ownerFn: () => TOwner;
254
209
  columns: string[];
255
210
  targetFn: TTargetFn;
256
211
  description?: string;
257
212
  });
258
-
259
- description(desc: string): ForeignKeyBuilder;
260
213
  }
261
214
  ```
262
215
 
263
- ## ForeignKeyTargetBuilder
216
+ N:1 FK relation builder. Creates an actual DB foreign key constraint.
264
217
 
265
- Foreign key reverse-reference builder (1:N). Loaded as array by default, call `.single()` for 1:1.
218
+ | Method | Signature | Description |
219
+ |--------|-----------|-------------|
220
+ | `description` | `(desc: string) => ForeignKeyBuilder` | Set relation description |
221
+
222
+ ## ForeignKeyTargetBuilder
266
223
 
267
224
  ```typescript
268
- class ForeignKeyTargetBuilder<TTargetTableFn extends () => TableBuilder, TIsSingle extends boolean> {
225
+ class ForeignKeyTargetBuilder<TTargetTableFn extends () => TableBuilder<any, any>, TIsSingle extends boolean> {
269
226
  constructor(readonly meta: {
270
227
  targetTableFn: TTargetTableFn;
271
228
  relationName: string;
272
229
  description?: string;
273
230
  isSingle?: TIsSingle;
274
231
  });
275
-
276
- description(desc: string): ForeignKeyTargetBuilder;
277
- single(): ForeignKeyTargetBuilder<TTargetTableFn, true>;
278
232
  }
279
233
  ```
280
234
 
281
- ## RelationKeyBuilder
235
+ 1:N FK reverse-reference builder. Loaded as array by default, single object with `.single()`.
282
236
 
283
- Logical relation builder (N:1). Same as `ForeignKeyBuilder` but does NOT create a FK constraint in the database. Usable from both Tables and Views.
237
+ | Method | Signature | Description |
238
+ |--------|-----------|-------------|
239
+ | `description` | `(desc: string) => ForeignKeyTargetBuilder` | Set relation description |
240
+ | `single` | `() => ForeignKeyTargetBuilder<..., true>` | Change to 1:1 (single object) |
284
241
 
285
- ```typescript
286
- class RelationKeyBuilder<TOwner, TTargetFn extends () => TableBuilder | ViewBuilder> {
287
- constructor(readonly meta: {
288
- ownerFn: () => TOwner;
289
- columns: string[];
290
- targetFn: TTargetFn;
291
- description?: string;
292
- });
242
+ ## RelationKeyBuilder
293
243
 
294
- description(desc: string): RelationKeyBuilder;
295
- }
244
+ ```typescript
245
+ class RelationKeyBuilder<
246
+ TOwner extends TableBuilder<any, any> | ViewBuilder<any, any, any>,
247
+ TTargetFn extends () => TableBuilder<any, any> | ViewBuilder<any, any, any>,
248
+ >
296
249
  ```
297
250
 
298
- ## RelationKeyTargetBuilder
251
+ Logical N:1 relation builder (no DB FK constraint). Works with both Tables and Views.
299
252
 
300
- Logical reverse-reference builder (1:N). Same as `ForeignKeyTargetBuilder` but without FK constraint. Usable from both Tables and Views.
253
+ | Method | Signature | Description |
254
+ |--------|-----------|-------------|
255
+ | `description` | `(desc: string) => RelationKeyBuilder` | Set relation description |
301
256
 
302
- ```typescript
303
- class RelationKeyTargetBuilder<TTargetTableFn, TIsSingle extends boolean> {
304
- constructor(readonly meta: {
305
- targetTableFn: TTargetTableFn;
306
- relationName: string;
307
- description?: string;
308
- isSingle?: TIsSingle;
309
- });
257
+ ## RelationKeyTargetBuilder
310
258
 
311
- description(desc: string): RelationKeyTargetBuilder;
312
- single(): RelationKeyTargetBuilder<TTargetTableFn, true>;
313
- }
259
+ ```typescript
260
+ class RelationKeyTargetBuilder<
261
+ TTargetTableFn extends () => TableBuilder<any, any> | ViewBuilder<any, any, any>,
262
+ TIsSingle extends boolean,
263
+ >
314
264
  ```
315
265
 
316
- ## createRelationFactory
266
+ Logical 1:N reverse-reference builder (no DB FK constraint). Works with both Tables and Views.
317
267
 
318
- Returns a relation factory. Tables get both FK and RelationKey methods; Views get only RelationKey methods.
268
+ | Method | Signature | Description |
269
+ |--------|-----------|-------------|
270
+ | `description` | `(desc: string) => RelationKeyTargetBuilder` | Set relation description |
271
+ | `single` | `() => RelationKeyTargetBuilder<..., true>` | Change to 1:1 (single object) |
272
+
273
+ ## createRelationFactory
319
274
 
320
275
  ```typescript
321
276
  function createRelationFactory<TOwner, TColumnKey extends string>(
322
277
  ownerFn: () => TOwner,
323
- ): TOwner extends TableBuilder
324
- ? RelationFkFactory & RelationRkFactory
325
- : RelationRkFactory;
278
+ ): RelationFactory
326
279
  ```
327
280
 
328
- **Factory methods (Table):**
329
-
330
- | Method | Description |
331
- |---|---|
332
- | `foreignKey(columns, targetFn)` | N:1 FK relation (creates DB constraint) |
333
- | `foreignKeyTarget(targetTableFn, relationName)` | 1:N FK reverse-reference |
334
- | `relationKey(columns, targetFn)` | N:1 logical relation (no DB constraint) |
335
- | `relationKeyTarget(targetTableFn, relationName)` | 1:N logical reverse-reference |
336
-
337
- ## Type Utilities
338
-
339
- | Type | Description |
340
- |---|---|
341
- | `ColumnBuilderRecord` | `Record<string, ColumnBuilder<ColumnPrimitive, ColumnMeta>>` |
342
- | `RelationBuilderRecord` | `Record<string, ForeignKeyBuilder \| ForeignKeyTargetBuilder \| RelationKeyBuilder \| RelationKeyTargetBuilder>` |
343
- | `InferColumns<T>` | Infer runtime value types from column builders |
344
- | `InferColumnExprs<T>` | Infer `ExprInput` types from column builders |
345
- | `InferInsertColumns<T>` | INSERT type: required fields + optional for autoIncrement/nullable/default |
346
- | `InferUpdateColumns<T>` | UPDATE type: all fields optional |
347
- | `RequiredInsertKeys<T>` | Extract required INSERT column keys |
348
- | `OptionalInsertKeys<T>` | Extract optional INSERT column keys |
349
- | `DataToColumnBuilderRecord<T>` | Convert data record to column builder record |
350
- | `ExtractRelationTarget<T>` | Extract target type from FK/RelationKey (single object) |
351
- | `ExtractRelationTargetResult<T>` | Extract target type from FKTarget/RelationKeyTarget (array or single) |
352
- | `InferDeepRelations<T>` | Deep relation type inference (all optional) |
281
+ Creates a relation factory. For `TableBuilder`: provides `foreignKey`, `foreignKeyTarget`, `relationKey`, `relationKeyTarget`. For `ViewBuilder`: provides only `relationKey`, `relationKeyTarget`.
282
+
283
+ ### Factory Methods (Table)
284
+
285
+ | Method | Signature | Description |
286
+ |--------|-----------|-------------|
287
+ | `foreignKey` | `(columns: TColumnKey[], targetFn: () => TableBuilder) => ForeignKeyBuilder` | N:1 FK (creates DB constraint) |
288
+ | `foreignKeyTarget` | `(targetTableFn: () => TableBuilder, relationName: string) => ForeignKeyTargetBuilder` | 1:N FK reverse-reference |
289
+ | `relationKey` | `(columns: TColumnKey[], targetFn: () => TableBuilder \| ViewBuilder) => RelationKeyBuilder` | N:1 logical relation (no DB FK) |
290
+ | `relationKeyTarget` | `(targetTableFn: () => TableBuilder \| ViewBuilder, relationName: string) => RelationKeyTargetBuilder` | 1:N logical reverse-reference |
291
+
292
+ ### Factory Methods (View)
293
+
294
+ Only `relationKey` and `relationKeyTarget` are available for ViewBuilder.