@mikro-orm/core 7.2.0-dev.9 → 7.2.0

package/metadata/MetadataDiscovery.d.ts

@@ -117,6 +117,7 @@ export declare class MetadataDiscovery {
     private createSchemaTable;
     private initCheckConstraints;
     private initTriggers;
+    private initPolicies;
     private initGeneratedColumn;
     private getDefaultVersionValue;
     private inferDefaultValue;
@@ -125,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

@@ -165,10 +165,14 @@ export class MetadataDiscovery {
         filtered.forEach(meta => this.initAutoincrement(meta)); // once again after we init custom types
         filtered.forEach(meta => this.initCheckConstraints(meta));
         filtered.forEach(meta => this.initTriggers(meta));
-        forEachProp((_m, p) => {
+        // 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) => {
             this.initDefaultValue(p);
             this.inferTypeFromDefault(p);
             this.initRelation(p);
+            this.initThroughRelation(m, p);
             this.initColumnType(p);
         });
         forEachProp((m, p) => this.initIndexes(m, p));
@@ -220,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);
                 }
@@ -441,7 +443,18 @@ export class MetadataDiscovery {
         if (prop.kind === ReferenceKind.SCALAR || prop.kind === ReferenceKind.EMBEDDED) {
             prop.fieldNames = [this.#namingStrategy.propertyToColumnName(prop.name, object)];
         }
-        else if ([ReferenceKind.MANY_TO_ONE, ReferenceKind.ONE_TO_ONE].includes(prop.kind) && !prop.polymorphic) {
+        else if ([ReferenceKind.MANY_TO_ONE, ReferenceKind.ONE_TO_ONE].includes(prop.kind) && prop.polymorphic) {
+            if (prop.targetMeta) {
+                // same layout as `initManyToOneFields` builds later: `[discriminatorColumn, ...fkIdColumns]`
+                const pkFields = prop.targetMeta.getPrimaryProps().flatMap(pk => {
+                    this.initFieldName(pk);
+                    return pk.fieldNames;
+                });
+                const idColumns = pkFields.map(fieldName => this.#namingStrategy.joinKeyColumnName(prop.discriminator, fieldName, pkFields.length > 1));
+                prop.fieldNames = [prop.discriminatorColumn, ...idColumns];
+            }
+        }
+        else if ([ReferenceKind.MANY_TO_ONE, ReferenceKind.ONE_TO_ONE].includes(prop.kind)) {
             prop.fieldNames = this.initManyToOneFieldName(prop, prop.name);
         }
         else if (prop.kind === ReferenceKind.MANY_TO_MANY && prop.owner) {
@@ -451,10 +464,13 @@ export class MetadataDiscovery {
     initManyToOneFieldName(prop, name) {
         const meta2 = prop.targetMeta;
         const ret = [];
-        for (const primaryKey of meta2.primaryKeys) {
-            this.initFieldName(meta2.properties[primaryKey]);
-            for (const fieldName of meta2.properties[primaryKey].fieldNames) {
-                ret.push(this.#namingStrategy.joinKeyColumnName(name, fieldName, meta2.compositePK));
+        // with `targetKey` on a composite PK target, derive the FK field name from that property
+        // instead of the PKs (simple PK targets keep the PK based naming for backwards compatibility)
+        const referencedKeys = prop.targetKey && meta2.compositePK ? [prop.targetKey] : meta2.primaryKeys;
+        for (const referencedKey of referencedKeys) {
+            this.initFieldName(meta2.properties[referencedKey]);
+            for (const fieldName of meta2.properties[referencedKey].fieldNames) {
+                ret.push(this.#namingStrategy.joinKeyColumnName(name, fieldName, !prop.targetKey && meta2.compositePK));
             }
         }
         return ret;
@@ -1055,11 +1071,18 @@ export class MetadataDiscovery {
         }
         // TPT children have their own tables that don't contain the parent's columns,
         // so propagating parent indexes/uniques/checks/triggers would target missing columns.
+        // deep equality, as the subclass items might be copies of the base class ones (e.g. with TC39 decorators)
         if (meta.inheritanceType !== 'tpt' || !meta.tptParent) {
-            meta.indexes = Utils.unique([...base.indexes, ...meta.indexes]);
-            meta.uniques = Utils.unique([...base.uniques, ...meta.uniques]);
-            meta.checks = Utils.unique([...base.checks, ...meta.checks]);
-            meta.triggers = Utils.unique([...base.triggers, ...meta.triggers]);
+            meta.indexes = Utils.unique([...base.indexes, ...meta.indexes], Utils.equals);
+            meta.uniques = Utils.unique([...base.uniques, ...meta.uniques], Utils.equals);
+            meta.checks = Utils.unique([...base.checks, ...meta.checks], Utils.equals);
+            meta.triggers = Utils.unique([...base.triggers, ...meta.triggers], Utils.equals);
+        }
+        // Policies pass down only from inlined abstract bases; STI children share the root table
+        // and TPT children own their tables, so both declare policies directly on the root/child.
+        if (base.abstract && base.inheritanceType !== 'sti' && (meta.inheritanceType !== 'tpt' || !meta.tptParent)) {
+            meta.policies = Utils.unique([...base.policies, ...meta.policies]);
+            meta.rowLevelSecurity ??= base.rowLevelSecurity;
         }
         const pks = Object.values(meta.properties)
             .filter(p => p.primary)
@@ -1247,8 +1270,17 @@ export class MetadataDiscovery {
             if (embeddedProp.nullable || refInArray) {
                 meta.properties[name].nullable = true;
             }
+            // polymorphic relations derive their column names from the discriminator, so prefix it too
+            if (meta.properties[name].polymorphic && !object) {
+                meta.properties[name].discriminator = prefix + meta.properties[name].discriminator;
+                meta.properties[name].discriminatorColumn = prefix + meta.properties[name].discriminatorColumn;
+            }
             if (meta.properties[name].fieldNames) {
-                meta.properties[name].fieldNames[0] = prefix + meta.properties[name].fieldNames[0];
+                const { fieldNames, polymorphic } = meta.properties[name];
+                // polymorphic `fieldNames` hold `[discriminatorColumn, ...fkIdColumns]`, so prefix all of them
+                for (let i = 0; i < (polymorphic ? fieldNames.length : 1); i++) {
+                    fieldNames[i] = prefix + fieldNames[i];
+                }
             }
             else {
                 const name2 = meta.properties[name].name;
@@ -1677,6 +1709,9 @@ export class MetadataDiscovery {
                 if (prop.persist === false || prop.nativeEnumName || !prop.items?.every(item => typeof item === 'string')) {
                     continue;
                 }
+                if (prop.customType instanceof t.json || ['json', 'jsonb'].includes(prop.columnTypes?.[0])) {
+                    continue;
+                }
                 this.initFieldName(prop);
                 let expression = null;
                 if (prop.enum) {
@@ -1716,6 +1751,28 @@ export class MetadataDiscovery {
         }
         meta.hasTriggers = true;
     }
+    initPolicies(meta) {
+        if (meta.policies.length === 0) {
+            return;
+        }
+        const columns = meta.createSchemaColumnMappingObject();
+        const table = this.createSchemaTable(meta);
+        // resolve callbacks into a copy — the defs can be shared with siblings via an inlined abstract base,
+        // and resolving in place would bake the first child's table into every other child's policy
+        meta.policies = meta.policies.map(policy => {
+            if (!(policy.using instanceof Function) && !(policy.check instanceof Function)) {
+                return policy;
+            }
+            const resolved = { ...policy };
+            if (resolved.using instanceof Function) {
+                resolved.using = resolved.using(columns, table);
+            }
+            if (resolved.check instanceof Function) {
+                resolved.check = resolved.check(columns, table);
+            }
+            return resolved;
+        });
+    }
     initGeneratedColumn(meta, prop) {
         if (!prop.generated && prop.columnTypes) {
             const match = /(.*) generated always as (.*)/i.exec(prop.columnTypes[0]);
@@ -2020,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
@@ -2080,6 +2189,7 @@ export class MetadataDiscovery {
             prop.columnTypes.push(...columnTypes);
             if (!targetMeta.compositePK || prop.targetKey) {
                 prop.customType = referencedProp.customType;
+                prop.collation ??= referencedProp.collation;
             }
         }
     }
@@ -2135,7 +2245,7 @@ export class MetadataDiscovery {
     shouldForceConstructorUsage(meta) {
         const forceConstructor = this.#config.get('forceEntityConstructor');
         if (Array.isArray(forceConstructor)) {
-            return forceConstructor.some(cls => Utils.className(cls) === meta.className);
+            return forceConstructor.some(cls => Utils.matchesEntity(cls, meta));
         }
         return forceConstructor;
     }

package/metadata/MetadataStorage.js

@@ -17,6 +17,7 @@ export class MetadataStorage {
     #idMap;
     #classNameMap;
     #uniqueNameMap;
+    #ambiguousNames = new Set();
     constructor(metadata = {}) {
         this.#idMap = {};
         this.#uniqueNameMap = {};
@@ -64,6 +65,10 @@ export class MetadataStorage {
     }
     /** Returns metadata for the given entity, optionally initializing it if not found. */
     get(entityName, init = false) {
+        // string lookups cannot be resolved when several classes were minified to the same name
+        if (typeof entityName === 'string' && this.#ambiguousNames.has(entityName)) {
+            throw MetadataError.ambiguousEntityName(entityName);
+        }
         const exists = this.find(entityName);
         if (exists) {
             return exists;
@@ -99,7 +104,13 @@ export class MetadataStorage {
         this.#metadataMap.set(entityName, meta);
         this.#idMap[meta._id] = meta;
         this.#uniqueNameMap[meta.uniqueName] = meta;
-        this.#classNameMap[Utils.className(entityName)] = meta;
+        const className = Utils.className(entityName);
+        const existing = this.#classNameMap[className];
+        // track name collisions caused by minifiers mangling two classes to the same name
+        if (existing && existing !== meta && existing.class !== meta.class) {
+            this.#ambiguousNames.add(className);
+        }
+        this.#classNameMap[className] = meta;
         return meta;
     }
     /** Removes metadata for the given entity from all internal maps. */
@@ -110,6 +121,11 @@ export class MetadataStorage {
             delete this.#idMap[meta._id];
             delete this.#uniqueNameMap[meta.uniqueName];
             delete this.#classNameMap[meta.className];
+            // the name may still be ambiguous among the remaining metas
+            const remaining = new Set([...this.#metadataMap.values()].filter(m => m.className === meta.className).map(m => m.class));
+            if (remaining.size <= 1) {
+                this.#ambiguousNames.delete(meta.className);
+            }
         }
     }
     /** Decorates all entity prototypes with helper methods (e.g. init, toJSON). */

package/metadata/types.d.ts

@@ -1,4 +1,4 @@
-import type { AnyEntity, Constructor, EntityName, AnyString, CheckCallback, GeneratedColumnCallback, FormulaCallback, FilterQuery, Dictionary, AutoPath, EntityClass, IndexCallback, ObjectQuery, Raw, SchemaColumns, TriggerDef } from '../typings.js';
+import type { AnyEntity, Constructor, EntityName, AnyString, CheckCallback, GeneratedColumnCallback, FormulaCallback, FilterQuery, Dictionary, AutoPath, EntityClass, IndexCallback, ObjectQuery, Raw, SchemaColumns, TriggerDef, PolicyDef } from '../typings.js';
 import type { Cascade, LoadStrategy, DeferMode, QueryOrderMap, EmbeddedPrefixMode } from '../enums.js';
 import type { Type, types } from '../types/index.js';
 import type { EntityManager } from '../EntityManager.js';
@@ -104,6 +104,10 @@ export type EntityOptions<T, E = T extends EntityClass<infer P> ? P : T> = {
     hasTriggers?: boolean;
     /** Database triggers to create for this entity's table. (SQL drivers only) */
     triggers?: TriggerDef<E>[];
+    /** PostgreSQL row level security policies for this entity's table. Declaring policies implicitly enables RLS. */
+    policies?: PolicyDef<E>[];
+    /** Enables PostgreSQL row level security on this entity's table. `'force'` also enforces it for the table owner. Set to `false` to keep declared policies staged while leaving RLS disabled. */
+    rowLevelSecurity?: boolean | 'force';
     /**
      * PostgreSQL partitioning definition for this table.
      *
@@ -427,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. */
@@ -481,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.9",
+  "version": "7.2.0",
   "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';
@@ -211,8 +211,9 @@ export declare abstract class Platform {
     getBlobDeclarationSQL(): string;
     getJsonDeclarationSQL(): string;
     getSearchJsonPropertySQL(path: string, type: string, aliased: boolean): string | Raw;
-    getSearchJsonPropertyKey(path: string[], type: string, aliased: boolean, value?: unknown): string | Raw;
-    processJsonCondition<T extends object>(o: FilterQuery<T>, value: EntityValue<T>, path: EntityKey<T>[], alias: boolean): FilterQuery<T>;
+    /** When `aliased` is a string, it holds an explicit alias the key was prefixed with. */
+    getSearchJsonPropertyKey(path: string[], type: string, aliased: boolean | string, value?: unknown): string | Raw;
+    processJsonCondition<T extends object>(o: FilterQuery<T>, value: EntityValue<T>, path: EntityKey<T>[], alias: boolean | string): FilterQuery<T>;
     protected getJsonValueType(value: unknown): string;
     getJsonIndexDefinition(index: {
         columnNames: string[];
@@ -229,6 +230,10 @@ 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`. */
+    supportsNullsOrdering(): boolean;
+    /** Where nulls land when an `orderBy` requests no explicit placement: lowest (`asc` puts them first) or highest. */
+    sortsNullsLowest(): 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. */
@@ -274,6 +279,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. */
@@ -315,6 +325,15 @@ export declare abstract class Platform {
     supportsDownMigrations(): boolean;
     /** Whether the platform supports deferred unique constraints. */
     supportsDeferredUniqueConstraints(): boolean;
+    /** Whether the platform supports row level security (PostgreSQL). */
+    supportsRowLevelSecurity(): boolean;
+    /** Whether the driver can apply the session context on every pooled connection acquire (`sessionContext: 'connection'`). */
+    supportsConnectionSessionContext(): boolean;
+    /**
+     * SQL cast suffix (e.g. `'::uuid'`, or `''` when none is needed) applied when an RLS filter reads a session
+     * variable via `current_setting()` as the given column type, or `null` if the type has no automatic cast.
+     */
+    getCurrentSettingCast(mappedType: Type<unknown>): string | null;
     /** Platform-specific validation of entity metadata. */
     validateMetadata(meta: EntityMetadata): void;
     /**

package/platforms/Platform.js

@@ -413,6 +413,7 @@ export class Platform {
     getSearchJsonPropertySQL(path, type, aliased) {
         return path;
     }
+    /** When `aliased` is a string, it holds an explicit alias the key was prefixed with. */
     getSearchJsonPropertyKey(path, type, aliased, value) {
         return path.join('.');
     }
@@ -424,7 +425,8 @@ export class Platform {
             return o;
         }
         if (path.length === 1) {
-            o[path[0]] = value;
+            const key = typeof alias === 'string' ? `${alias}.${path[0]}` : path[0];
+            o[key] = value;
             return o;
         }
         const type = this.getJsonValueType(value);
@@ -469,6 +471,14 @@ export class Platform {
     preservesDatesInsideJson() {
         return false;
     }
+    /** Whether `nulls first`/`nulls last` can be requested in an `orderBy`. */
+    supportsNullsOrdering() {
+        return true;
+    }
+    /** Where nulls land when an `orderBy` requests no explicit placement: lowest (`asc` puts them first) or highest. */
+    sortsNullsLowest() {
+        return false;
+    }
     /** Converts a JS value to its JSON database representation (typically JSON.stringify). */
     convertJsonToDatabaseValue(value, context) {
         return JSON.stringify(value);
@@ -614,6 +624,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;
@@ -720,11 +738,51 @@ export class Platform {
     supportsDeferredUniqueConstraints() {
         return true;
     }
+    /** Whether the platform supports row level security (PostgreSQL). */
+    supportsRowLevelSecurity() {
+        return false;
+    }
+    /** Whether the driver can apply the session context on every pooled connection acquire (`sessionContext: 'connection'`). */
+    supportsConnectionSessionContext() {
+        return false;
+    }
+    /**
+     * SQL cast suffix (e.g. `'::uuid'`, or `''` when none is needed) applied when an RLS filter reads a session
+     * variable via `current_setting()` as the given column type, or `null` if the type has no automatic cast.
+     */
+    getCurrentSettingCast(mappedType) {
+        return null;
+    }
     /** Platform-specific validation of entity metadata. */
     validateMetadata(meta) {
         if (meta.partitionBy && !this.supportsPartitionedTables()) {
             throw new MetadataError(`Entity ${meta.className} uses partitionBy, but ${this.constructor.name} does not support partitioned tables`);
         }
+        const declaresRls = meta.policies.length > 0 || !!meta.rowLevelSecurity;
+        if (declaresRls && !this.supportsRowLevelSecurity()) {
+            throw MetadataError.rowLevelSecurityNotSupportedByDriver(meta);
+        }
+        // STI hierarchies share a single table, so only the root may declare policies; `root` is optional-chained
+        // as `validateMetadata` is public API and tolerates partially populated metadata
+        if (declaresRls && meta.root?.inheritanceType === 'sti' && meta.root !== meta) {
+            throw MetadataError.rowLevelSecurityOnNonRootStiEntity(meta);
+        }
+        if (meta.root?.inheritanceType === 'sti' && meta.root !== meta) {
+            for (const filter of Object.values(meta.filters)) {
+                // inherited root filters share the def object; only defs declared on the child itself are a problem,
+                // as non-root STI metas never reach the schema generator and the policy would silently not exist
+                if (filter.rls && meta.root.filters[filter.name] !== filter) {
+                    throw MetadataError.rlsFilterOnNonRootStiEntity(meta, filter.name);
+                }
+            }
+        }
+        if (!this.supportsRowLevelSecurity()) {
+            for (const filter of Object.values(meta.filters)) {
+                if (filter.rls) {
+                    throw MetadataError.rlsFilterNotSupportedByDriver(meta, filter.name);
+                }
+            }
+        }
     }
     /**
      * Generates a custom order by statement given a set of in order values, eg.

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

@@ -1,10 +1,21 @@
 import { Type } from './Type.js';
 import type { Platform } from '../platforms/Platform.js';
 import type { EntityProperty } from '../typings.js';
-/** Maps a database VARCHAR column to a JS `string`. */
-export declare class StringType extends Type<string | null | undefined, string | null | undefined> {
-    getColumnType(prop: EntityProperty, platform: Platform): string;
+export interface StringTypeOptions {
+    trim?: boolean;
+    case?: 'upper' | 'lower';
+}
+/** @internal */
+export declare abstract class BaseStringType extends Type<string | null | undefined, string | null | undefined> {
+    readonly options: StringTypeOptions;
+    constructor(options?: StringTypeOptions);
+    convertToDatabaseValue(value: string | null | undefined): string | null | undefined;
     compareAsType(): string;
     ensureComparable(): boolean;
+    private normalize;
+}
+/** Maps a database VARCHAR column to a JS `string`. */
+export declare class StringType extends BaseStringType {
+    getColumnType(prop: EntityProperty, platform: Platform): string;
     getDefaultLength(platform: Platform): number;
 }

package/types/StringType.js

@@ -1,8 +1,17 @@
 import { Type } from './Type.js';
-/** Maps a database VARCHAR column to a JS `string`. */
-export class StringType extends Type {
-    getColumnType(prop, platform) {
-        return platform.getVarcharTypeDeclarationSQL(prop);
+/** @internal */
+export class BaseStringType extends Type {
+    options;
+    constructor(options = {}) {
+        super();
+        this.options = options;
+        // a defined `compareValues` replaces the inline `!==` comparator, so only provide it when normalization is configured
+        if (options.trim || options.case) {
+            this.compareValues = (a, b) => this.normalize(a) === this.normalize(b);
+        }
+    }
+    convertToDatabaseValue(value) {
+        return this.normalize(value);
     }
     compareAsType() {
         return 'string';
@@ -10,6 +19,27 @@ export class StringType extends Type {
     ensureComparable() {
         return false;
     }
+    normalize(value) {
+        if (value == null) {
+            return value;
+        }
+        if (this.options.trim) {
+            value = value.trim();
+        }
+        if (this.options.case === 'upper') {
+            return value.toUpperCase();
+        }
+        if (this.options.case === 'lower') {
+            return value.toLowerCase();
+        }
+        return value;
+    }
+}
+/** Maps a database VARCHAR column to a JS `string`. */
+export class StringType extends BaseStringType {
+    getColumnType(prop, platform) {
+        return platform.getVarcharTypeDeclarationSQL(prop);
+    }
     getDefaultLength(platform) {
         return platform.getDefaultVarcharLength();
     }