metal-orm 1.0.58 → 1.0.59

package/src/schema/relation.ts

@@ -57,12 +57,15 @@ export interface BelongsToRelation<TTarget extends TableDef = TableDef> {
 /**
  * Many-to-many relationship definition with rich pivot metadata
  */
-export interface BelongsToManyRelation<TTarget extends TableDef = TableDef> {
-    type: typeof RelationKinds.BelongsToMany;
-    target: TTarget;
-    pivotTable: TableDef;
-    pivotForeignKeyToRoot: string;
-    pivotForeignKeyToTarget: string;
+export interface BelongsToManyRelation<
+  TTarget extends TableDef = TableDef,
+  TPivot extends TableDef = TableDef
+> {
+    type: typeof RelationKinds.BelongsToMany;
+    target: TTarget;
+    pivotTable: TPivot;
+    pivotForeignKeyToRoot: string;
+    pivotForeignKeyToTarget: string;
     localKey?: string;
     targetKey?: string;
     pivotPrimaryKey?: string;
@@ -156,24 +159,25 @@ export const belongsTo = <TTarget extends TableDef>(
  * @param options - Pivot metadata configuration
  * @returns BelongsToManyRelation definition
  */
-export const belongsToMany = <
-  TTarget extends TableDef
->(
-  target: TTarget,
-  pivotTable: TableDef,
-  options: {
-    pivotForeignKeyToRoot: string;
-    pivotForeignKeyToTarget: string;
+export const belongsToMany = <
+  TTarget extends TableDef,
+  TPivot extends TableDef = TableDef
+>(
+  target: TTarget,
+  pivotTable: TPivot,
+  options: {
+    pivotForeignKeyToRoot: string;
+    pivotForeignKeyToTarget: string;
     localKey?: string;
     targetKey?: string;
     pivotPrimaryKey?: string;
     defaultPivotColumns?: string[];
     cascade?: CascadeMode;
   }
-): BelongsToManyRelation<TTarget> => ({
-    type: RelationKinds.BelongsToMany,
-    target,
-    pivotTable,
+): BelongsToManyRelation<TTarget, TPivot> => ({
+    type: RelationKinds.BelongsToMany,
+    target,
+    pivotTable,
     pivotForeignKeyToRoot: options.pivotForeignKeyToRoot,
     pivotForeignKeyToTarget: options.pivotForeignKeyToTarget,
     localKey: options.localKey,

package/src/schema/table.ts

@@ -85,13 +85,13 @@ export interface TableDef<T extends Record<string, ColumnDef> = Record<string, C
  * });
  * ```
  */
-export const defineTable = <T extends Record<string, ColumnDef>>(
-  name: string,
-  columns: T,
-  relations: Record<string, RelationDef> = {},
-  hooks?: TableHooks,
-  options: TableOptions = {}
-): TableDef<T> => {
+export const defineTable = <T extends Record<string, ColumnDef>>(
+  name: string,
+  columns: T,
+  relations: Record<string, RelationDef> = {},
+  hooks?: TableHooks,
+  options: TableOptions = {}
+): TableDef<T> => {
   // Runtime mutability to assign names to column definitions for convenience
   const colsWithNames = Object.entries(columns).reduce((acc, [key, def]) => {
     const colDef = { ...def, name: key, table: name };
@@ -112,8 +112,21 @@ export const defineTable = <T extends Record<string, ColumnDef>>(
     engine: options.engine,
     charset: options.charset,
     collation: options.collation
-  };
-};
+  };
+};
+
+/**
+ * Assigns relations to a table definition while preserving literal typing.
+ */
+export function setRelations<
+  TTable extends TableDef,
+  TRelations extends Record<string, RelationDef>
+>(
+  table: TTable,
+  relations: TRelations
+): asserts table is TTable & { relations: TRelations } {
+  table.relations = relations;
+}
 
 type DirectColumnKeys<T extends TableDef> =
   Exclude<keyof T["columns"] & string, keyof T | "$">;

package/src/schema/types.ts

@@ -12,12 +12,12 @@ import {
 /**
  * Resolves a relation definition to its target table type.
  */
-export type RelationTargetTable<TRel extends RelationDef> =
-  TRel extends HasManyRelation<infer TTarget> ? TTarget :
-  TRel extends HasOneRelation<infer TTarget> ? TTarget :
-  TRel extends BelongsToRelation<infer TTarget> ? TTarget :
-  TRel extends BelongsToManyRelation<infer TTarget> ? TTarget :
-  never;
+export type RelationTargetTable<TRel extends RelationDef> =
+  TRel extends HasManyRelation<infer TTarget> ? TTarget :
+  TRel extends HasOneRelation<infer TTarget> ? TTarget :
+  TRel extends BelongsToRelation<infer TTarget> ? TTarget :
+  TRel extends BelongsToManyRelation<infer TTarget, TableDef> ? TTarget :
+  never;
 
 type NormalizedColumnType<T extends ColumnDef> = Lowercase<T['type'] & string>;
 
@@ -47,7 +47,7 @@ type RelationResult<T extends RelationDef> =
   T extends HasManyRelation<infer TTarget> ? InferRow<TTarget>[] :
   T extends HasOneRelation<infer TTarget> ? InferRow<TTarget> | null :
   T extends BelongsToRelation<infer TTarget> ? InferRow<TTarget> | null :
-  T extends BelongsToManyRelation<infer TTarget> ? (InferRow<TTarget> & { _pivot?: Record<string, unknown> })[] :
+  T extends BelongsToManyRelation<infer TTarget, TableDef> ? (InferRow<TTarget> & { _pivot?: Record<string, unknown> })[] :
   never;
 
 /**
@@ -63,9 +63,9 @@ type RelationWrapper<TRel extends RelationDef> =
     : TRel extends HasOneRelation<infer TTarget>
       ? HasOneReference<EntityInstance<TTarget>>
       : TRel extends BelongsToManyRelation<infer TTarget>
-        ? ManyToManyCollection<EntityInstance<TTarget> & { _pivot?: Record<string, unknown> }>
-          & ReadonlyArray<EntityInstance<TTarget> & { _pivot?: Record<string, unknown> }>
-        : TRel extends BelongsToRelation<infer TTarget>
+    ? ManyToManyCollection<EntityInstance<TTarget> & { _pivot?: Record<string, unknown> }>
+      & ReadonlyArray<EntityInstance<TTarget> & { _pivot?: Record<string, unknown> }>
+    : TRel extends BelongsToRelation<infer TTarget>
           ? BelongsToReference<EntityInstance<TTarget>>
           : never;
 
@@ -96,7 +96,7 @@ export interface HasOneReferenceApi<TChild extends object = object> {
 
 export type HasOneReference<TChild extends object = object> = HasOneReferenceApi<TChild> & Partial<TChild>;
 
-export interface ManyToManyCollection<TTarget> {
+export interface ManyToManyCollection<TTarget, TPivot extends object | undefined = undefined> {
   length: number;
   [Symbol.iterator](): Iterator<TTarget>;
   load(): Promise<TTarget[]>;
@@ -104,7 +104,9 @@ export interface ManyToManyCollection<TTarget> {
   attach(target: TTarget | number | string): void;
   detach(target: TTarget | number | string): void;
   syncByIds(ids: (number | string)[]): Promise<void>;
-}
+  /** @internal Type-level marker for the related pivot entity */
+  readonly __pivotType?: TPivot;
+}
 
 export type EntityInstance<
   TTable extends TableDef,