@mikro-orm/core 7.2.0-dev.2 → 7.2.0-dev.21

package/entity/EntityLoader.js

@@ -1,5 +1,5 @@
 import { QueryHelper } from '../utils/QueryHelper.js';
-import { Utils } from '../utils/Utils.js';
+import { DANGEROUS_PROPERTY_NAMES, Utils } from '../utils/Utils.js';
 import { ValidationError } from '../errors.js';
 import { LoadStrategy, PopulatePath, ReferenceKind, } from '../enums.js';
 import { Reference } from './Reference.js';
@@ -124,10 +124,10 @@ export class EntityLoader {
     mergeNestedPopulate(populate) {
         const tmp = populate.reduce((ret, item) => {
             /* v8 ignore next */
-            if (item.field === PopulatePath.ALL) {
+            if (item.field === PopulatePath.ALL || DANGEROUS_PROPERTY_NAMES.includes(item.field)) {
                 return ret;
             }
-            if (!ret[item.field]) {
+            if (!Object.hasOwn(ret, item.field)) {
                 ret[item.field] = item;
                 return ret;
             }
@@ -229,9 +229,10 @@ export class EntityLoader {
                 }
                 toPopulate.push(entity);
             }
-            else if (refValue == null && !helper(entity).__loadedProperties.has(prop.name)) {
+            else if (refValue == null && !prop.object && !helper(entity).__loadedProperties.has(prop.name)) {
                 // FK columns weren't loaded (partial loading) — need to re-fetch them.
                 // If the property IS in __loadedProperties, the FK was loaded and is genuinely null.
+                // Object-embedded virtual props are skipped — they are populated via the embeddable instance.
                 needsFkLoad.push(entity);
             }
         }
@@ -333,7 +334,7 @@ export class EntityLoader {
         // When targetKey is set, use it for FK lookup instead of the PK
         let fk = prop.targetKey ?? Utils.getPrimaryKeyHash(meta.primaryKeys);
         let schema = options.schema;
-        const partial = !Utils.isEmpty(prop.where) || !Utils.isEmpty(options.where);
+        const partial = !Utils.isEmpty(prop.where) || !Utils.isEmpty(options.where) || !Utils.isEmpty(options.populateFilter);
         let polymorphicOwnerProp;
         const ownerProp = prop.kind === ReferenceKind.ONE_TO_MANY || (prop.kind === ReferenceKind.MANY_TO_MANY && !prop.owner)
             ? meta.properties[prop.mappedBy]
@@ -393,12 +394,20 @@ export class EntityLoader {
         if (!Utils.isEmpty(prop.where) || Raw.hasObjectFragments(prop.where)) {
             where = { $and: [where, prop.where] };
         }
+        const childFilter = options.populateFilter ? await this.extractChildPopulateFilter(options, prop) : undefined;
+        // conditions on the populated entity itself have no sink in the child query (the joined strategy puts
+        // them on the join), only the nested relation ones can be forwarded as its own `populateFilter`
+        const [ownFilter, nestedFilter] = this.splitPopulateFilter(childFilter, meta);
+        if (ownFilter) {
+            where = { $and: [where, ownFilter] };
+        }
         const orderBy = QueryHelper.mergeOrderBy(options.orderBy, prop.orderBy);
         const findOptions = {
             filters,
             convertCustomTypes,
             lockMode,
             populateWhere,
+            populateFilter: nestedFilter,
             logging,
             orderBy,
             populate: populate.children ?? populate.all ?? [],
@@ -445,7 +454,10 @@ export class EntityLoader {
                 }
             }
         }
-        if ([ReferenceKind.ONE_TO_ONE, ReferenceKind.MANY_TO_ONE].includes(prop.kind) && items.length !== children.length) {
+        // a missing target row means an orphaned reference, unless the query was narrowed by a populate condition
+        if ([ReferenceKind.ONE_TO_ONE, ReferenceKind.MANY_TO_ONE].includes(prop.kind) &&
+            items.length !== children.length &&
+            Utils.isEmpty(options.where)) {
             const nullVal = this.#em.config.get('forceUndefined') ? undefined : null;
             const itemsMap = new Set();
             const childrenMap = new Set();
@@ -571,6 +583,9 @@ export class EntityLoader {
                 filters,
                 ignoreLazyScalarProperties,
                 populateWhere,
+                populateFilter: options.populateFilter
+                    ? (await this.extractChildPopulateFilter(options, prop))
+                    : undefined,
                 connectionType,
                 logging,
                 schema,
@@ -607,7 +622,7 @@ export class EntityLoader {
         const fields = this.buildFields(options.fields, prop);
         // oxfmt-ignore
         const exclude = Array.isArray(options.exclude) ? Utils.extractChildElements(options.exclude, prop.name) : options.exclude;
-        const populateFilter = options.populateFilter?.[prop.name];
+        const populateFilter = options.populateFilter ? await this.extractChildPopulateFilter(options, prop) : undefined;
         const options2 = { ...options, fields, exclude, populateFilter };
         ['limit', 'offset', 'first', 'last', 'before', 'after', 'overfetch'].forEach(prop => delete options2[prop]);
         options2.populate = populate?.children ?? [];
@@ -620,7 +635,7 @@ export class EntityLoader {
         if (!Utils.isEmpty(prop.where)) {
             where = { $and: [where, prop.where] };
         }
-        const map = await this.#driver.loadFromPivotTable(prop, ids, where, orderBy, this.#em.getTransactionContext(), options2, pivotJoin);
+        const map = await this.#em.withSessionContext(this.#em.getTransactionContext(), ctx => this.#driver.loadFromPivotTable(prop, ids, where, orderBy, ctx, options2, pivotJoin));
         const children = [];
         const isUnionTargetMN = QueryHelper.isUnionTargetPolymorphic(prop);
         for (let i = 0; i < filtered.length; i++) {
@@ -652,7 +667,8 @@ export class EntityLoader {
     }
     async extractChildCondition(options, prop, filters = false) {
         const where = options.where;
-        const subCond = Utils.isPlainObject(where[prop.name]) ? where[prop.name] : {};
+        // shallow copy, the operator normalization below must not mutate the caller's condition
+        const subCond = Utils.isPlainObject(where[prop.name]) ? { ...where[prop.name] } : {};
         const meta2 = prop.targetMeta;
         const pk = Utils.getPrimaryKeyHash(meta2.primaryKeys);
         ['$and', '$or'].forEach(op => {
@@ -667,15 +683,16 @@ export class EntityLoader {
                     }
                     return cond;
                 });
-                if (child.length > 0) {
+                // partial extraction from `$or` is unsound — the parent may have matched via a dropped branch
+                if (child.length > 0 && (op === '$and' || child.length === where[op].length)) {
                     subCond[op] = child;
                 }
             }
         });
         const operators = Object.keys(subCond).filter(key => Utils.isOperator(key, false));
         if (operators.length > 0) {
+            subCond[pk] = Utils.isPlainObject(subCond[pk]) ? { ...subCond[pk] } : (subCond[pk] ?? {});
             operators.forEach(op => {
-                subCond[pk] ??= {};
                 subCond[pk][op] = subCond[op];
                 delete subCond[op];
             });
@@ -685,6 +702,24 @@ export class EntityLoader {
         }
         return subCond;
     }
+    /** Extracts the part of `options.populateFilter` that applies to the given relation. */
+    async extractChildPopulateFilter(options, prop) {
+        const filter = await this.extractChildCondition({ ...options, where: options.populateFilter }, prop);
+        return Utils.isEmpty(filter) ? undefined : filter;
+    }
+    /** Splits an extracted populate filter into the conditions on the populated entity and those on its own relations. */
+    splitPopulateFilter(filter, meta) {
+        if (!filter) {
+            return [undefined, undefined];
+        }
+        const own = {};
+        const nested = {};
+        for (const key of Object.keys(filter)) {
+            const target = meta.relations.some(rel => rel.name === key) ? nested : own;
+            target[key] = filter[key];
+        }
+        return [Utils.isEmpty(own) ? undefined : own, Utils.isEmpty(nested) ? undefined : nested];
+    }
     buildFields(fields = [], prop, ref) {
         if (ref) {
             fields = prop.targetMeta.primaryKeys.map(targetPkName => `${prop.name}.${targetPkName}`);

package/entity/EntityRepository.d.ts

@@ -1,5 +1,5 @@
 import type { PopulatePath } from '../enums.js';
-import type { CreateOptions, EntityManager, MergeOptions } from '../EntityManager.js';
+import type { CreateOptions, EntityManager, MapOptions, MergeOptions } from '../EntityManager.js';
 import type { AssignOptions } from './EntityAssigner.js';
 import type { Dictionary, EntityData, EntityDictionary, EntityKey, EntityName, FilterQuery, Loaded, Primary, AutoPath, RequiredEntityData, Ref, EntityType, EntityDTO, MergeSelected, FromEntityType, IsSubset, MergeLoaded, ArrayElement, IndexFilterQuery, WithUsingOptions } from '../typings.js';
 import type { CountByOptions, CountOptions, DeleteOptions, FindAllOptions, FindByCursorOptions, FindOneOptions, FindOneOrFailOptions, FindOptions, GetReferenceOptions, NativeInsertUpdateOptions, StreamOptions, UpdateOptions, UpsertManyOptions, UpsertOptions } from '../drivers/IDatabaseDriver.js';
@@ -115,11 +115,10 @@ export declare class EntityRepository<Entity extends object> {
      */
     nativeDelete(where: FilterQuery<Entity>, options?: DeleteOptions<Entity>): Promise<number>;
     /**
-     * Maps raw database result to an entity and merges it to this EntityManager.
+     * Maps raw database result to an entity and merges it to this EntityManager by default.
+     * Use `disableIdentityMap` to return an isolated entity without affecting the current context.
      */
-    map(result: EntityDictionary<Entity>, options?: {
-        schema?: string;
-    }): Entity;
+    map(result: EntityDictionary<Entity>, options?: Omit<MapOptions, 'mapped'>): Entity;
     /**
      * Gets a reference to the entity identified by the given type and alternate key property without actually loading it.
      * The key option specifies which property to use for identity map lookup instead of the primary key.

package/entity/EntityRepository.js

@@ -131,7 +131,8 @@ export class EntityRepository {
         return this.getEntityManager().nativeDelete(this.entityName, where, options);
     }
     /**
-     * Maps raw database result to an entity and merges it to this EntityManager.
+     * Maps raw database result to an entity and merges it to this EntityManager by default.
+     * Use `disableIdentityMap` to return an isolated entity without affecting the current context.
      */
     map(result, options) {
         return this.getEntityManager().map(this.entityName, result, options);
@@ -223,7 +224,11 @@ export class EntityRepository {
         }
         const entityName = entities[0].constructor.name;
         const repoType = Utils.className(this.entityName);
-        if (entityName && repoType !== entityName) {
+        // compare class identity where possible, as minifiers can mangle two classes to the same name
+        const entityMeta = entities[0].__meta;
+        const repoMeta = this.getEntityManager().getMetadata?.().find(this.entityName);
+        const mismatch = entityMeta && repoMeta ? entityMeta.class !== repoMeta.class : entityName && repoType !== entityName;
+        if (mismatch) {
             throw ValidationError.fromWrongRepositoryType(entityName, repoType, method);
         }
     }

package/entity/defineEntity.d.ts

@@ -1,6 +1,6 @@
 import type { EntityManager } from '../EntityManager.js';
 import type { ColumnType, PropertyOptions, ReferenceOptions, EnumOptions, EmbeddedOptions, ManyToOneOptions, OneToManyOptions, OneToOneOptions, ManyToManyOptions, IndexColumnOptions } from '../metadata/types.js';
-import type { AnyString, GeneratedColumnCallback, Constructor, CheckCallback, FilterQuery, EntityName, Dictionary, EntityMetadata, PrimaryKeyProp, EntityRepositoryType, Hidden, Opt, Primary, EntityClass, EntitySchemaWithMeta, InferEntity, MaybeReturnType, Ref, LazyRef, IndexCallback, TriggerCallback, FormulaCallback, EntityCtor, IsNever, IWrappedEntity, DefineConfig, Config, MaybePromise, IndexHints, ExtractDefineEntityProperties } from '../typings.js';
+import type { AnyString, GeneratedColumnCallback, Constructor, CheckCallback, FilterQuery, EntityName, Dictionary, EntityMetadata, PrimaryKeyProp, EntityRepositoryType, Hidden, Opt, Primary, EntityClass, EntitySchemaWithMeta, InferEntity, MaybeReturnType, Ref, LazyRef, IndexCallback, TriggerCallback, FormulaCallback, EntityCtor, IsNever, IWrappedEntity, DefineConfig, Config, MaybePromise, IndexHints, OptionalProps, ExtractDefineEntityProperties } from '../typings.js';
 import type { Raw } from '../utils/RawQueryFragment.js';
 import type { ScalarReference } from './Reference.js';
 import type { SerializeOptions } from '../serialization/EntitySerializer.js';
@@ -22,7 +22,7 @@ type HasKind<Options, K extends string> = Options extends {
     kind: infer X extends string;
 } ? X extends K ? true : false : false;
 /** Lightweight chain result type for property builders - reduces type instantiation cost by avoiding full class resolution. */
-export interface PropertyChain<Value, Options> {
+export interface PropertyChain<in out Value, in out Options> {
     '~type'?: {
         value: Value;
     };
@@ -112,7 +112,7 @@ export interface PropertyChain<Value, Options> {
     getter(getter?: boolean): PropertyChain<Value, Options>;
     getterName(getterName: string): PropertyChain<Value, Options>;
     serializedPrimaryKey(serializedPrimaryKey?: boolean): PropertyChain<Value, Options>;
-    serializer(serializer: (value: Value, options?: SerializeOptions<any>) => any): PropertyChain<Value, Options>;
+    serializer(serializer: (value: SerializerValue<Value, Options>, options?: SerializeOptions<any>) => any): PropertyChain<Value, Options>;
     serializedName(serializedName: string): PropertyChain<Value, Options>;
     groups(...groups: string[]): PropertyChain<Value, Options>;
     customOrder(...customOrder: string[] | number[] | boolean[]): PropertyChain<Value, Options>;
@@ -148,6 +148,8 @@ export interface PropertyChain<Value, 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;
@@ -180,7 +182,7 @@ export interface PropertyChain<Value, Options> {
     foreignKeyName(foreignKeyName: string): HasKind<Options, 'm:1' | '1:m' | '1:1' | 'm:n'> extends true ? PropertyChain<Value, Options> : never;
 }
 /** @internal */
-export declare class UniversalPropertyOptionsBuilder<Value, Options, IncludeKeys extends BuilderKeys> implements Record<Exclude<UniversalPropertyKeys, ExcludeKeys>, any> {
+export declare class UniversalPropertyOptionsBuilder<in out Value, in out Options, in out IncludeKeys extends BuilderKeys> implements Record<Exclude<UniversalPropertyKeys, ExcludeKeys>, any> {
     '~options': Options;
     '~type'?: {
         value: Value;
@@ -528,6 +530,8 @@ export declare class UniversalPropertyOptionsBuilder<Value, Options, IncludeKeys
     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. */
@@ -570,6 +574,13 @@ export declare class UniversalPropertyOptionsBuilder<Value, Options, IncludeKeys
 export interface EmptyOptions extends Partial<Record<UniversalPropertyKeys, unknown>> {
 }
 /** @internal */
+export declare class StringPropertyOptionsBuilder<Value, Options> extends UniversalPropertyOptionsBuilder<Value, Options, IncludeKeysForProperty> {
+    trim(): StringPropertyOptionsBuilder<Value, Options>;
+    lowercase(): StringPropertyOptionsBuilder<Value, Options>;
+    uppercase(): StringPropertyOptionsBuilder<Value, Options>;
+    private withOptions;
+}
+/** @internal */
 export declare class OneToManyOptionsBuilderOnlyMappedBy<Value extends object> extends UniversalPropertyOptionsBuilder<Value, EmptyOptions & {
     kind: '1:m';
 }, IncludeKeysForOneToManyOptions> {
@@ -582,7 +593,7 @@ type EntityTarget = {
     '~entity': any;
 } | EntityClass;
 declare const propertyBuilders: PropertyBuilders;
-type PropertyBuildersOverrideKeys = 'bigint' | 'array' | 'decimal' | 'json' | 'datetime' | 'time' | 'enum';
+type PropertyBuildersOverrideKeys = 'bigint' | 'array' | 'decimal' | 'json' | 'string' | 'text' | 'datetime' | 'time' | 'enum';
 /** Map of factory functions for creating type-safe property builders (scalars, enums, embeddables, and relations). */
 export type PropertyBuilders = {
     [K in Exclude<keyof typeof types, PropertyBuildersOverrideKeys>]: () => UniversalPropertyOptionsBuilder<InferPropertyValueType<(typeof types)[K]>, EmptyOptions, IncludeKeysForProperty>;
@@ -591,6 +602,8 @@ export type PropertyBuilders = {
     array: <T = string>(toJsValue?: (i: string) => T, toDbValue?: (i: T) => string) => UniversalPropertyOptionsBuilder<InferPropertyValueType<typeof types.array<T>>, EmptyOptions, IncludeKeysForProperty>;
     decimal: <Mode extends 'number' | 'string' = 'string'>(mode?: Mode) => UniversalPropertyOptionsBuilder<InferPropertyValueType<typeof types.decimal<Mode>>, EmptyOptions, IncludeKeysForProperty>;
     json: <T>() => UniversalPropertyOptionsBuilder<T, EmptyOptions, IncludeKeysForProperty>;
+    string: () => StringPropertyOptionsBuilder<InferPropertyValueType<typeof types.string>, EmptyOptions>;
+    text: () => StringPropertyOptionsBuilder<InferPropertyValueType<typeof types.text>, EmptyOptions>;
     formula: <T>(formula: string | FormulaCallback<any>) => UniversalPropertyOptionsBuilder<T, EmptyOptions, IncludeKeysForProperty>;
     datetime: (length?: number) => UniversalPropertyOptionsBuilder<InferPropertyValueType<typeof types.datetime>, EmptyOptions, IncludeKeysForProperty>;
     time: (length?: number) => UniversalPropertyOptionsBuilder<InferPropertyValueType<typeof types.time>, EmptyOptions, IncludeKeysForProperty>;
@@ -618,7 +631,7 @@ type PartialWhere<TProperties, TBase> = string | FilterQuery<{
     [K in AllKeys<TProperties, TBase> & string]?: unknown;
 }>;
 /** Metadata descriptor for `defineEntity()`, combining entity options with property definitions. */
-export interface EntityMetadataWithProperties<TName extends string, TTableName extends string, TProperties extends Record<string, any>, TPK extends (keyof TProperties)[] | undefined = undefined, TBase = never, TRepository = never, TForceObject extends boolean = false, TDiscriminatorColumn extends string | undefined = undefined, TDiscriminatorValue extends string | number | undefined = undefined, TBaseDiscriminatorColumn extends string | undefined = undefined> extends Omit<Partial<EntityMetadata<InferEntityFromProperties<TProperties, TPK, TBase, TRepository>>>, 'properties' | 'extends' | 'primaryKeys' | 'hooks' | 'discriminator' | 'discriminatorColumn' | 'discriminatorValue' | 'versionProperty' | 'concurrencyCheckKeys' | 'serializedPrimaryKey' | 'indexes' | 'uniques' | 'triggers' | 'repository' | 'filters' | 'orderBy'> {
+export interface EntityMetadataWithProperties<TName extends string, TTableName extends string, TProperties extends Record<string, any>, TPK extends (keyof TProperties)[] | undefined = undefined, TBase = never, TRepository = never, TForceObject extends boolean = false, TDiscriminatorColumn extends string | undefined = undefined, TDiscriminatorValue extends string | number | undefined = undefined, TBaseDiscriminatorColumn extends string | undefined = undefined, TEmbeddable extends boolean = false> extends Omit<Partial<EntityMetadata<InferEntityFromProperties<TProperties, TPK, TBase, TRepository>>>, 'properties' | 'extends' | 'primaryKeys' | 'hooks' | 'discriminator' | 'discriminatorColumn' | 'discriminatorValue' | 'versionProperty' | 'concurrencyCheckKeys' | 'serializedPrimaryKey' | 'indexes' | 'uniques' | 'triggers' | 'repository' | 'filters' | 'orderBy'> {
     name: TName;
     tableName?: TTableName;
     extends?: {
@@ -638,8 +651,12 @@ export interface EntityMetadataWithProperties<TName extends string, TTableName e
         entity?: EntityName<any> | EntityName<any>[];
         args?: boolean;
         strict?: boolean;
+        rls?: boolean | {
+            setting?: string;
+        };
     }>;
     forceObject?: TForceObject;
+    embeddable?: TEmbeddable;
     inheritance?: 'tpt';
     orderBy?: {
         [K in Extract<AllKeys<TProperties, TBase>, string>]?: QueryOrderKeysFlat;
@@ -690,7 +707,7 @@ export interface EntityMetadataWithProperties<TName extends string, TTableName e
     }[];
 }
 /** Defines an entity schema using property builders, with full type inference from the property definitions. */
-export declare function defineEntity<const TName extends string, const TTableName extends string, const TProperties extends Record<string, any>, const TPK extends (keyof TProperties)[] | undefined = undefined, const TBase = never, const TRepository = never, const TForceObject extends boolean = false, const TDiscriminatorColumn extends string | undefined = undefined, const TDiscriminatorValue extends string | number | undefined = undefined, const TBaseDiscriminatorColumn extends string | undefined = undefined>(meta: EntityMetadataWithProperties<TName, TTableName, TProperties, TPK, TBase, TRepository, TForceObject, TDiscriminatorColumn, TDiscriminatorValue, TBaseDiscriminatorColumn>): EntitySchemaWithMeta<TName, TTableName, InferEntityFromProperties<TProperties, TPK, TBase, TRepository, TForceObject, TBaseDiscriminatorColumn, TDiscriminatorValue>, TBase, TProperties, EntityCtor<InferEntityFromProperties<TProperties, TPK, TBase, TRepository, TForceObject, TBaseDiscriminatorColumn, TDiscriminatorValue>>, TDiscriminatorColumn>;
+export declare function defineEntity<const TName extends string, const TTableName extends string, const TProperties extends Record<string, any>, const TPK extends (keyof TProperties)[] | undefined = undefined, const TBase = never, const TRepository = never, const TForceObject extends boolean = false, const TDiscriminatorColumn extends string | undefined = undefined, const TDiscriminatorValue extends string | number | undefined = undefined, const TBaseDiscriminatorColumn extends string | undefined = undefined, const TEmbeddable extends boolean = false>(meta: EntityMetadataWithProperties<TName, TTableName, TProperties, TPK, TBase, TRepository, TForceObject, TDiscriminatorColumn, TDiscriminatorValue, TBaseDiscriminatorColumn, TEmbeddable>): EntitySchemaWithMeta<TName, TTableName, InferEntityFromProperties<TProperties, TPK, TBase, TRepository, TForceObject, TBaseDiscriminatorColumn, TDiscriminatorValue, TEmbeddable>, TBase, TProperties, EntityCtor<InferEntityFromProperties<TProperties, TPK, TBase, TRepository, TForceObject, TBaseDiscriminatorColumn, TDiscriminatorValue, TEmbeddable>>, TDiscriminatorColumn>;
 export declare namespace defineEntity {
     export { propertyBuilders as properties };
 }
@@ -725,22 +742,24 @@ type InferTypeByString<T extends string> = T extends keyof typeof types ? InferJ
 type InferJSType<T> = T extends typeof Type<infer TValue, any> ? NonNullable<TValue> : never;
 type InferColumnType<T extends string> = T extends 'int' | 'int4' | 'integer' | 'bigint' | 'int8' | 'int2' | 'tinyint' | 'smallint' | 'mediumint' ? number : T extends 'double' | 'double precision' | 'real' | 'float8' | 'decimal' | 'numeric' | 'float' | 'float4' ? number : T extends 'datetime' | 'time' | 'time with time zone' | 'timestamp' | 'timestamp with time zone' | 'timetz' | 'timestamptz' | 'date' | 'interval' ? Date : T extends 'ObjectId' | 'objectId' | 'character varying' | 'varchar' | 'char' | 'character' | 'uuid' | 'text' | 'tinytext' | 'mediumtext' | 'longtext' | 'enum' ? string : T extends 'boolean' | 'bool' | 'bit' ? boolean : T extends 'blob' | 'tinyblob' | 'mediumblob' | 'longblob' | 'bytea' ? Buffer : T extends 'point' | 'line' | 'lseg' | 'box' | 'circle' | 'path' | 'polygon' | 'geometry' ? number[] : T extends 'tsvector' | 'tsquery' ? string[] : T extends 'json' | 'jsonb' ? any : any;
 type BaseEntityMethodKeys = 'toObject' | 'toPOJO' | 'serialize' | 'assign' | 'populate' | 'init' | 'toReference';
+interface BaseEntityMethods<in out Entity extends object> extends Pick<IWrappedEntity<Entity>, BaseEntityMethodKeys> {
+}
 /** Infers the entity type from a `defineEntity()` properties map, resolving builders, base classes, and primary keys. */
-export type InferEntityFromProperties<Properties extends Record<string, any>, PK extends (keyof Properties)[] | undefined = undefined, Base = never, Repository = never, ForceObject extends boolean = false, BaseDiscriminatorColumn extends string | undefined = undefined, DiscriminatorValue extends string | number | undefined = undefined> = (IsNever<Base> extends true ? {} : Base extends {
+export type InferEntityFromProperties<Properties extends Record<string, any>, PK extends (keyof Properties)[] | undefined = undefined, Base = never, Repository = never, ForceObject extends boolean = false, BaseDiscriminatorColumn extends string | undefined = undefined, DiscriminatorValue extends string | number | undefined = undefined, Embeddable extends boolean = false> = (IsNever<Base> extends true ? {} : Base extends {
     toObject(...args: any[]): any;
-} ? Pick<IWrappedEntity<{
+} ? BaseEntityMethods<{
     -readonly [K in keyof Properties]: InferBuilderValue<MaybeReturnType<Properties[K]>>;
 } & {
     [PrimaryKeyProp]?: InferCombinedPrimaryKey<Properties, PK, Base>;
 } & (IsNever<Repository> extends true ? {} : {
     [EntityRepositoryType]?: Repository extends Constructor<infer R> ? R : Repository;
-}) & NarrowDiscriminator<Omit<Base, typeof PrimaryKeyProp>, BaseDiscriminatorColumn, DiscriminatorValue>>, BaseEntityMethodKeys> : {}) & {
+}) & NarrowDiscriminator<Omit<Base, typeof PrimaryKeyProp>, BaseDiscriminatorColumn, DiscriminatorValue, Embeddable>> : {}) & {
     -readonly [K in keyof Properties]: InferBuilderValue<MaybeReturnType<Properties[K]>>;
 } & {
     [PrimaryKeyProp]?: InferCombinedPrimaryKey<Properties, PK, Base>;
 } & (IsNever<Repository> extends true ? {} : {
     [EntityRepositoryType]?: Repository extends Constructor<infer R> ? R : Repository;
-}) & (IsNever<Base> extends true ? {} : NarrowDiscriminator<Omit<Base, typeof PrimaryKeyProp>, BaseDiscriminatorColumn, DiscriminatorValue>) & (ForceObject extends true ? {
+}) & (IsNever<Base> extends true ? {} : NarrowDiscriminator<Omit<Base, typeof PrimaryKeyProp>, BaseDiscriminatorColumn, DiscriminatorValue, Embeddable>) & (ForceObject extends true ? {
     [Config]?: DefineConfig<{
         forceObject: true;
     }>;
@@ -748,13 +767,26 @@ export type InferEntityFromProperties<Properties extends Record<string, any>, PK
     [IndexHints]?: [Omit<ExtractBaseProperties<Base>, keyof Properties> & Properties];
 };
 type ExtractBaseProperties<Base> = [ExtractDefineEntityProperties<Base>] extends [infer P extends Record<string, any>] ? [P] extends [never] ? {} : P : {};
-type NarrowDiscriminator<Base, DiscColumn extends string | undefined, DiscValue> = DiscColumn extends string ? DiscColumn extends keyof Base ? DiscValue extends string | number ? Omit<Base, DiscColumn> & {
+type ExtractOptionalProps<Base> = Base extends {
+    [OptionalProps]?: infer K;
+} ? (K extends string ? K : never) : never;
+type NarrowDiscriminator<Base, DiscColumn extends string | undefined, DiscValue, Embeddable extends boolean = false> = DiscColumn extends string ? DiscColumn extends keyof Base ? DiscValue extends string | number ? Embeddable extends true ? Omit<Base, DiscColumn> & {
+    [K in DiscColumn]: DiscValue;
+} : Omit<Base, DiscColumn | typeof OptionalProps> & {
     [K in DiscColumn]: DiscValue;
+} & {
+    [OptionalProps]?: DiscColumn | ExtractOptionalProps<Base>;
 } : Base : Base : Base;
 type InferCombinedPrimaryKey<Properties extends Record<string, any>, PK, Base> = PK extends undefined ? CombinePrimaryKeys<InferPrimaryKey<Properties>, ExtractBasePrimaryKey<Base>> : PK;
-type ExtractBasePrimaryKey<Base> = Base extends {
+type ExtractBasePrimaryKey<Base> = typeof PrimaryKeyProp extends keyof Base ? Base extends {
     [PrimaryKeyProp]?: infer BasePK;
-} ? BasePK : never;
+} ? BasePK : never : [keyof Base] extends [never] ? never : Base extends {
+    _id?: any;
+} ? '_id' : Base extends {
+    id?: any;
+} ? 'id' : Base extends {
+    uuid?: any;
+} ? 'uuid' : never;
 type CombinePrimaryKeys<ChildPK, BasePK> = [ChildPK] extends [never] ? BasePK : [BasePK] extends [never] ? IsUnion<ChildPK> extends true ? ChildPK[] : ChildPK : ChildPK | BasePK;
 /** Extracts the primary key property names from a properties map by finding builders with `primary: true`. */
 export type InferPrimaryKey<Properties extends Record<string, any>> = {
@@ -781,6 +813,8 @@ type InferBuilderValue<Builder> = Builder extends {
 type MaybeArray<Value, Options> = Options extends {
     array: true;
 } ? Value[] : Value;
+/** The runtime value passed to a custom serializer — the property value as stored on the entity (e.g. `Collection`/`Ref` for relations). Skips `MaybeMapToPk`, as its `Primary<Value>` branch is too costly for the type checker. */
+type SerializerValue<Value, Options> = MaybeNullable<MaybeRelationRef<MaybeArray<Value, Options>, Options>, Options>;
 type MaybeMapToPk<Value, Options> = Options extends {
     mapToPk: true;
 } ? Primary<Value> : Value;

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 });
@@ -472,10 +476,31 @@ export class UniversalPropertyOptionsBuilder {
     }
 }
 /** @internal */
+export class StringPropertyOptionsBuilder extends UniversalPropertyOptionsBuilder {
+    trim() {
+        return this.withOptions({ trim: true });
+    }
+    lowercase() {
+        return this.withOptions({ case: 'lower' });
+    }
+    uppercase() {
+        return this.withOptions({ case: 'upper' });
+    }
+    withOptions(options) {
+        const type = this['~options'].type;
+        const TypeClass = typeof type === 'function' ? type : type.constructor;
+        const currentOptions = typeof type === 'function' ? {} : type.options;
+        return new StringPropertyOptionsBuilder({
+            ...this['~options'],
+            type: new TypeClass({ ...currentOptions, ...options }),
+        });
+    }
+}
+/** @internal */
 export class OneToManyOptionsBuilderOnlyMappedBy extends UniversalPropertyOptionsBuilder {
     /** Point to the owning side property name. */
     mappedBy(mappedBy) {
-        return new UniversalPropertyOptionsBuilder({ ...this['~options'], mappedBy });
+        return this.assignOptions({ mappedBy });
     }
 }
 function createPropertyBuilders(options) {
@@ -487,6 +512,12 @@ const propertyBuilders = {
     array: (toJsValue = i => i, toDbValue = i => i) => new UniversalPropertyOptionsBuilder({ type: new types.array(toJsValue, toDbValue) }),
     decimal: (mode) => new UniversalPropertyOptionsBuilder({ type: new types.decimal(mode) }),
     json: () => new UniversalPropertyOptionsBuilder({ type: types.json }),
+    string: () => new StringPropertyOptionsBuilder({
+        type: types.string,
+    }),
+    text: () => new StringPropertyOptionsBuilder({
+        type: types.text,
+    }),
     formula: (formula) => new UniversalPropertyOptionsBuilder({ formula }),
     datetime: (length) => new UniversalPropertyOptionsBuilder({ type: types.datetime, length }),
     time: (length) => new UniversalPropertyOptionsBuilder({ type: types.time, length }),

package/enums.d.ts

@@ -1,4 +1,4 @@
-import type { EntityKey, ExpandProperty } from './typings.js';
+import type { EntityKey, ExpandProperty, SessionContext } from './typings.js';
 import type { InflightQueryAbortStrategy, Transaction } from './connections/Connection.js';
 import type { LogContext } from './logging/Logger.js';
 /** Controls when the `EntityManager` flushes pending changes to the database. */
@@ -39,6 +39,8 @@ export declare enum QueryOperator {
     $in = "in",
     /** Not included in the given list. */
     $nin = "not in",
+    /** Contains all of the given values, supported on collection properties and on mongo arrays. */
+    $all = "all",
     /** Greater than. */
     $gt = ">",
     /** Greater than or equal to. */
@@ -307,6 +309,8 @@ export interface TransactionOptions {
     flushMode?: FlushMode | `${FlushMode}`;
     ignoreNestedTransactions?: boolean;
     loggerContext?: LogContext;
+    /** @internal database session context applied on `begin()` (set via `em.setSessionContext()`). */
+    sessionContext?: SessionContext;
     /**
      * `AbortSignal` cancelling every query within the transaction (including the implicit flush).
      * Cancelling mid-transaction triggers a rollback once the in-flight query settles.

package/enums.js

@@ -41,6 +41,8 @@ export var QueryOperator;
     QueryOperator["$in"] = "in";
     /** Not included in the given list. */
     QueryOperator["$nin"] = "not in";
+    /** Contains all of the given values, supported on collection properties and on mongo arrays. */
+    QueryOperator["$all"] = "all";
     /** Greater than. */
     QueryOperator["$gt"] = ">";
     /** Greater than or equal to. */

package/errors.d.ts

@@ -25,6 +25,13 @@ export declare class ValidationError<T extends AnyEntity = AnyEntity> extends Er
     static invalidCompositeIdentifier(meta: EntityMetadata): ValidationError;
     static cannotCommit(): ValidationError;
     static cannotUseGlobalContext(): ValidationError;
+    static sessionContextNotSupported(): ValidationError;
+    static sessionContextRequiresImplicitTransactions(): ValidationError;
+    static sessionContextWithDisabledTransactions(): ValidationError;
+    static sessionContextInsideTransaction(action?: 'set' | 'clear'): ValidationError;
+    static cannotStageNonScalarSessionVariable(filterName: string, argName: string): ValidationError;
+    static sessionContextStreamRequiresTransaction(): ValidationError;
+    static connectionSessionContextNotSupported(): ValidationError;
     static cannotUseOperatorsInsideEmbeddables(entityName: EntityName, propName: string, payload: unknown): ValidationError;
     static cannotUseGroupOperatorsInsideScalars(entityName: EntityName, propName: string, payload: unknown): ValidationError;
     static invalidEmbeddableQuery(entityName: EntityName, propName: string, embeddableType: string): ValidationError;
@@ -34,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> {
@@ -60,11 +68,15 @@ export declare class MetadataError<T extends AnyEntity = AnyEntity> extends Vali
     static duplicateFieldName(entityName: EntityName, names: [string, string][]): MetadataError;
     static multipleDecorators(entityName: string, propertyName: string): MetadataError;
     static missingMetadata(entity: string): MetadataError;
+    static ambiguousEntityName(className: string): MetadataError;
     static invalidPrimaryKey(meta: EntityMetadata, prop: EntityProperty, requiredName: string): MetadataError;
     static invalidManyToManyWithPivotEntity(meta1: EntityMetadata, prop1: EntityProperty, meta2: EntityMetadata, prop2: EntityProperty): MetadataError;
     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;
@@ -76,6 +88,30 @@ export declare class MetadataError<T extends AnyEntity = AnyEntity> extends Vali
     static tptNotSupportedByDriver(meta: EntityMetadata): MetadataError;
     /** Thrown when database triggers are defined on an entity using a driver that does not support them. */
     static triggersNotSupportedByDriver(meta: EntityMetadata): MetadataError;
+    /** Thrown when row level security is declared on an entity using a driver that does not support it. */
+    static rowLevelSecurityNotSupportedByDriver(meta: EntityMetadata): MetadataError;
+    /** Thrown when row level security is declared on a non-root entity of an STI hierarchy. */
+    static rowLevelSecurityOnNonRootStiEntity(meta: EntityMetadata): MetadataError;
+    /** Thrown when two policies on the same entity are given the same explicit name. */
+    static duplicatePolicyName(meta: EntityMetadata, name: string): MetadataError;
+    /** Thrown when a filter flagged with `rls` is declared on a driver that does not support row level security. */
+    static rlsFilterNotSupportedByDriver(meta: EntityMetadata, filterName: string): MetadataError;
+    /** Thrown when a filter flagged with `rls` is declared on a non-root entity of an STI hierarchy. */
+    static rlsFilterOnNonRootStiEntity(meta: EntityMetadata, filterName: string): MetadataError;
+    /** Thrown when a global (config or EM registered) filter is flagged with `rls`; RLS filters must be entity scoped. */
+    static rlsFilterMustBeEntityScoped(filterName: string): MetadataError;
+    /** Thrown when an entity-scoped `rls` filter is registered at runtime via `em.addFilter()` instead of in metadata. */
+    static rlsFilterCannotBeRegisteredAtRuntime(filterName: string): MetadataError;
+    /** Thrown when a filter's custom `setting` is used with more than one argument. */
+    static rlsFilterMultiArgSetting(filterName: string, args: string[]): MetadataError;
+    /** Thrown when an `rls` filter's condition depends on runtime state and cannot be compiled to a static policy. */
+    static rlsFilterDependsOnRuntimeState(filterName: string): MetadataError;
+    /** Thrown when an `rls` filter compares against a column whose type has no automatic session-variable cast. */
+    static rlsFilterUncastableType(filterName: string, columnType: string): MetadataError;
+    /** Thrown when an `rls` filter references an argument outside of a direct comparison, which cannot be compiled. */
+    static rlsFilterUnsupportedCond(filterName: string): MetadataError;
+    /** Thrown when an `rls` filter compares against a column the schema generator does not manage. */
+    static rlsFilterUnmanagedColumn(filterName: string, column: string): MetadataError;
     private static fromMessage;
 }
 /** Error thrown when an entity lookup fails to find the expected result. */