metal-orm 1.0.57 → 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

@@ -1,111 +1,130 @@
-import type { ColumnDef } from './column-types.js';
-export type { ColumnDef };
-import { TableDef } from './table.js';
-import {
-  RelationDef,
-  HasManyRelation,
-  HasOneRelation,
-  BelongsToRelation,
-  BelongsToManyRelation
-} from './relation.js';
-
-/**
- * Resolves a relation definition to its target table type.
- */
+import type { ColumnDef } from './column-types.js';
+export type { ColumnDef };
+import { TableDef } from './table.js';
+import {
+  RelationDef,
+  HasManyRelation,
+  HasOneRelation,
+  BelongsToRelation,
+  BelongsToManyRelation
+} from './relation.js';
+
+/**
+ * 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 :
+  TRel extends BelongsToManyRelation<infer TTarget, TableDef> ? TTarget :
   never;
-
-type NormalizedColumnType<T extends ColumnDef> = Lowercase<T['type'] & string>;
-
-/**
- * Maps a ColumnDef to its TypeScript type representation
- */
-export type ColumnToTs<T extends ColumnDef> =
-  [unknown] extends [T['tsType']]
-  ? NormalizedColumnType<T> extends 'int' | 'integer' ? number :
-  NormalizedColumnType<T> extends 'bigint' ? number | bigint :
-  NormalizedColumnType<T> extends 'decimal' | 'float' | 'double' ? number :
-  NormalizedColumnType<T> extends 'boolean' ? boolean :
-  NormalizedColumnType<T> extends 'json' ? unknown :
-  NormalizedColumnType<T> extends 'blob' | 'binary' | 'varbinary' | 'bytea' ? Buffer :
-  NormalizedColumnType<T> extends 'date' | 'datetime' | 'timestamp' | 'timestamptz' ? string :
-  string
-  : Exclude<T['tsType'], undefined>;
-
-/**
- * Infers a row shape from a table definition
- */
-export type InferRow<TTable extends TableDef> = {
-  [K in keyof TTable['columns']]: ColumnToTs<TTable['columns'][K]>;
-};
-
+
+type NormalizedColumnType<T extends ColumnDef> = Lowercase<T['type'] & string>;
+
+/**
+ * Maps a ColumnDef to its TypeScript type representation
+ */
+export type ColumnToTs<T extends ColumnDef> =
+  [unknown] extends [T['tsType']]
+  ? NormalizedColumnType<T> extends 'int' | 'integer' ? number :
+  NormalizedColumnType<T> extends 'bigint' ? number | bigint :
+  NormalizedColumnType<T> extends 'decimal' | 'float' | 'double' ? number :
+  NormalizedColumnType<T> extends 'boolean' ? boolean :
+  NormalizedColumnType<T> extends 'json' ? unknown :
+  NormalizedColumnType<T> extends 'blob' | 'binary' | 'varbinary' | 'bytea' ? Buffer :
+  NormalizedColumnType<T> extends 'date' | 'datetime' | 'timestamp' | 'timestamptz' ? string :
+  string
+  : Exclude<T['tsType'], undefined>;
+
+/**
+ * Infers a row shape from a table definition
+ */
+export type InferRow<TTable extends TableDef> = {
+  [K in keyof TTable['columns']]: ColumnToTs<TTable['columns'][K]>;
+};
+
 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?: unknown })[] :
+  T extends BelongsToManyRelation<infer TTarget, TableDef> ? (InferRow<TTarget> & { _pivot?: Record<string, unknown> })[] :
   never;
-
-/**
- * Maps relation names to the expected row results
- */
-export type RelationMap<TTable extends TableDef> = {
-  [K in keyof TTable['relations']]: RelationResult<TTable['relations'][K]>;
-};
+
+/**
+ * Maps relation names to the expected row results
+ */
+export type RelationMap<TTable extends TableDef> = {
+  [K in keyof TTable['relations']]: RelationResult<TTable['relations'][K]>;
+};
+
+type RelationWrapper<TRel extends RelationDef> =
+  TRel extends HasManyRelation<infer TTarget>
+    ? HasManyCollection<EntityInstance<TTarget>> & ReadonlyArray<EntityInstance<TTarget>>
+    : 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>
+          ? BelongsToReference<EntityInstance<TTarget>>
+          : never;
 
 export interface HasManyCollection<TChild> {
+  length: number;
+  [Symbol.iterator](): Iterator<TChild>;
   load(): Promise<TChild[]>;
   getItems(): TChild[];
   add(data: Partial<TChild>): TChild;
   attach(entity: TChild): void;
   remove(entity: TChild): void;
-  clear(): void;
-}
-
-export interface BelongsToReference<TParent> {
-  load(): Promise<TParent | null>;
-  get(): TParent | null;
-  set(data: Partial<TParent> | TParent | null): TParent | null;
-}
-
-export interface HasOneReference<TChild> {
-  load(): Promise<TChild | null>;
-  get(): TChild | null;
-  set(data: Partial<TChild> | TChild | null): TChild | null;
-}
-
-export interface ManyToManyCollection<TTarget> {
+  clear(): void;
+}
+
+export interface BelongsToReferenceApi<TParent extends object = object> {
+  load(): Promise<TParent | null>;
+  get(): TParent | null;
+  set(data: Partial<TParent> | TParent | null): TParent | null;
+}
+
+export type BelongsToReference<TParent extends object = object> = BelongsToReferenceApi<TParent> & Partial<TParent>;
+
+export interface HasOneReferenceApi<TChild extends object = object> {
+  load(): Promise<TChild | null>;
+  get(): TChild | null;
+  set(data: Partial<TChild> | TChild | null): TChild | null;
+}
+
+export type HasOneReference<TChild extends object = object> = HasOneReferenceApi<TChild> & Partial<TChild>;
+
+export interface ManyToManyCollection<TTarget, TPivot extends object | undefined = undefined> {
+  length: number;
+  [Symbol.iterator](): Iterator<TTarget>;
   load(): Promise<TTarget[]>;
   getItems(): 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,
-  TRow = InferRow<TTable>
-> = TRow & {
-  [K in keyof RelationMap<TTable>]:
-  TTable['relations'][K] extends HasManyRelation<infer TTarget>
-  ? HasManyCollection<EntityInstance<TTarget>>
-  : TTable['relations'][K] extends HasOneRelation<infer TTarget>
-  ? HasOneReference<EntityInstance<TTarget>>
-  : TTable['relations'][K] extends BelongsToManyRelation<infer TTarget>
-  ? ManyToManyCollection<EntityInstance<TTarget>>
-  : TTable['relations'][K] extends BelongsToRelation<infer TTarget>
-  ? BelongsToReference<EntityInstance<TTarget>>
-  : never;
-} & {
-  $load<K extends keyof RelationMap<TTable>>(relation: K): Promise<RelationMap<TTable>[K]>;
-};
-
+
+export type EntityInstance<
+  TTable extends TableDef,
+  TRow = InferRow<TTable>
+> = TRow & {
+  [K in keyof RelationMap<TTable>]: RelationWrapper<TTable['relations'][K]>;
+} & {
+  $load<K extends keyof RelationMap<TTable>>(relation: K): Promise<RelationMap<TTable>[K]>;
+};
+
 export type Primitive = string | number | boolean | Date | bigint | Buffer | null | undefined;
 
+type IsAny<T> = 0 extends (1 & T) ? true : false;
+
 export type SelectableKeys<T> = {
-  [K in keyof T]-?: NonNullable<T[K]> extends Primitive ? K : never
+  [K in keyof T]-?: IsAny<T[K]> extends true
+    ? never
+    : NonNullable<T[K]> extends Primitive
+      ? K
+      : never
 }[keyof T];