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

package/metadata/types.d.ts

@@ -1,9 +1,52 @@
-import type { AnyEntity, Constructor, EntityName, AnyString, CheckCallback, GeneratedColumnCallback, FormulaCallback, FilterQuery, Dictionary, AutoPath, EntityClass, IndexCallback, ObjectQuery, Raw } from '../typings.js';
+import type { AnyEntity, Constructor, EntityName, AnyString, CheckCallback, GeneratedColumnCallback, FormulaCallback, FilterQuery, Dictionary, AutoPath, EntityClass, IndexCallback, ObjectQuery, Raw, SchemaColumns, TriggerDef } 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';
 import type { FilterOptions, FindOptions } from '../drivers/IDatabaseDriver.js';
 import type { SerializeOptions } from '../serialization/EntitySerializer.js';
+/** Supported PostgreSQL partitioning strategies. */
+export type EntityPartitionType = 'hash' | 'list' | 'range';
+/**
+ * Partition key expression for PostgreSQL partitioned tables.
+ *
+ * You can use:
+ * - a property name, e.g. `'type'`
+ * - a list of property names for composite expressions, e.g. `['tenant', 'createdAt']`
+ * - a raw SQL expression string, e.g. `"date_trunc('month', created_at)"`
+ * - a callback that receives schema column mappings and returns SQL
+ */
+export type EntityPartitionExpression<E = AnyEntity> = (keyof E & string) | readonly (keyof E & string)[] | AnyString | ((columns: SchemaColumns<E>) => string);
+/** Explicit child partition definition for PostgreSQL `list` and `range` partitioning. */
+export interface EntityPartition<E = AnyEntity> {
+    /**
+     * Optional child table name. Defaults to `<tableName>_<index>`. A single `.` is treated as a
+     * `schema.table` separator; names with more than one `.` are rejected to avoid ambiguity.
+     */
+    name?: string;
+    /** Partition bound clause, either as `for values ...` or the trailing part such as `in (...)`, `from ... to ...`, or `default`. */
+    values: string;
+}
+/**
+ * PostgreSQL table partitioning definition.
+ *
+ * - `hash` partitions generate child tables automatically from the partition count
+ * - `list` and `range` partitions require explicit child partition definitions
+ */
+export type EntityPartitionBy<E = AnyEntity> = {
+    type: Extract<EntityPartitionType, 'hash'>;
+    expression: EntityPartitionExpression<E>;
+    /**
+     * Hash partition fan-out: either a number (auto-named as `${tableName}_N`) or an array of
+     * explicit partition names in remainder order. Names may be `schema.name` to create the
+     * child in a non-default schema.
+     */
+    partitions: number | readonly string[];
+} | {
+    type: Exclude<EntityPartitionType, 'hash'>;
+    expression: EntityPartitionExpression<E>;
+    /** Explicit child partitions created in the order provided. */
+    partitions: EntityPartition<E>[];
+};
 export type EntityOptions<T, E = T extends EntityClass<infer P> ? P : T> = {
     /** Override default collection/table name. Alias for `collection`. */
     tableName?: string;
@@ -57,6 +100,15 @@ export type EntityOptions<T, E = T extends EntityClass<infer P> ? P : T> = {
     };
     /** Used to make ORM aware of externally defined triggers. This is needed for MS SQL Server multi inserts, ignored in other dialects. */
     hasTriggers?: boolean;
+    /** Database triggers to create for this entity's table. (SQL drivers only) */
+    triggers?: TriggerDef<E>[];
+    /**
+     * PostgreSQL partitioning definition for this table.
+     *
+     * Partitioned tables are tracked by the schema generator and introspected back from PostgreSQL.
+     * Changing an existing partition layout still requires a manual migration.
+     */
+    partitionBy?: EntityPartitionBy<E>;
     /** SQL query that maps to a {@doclink virtual-entities | virtual entity}, or for view entities, the view definition. */
     expression?: string | ((em: any, where: ObjectQuery<E>, options: FindOptions<E, any, any, any>, stream?: boolean) => object);
     /** Set {@doclink repositories#custom-repository | custom repository class}. */
@@ -202,6 +254,12 @@ export interface PropertyOptions<Owner> {
      * @see https://mikro-orm.io/docs/defining-entities#lazy-scalar-properties
      */
     lazy?: boolean;
+    /**
+     * Marks this property as an array. When used with a custom type, the type is automatically
+     * wrapped in an `ArrayType` that delegates element conversion to the inner type.
+     * The column type is inferred as `innerType[]` (e.g. `int[]`, `time[]`).
+     */
+    array?: boolean;
     /**
      * Set true to define entity's unique primary key identifier.
      * Alias for `@PrimaryKey()` decorator
@@ -334,7 +392,7 @@ export interface PropertyOptions<Owner> {
 }
 export interface ReferenceOptions<Owner, Target> extends PropertyOptions<Owner> {
     /** Set target entity type. For polymorphic relations, pass an array of entity types. */
-    entity?: () => EntityName<Target> | EntityName<Target>[];
+    entity?: () => EntityName<Target> | EntityName[];
     /** Set what actions on owning entity should be cascaded to the relationship. Defaults to [Cascade.PERSIST, Cascade.MERGE] (see {@doclink cascading}). */
     cascade?: Cascade[];
     /** Always load the relationship. Discouraged for use with to-many relations for performance reasons. */
@@ -499,7 +557,7 @@ export interface EmbeddableOptions<Owner> {
     abstract?: boolean;
 }
 export interface EnumOptions<T> extends PropertyOptions<T> {
-    items?: readonly (number | string)[] | (() => Dictionary);
+    items?: readonly (number | string)[] | Dictionary | (() => Dictionary);
     array?: boolean;
     /** for postgres, by default it uses text column with check constraint */
     nativeEnumName?: string;
@@ -543,6 +601,16 @@ interface BaseOptions<T, H extends string> {
     include?: T extends EntityClass<infer P> ? Properties<P, H> : Properties<T, H>;
     /** Fill factor for the index as a percentage 0-100 (PostgreSQL, MSSQL). */
     fillFactor?: number;
+    /**
+     * Predicate for partial indexes. Object form is a `FilterQuery` and is portable across
+     * SQL drivers and MongoDB; string form is a raw SQL fragment (SQL drivers only).
+     *
+     * Native support: PostgreSQL, SQLite, MSSQL (`WHERE`), MongoDB (`partialFilterExpression`).
+     * MySQL 8.0.13+ / Oracle: emulated via `CASE WHEN` functional index (uniqueness only enforced
+     * where the predicate holds). MariaDB is not supported — it has no inline expression indexes;
+     * define a virtual generated column and index that instead.
+     */
+    where?: string | FilterQuery<NoInfer<T> extends EntityClass<infer P> ? P : NoInfer<T>>;
 }
 export interface UniqueOptions<T, H extends string = string> extends BaseOptions<T, H> {
     deferMode?: DeferMode | `${DeferMode}`;

package/naming-strategy/AbstractNamingStrategy.d.ts

@@ -4,7 +4,7 @@ import { type ReferenceKind } from '../enums.js';
 export declare abstract class AbstractNamingStrategy implements NamingStrategy {
     getClassName(file: string, separator?: string): string;
     classToMigrationName(timestamp: string, customMigrationName?: string): string;
-    indexName(tableName: string, columns: string[], type: 'primary' | 'foreign' | 'unique' | 'index' | 'sequence' | 'check' | 'default'): string;
+    indexName(tableName: string, columns: string[], type: 'primary' | 'foreign' | 'unique' | 'index' | 'sequence' | 'check' | 'default' | 'trigger'): string;
     /**
      * @inheritDoc
      */

package/naming-strategy/NamingStrategy.d.ts

@@ -75,7 +75,7 @@ export interface NamingStrategy {
     /**
      * Returns key/constraint name for the given type. Some drivers might not support all the types (e.g. mysql and sqlite enforce the PK name).
      */
-    indexName(tableName: string, columns: string[], type: 'primary' | 'foreign' | 'unique' | 'index' | 'sequence' | 'check' | 'default'): string;
+    indexName(tableName: string, columns: string[], type: 'primary' | 'foreign' | 'unique' | 'index' | 'sequence' | 'check' | 'default' | 'trigger'): string;
     /**
      * Returns alias name for given entity. The alias needs to be unique across the query, which is by default
      * ensured via appended index parameter. It is optional to use it as long as you ensure it will be unique.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mikro-orm/core",
-  "version": "7.1.0-dev.2",
+  "version": "7.1.0-dev.21",
   "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

@@ -43,6 +43,8 @@ export declare abstract class Platform {
     getEnumArrayCheckConstraintExpression(column: string, items: string[]): string | null;
     /** Whether this platform supports materialized views. */
     supportsMaterializedViews(): boolean;
+    /** Whether this platform supports declarative table partitioning in schema generation. */
+    supportsPartitionedTables(): boolean;
     /** Returns the schema helper instance for this platform, or undefined if not supported. */
     getSchemaHelper(): unknown;
     /** Whether the platform automatically creates indexes on foreign key columns. */
@@ -168,7 +170,7 @@ export declare abstract class Platform {
     getUuidTypeDeclarationSQL(column: {
         length?: number;
     }): string;
-    /** Extracts the base type name from a full SQL type declaration (e.g. "varchar(255)" -> "varchar"). */
+    /** Extracts the base type name from a full SQL type declaration (e.g. `varchar(255)` -> `varchar`). */
     extractSimpleType(type: string): string;
     /**
      * This should be used only to compare types, it can strip some information like the length.
@@ -211,6 +213,11 @@ export declare abstract class Platform {
     getFullTextWhereClause(prop: EntityProperty): string;
     supportsCreatingFullTextIndex(): boolean;
     getFullTextIndexExpression(indexName: string, schemaName: string | undefined, tableName: string, columns: SimpleColumnMeta[]): string;
+    /**
+     * Generates the SQL index hint clause for the given index names.
+     * Returns `undefined` when the platform does not support index hints (e.g. PostgreSQL, SQLite).
+     */
+    formatIndexHint(indexNames: string[]): string | undefined;
     /** Whether the driver automatically parses JSON columns into JS objects. */
     convertsJsonAutomatically(): boolean;
     /** Converts a JS value to its JSON database representation (typically JSON.stringify). */

package/platforms/Platform.js

@@ -2,12 +2,22 @@ import { clone } from '../utils/clone.js';
 import { EntityRepository } from '../entity/EntityRepository.js';
 import { UnderscoreNamingStrategy } from '../naming-strategy/UnderscoreNamingStrategy.js';
 import { ExceptionConverter } from './ExceptionConverter.js';
+import { MetadataError } from '../errors.js';
 import { ArrayType, BigIntType, BlobType, BooleanType, CharacterType, DateTimeType, DateType, DecimalType, DoubleType, EnumType, FloatType, IntegerType, IntervalType, JsonType, MediumIntType, SmallIntType, StringType, TextType, TimeType, TinyIntType, Type, Uint8ArrayType, UnknownType, UuidType, } from '../types/index.js';
 import { parseJsonSafe, Utils } from '../utils/Utils.js';
 import { ReferenceKind } from '../enums.js';
 import { Raw } from '../utils/RawQueryFragment.js';
 /** Symbol used to tag cloned embeddable data for JSON serialization handling. */
 export const JsonProperty = Symbol('JsonProperty');
+const MULTI_WORD_SQL_TYPES = [
+    'timestamp with time zone',
+    'timestamp without time zone',
+    'time with time zone',
+    'time without time zone',
+    'character varying',
+    'double precision',
+    'bit varying',
+];
 /** Abstract base class providing database-specific behavior and SQL dialect differences. */
 export class Platform {
     exceptionConverter = new ExceptionConverter();
@@ -62,6 +72,10 @@ export class Platform {
     supportsMaterializedViews() {
         return false;
     }
+    /** Whether this platform supports declarative table partitioning in schema generation. */
+    supportsPartitionedTables() {
+        return false;
+    }
     /** Returns the schema helper instance for this platform, or undefined if not supported. */
     getSchemaHelper() {
         return undefined;
@@ -222,9 +236,15 @@ export class Platform {
         column.length ??= 36;
         return this.getVarcharTypeDeclarationSQL(column);
     }
-    /** Extracts the base type name from a full SQL type declaration (e.g. "varchar(255)" -> "varchar"). */
+    /** Extracts the base type name from a full SQL type declaration (e.g. `varchar(255)` -> `varchar`). */
     extractSimpleType(type) {
-        return /[^(), ]+/.exec(type.toLowerCase())[0];
+        const lower = type.toLowerCase();
+        for (const multiWord of MULTI_WORD_SQL_TYPES) {
+            if (lower.startsWith(multiWord)) {
+                return multiWord;
+            }
+        }
+        return /[^(), ]+/.exec(lower)[0];
     }
     /**
      * This should be used only to compare types, it can strip some information like the length.
@@ -248,6 +268,7 @@ export class Platform {
                 return Type.getType(CharacterType);
             case 'string':
             case 'varchar':
+            case 'character varying':
                 return Type.getType(StringType);
             case 'interval':
                 return Type.getType(IntervalType);
@@ -267,6 +288,7 @@ export class Platform {
             case 'float':
                 return Type.getType(FloatType);
             case 'double':
+            case 'double precision':
                 return Type.getType(DoubleType);
             case 'integer':
                 return Type.getType(IntegerType);
@@ -286,8 +308,12 @@ export class Platform {
                 return Type.getType(DateType);
             case 'datetime':
             case 'timestamp':
+            case 'timestamp with time zone':
+            case 'timestamp without time zone':
                 return Type.getType(DateTimeType);
             case 'time':
+            case 'time with time zone':
+            case 'time without time zone':
                 return Type.getType(TimeType);
             case 'object':
             case 'json':
@@ -415,6 +441,13 @@ export class Platform {
     getFullTextIndexExpression(indexName, schemaName, tableName, columns) {
         throw new Error('Full text searching is not supported by this driver.');
     }
+    /**
+     * Generates the SQL index hint clause for the given index names.
+     * Returns `undefined` when the platform does not support index hints (e.g. PostgreSQL, SQLite).
+     */
+    formatIndexHint(indexNames) {
+        return undefined;
+    }
     /** Whether the driver automatically parses JSON columns into JS objects. */
     convertsJsonAutomatically() {
         return true;
@@ -651,7 +684,9 @@ export class Platform {
     }
     /** Platform-specific validation of entity metadata. */
     validateMetadata(meta) {
-        return;
+        if (meta.partitionBy && !this.supportsPartitionedTables()) {
+            throw new MetadataError(`Entity ${meta.className} uses partitionBy, but ${this.constructor.name} does not support partitioned tables`);
+        }
     }
     /**
      * Generates a custom order by statement given a set of in order values, eg.

package/typings.d.ts

@@ -11,7 +11,7 @@ import type { SerializationContext } from './serialization/SerializationContext.
 import type { SerializeOptions } from './serialization/EntitySerializer.js';
 import type { MetadataStorage } from './metadata/MetadataStorage.js';
 import type { EntitySchema } from './metadata/EntitySchema.js';
-import type { IndexColumnOptions } from './metadata/types.js';
+import type { EntityPartitionBy, IndexColumnOptions } from './metadata/types.js';
 import type { Type, types } from './types/index.js';
 import type { Platform } from './platforms/Platform.js';
 import type { Configuration } from './utils/Configuration.js';
@@ -47,7 +47,7 @@ export type AsyncFunction<R = any, T = Dictionary> = (args: T) => Promise<T>;
 export type Compute<T> = {
     [K in keyof T]: T[K];
 } & {};
-type InternalKeys = 'EntityRepositoryType' | 'PrimaryKeyProp' | 'OptionalProps' | 'EagerProps' | 'HiddenProps' | '__selectedType' | '__loadedType';
+type InternalKeys = 'EntityRepositoryType' | 'PrimaryKeyProp' | 'OptionalProps' | 'EagerProps' | 'HiddenProps' | 'IndexHints' | '__selectedType' | '__loadedType';
 /** Filters out function, symbol, and internal keys from an entity type. When `B = true`, also excludes scalar keys. */
 export type CleanKeys<T, K extends keyof T, B extends boolean = false> = T[K] & {} extends Function ? never : K extends symbol | InternalKeys ? never : B extends true ? T[K] & {} extends Scalar ? never : K : K;
 /** Extracts keys of `T` whose values are functions. */
@@ -113,7 +113,7 @@ type LoadedReferenceShape<T = any> = ReferenceShape & {
  * Using this instead of `Loadable<any>` in conditional type checks prevents
  * TypeScript from evaluating the full Collection/Reference interfaces.
  */
-type LoadableShape = CollectionShape | ReferenceShape | readonly any[];
+type LoadableShape = CollectionShape | ReferenceShape | LazyRef.Brand<any> | readonly any[];
 /** Gets all keys from all members of a union type (distributes over the union). */
 export type UnionKeys<T> = T extends any ? keyof T : never;
 /** Gets the type of a property from all union members that have it (distributes over the union). */
@@ -150,6 +150,44 @@ export declare const EntityName: unique symbol;
 export type InferEntityName<T> = T extends {
     [EntityName]?: infer Name;
 } ? (Name extends string ? Name : never) : never;
+/**
+ * Symbol used to declare index-to-column mappings on an entity type.
+ * For decorator entities, declare as a phantom property:
+ * ```typescript
+ * [IndexHints]?: { idx_email: 'email'; idx_name_age: 'name' | 'age' };
+ * ```
+ * For `defineEntity` entities, index hints are inferred automatically from
+ * named indexes (property-level `.index('name')` and entity-level `indexes`/`uniques`).
+ */
+export declare const IndexHints: unique symbol;
+/**
+ * Extracts the index hints map from an entity type. Returns `never` when no hints are declared.
+ * For decorator entities, `[IndexHints]` contains a pre-computed `{ idxName: 'prop' }` map.
+ * For `defineEntity` entities, `[IndexHints]` contains `[Properties]` (a tuple wrapping the
+ * raw property builders), which is lazily converted to the index map when first accessed.
+ */
+export type ExtractIndexHints<T> = T extends {
+    [IndexHints]?: infer H;
+} ? H extends [infer P extends Record<string, any>] ? InferPropertyIndexMap<P> : H : never;
+/**
+ * Extracts `{ indexName: propertyKey }` from property builder options.
+ * Checks `.index('name')` and `.unique('name')` on each property in a single pass.
+ */
+export type InferPropertyIndexMap<Properties extends Record<string, any>> = {
+    [K in keyof Properties as MaybeReturnType<Properties[K]> extends {
+        '~options': {
+            index: infer N extends string;
+        };
+    } ? N : MaybeReturnType<Properties[K]> extends {
+        '~options': {
+            unique: infer N extends string;
+        };
+    } ? N : never]: K & string;
+};
+/** Union of declared index names on an entity. Falls back to `string` when no `[IndexHints]` are declared. */
+export type IndexName<T> = [ExtractIndexHints<T>] extends [never] ? string : (keyof ExtractIndexHints<T> & string) | (string & {});
+/** Properties covered by the named index on entity T. Falls back to all entity keys when the index is unknown. */
+export type IndexColumns<T, Name extends string> = ExtractIndexHints<T> extends Record<Name, infer Cols> ? Cols & string : EntityKey<T>;
 /**
  * Branded type that marks a property as optional in `em.create()`.
  * Use as a property type wrapper: `createdAt: Opt<Date>` instead of listing in `[OptionalProps]`.
@@ -328,6 +366,18 @@ export type ObjectQuery<T> = OperatorMap<T> & FilterObject<T>;
  * Accepts an object query, a primary key value, entity props with operators, or an array of filters.
  */
 export type FilterQuery<T> = ObjectQuery<T> | NonNullable<ExpandScalar<Primary<T>>> | NonNullable<EntityProps<T> & OperatorMap<T>> | FilterQuery<T>[];
+/**
+ * `FilterQuery` restricted to only properties covered by the specified index(es).
+ * Used when `using` option is set in `FindOptions` to enforce type-safe index usage.
+ */
+export type IndexFilterQuery<T, Using extends string> = [Using] extends [never] ? FilterQuery<T> : (OperatorMap<T> & {
+    -readonly [K in Extract<EntityKey<T>, IndexColumns<T, Using>>]?: ExpandQuery<ExpandProperty<FilterObjectProp<T, K>>> | ExpandQueryMerged<ExpandProperty<FilterObjectProp<T, K>>> | FilterValue<ExpandProperty<FilterObjectProp<T, K>>> | ElemMatchFilter<FilterObjectProp<T, K>> | null;
+}) | NonNullable<ExpandScalar<Primary<T>>> | IndexFilterQuery<T, Using>[];
+/** Replaces `where` and `using` on an options type with index-aware variants when `Using` is specified. */
+export type WithUsingOptions<Opts, Entity, Using extends string> = Omit<Opts, 'where' | 'using'> & {
+    using?: Using | Using[];
+    where?: [Using] extends [never] ? FilterQuery<Entity> : IndexFilterQuery<Entity, Using>;
+};
 /** Public interface for the entity wrapper, accessible via `wrap(entity)`. Provides helper methods for entity state management. */
 export interface IWrappedEntity<Entity extends object> {
     isInitialized(): boolean;
@@ -417,12 +467,12 @@ type NonArrayObject = object & {
 export type EntityDataProp<T, C extends boolean> = T extends Date ? string | Date : T extends Scalar ? T : T extends ScalarReference<infer U> ? EntityDataProp<U, C> : T extends {
     __runtime?: infer Runtime;
     __raw?: infer Raw;
-} ? C extends true ? Raw : Runtime : T extends ReferenceShape<infer U> ? EntityDataNested<U, C> : T extends CollectionShape<infer U> ? U | U[] | EntityDataNested<U & object, C> | EntityDataNested<U & object, C>[] : T extends readonly (infer U)[] ? U extends NonArrayObject ? U | U[] | EntityDataNested<U, C> | EntityDataNested<U, C>[] : U[] | EntityDataNested<U, C>[] : EntityDataNested<T, C>;
+} ? C extends true ? Raw : Runtime : T extends LazyRef.Brand<infer U> ? EntityDataNested<U, C> : T extends ReferenceShape<infer U> ? EntityDataNested<U, C> : T extends CollectionShape<infer U> ? U | U[] | EntityDataNested<U & object, C> | EntityDataNested<U & object, C>[] : T extends readonly (infer U)[] ? U extends NonArrayObject ? U | U[] | EntityDataNested<U, C> | EntityDataNested<U, C>[] : U[] | EntityDataNested<U, C>[] : EntityDataNested<T, C>;
 /** Like `EntityDataProp` but used in `RequiredEntityData` context with required/optional key distinction. */
 export type RequiredEntityDataProp<T, O, C extends boolean> = T extends Date ? string | Date : Exclude<T, null> extends RequiredNullable.Brand ? T | null : T extends Scalar ? T : T extends ScalarReference<infer U> ? RequiredEntityDataProp<U, O, C> : T extends {
     __runtime?: infer Runtime;
     __raw?: infer Raw;
-} ? C extends true ? Raw : Runtime : T extends ReferenceShape<infer U> ? RequiredEntityDataNested<U, O, C> : T extends CollectionShape<infer U> ? U | U[] | RequiredEntityDataNested<U & object, O, C> | RequiredEntityDataNested<U & object, O, C>[] : T extends readonly (infer U)[] ? U extends NonArrayObject ? U | U[] | RequiredEntityDataNested<U, O, C> | RequiredEntityDataNested<U, O, C>[] : U[] | RequiredEntityDataNested<U, O, C>[] : RequiredEntityDataNested<T, O, C>;
+} ? C extends true ? Raw : Runtime : T extends LazyRef.Brand<infer U> ? RequiredEntityDataNested<U, O, C> : T extends ReferenceShape<infer U> ? RequiredEntityDataNested<U, O, C> : T extends CollectionShape<infer U> ? U | U[] | RequiredEntityDataNested<U & object, O, C> | RequiredEntityDataNested<U & object, O, C>[] : T extends readonly (infer U)[] ? U extends NonArrayObject ? U | U[] | RequiredEntityDataNested<U, O, C> | RequiredEntityDataNested<U, O, C>[] : U[] | RequiredEntityDataNested<U, O, C>[] : RequiredEntityDataNested<T, O, C>;
 /** Nested entity data shape for embedded or related entities within `EntityData`. */
 export type EntityDataNested<T, C extends boolean = false> = T extends undefined ? never : T extends any[] ? Readonly<T> : EntityData<T, C> | ExpandEntityProp<T, C>;
 type UnwrapScalarRef<T> = T extends ScalarReference<infer U> ? U : T;
@@ -471,6 +521,35 @@ type Relation<T> = {
 export type Rel<T> = T;
 /** Alias for `ScalarReference` (see {@apilink Ref}). */
 export type ScalarRef<T> = ScalarReference<T>;
+/**
+ * Type-level marker for a to-one relation that is **direct at runtime** (no `Reference` wrapper) but
+ * **restricted at compile time** until narrowed via `Loaded<>`.
+ *
+ * Use as the property type on a `@ManyToOne`/`@OneToOne` relation that does **not** have `ref: true`:
+ *
+ * ```ts
+ * @ManyToOne(() => User)
+ * author!: LazyRef<User>;
+ * ```
+ *
+ * Semantics:
+ * - **Runtime**: identical to a plain direct relation — `article.author` is a `User` instance (stub or hydrated),
+ *   `article.author instanceof User` is `true`, no `Reference` object is created.
+ * - **Type (unloaded view)**: only the primary key is accessible. Accessing other properties is a compile error.
+ * - **Type (loaded view)**: once the relation is in the populate hint of a `Loaded<Entity, 'author'>`, it narrows
+ *   back to the full entity — no `.$` or `.get()` indirection needed.
+ *
+ * Note: the safety is purely compile-time. JS code or `as any` casts bypass it.
+ */
+export type LazyRef<T extends object> = IsAny<T> extends true ? LazyRef.Brand<T> : {
+    [K in PrimaryProperty<T> & keyof T]: T[K];
+} & LazyRef.Brand<T>;
+export declare namespace LazyRef {
+    const __lazyRef: unique symbol;
+    interface Brand<T> {
+        [__lazyRef]?: (arg: T) => T;
+    }
+}
 /** Alias for `Reference<T> & { id: number }` (see {@apilink Ref}). */
 export type EntityRef<T extends object> = true extends IsUnknown<PrimaryProperty<T>> ? Reference<T> : IsAny<T> extends true ? Reference<T> : {
     [K in PrimaryProperty<T> & keyof T]: T[K];
@@ -606,6 +685,8 @@ export type IndexCallback<T> = (columns: Record<PropertyName<T>, string>, table:
 export type FormulaCallback<T> = (columns: FormulaColumns<T>, table: FormulaTable) => string | Raw;
 /** Callback for CHECK constraint expressions. Receives column mappings and table info. */
 export type CheckCallback<T> = (columns: Record<PropertyName<T>, string>, table: SchemaTable) => string | Raw;
+/** Callback for trigger body expressions. Receives column mappings and table info. */
+export type TriggerCallback<T> = (columns: Record<PropertyName<T>, string>, table: SchemaTable) => string | Raw;
 /** Callback for generated (computed) column expressions. Receives column mappings and table info. */
 export type GeneratedColumnCallback<T> = (columns: Record<PropertyName<T>, string>, table: SchemaTable) => string | Raw;
 /** Definition of a CHECK constraint on a table or property. */
@@ -614,6 +695,23 @@ export interface CheckConstraint<T = any> {
     property?: string;
     expression: string | Raw | CheckCallback<T>;
 }
+/** Definition of a database trigger on a table. */
+export interface TriggerDef<T = any> {
+    /** Trigger name. Auto-generated if omitted. */
+    name?: string;
+    /** When the trigger fires relative to the event. */
+    timing: 'before' | 'after' | 'instead of';
+    /** Which DML events activate the trigger. */
+    events: ('insert' | 'update' | 'delete' | 'truncate')[];
+    /** Whether the trigger fires once per row or per statement. Defaults to `'row'`. */
+    forEach?: 'row' | 'statement';
+    /** SQL body of the trigger. Can be a string, Raw query, or callback receiving column name mappings. */
+    body?: string | Raw | TriggerCallback<T>;
+    /** Optional SQL WHEN condition for the trigger. */
+    when?: string;
+    /** Raw DDL escape hatch — full CREATE TRIGGER statement. Mutually exclusive with `body`. */
+    expression?: string;
+}
 /** Branded string that accepts any string value while preserving autocompletion for known literals. */
 export type AnyString = string & {};
 /** Describes a single property (column, relation, or embedded) within an entity's metadata. */
@@ -776,6 +874,8 @@ export interface EntityMetadata<Entity = any, Class extends EntityCtor<Entity> =
     materialized?: boolean;
     /** For materialized views, whether data is populated on creation. Defaults to true. */
     withData?: boolean;
+    /** PostgreSQL partitioning definition for this table. */
+    partitionBy?: EntityPartitionBy<Entity>;
     expression?: string | ((em: any, where: ObjectQuery<Entity>, options: FindOptions<Entity, any, any, any>, stream?: boolean) => MaybePromise<Raw | object | string>);
     discriminatorColumn?: EntityKey<Entity> | AnyString;
     discriminatorValue?: number | string;
@@ -814,6 +914,7 @@ export interface EntityMetadata<Entity = any, Class extends EntityCtor<Entity> =
         type?: string;
         options?: Dictionary;
         expression?: string | IndexCallback<Entity>;
+        where?: string | FilterQuery<Entity>;
         columns?: IndexColumnOptions[];
         include?: EntityKey<Entity> | EntityKey<Entity>[];
         fillFactor?: number;
@@ -826,6 +927,7 @@ export interface EntityMetadata<Entity = any, Class extends EntityCtor<Entity> =
         name?: string;
         options?: Dictionary;
         expression?: string | IndexCallback<Entity>;
+        where?: string | FilterQuery<Entity>;
         deferMode?: DeferMode | `${DeferMode}`;
         columns?: IndexColumnOptions[];
         include?: EntityKey<Entity> | EntityKey<Entity>[];
@@ -833,6 +935,7 @@ export interface EntityMetadata<Entity = any, Class extends EntityCtor<Entity> =
         disabled?: boolean;
     }[];
     checks: CheckConstraint<Entity>[];
+    triggers: TriggerDef<Entity>[];
     repositoryClass?: string;
     repository: () => EntityClass<EntityRepository<any>>;
     hooks: {
@@ -853,6 +956,8 @@ export interface EntityMetadata<Entity = any, Class extends EntityCtor<Entity> =
     polymorphicDiscriminatorMap?: Dictionary<EntityClass>;
     /** Inheritance type: 'sti' (Single Table Inheritance) or 'tpt' (Table-Per-Type). Only set on root entities. */
     inheritanceType?: 'sti' | 'tpt';
+    /** Legacy alias populated from `EntityOptions.inheritance`; mirrored to `inheritanceType` during discovery. */
+    inheritance?: 'tpt';
     /** For TPT: direct parent entity metadata (the entity this one extends). */
     tptParent?: EntityMetadata;
     /** For TPT: direct child entities (entities that extend this one). */
@@ -1060,6 +1165,11 @@ export interface IMigrator {
      * Executes down migrations to the given point. Without parameter it will migrate one version down.
      */
     down(options?: string | string[] | Omit<MigrateOptions, 'from'>): Promise<MigrationInfo[]>;
+    /**
+     * Combines multiple executed migrations into a single migration file.
+     * Concatenates source code without touching the database schema.
+     */
+    rollup(migrations?: string[]): Promise<MigrationResult>;
     /**
      * Registers event handler.
      */
@@ -1142,13 +1252,32 @@ export type PopulateOptions<T> = {
     children?: PopulateOptions<T[keyof T]>[];
     /** When true, ignores `mapToPk` on the property and returns full entity data instead of just PKs. */
     dataOnly?: boolean;
+    /** Limit the number of items loaded per parent entity. Collections will be marked as partial and readonly. */
+    limit?: number;
+    /** Offset for per-parent limiting (used with `limit`). */
+    offset?: number;
+    /** Order by clause for per-parent limiting. Takes precedence over nested `FindOptions.orderBy`. */
+    orderBy?: QueryOrderMap<T[keyof T]>;
 };
 /** Inline options that can be appended to populate hint strings (e.g., strategy, join type). */
 export type PopulateHintOptions = {
     strategy?: LoadStrategy.JOINED | LoadStrategy.SELECT_IN | 'joined' | 'select-in';
     joinType?: 'inner join' | 'left join';
+    /** Limit the number of items loaded per parent entity. Collections will be marked as partial and readonly. */
+    limit?: number;
+    /** Offset for per-parent limiting (used with `limit`). */
+    offset?: number;
+    /** Order by clause for per-parent limiting. Takes precedence over nested `FindOptions.orderBy`. */
+    orderBy?: QueryOrderMap<any>;
 };
 type ExtractType<T> = T extends CollectionShape<infer U> ? U : T extends ReferenceShape<infer U> ? U : T extends Ref<infer U> ? U : T extends readonly (infer U)[] ? U : T;
+/**
+ * Like {@link ExtractType} but also unwraps {@link LazyRef}. Kept separate so {@link ExtractType}'s
+ * hot path (used by `IsOptional`, `EntityData`, `RequiredEntityData`) doesn't pay the cost of the
+ * extra branch — those contexts handle `LazyRef` in their own earlier branches (see
+ * `EntityDataProp` / `RequiredEntityDataProp`) before delegating to `ExtractType`.
+ */
+type ExtractTypeWithLazyRef<T> = T extends LazyRef.Brand<infer U> ? U : ExtractType<T>;
 type ExtractStringKeys<T> = {
     [K in keyof T]-?: CleanKeys<T, K>;
 }[keyof T] & {};
@@ -1156,8 +1285,8 @@ type ExtractStringKeys<T> = {
  * Extracts string keys from an entity type, handling Collection/Reference wrappers.
  * Simplified to just check `T extends object` since ExtractType handles the unwrapping.
  */
-type StringKeys<T, E extends string = never> = T extends object ? ExtractStringKeys<ExtractType<T>> | E : never;
-type GetStringKey<T, K extends StringKeys<T, string>, E extends string> = K extends keyof T ? ExtractType<T[K]> : K extends E ? keyof T : never;
+type StringKeys<T, E extends string = never> = T extends object ? ExtractStringKeys<ExtractTypeWithLazyRef<T>> | E : never;
+type GetStringKey<T, K extends StringKeys<T, string>, E extends string> = K extends keyof T ? ExtractTypeWithLazyRef<T[K]> : K extends E ? keyof T : never;
 type Prev = [never, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9];
 type RelationKeys<T> = T extends object ? {
     [K in keyof T]-?: CleanKeys<T, K, true>;
@@ -1172,8 +1301,8 @@ export type UnboxArray<T> = T extends any[] ? ArrayElement<T> : T;
 /** Extracts the element type from an array type. */
 export type ArrayElement<ArrayType extends unknown[]> = ArrayType extends (infer ElementType)[] ? ElementType : never;
 /** Unwraps a property type from its wrapper (Reference, Collection, or array) to the inner entity type. */
-export type ExpandProperty<T> = T extends ReferenceShape<infer U> ? NonNullable<U> : T extends CollectionShape<infer U> ? NonNullable<U> : T extends (infer U)[] ? NonNullable<U> : NonNullable<T>;
-type LoadedLoadable<T, E extends object> = T extends CollectionShape ? LoadedCollection<E> : T extends ScalarReference<infer U> ? LoadedScalarReference<U> : T extends ReferenceShape ? T & LoadedReference<E> : T extends Scalar ? T : T extends (infer U)[] ? U extends Scalar ? T : E[] : E;
+export type ExpandProperty<T> = T extends LazyRef.Brand<infer U> ? NonNullable<U> : T extends ReferenceShape<infer U> ? NonNullable<U> : T extends CollectionShape<infer U> ? NonNullable<U> : T extends (infer U)[] ? NonNullable<U> : NonNullable<T>;
+type LoadedLoadable<T, E extends object> = T extends CollectionShape ? LoadedCollection<E> : T extends ScalarReference<infer U> ? LoadedScalarReference<U> : T extends LazyRef.Brand<any> ? E : T extends ReferenceShape ? T & LoadedReference<E> : T extends Scalar ? T : T extends (infer U)[] ? U extends Scalar ? T : E[] : E;
 type IsTrue<T> = IsNever<T> extends true ? false : T extends boolean ? (T extends true ? true : false) : false;
 type StringLiteral<T> = T extends string ? (string extends T ? never : T) : never;
 type Prefix<T, K> = K extends `${infer S}.${string}` ? S : K extends '*' ? keyof T : K;
@@ -1207,7 +1336,7 @@ export type MergeSelected<T, U, F extends string> = IsLoadedType<T> extends true
 export type MergeLoaded<T, U, P extends string, F extends string, E extends string, R extends boolean = false> = IsLoadedType<T> extends true ? T & Loaded<U, P, F, E> : Loaded<T, P, F, E>;
 /** Extracts the nullability modifiers (`null`, `undefined`, or both) from a type `T`. */
 export type AddOptional<T> = undefined | null extends T ? null | undefined : null extends T ? null : undefined extends T ? undefined : never;
-type LoadedProp<T, L extends string = never, F extends string = '*', E extends string = never> = LoadedLoadable<T, Loaded<ExtractType<T>, L, F, E>>;
+type LoadedProp<T, L extends string = never, F extends string = '*', E extends string = never> = LoadedLoadable<T, Loaded<ExtractTypeWithLazyRef<T>, L, F, E>>;
 /** Extracts the eager-loaded property names declared via `[EagerProps]` as a string union. */
 export type AddEager<T> = ExtractEagerProps<T> & string;
 /** Combines an explicit populate hint `L` with the entity's eagerly loaded properties. */

package/typings.js

@@ -4,7 +4,6 @@ import { EntityHelper } from './entity/EntityHelper.js';
 import { helper } from './entity/wrap.js';
 import { Utils } from './utils/Utils.js';
 import { EntityComparator } from './utils/EntityComparator.js';
-import { BaseEntity } from './entity/BaseEntity.js';
 /** Symbol used to declare a custom repository type on an entity class (e.g., `[EntityRepositoryType]?: BookRepository`). */
 export const EntityRepositoryType = Symbol('EntityRepositoryType');
 /** Symbol used to declare the primary key property name(s) on an entity (e.g., `[PrimaryKeyProp]?: 'id'`). */
@@ -22,6 +21,16 @@ export const Config = Symbol('Config');
 /** Symbol used to declare the entity name as a string literal type (used by `defineEntity`). */
 // eslint-disable-next-line @typescript-eslint/no-redeclare
 export const EntityName = Symbol('EntityName');
+/**
+ * Symbol used to declare index-to-column mappings on an entity type.
+ * For decorator entities, declare as a phantom property:
+ * ```typescript
+ * [IndexHints]?: { idx_email: 'email'; idx_name_age: 'name' | 'age' };
+ * ```
+ * For `defineEntity` entities, index hints are inferred automatically from
+ * named indexes (property-level `.index('name')` and entity-level `indexes`/`uniques`).
+ */
+export const IndexHints = Symbol('IndexHints');
 /**
  * Runtime metadata for an entity, holding its properties, relations, indexes, hooks, and more.
  * Created during metadata discovery and used throughout the ORM lifecycle.
@@ -39,12 +48,20 @@ export class EntityMetadata {
         this.indexes = [];
         this.uniques = [];
         this.checks = [];
+        this.triggers = [];
         this.referencingProperties = [];
         this.concurrencyCheckKeys = new Set();
         Object.assign(this, meta);
         const name = meta.className ?? meta.name;
         if (!this.class && name) {
-            const Class = this.extends === BaseEntity ? { [name]: class extends BaseEntity {
+            let Parent;
+            if (typeof this.extends === 'function') {
+                Parent = this.extends;
+            }
+            else if (this.extends != null && typeof this.extends.class === 'function') {
+                Parent = this.extends.class;
+            }
+            const Class = Parent ? { [name]: class extends Parent {
                 } }[name] : { [name]: class {
                 } }[name];
             this.class = Class;
@@ -244,8 +261,8 @@ export class EntityMetadata {
         }, { __gettersDefined: { value: true, enumerable: false } });
     }
     initIndexes(prop) {
-        const simpleIndex = this.indexes.find(index => index.properties === prop.name && !index.options && !index.type && !index.expression);
-        const simpleUnique = this.uniques.find(index => index.properties === prop.name && !index.options);
+        const simpleIndex = this.indexes.find(index => index.properties === prop.name && !index.options && !index.type && !index.expression && index.where == null);
+        const simpleUnique = this.uniques.find(index => index.properties === prop.name && !index.options && !index.expression && index.where == null);
         const owner = prop.kind === ReferenceKind.MANY_TO_ONE;
         if (!prop.index && simpleIndex) {
             Utils.defaultValue(simpleIndex, 'name', true);