@mikro-orm/core 7.2.0-dev.15 → 7.2.0-dev.16

package/entity/defineEntity.d.ts

@@ -148,6 +148,8 @@ export interface PropertyChain<in out Value, in out Options> {
     orphanRemoval(orphanRemoval?: boolean): HasKind<Options, '1:m' | '1:1'> extends true ? PropertyChain<Value, Options> : never;
     discriminator(discriminator: string): HasKind<Options, 'm:1' | '1:1' | 'm:n'> extends true ? PropertyChain<Value, Options> : never;
     discriminatorMap(discriminatorMap: Dictionary<string>): HasKind<Options, 'm:1' | '1:1' | 'm:n'> extends true ? PropertyChain<Value, Options> : never;
+    /** Resolve this read-only to-one relation via a subquery on another entity (see {@doclink relationships#to-one-relations-through-another-entity | To-one relations through another entity}). */
+    through(through: () => EntityName): HasKind<Options, 'm:1' | '1:1'> extends true ? PropertyChain<Value, Options> : never;
     pivotTable(pivotTable: string): HasKind<Options, 'm:n'> extends true ? PropertyChain<Value, Options> : never;
     pivotEntity(pivotEntity: () => EntityName): HasKind<Options, 'm:n'> extends true ? PropertyChain<Value, Options> : never;
     fixedOrder(fixedOrder?: boolean): HasKind<Options, 'm:n'> extends true ? PropertyChain<Value, Options> : never;
@@ -528,6 +530,8 @@ export declare class UniversalPropertyOptionsBuilder<in out Value, in out Option
     fixedOrderColumn(fixedOrderColumn: string): Pick<UniversalPropertyOptionsBuilder<Value, Options, IncludeKeys>, IncludeKeys>;
     /** Override default name for pivot table (see {@doclink naming-strategy | Naming Strategy}). */
     pivotTable(pivotTable: string): Pick<UniversalPropertyOptionsBuilder<Value, Options, IncludeKeys>, IncludeKeys>;
+    /** Resolve this read-only to-one relation via a subquery on another entity (see {@doclink relationships#to-one-relations-through-another-entity | To-one relations through another entity}). */
+    through(through: () => EntityName): Pick<UniversalPropertyOptionsBuilder<Value, Options, IncludeKeys>, IncludeKeys>;
     /** Set pivot entity for this relation (see {@doclink collections#custom-pivot-table-entity | Custom pivot table entity}). */
     pivotEntity(pivotEntity: () => EntityName): Pick<UniversalPropertyOptionsBuilder<Value, Options, IncludeKeys>, IncludeKeys>;
     /** Override the default database column name on the owning side (see {@doclink naming-strategy | Naming Strategy}). This option is only for simple properties represented by a single column. */

package/entity/defineEntity.js

@@ -403,6 +403,10 @@ export class UniversalPropertyOptionsBuilder {
     pivotTable(pivotTable) {
         return this.assignOptions({ pivotTable });
     }
+    /** Resolve this read-only to-one relation via a subquery on another entity (see {@doclink relationships#to-one-relations-through-another-entity | To-one relations through another entity}). */
+    through(through) {
+        return this.assignOptions({ through });
+    }
     /** Set pivot entity for this relation (see {@doclink collections#custom-pivot-table-entity | Custom pivot table entity}). */
     pivotEntity(pivotEntity) {
         return this.assignOptions({ pivotEntity });

package/errors.d.ts

@@ -73,6 +73,9 @@ export declare class MetadataError<T extends AnyEntity = AnyEntity> extends Vali
     static targetIsAbstract(meta: EntityMetadata, prop: EntityProperty): MetadataError;
     static nonPersistentCompositeProp(meta: EntityMetadata, prop: EntityProperty): MetadataError;
     static propertyTargetsEntityType(meta: EntityMetadata, prop: EntityProperty, target: EntityMetadata): MetadataError;
+    static throughRelationMissingProperty(meta: EntityMetadata, prop: EntityProperty, through: EntityMetadata, side: 'owner' | 'target'): MetadataError;
+    static throughRelationCompositeTarget(meta: EntityMetadata, prop: EntityProperty): MetadataError;
+    static throughRelationInvalidKind(meta: EntityMetadata, prop: EntityProperty): MetadataError;
     static fromMissingOption(meta: EntityMetadata, prop: EntityProperty, option: string): MetadataError;
     static targetKeyOnManyToMany(meta: EntityMetadata, prop: EntityProperty): MetadataError;
     static targetKeyNotUnique(meta: EntityMetadata, prop: EntityProperty, target?: EntityMetadata): MetadataError;

package/errors.js

@@ -241,6 +241,16 @@ export class MetadataError extends ValidationError {
         const suggestion = target.embeddable ? 'Embedded' : 'ManyToOne';
         return this.fromMessage(meta, prop, `is defined as scalar @Property(), but its type is a discovered entity ${target.className}. Maybe you want to use @${suggestion}() decorator instead?`);
     }
+    static throughRelationMissingProperty(meta, prop, through, side) {
+        const target = side === 'owner' ? meta.className : prop.targetMeta.className;
+        return this.fromMessage(meta, prop, `uses 'through' entity ${through.className} which has no ManyToOne property pointing to ${target}`);
+    }
+    static throughRelationCompositeTarget(meta, prop) {
+        return this.fromMessage(meta, prop, `uses 'through' option which is not supported for targets with composite primary key`);
+    }
+    static throughRelationInvalidKind(meta, prop) {
+        return this.fromMessage(meta, prop, `uses 'through' option which is only supported for ManyToOne and OneToOne relations`);
+    }
     static fromMissingOption(meta, prop, option) {
         return this.fromMessage(meta, prop, `is missing '${option}' option`);
     }

package/metadata/MetadataDiscovery.d.ts

@@ -126,6 +126,8 @@ export declare class MetadataDiscovery {
     private initVersionProperty;
     private initCustomType;
     private initRelation;
+    /** Resolves the `through` option of a virtual to-one relation into a read-only formula property. */
+    private initThroughRelation;
     private initColumnType;
     private getMappedType;
     private getPrefix;

package/metadata/MetadataDiscovery.js

@@ -168,10 +168,11 @@ export class MetadataDiscovery {
         // filter names are load-bearing for RLS (policy and session variable names), backfill from the dictionary key
         filtered.forEach(meta => Object.entries(meta.filters).forEach(([key, filter]) => (filter.name ??= key)));
         filtered.forEach(meta => this.initPolicies(meta));
-        forEachProp((_m, p) => {
+        forEachProp((m, p) => {
             this.initDefaultValue(p);
             this.inferTypeFromDefault(p);
             this.initRelation(p);
+            this.initThroughRelation(m, p);
             this.initColumnType(p);
         });
         forEachProp((m, p) => this.initIndexes(m, p));
@@ -223,11 +224,9 @@ export class MetadataDiscovery {
         };
         const missing = [];
         this.#discovered.forEach(meta => Object.values(meta.properties).forEach(prop => {
-            if (prop.kind === ReferenceKind.MANY_TO_MANY && prop.pivotEntity) {
-                const pivotEntity = prop.pivotEntity;
-                const target = typeof pivotEntity === 'function' && !pivotEntity.prototype
-                    ? pivotEntity()
-                    : pivotEntity;
+            const indirect = (prop.kind === ReferenceKind.MANY_TO_MANY ? prop.pivotEntity : prop.through);
+            if (indirect) {
+                const target = typeof indirect === 'function' && !indirect.prototype ? indirect() : indirect;
                 if (!this.#discovered.find(m => m.className === Utils.className(target)) || !discoveredByIdentity(target)) {
                     missing.push(target);
                 }
@@ -2078,6 +2077,58 @@ export class MetadataDiscovery {
             }
         }
     }
+    /** Resolves the `through` option of a virtual to-one relation into a read-only formula property. */
+    initThroughRelation(meta, prop) {
+        // already resolved, or not a through relation at all
+        if (prop.through?.ownerProperty || !prop.through) {
+            return;
+        }
+        if (![ReferenceKind.MANY_TO_ONE, ReferenceKind.ONE_TO_ONE].includes(prop.kind)) {
+            throw MetadataError.throughRelationInvalidKind(meta, prop);
+        }
+        const targetMeta = prop.targetMeta;
+        // the subquery selects a single column
+        if (targetMeta.compositePK) {
+            throw MetadataError.throughRelationCompositeTarget(meta, prop);
+        }
+        const through = prop.through;
+        const throughMeta = this.#metadata.get(!through.prototype ? through() : through);
+        // a property is considered to point at an entity when it targets it or one of its parents
+        const pointsTo = (p, m) => {
+            const candidate = this.#metadata.find(p.target);
+            /* v8 ignore next 3 */
+            if (!candidate) {
+                return false;
+            }
+            return candidate.class === m.class || m.class.prototype instanceof candidate.class;
+        };
+        const fks = Object.values(throughMeta.properties).filter(p => p.kind === ReferenceKind.MANY_TO_ONE);
+        const ownerProp = fks.find(p => pointsTo(p, meta));
+        if (!ownerProp) {
+            throw MetadataError.throughRelationMissingProperty(meta, prop, throughMeta, 'owner');
+        }
+        let targetProperty;
+        const selectsTarget = throughMeta.class === targetMeta.class || throughMeta.class.prototype instanceof targetMeta.class;
+        if (!selectsTarget) {
+            const targetProp = fks.find(p => p !== ownerProp && pointsTo(p, targetMeta));
+            if (!targetProp) {
+                throw MetadataError.throughRelationMissingProperty(meta, prop, throughMeta, 'target');
+            }
+            targetProperty = targetProp.name;
+        }
+        prop.through = {
+            entity: throughMeta.class,
+            where: prop.where,
+            orderBy: prop.orderBy ? Utils.asArray(prop.orderBy) : undefined,
+            ownerProperty: ownerProp.name,
+            targetProperty,
+        };
+        // the condition and ordering apply to the `through` entity, not to the target, so they must not leak into the target joins
+        delete prop.where;
+        delete prop.orderBy;
+        prop.persist = false;
+        prop.formula = columns => this.#platform.getThroughRelationFormula(prop, columns);
+    }
     initColumnType(prop) {
         this.initUnsigned(prop);
         // Get the target properties for FK relations - use targetKey property if specified, otherwise PKs

package/metadata/types.d.ts

@@ -431,9 +431,15 @@ interface PolymorphicOptions {
      */
     discriminatorMap?: Dictionary<string>;
 }
-export interface ManyToOneOptions<Owner, Target> extends ReferenceOptions<Owner, Target>, PolymorphicOptions {
+export interface ManyToOneOptions<Owner, Target, Through = Target> extends ReferenceOptions<Owner, Target>, PolymorphicOptions {
     /** Point to the inverse side property name. */
     inversedBy?: (string & keyof Target) | ((e: Target) => any);
+    /** Resolve this read-only relation via a subquery on another entity: a pivot entity with FKs to both sides, or the target itself to pick a single item out of a to-many relation (see {@doclink relationships#to-one-relations-through-another-entity | To-one relations through another entity}). */
+    through?: () => EntityName<Through>;
+    /** Condition applied on the `through` entity. */
+    where?: FilterQuery<Through>;
+    /** Ordering applied on the `through` entity, the first matching row is used. */
+    orderBy?: QueryOrderMap<Through> | QueryOrderMap<Through>[];
     /** Wrap the entity in {@apilink Reference} wrapper. */
     ref?: boolean;
     /** Use this relation as a primary key. */
@@ -485,9 +491,15 @@ export interface OneToManyOptions<Owner, Target> extends ReferenceOptions<Owner,
     /** Point to the owning side property name. */
     mappedBy: (string & keyof Target) | ((e: Target) => any);
 }
-export interface OneToOneOptions<Owner, Target> extends Partial<Omit<OneToManyOptions<Owner, Target>, 'orderBy'>>, PolymorphicOptions {
+export interface OneToOneOptions<Owner, Target, Through = Target> extends Partial<Omit<OneToManyOptions<Owner, Target>, 'orderBy' | 'where'>>, PolymorphicOptions {
     /** Set this side as owning. Owning side is where the foreign key is defined. This option is not required if you use `inversedBy` or `mappedBy` to distinguish owning and inverse side. */
     owner?: boolean;
+    /** Resolve this read-only relation via a subquery on another entity: a pivot entity with FKs to both sides, or the target itself to pick a single item out of a to-many relation (see {@doclink relationships#to-one-relations-through-another-entity | To-one relations through another entity}). */
+    through?: () => EntityName<Through>;
+    /** Condition for {@doclink collections#declarative-partial-loading | Declarative partial loading}, or the condition applied on the `through` entity. */
+    where?: FilterQuery<Through>;
+    /** Ordering applied on the `through` entity, the first matching row is used. */
+    orderBy?: QueryOrderMap<Through> | QueryOrderMap<Through>[];
     /** Point to the inverse side property name. */
     inversedBy?: (string & keyof Target) | ((e: Target) => any);
     /** Wrap the entity in {@apilink Reference} wrapper. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mikro-orm/core",
-  "version": "7.2.0-dev.15",
+  "version": "7.2.0-dev.16",
   "description": "TypeScript ORM for Node.js based on Data Mapper, Unit of Work and Identity Map patterns. Supports MongoDB, MySQL, PostgreSQL and SQLite databases as well as usage with vanilla JavaScript.",
   "keywords": [
     "data-mapper",

package/platforms/Platform.d.ts

@@ -1,6 +1,6 @@
 import { EntityRepository } from '../entity/EntityRepository.js';
 import { type NamingStrategy } from '../naming-strategy/NamingStrategy.js';
-import type { Constructor, EntityMetadata, EntityProperty, IPrimaryKey, ISchemaGenerator, PopulateOptions, Primary, SimpleColumnMeta, FilterQuery, EntityValue, EntityKey } from '../typings.js';
+import type { Constructor, EntityMetadata, EntityProperty, IPrimaryKey, ISchemaGenerator, PopulateOptions, Primary, SimpleColumnMeta, FilterQuery, EntityValue, EntityKey, FormulaColumns } from '../typings.js';
 import { ExceptionConverter } from './ExceptionConverter.js';
 import type { EntityManager } from '../EntityManager.js';
 import type { Configuration } from '../utils/Configuration.js';
@@ -275,6 +275,11 @@ export declare abstract class Platform {
     formatQuery(sql: string, params: readonly any[]): string;
     /** Deep-clones embeddable data and tags it for JSON serialization. */
     cloneEmbeddable<T>(data: T): T;
+    /**
+     * Builds the correlated subquery used as the formula of a virtual to-one relation defined via `through`.
+     * @internal
+     */
+    getThroughRelationFormula(prop: EntityProperty, columns: FormulaColumns<any>): string;
     /** Initializes the platform with the ORM configuration. */
     setConfig(config: Configuration): void;
     /** Returns the current ORM configuration. */

package/platforms/Platform.js

@@ -616,6 +616,14 @@ export class Platform {
         Object.defineProperty(copy, JsonProperty, { enumerable: false, value: true });
         return copy;
     }
+    /**
+     * Builds the correlated subquery used as the formula of a virtual to-one relation defined via `through`.
+     * @internal
+     */
+    /* v8 ignore next 3 */
+    getThroughRelationFormula(prop, columns) {
+        throw new Error(`${this.constructor.name} does not support the 'through' option of ${prop.name}`);
+    }
     /** Initializes the platform with the ORM configuration. */
     setConfig(config) {
         this.config = config;

package/typings.d.ts

@@ -653,6 +653,16 @@ export type SerializeDTO<T, H extends string = never, E extends string = never,
 };
 type TargetKeys<T> = T extends EntityClass<infer P> ? keyof P : keyof T;
 type PropertyName<T> = IsUnknown<T> extends false ? TargetKeys<T> : string;
+/** Resolved `through` option of a virtual to-one relation, populated during discovery. */
+export interface ThroughRelation {
+    entity: EntityClass;
+    where?: FilterQuery<any>;
+    orderBy?: QueryOrderMap<any>[];
+    /** M:1 property on the `through` entity pointing back to the owner. */
+    ownerProperty: string;
+    /** M:1 property on the `through` entity pointing to the target, undefined when the target is selected directly. */
+    targetProperty?: string;
+}
 /** Table reference object passed to formula callbacks, including alias and schema information. */
 export type FormulaTable = {
     alias: string;
@@ -1043,6 +1053,7 @@ export interface EntityProperty<Owner = any, Target = any> {
     fixedOrderColumn?: string;
     pivotTable: string;
     pivotEntity: EntityClass<Target>;
+    through?: ThroughRelation;
     joinColumns: string[];
     ownColumns: string[];
     inverseJoinColumns: string[];

package/utils/Utils.js

@@ -153,7 +153,7 @@ export function parseJsonSafe(value) {
 /** Collection of general-purpose utility methods used throughout the ORM. */
 export class Utils {
     static PK_SEPARATOR = '~~~';
-    static #ORM_VERSION = '7.2.0-dev.15';
+    static #ORM_VERSION = '7.2.0-dev.16';
     /** Default session variable name backing an RLS filter argument (`current_setting('mikro.<filter>.<arg>')`). */
     static getRlsSettingName(filterName, argName) {
         return `mikro.${filterName}.${argName}`;