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

package/drivers/DatabaseDriver.d.ts

@@ -65,13 +65,22 @@ export declare abstract class DatabaseDriver<C extends Connection> implements ID
         where: FilterQuery<T>;
     };
     /**
-     * Restores the JS value of a single cursor offset: ISO strings become `Date` instances based on the
-     * property type (never based on the string shape alone), and custom types are restored via
-     * `convertToJSValue`. Values compared against a JSON document keep their serialized form instead,
-     * unless the platform preserves native date types inside JSON documents (mongo).
+     * Resolves a leaf `orderBy` direction into the two flags the rewritten `orderBy` and the cursor
+     * condition have to agree on, or pagination skips rows at the null boundary. Platforms that cannot
+     * order nulls explicitly sort them as the lowest value, elsewhere the requested placement wins,
+     * defaulting to nulls last for `asc` and nulls first for `desc`.
+     */
+    private parseCursorDirection;
+    /**
+     * Restores the JS value of a single cursor offset. String-cursor values (`fromJson`) are decoded
+     * JSON: types implementing `fromJSON` own the round trip, other custom types restore via
+     * `convertToJSValue`, with `Date` healing for date-like columns based on the property type (never
+     * based on the string shape alone). POJO values are already JS values and only date-like strings
+     * are healed. Values compared against a JSON document keep their serialized form instead, unless
+     * the platform preserves native date types inside JSON documents (mongo).
      */
     private mapCursorOffset;
-    protected createCursorCondition<T extends object>(definition: (readonly [keyof T & string, QueryOrder])[], offsets: Dictionary[], inverse: boolean, meta: EntityMetadata<T>): FilterQuery<T>;
+    protected createCursorCondition<T extends object>(definition: (readonly [keyof T & string, QueryOrder])[], offsets: Dictionary[], inverse: boolean, meta: EntityMetadata<T>, fromJson?: boolean): FilterQuery<T>;
     /** @internal */
     mapDataToFieldNames(data: Dictionary, stringifyJsonArrays: boolean, properties?: Record<string, EntityProperty>, convertCustomTypes?: boolean, object?: boolean): Dictionary;
     protected inlineEmbeddables<T extends object>(meta: EntityMetadata<T>, data: T, where?: boolean): void;

package/drivers/DatabaseDriver.js

@@ -10,7 +10,6 @@ import { helper } from '../entity/wrap.js';
 import { Reference } from '../entity/Reference.js';
 import { PolymorphicRef } from '../entity/PolymorphicRef.js';
 import { JsonType } from '../types/JsonType.js';
-import { DateTimeType } from '../types/DateTimeType.js';
 import { QueryHelper } from '../utils/QueryHelper.js';
 import { MikroORM } from '../MikroORM.js';
 /** Abstract base class for all database drivers, implementing common driver logic. */
@@ -146,6 +145,7 @@ export class DatabaseDriver {
         const createCursor = (val, key, inverse = false) => {
             const def = Reference.unwrapReference((isCursor(val, key) ? val[key] : val));
             let offsets;
+            let fromJson = false;
             // entity (and reference) instances are supported as cursors too, their properties are read the same way
             if (Utils.isPlainObject(def) || Utils.isEntity(def)) {
                 // POJO values are already JS values, extract them ordered per the definition,
@@ -158,11 +158,17 @@ export class DatabaseDriver {
                 });
             }
             else {
-                /* v8 ignore next */
-                offsets = def ? Cursor.decode(def) : [];
+                try {
+                    /* v8 ignore next */
+                    offsets = def ? Cursor.decode(def) : [];
+                }
+                catch (error) {
+                    throw CursorError.invalidCursor(meta.className, error);
+                }
+                fromJson = true;
             }
             if (definition.length > 0 && definition.length === offsets.length) {
-                return this.createCursorCondition(definition, offsets, inverse, meta);
+                return this.createCursorCondition(definition, offsets, inverse, meta, fromJson);
             }
             /* v8 ignore next */
             return {};
@@ -176,16 +182,25 @@ export class DatabaseDriver {
         if (limit != null) {
             options.limit = limit + (overfetch ? 1 : 0);
         }
-        const createOrderBy = (prop, direction) => {
+        const createOrderBy = (prop, direction, properties = meta.properties, nullable = false) => {
+            const propMeta = properties[prop];
+            // a nullable relation or embeddable makes its joined columns null too
+            nullable ||= !!propMeta?.nullable;
             if (Utils.isPlainObject(direction)) {
+                const childProps = propMeta?.kind === ReferenceKind.EMBEDDED ? propMeta.embeddedProps : propMeta?.targetMeta?.properties;
                 const value = Utils.getObjectQueryKeys(direction).reduce((o, key) => {
-                    Object.assign(o, createOrderBy(key, direction[key]));
+                    Object.assign(o, createOrderBy(key, direction[key], childProps ?? {}, nullable));
                     return o;
                 }, {});
                 return { [prop]: value };
             }
-            const desc = direction === QueryOrderNumeric.DESC || direction.toString().toLowerCase() === 'desc';
+            const { desc, nullsFirst } = this.parseCursorDirection(direction);
             const dir = Utils.xor(desc, isLast) ? 'desc' : 'asc';
+            // the condition assumes a placement, spell it out instead of taking the database default
+            if (nullable && this.platform.supportsNullsOrdering()) {
+                const nulls = Utils.xor(nullsFirst, isLast) ? 'first' : 'last';
+                return { [prop]: `${dir} nulls ${nulls}` };
+            }
             return { [prop]: dir };
         };
         // the cursor condition is created at the driver level, after the EM already converted custom types
@@ -203,12 +218,34 @@ export class DatabaseDriver {
         };
     }
     /**
-     * Restores the JS value of a single cursor offset: ISO strings become `Date` instances based on the
-     * property type (never based on the string shape alone), and custom types are restored via
-     * `convertToJSValue`. Values compared against a JSON document keep their serialized form instead,
-     * unless the platform preserves native date types inside JSON documents (mongo).
+     * Resolves a leaf `orderBy` direction into the two flags the rewritten `orderBy` and the cursor
+     * condition have to agree on, or pagination skips rows at the null boundary. Platforms that cannot
+     * order nulls explicitly sort them as the lowest value, elsewhere the requested placement wins,
+     * defaulting to nulls last for `asc` and nulls first for `desc`.
+     */
+    parseCursorDirection(direction) {
+        const dir = ('' + direction).toLowerCase();
+        const desc = direction === QueryOrderNumeric.DESC || dir.startsWith('desc');
+        if (!this.platform.supportsNullsOrdering()) {
+            return { desc, nullsFirst: !desc };
+        }
+        if (dir.includes('nulls first')) {
+            return { desc, nullsFirst: true };
+        }
+        if (dir.includes('nulls last')) {
+            return { desc, nullsFirst: false };
+        }
+        return { desc, nullsFirst: desc };
+    }
+    /**
+     * Restores the JS value of a single cursor offset. String-cursor values (`fromJson`) are decoded
+     * JSON: types implementing `fromJSON` own the round trip, other custom types restore via
+     * `convertToJSValue`, with `Date` healing for date-like columns based on the property type (never
+     * based on the string shape alone). POJO values are already JS values and only date-like strings
+     * are healed. Values compared against a JSON document keep their serialized form instead, unless
+     * the platform preserves native date types inside JSON documents (mongo).
      */
-    mapCursorOffset(prop, value, insideJson) {
+    mapCursorOffset(prop, value, insideJson, fromJson) {
         if (Utils.isScalarReference(value)) {
             value = value.unwrap();
         }
@@ -219,25 +256,65 @@ export class DatabaseDriver {
         if (value == null) {
             return value;
         }
+        // mongo preserves native date types inside JSON documents, restored JS values compare directly
         if (insideJson && !this.platform.preservesDatesInsideJson()) {
-            // compared against the JSON document, which holds the serialized form
+            // compared against the JSON document, which holds the JSON form of the database value
             if (value instanceof Date) {
                 return value.toISOString();
             }
-            // restore the JS value from the serialized form, `processWhere` then converts it to
-            // the database form, which is what the JSON document holds for custom typed props
-            return prop?.customType ? prop.customType.convertToJSValue(value, this.platform) : value;
+            if (prop?.customType && fromJson) {
+                const restored = prop.customType.fromJSON
+                    ? prop.customType.fromJSON(value, this.platform)
+                    : prop.customType.convertToJSValue(value, this.platform);
+                // a restored `Date` compares against its ISO string in the document, everything else
+                // keeps the JS value and gets its single `convertToDatabaseValue` in `processWhere`
+                if (restored instanceof Date) {
+                    const converted = prop.customType.convertToDatabaseValue(restored, this.platform, {
+                        fromQuery: true,
+                        key: prop.name,
+                        mode: 'query',
+                    });
+                    if (converted instanceof Date) {
+                        return converted.toISOString();
+                    }
+                }
+                return restored;
+            }
+            return value;
         }
-        if (typeof value === 'string' &&
-            (prop?.runtimeType === 'Date' ||
-                (prop?.customType && this.platform.getMappedType(prop.columnTypes?.[0] ?? '') instanceof DateTimeType))) {
-            value = new Date(value);
+        if (prop?.customType) {
+            if (fromJson && prop.customType.fromJSON) {
+                // the type owns its JSON round trip
+                return prop.customType.fromJSON(value, this.platform);
+            }
+            // A string is either a serialized form (string cursor) or a hand-written one (POJO).
+            // Types whose JS value is a `Date` must receive one. The rest get the string first,
+            // so any sub-millisecond precision survives.
+            if (typeof value === 'string' &&
+                (prop.runtimeType === 'Date' || this.platform.getMappedType(prop.columnTypes?.[0] ?? '').runtimeType === 'Date')) {
+                if (prop.runtimeType !== 'Date') {
+                    try {
+                        return prop.customType.convertToJSValue(value, this.platform);
+                    }
+                    catch {
+                        // the type cannot read the serialized string, fall back to the `Date` form
+                    }
+                }
+                return prop.customType.convertToJSValue(new Date(value), this.platform);
+            }
+            // serialized non-string values still need restoring; POJO values are already JS values
+            return fromJson ? prop.customType.convertToJSValue(value, this.platform) : value;
+        }
+        if (typeof value === 'string' && prop?.runtimeType === 'Date') {
+            return new Date(value);
         }
-        return prop?.customType ? prop.customType.convertToJSValue(value, this.platform) : value;
+        return value;
     }
-    createCursorCondition(definition, offsets, inverse, meta) {
-        const createCondition = (prop, direction, offset, eq = false, path = prop, properties = meta.properties, insideJson = false) => {
+    createCursorCondition(definition, offsets, inverse, meta, fromJson = false) {
+        const createCondition = (prop, direction, offset, eq = false, path = prop, properties = meta.properties, insideJson = false, nullable = false) => {
             const propMeta = properties[prop];
+            // a nullable relation or embeddable makes its joined columns null too
+            nullable ||= !!propMeta?.nullable;
             if (Utils.isPlainObject(direction)) {
                 if (offset === undefined) {
                     throw CursorError.missingValue(meta.className, path);
@@ -247,40 +324,45 @@ export class DatabaseDriver {
                 const childProps = propMeta?.kind === ReferenceKind.EMBEDDED ? propMeta.embeddedProps : propMeta?.targetMeta?.properties;
                 insideJson ||=
                     (propMeta?.kind === ReferenceKind.EMBEDDED && !!propMeta.object) || propMeta?.customType instanceof JsonType;
-                const value = Utils.keys(direction).reduce((o, key) => {
-                    Object.assign(o, createCondition(key, direction[key], offset?.[key], eq, `${path}.${key}`, childProps ?? {}, insideJson));
-                    return o;
-                }, {});
-                return { [prop]: value };
-            }
-            const isDesc = direction === QueryOrderNumeric.DESC || direction.toString().toLowerCase() === 'desc';
-            const dirStr = direction.toString().toLowerCase();
-            let nullsFirst;
-            if (dirStr.includes('nulls first')) {
-                nullsFirst = true;
-            }
-            else if (dirStr.includes('nulls last')) {
-                nullsFirst = false;
-            }
-            else {
-                // Default: NULLS LAST for ASC, NULLS FIRST for DESC (matches most databases)
-                nullsFirst = isDesc;
+                const children = Utils.keys(direction)
+                    .map(key => createCondition(key, direction[key], 
+                // a null relation offset means the whole sort key is null, propagate it to the leaves
+                offset === null ? null : offset[key], eq, `${path}.${key}`, childProps ?? {}, insideJson, nullable))
+                    .filter(child => Utils.hasObjectKeys(child));
+                // children comparing against nulls are group conditions, those cannot be merged into one object
+                const value = children.length > 1 && children.some(child => '$or' in child)
+                    ? { $and: children }
+                    : children.reduce((o, child) => Object.assign(o, child), {});
+                // an unconstrained child condition must not degrade to `{ [prop]: {} }`
+                return children.length > 0 ? { [prop]: value } : {};
             }
+            const { desc: isDesc, nullsFirst } = this.parseCursorDirection(direction);
             const operator = Utils.xor(isDesc, inverse) ? '$lt' : '$gt';
             // For leaf-level properties, undefined means missing value
             if (offset === undefined) {
                 throw CursorError.missingValue(meta.className, path);
             }
-            offset = this.mapCursorOffset(propMeta, offset, insideJson);
+            // string-cursor values are client supplied, so a value the type cannot restore is an
+            // invalid cursor, letting callers map `CursorError` to a client error response
+            try {
+                offset = this.mapCursorOffset(propMeta, offset, insideJson, fromJson);
+            }
+            catch (error) {
+                if (!fromJson || error instanceof CursorError) {
+                    throw error;
+                }
+                throw CursorError.invalidCursor(meta.className, error);
+            }
             // Handle null offset (intentional null cursor value)
             if (offset === null) {
+                // hasItemsAfterNull: forward + nullsFirst, or backward + nullsLast
+                const hasItemsAfterNull = Utils.xor(nullsFirst, inverse);
                 if (eq) {
-                    // Equal to null
-                    return { [prop]: null };
+                    // at-or-after a null sort key means every row when non-null rows follow the null block,
+                    // so the tie-breaker in the `$or` sibling can reach past it
+                    return hasItemsAfterNull ? {} : { [prop]: null };
                 }
                 // Strict comparison with null cursor value
-                // hasItemsAfterNull: forward + nullsFirst, or backward + nullsLast
-                const hasItemsAfterNull = Utils.xor(nullsFirst, inverse);
                 if (hasItemsAfterNull) {
                     return { [prop]: { $ne: null } };
                 }
@@ -288,7 +370,12 @@ export class DatabaseDriver {
                 return { [prop]: [] };
             }
             // Non-null offset
-            return { [prop]: { [operator + (eq ? 'e' : '')]: offset } };
+            const condition = { [prop]: { [operator + (eq ? 'e' : '')]: offset } };
+            // null sort keys lie past the offset here, and no comparison ever matches them
+            if (nullable && !Utils.xor(nullsFirst, inverse)) {
+                return { $or: [condition, { [prop]: null }] };
+            }
+            return condition;
         };
         const [order, ...otherOrders] = definition;
         const [offset, ...otherOffsets] = offsets;
@@ -296,13 +383,18 @@ export class DatabaseDriver {
         if (!otherOrders.length) {
             return createCondition(prop, direction, offset);
         }
-        return {
-            ...createCondition(prop, direction, offset, true),
+        const atOrPast = createCondition(prop, direction, offset, true);
+        const past = {
             $or: [
                 createCondition(prop, direction, offset),
-                this.createCursorCondition(otherOrders, otherOffsets, inverse, meta),
+                this.createCursorCondition(otherOrders, otherOffsets, inverse, meta, fromJson),
             ],
         };
+        // the `at or past` prefix is itself a group condition when it compares against nulls
+        if ('$or' in atOrPast) {
+            return { $and: [atOrPast, past] };
+        }
+        return { ...atOrPast, ...past };
     }
     /** @internal */
     mapDataToFieldNames(data, stringifyJsonArrays, properties, convertCustomTypes, object) {

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

@@ -41,6 +41,7 @@ export declare class ValidationError<T extends AnyEntity = AnyEntity> extends Er
 export declare class CursorError<T extends AnyEntity = AnyEntity> extends ValidationError<T> {
     static entityNotPopulated(entity: AnyEntity, prop: string): ValidationError;
     static missingValue(entityName: string, prop: string): ValidationError;
+    static invalidCursor(entityName: string, cause: Error): CursorError;
 }
 /** Error thrown when an optimistic lock conflict is detected during entity persistence. */
 export declare class OptimisticLockError<T extends AnyEntity = AnyEntity> extends ValidationError<T> {
@@ -73,6 +74,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

@@ -140,6 +140,11 @@ export class CursorError extends ValidationError {
     static missingValue(entityName, prop) {
         return new CursorError(`Invalid cursor condition, value for '${entityName}.${prop}' is missing.`);
     }
+    static invalidCursor(entityName, cause) {
+        const error = new CursorError(`Invalid cursor for entity ${entityName}: ${cause.message}`);
+        error.cause = cause;
+        return error;
+    }
 }
 /** Error thrown when an optimistic lock conflict is detected during entity persistence. */
 export class OptimisticLockError extends ValidationError {
@@ -241,6 +246,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.17",
   "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';
@@ -230,6 +230,8 @@ export declare abstract class Platform {
     convertsJsonAutomatically(): boolean;
     /** Whether date values inside JSON documents keep their native type (e.g. BSON dates), instead of being serialized to ISO strings. */
     preservesDatesInsideJson(): boolean;
+    /** Whether `nulls first`/`nulls last` can be requested in an `orderBy`. Platforms returning `false` always sort nulls as the lowest value. */
+    supportsNullsOrdering(): boolean;
     /** Converts a JS value to its JSON database representation (typically JSON.stringify). */
     convertJsonToDatabaseValue(value: unknown, context?: TransformContext): unknown;
     /** Converts a database JSON value to its JS representation. */
@@ -275,6 +277,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

@@ -471,6 +471,10 @@ export class Platform {
     preservesDatesInsideJson() {
         return false;
     }
+    /** Whether `nulls first`/`nulls last` can be requested in an `orderBy`. Platforms returning `false` always sort nulls as the lowest value. */
+    supportsNullsOrdering() {
+        return true;
+    }
     /** Converts a JS value to its JSON database representation (typically JSON.stringify). */
     convertJsonToDatabaseValue(value, context) {
         return JSON.stringify(value);
@@ -616,6 +620,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/types/BigIntType.d.ts

@@ -11,6 +11,7 @@ export declare class BigIntType<Mode extends 'bigint' | 'number' | 'string' = 'b
     convertToDatabaseValue(value: JSTypeByMode<Mode> | null | undefined): string | null | undefined;
     convertToJSValue(value: string | bigint | null | undefined): JSTypeByMode<Mode> | null | undefined;
     toJSON(value: JSTypeByMode<Mode> | null | undefined): JSTypeByMode<Mode> | null | undefined;
+    fromJSON(value: unknown): JSTypeByMode<Mode> | null | undefined;
     getColumnType(prop: EntityProperty, platform: Platform): string;
     compareAsType(): string;
     compareValues(a: string, b: string): boolean;

package/types/BigIntType.js

@@ -1,4 +1,5 @@
 import { Type } from './Type.js';
+import { ValidationError } from '../errors.js';
 /**
  * This type will automatically convert string values returned from the database to native JS bigints (default)
  * or numbers (safe only for values up to `Number.MAX_SAFE_INTEGER`), or strings, depending on the `mode`.
@@ -36,6 +37,28 @@ export class BigIntType extends Type {
         }
         return this.convertToDatabaseValue(value);
     }
+    fromJSON(value) {
+        // the serialized form is a decimal string, or a plain number in `number` mode
+        const valid = (typeof value === 'string' && /^-?\d+$/.test(value)) || (typeof value === 'number' && Number.isInteger(value));
+        if (!valid) {
+            throw ValidationError.invalidType(BigIntType, value, 'JSON');
+        }
+        switch (this.mode) {
+            case 'number': {
+                // `Number` silently rounds past `MAX_SAFE_INTEGER`, tampered cursors must fail loudly
+                const num = Number(value);
+                if (!Number.isSafeInteger(num)) {
+                    throw ValidationError.invalidType(BigIntType, value, 'JSON');
+                }
+                return num;
+            }
+            case 'string':
+                return String(value);
+            case 'bigint':
+            default:
+                return BigInt(value);
+        }
+    }
     getColumnType(prop, platform) {
         return platform.getBigIntTypeDeclarationSQL(prop);
     }

package/types/DateTimeType.d.ts

@@ -5,6 +5,7 @@ import type { EntityProperty } from '../typings.js';
 export declare class DateTimeType extends Type<Date, string> {
     getColumnType(prop: EntityProperty, platform: Platform): string;
     compareAsType(): string;
+    fromJSON(value: unknown): Date;
     get runtimeType(): string;
     ensureComparable(): boolean;
     getDefaultLength(platform: Platform): number;

package/types/DateTimeType.js

@@ -1,4 +1,5 @@
 import { Type } from './Type.js';
+import { ValidationError } from '../errors.js';
 /** Maps a database DATETIME/TIMESTAMP column to a JS `Date` object. */
 export class DateTimeType extends Type {
     getColumnType(prop, platform) {
@@ -7,6 +8,13 @@ export class DateTimeType extends Type {
     compareAsType() {
         return 'Date';
     }
+    fromJSON(value) {
+        const date = new Date(value);
+        if (typeof value !== 'string' || Number.isNaN(date.getTime())) {
+            throw ValidationError.invalidType(DateTimeType, value, 'JSON');
+        }
+        return date;
+    }
     get runtimeType() {
         return 'Date';
     }

package/types/Type.d.ts

@@ -59,6 +59,17 @@ export declare abstract class Type<JSType = string, DBType = JSType> {
      * By default uses the runtime value.
      */
     toJSON(value: JSType, platform: Platform): JSType | DBType;
+    /**
+     * Converts a value from its serialized JSON form back to its JS representation. Used when
+     * decoding cursor values. The input is what `toJSON` produced, after a `JSON.parse` round
+     * trip, and never an already restored JS value. Cursors are client supplied, so the value
+     * can be any JSON shape: validate it and throw for values the type cannot restore, and
+     * `findByCursor` surfaces the failure as a `CursorError`.
+     * Implementing this method also makes cursor encoding use `toJSON`. Without it, cursors
+     * carry the raw JS value, and decoding falls back to `convertToJSValue`, with type-based
+     * `Date` restoration for date-like columns.
+     */
+    fromJSON?(value: unknown, platform: Platform): JSType;
     /**
      * Gets the SQL declaration snippet for a field of this type.
      */

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/Cursor.d.ts

@@ -61,6 +61,8 @@ export declare class Cursor<Entity extends object, Hint extends string = never,
      * Computes the cursor value for a given entity.
      */
     from(entity: Entity | Loaded<Entity, Hint, Fields, Excludes>): string;
+    /** Serializes a single cursor value, walking nested directions and reading the owner's properties. */
+    private static serialize;
     [Symbol.iterator](): IterableIterator<Loaded<Entity, Hint, Fields, Excludes>>;
     get length(): number;
     /**

package/utils/Cursor.js

@@ -58,6 +58,7 @@ export class Cursor {
     hasPrevPage;
     hasNextPage;
     #definition;
+    #meta;
     constructor(items, totalCount, options, meta) {
         this.items = items;
         this.totalCount = totalCount;
@@ -76,6 +77,7 @@ export class Cursor {
             }
         }
         this.#definition = Cursor.getDefinition(meta, orderBy);
+        this.#meta = meta;
     }
     get startCursor() {
         if (this.items.length === 0) {
@@ -93,37 +95,46 @@ export class Cursor {
      * Computes the cursor value for a given entity.
      */
     from(entity) {
-        const processEntity = (entity, prop, direction, object = false) => {
-            if (Utils.isPlainObject(direction)) {
-                const unwrapped = Reference.unwrapReference(entity[prop]);
-                // Check if the relation is loaded - for nested properties, undefined means not populated
-                if (Utils.isEntity(unwrapped) && !helper(unwrapped).isInitialized()) {
-                    throw CursorError.entityNotPopulated(entity, prop);
-                }
-                return Utils.keys(direction).reduce((o, key) => {
-                    Object.assign(o, processEntity(unwrapped, key, direction[key], true));
-                    return o;
-                }, {});
-            }
-            let value = entity[prop];
-            // Allow null/undefined values in cursor - they will be handled in createCursorCondition
-            // undefined can occur with forceUndefined config option which converts null to undefined
-            if (value == null) {
-                return object ? { [prop]: null } : null;
-            }
-            if (Utils.isEntity(value, true)) {
-                value = helper(value).getPrimaryKey();
-            }
-            if (Utils.isScalarReference(value)) {
-                value = value.unwrap();
+        const value = this.#definition.map(([key, direction]) => Cursor.serialize(this.#meta.properties, entity, key, direction));
+        return Cursor.encode(value);
+    }
+    /** Serializes a single cursor value, walking nested directions and reading the owner's properties. */
+    static serialize(properties, owner, key, direction) {
+        const prop = properties[key];
+        let value = owner[key];
+        if (Utils.isPlainObject(direction)) {
+            const unwrapped = Reference.unwrapReference(value);
+            // for nested properties, an uninitialized relation means not populated
+            if (Utils.isEntity(unwrapped) && !helper(unwrapped).isInitialized()) {
+                throw CursorError.entityNotPopulated(owner, key);
             }
-            if (object) {
-                return { [prop]: value };
+            if (unwrapped == null || typeof unwrapped !== 'object') {
+                return unwrapped;
             }
-            return value;
-        };
-        const value = this.#definition.map(([key, direction]) => processEntity(entity, key, direction));
-        return Cursor.encode(value);
+            const childProps = prop?.kind === ReferenceKind.EMBEDDED ? prop.embeddedProps : prop?.targetMeta?.properties;
+            return Utils.keys(direction).reduce((o, childKey) => {
+                o[childKey] = Cursor.serialize(childProps ?? {}, unwrapped, childKey, direction[childKey]);
+                return o;
+            }, {});
+        }
+        // allow null/undefined values in cursor - they will be handled in createCursorCondition
+        // undefined can occur with forceUndefined config option which converts null to undefined
+        if (value == null) {
+            return null;
+        }
+        if (Utils.isEntity(value, true)) {
+            value = helper(value).getPrimaryKey();
+        }
+        if (Utils.isScalarReference(value)) {
+            value = value.unwrap();
+        }
+        // only types implementing `fromJSON` own their wire format, others keep the raw JS value,
+        // so their cursors stay decodable by the `convertToJSValue` fallback
+        if (prop?.customType?.fromJSON) {
+            // the platform is assigned to the type instance during discovery
+            return prop.customType.toJSON(value, prop.customType.platform);
+        }
+        return value;
     }
     *[Symbol.iterator]() {
         for (const item of this.items) {
@@ -138,12 +149,11 @@ export class Cursor {
      */
     static for(meta, entity, orderBy) {
         const definition = this.getDefinition(meta, orderBy);
-        return Cursor.encode(definition.map(([key]) => {
-            const value = entity[key];
-            if (value === undefined) {
+        return Cursor.encode(definition.map(([key, direction]) => {
+            if (entity[key] === undefined) {
                 throw CursorError.missingValue(meta.className, key);
             }
-            return value;
+            return this.serialize(meta.properties, entity, key, direction);
         }));
     }
     static encode(value) {

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.17';
     /** Default session variable name backing an RLS filter argument (`current_setting('mikro.<filter>.<arg>')`). */
     static getRlsSettingName(filterName, argName) {
         return `mikro.${filterName}.${argName}`;