@tstdl/base 0.93.87 → 0.93.90

package/orm/server/repository.js

@@ -4,58 +4,91 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
-import { and, asc, count, desc, eq, inArray, isNull as isSqlNull, isSQLWrapper, lte, or, SQL, sql } from 'drizzle-orm';
+import { and, asc, count, desc, eq, getTableName, inArray, isNull as isSqlNull, isSQLWrapper, lte, or, SQL, sql } from 'drizzle-orm';
 import { match, P } from 'ts-pattern';
 import { CancellationSignal } from '../../cancellation/token.js';
 import { NotFoundError } from '../../errors/not-found.error.js';
 import { Singleton } from '../../injector/decorators.js';
 import { inject, injectArgument } from '../../injector/inject.js';
 import { afterResolve, resolveArgumentType } from '../../injector/interfaces.js';
+import { reflectionRegistry } from '../../reflection/index.js';
 import { distinct, toArray } from '../../utils/array/array.js';
 import { mapAsync } from '../../utils/async-iterable-helpers/map.js';
 import { toArrayAsync } from '../../utils/async-iterable-helpers/to-array.js';
 import { importSymmetricKey } from '../../utils/cryptography.js';
-import { assignDeep, fromEntries, objectEntries } from '../../utils/object/object.js';
+import { assignDeep, fromEntries, objectEntries, objectKeys } from '../../utils/object/object.js';
 import { toSnakeCase } from '../../utils/string/index.js';
 import { cancelableTimeout } from '../../utils/timing.js';
 import { tryIgnoreAsync } from '../../utils/try-ignore.js';
-import { assertDefined, assertDefinedPass, isArray, isBoolean, isDefined, isFunction, isInstanceOf, isString, isUndefined } from '../../utils/type-guards.js';
+import { assertDefined, assertDefinedPass, isArray, isBoolean, isDefined, isFunction, isInstanceOf, isNullOrUndefined, isString, isUndefined } from '../../utils/type-guards.js';
 import { typeExtends } from '../../utils/type/index.js';
 import { millisecondsPerSecond } from '../../utils/units.js';
 import { Entity } from '../entity.js';
 import { distance, isSimilar, isStrictWordSimilar, isWordSimilar, TRANSACTION_TIMESTAMP, tsHeadline, tsRankCd } from '../sqls/index.js';
-import { getColumnDefinitions, getColumnDefinitionsMap, getDrizzleTableFromType } from './drizzle/schema-converter.js';
+import { getInheritanceMetadata, isChildEntity } from '../utils.js';
+import { getColumnDefinitions, getColumnDefinitionsMap, getDrizzleTableFromType, getTableColumnDefinitions, isTableOwning } from './drizzle/schema-converter.js';
 import { convertQuery, getTsQuery, getTsVector, resolveTargetColumn } from './query-converter.js';
+import { EntityRepositoryConfig } from './repository-config.js';
 import { ENCRYPTION_SECRET } from './tokens.js';
-import { getTransactionalContextData, injectTransactional, injectTransactionalAsync, isInTransactionalContext, Transactional } from './transactional.js';
+import { injectTransactional, injectTransactionalAsync, isInTransactionalContext, Transactional, tryGetTransactionalContextData } from './transactional.js';
 const searchScoreColumn = '__tsl_score';
 const searchDistanceColumn = '__tsl_distance';
 const searchHighlightColumn = '__tsl_highlight';
 const searchHighlightPositionsColumn = '__tsl_highlight_positions';
 export const repositoryType = Symbol('repositoryType');
-/**
- * Configuration class for EntityRepository.
- * Specifies the database schema to be used.
- */
-export class EntityRepositoryConfig {
-    /** The name of the database schema. */
-    schema;
-}
 const entityTypeToken = Symbol('EntityType');
 let EntityRepository = class EntityRepository extends Transactional {
-    #context = isInTransactionalContext() ? getTransactionalContextData(this) : {};
+    #context = (isInTransactionalContext() ? tryGetTransactionalContextData(this) : undefined) ?? {};
     #encryptionSecret = isInTransactionalContext() ? this.#context.encryptionSecret : inject(ENCRYPTION_SECRET, undefined, { optional: true });
     #cancellationSignal = isInTransactionalContext() ? undefined : inject(CancellationSignal);
     #transformContext = this.#context.transformContext;
-    type = this.#context.type ?? injectArgument(this, { optional: true }) ?? assertDefinedPass(this.constructor[entityTypeToken], 'Missing entity type.');
+    type = assertDefinedPass(this.#context.type ?? this.constructor[entityTypeToken] ?? injectArgument(this, { optional: true }), 'Missing entity type.');
     typeName = this.type.entityName ?? this.type.name;
-    #table = this.#context.table ?? getDrizzleTableFromType(this.type, inject(EntityRepositoryConfig, undefined, { optional: true })?.schema);
-    #tableWithMetadata = this.#table;
+    #schema = inject(EntityRepositoryConfig, undefined, { optional: true })?.schema;
+    #table = this.#context.table ?? getDrizzleTableFromType(this.type, this.#schema);
+    #tableColumnDefinitions = getTableColumnDefinitions(this.#table);
+    #isChild = isChildEntity(this.type);
+    #tablesChain = this.getTablesChain(this.type);
+    #baseTableInfo = this.#tablesChain[0];
+    #baseTable = this.#baseTableInfo.table;
+    #baseTableWithMetadata = this.#baseTable;
     #columnDefinitions = this.#context.columnDefinitions ?? getColumnDefinitions(this.#table);
     #columnDefinitionsMap = this.#context.columnDefinitionsMap ?? getColumnDefinitionsMap(this.#table);
-    #upsertManyExcludedMapping = fromEntries(this.#columnDefinitions
+    #joinedTables = this.#tablesChain.filter((info) => info.table != this.#table).map((info) => info.table);
+    #inheritanceMetadata = getInheritanceMetadata(this.type);
+    #subclasses = this.#inheritanceMetadata?.subclasses ?? [];
+    #subclassTablesInfo = this.#subclasses.map((subclass) => {
+        const table = getDrizzleTableFromType(subclass, this.#schema);
+        const tablesChain = this.getTablesChain(subclass);
+        return {
+            type: subclass,
+            table,
+            tablesChain,
+            columnDefinitions: getColumnDefinitions(table),
+            discriminatorValue: reflectionRegistry.getMetadata(subclass)?.data.tryGet('orm')?.childEntity?.discriminatorValue, // eslint-disable-line @typescript-eslint/no-non-null-asserted-optional-chain
+        };
+    });
+    #discriminatorInfo = (() => {
+        if (!this.#isChild) {
+            return undefined;
+        }
+        const inheritanceMetadata = getInheritanceMetadata(this.#baseTableInfo.type);
+        const childEntityMetadata = reflectionRegistry.getMetadata(this.type)?.data.tryGet('orm')?.childEntity;
+        if (isDefined(inheritanceMetadata) && isDefined(childEntityMetadata) && isString(inheritanceMetadata.discriminatorColumn)) {
+            return {
+                columnName: inheritanceMetadata.discriminatorColumn,
+                value: childEntityMetadata.discriminatorValue,
+            };
+        }
+        return undefined;
+    })();
+    #defaultSelection = fromEntries(this.#columnDefinitions.map((column) => [column.name, this.resolveTargetColumn(column)]));
+    #upsertManyExcludedMapping = fromEntries(this.#tableColumnDefinitions
         .filter((column) => column.name != this.#table.id.name)
         .map((column) => [column.name, sql `excluded.${sql.identifier(this.getColumn(column).name)}`]));
+    #expirationColumns = this.#columnDefinitions.filter((column) => isDefined(column.reflectionData?.expirationField));
+    #softExpirationColumns = this.#expirationColumns.filter((column) => column.reflectionData.expirationField.mode == 'soft');
+    #hardExpirationColumns = this.#expirationColumns.filter((column) => column.reflectionData.expirationField.mode == 'hard');
     hasMetadata = typeExtends(this.type, Entity);
     /**
      * Gets the Drizzle table definition for the entity type.
@@ -68,23 +101,30 @@ let EntityRepository = class EntityRepository extends Transactional {
             void this.expirationLoop();
         }
     }
+    /**
+     * Processes expired entities (soft or hard delete) based on metadata.
+     * Exposed primarily for testing, but can be used in other scenarios as needed.
+     */
+    async processExpirations() {
+        if (this.#expirationColumns.length == 0) {
+            return;
+        }
+        const softDeletionQuery = or(...this.#softExpirationColumns.map((column) => lte(sql `${this.resolveTargetColumn(column)} + INTERVAL '${sql.raw(String(column.reflectionData.expirationField.after))} ms'`, TRANSACTION_TIMESTAMP)));
+        const hardDeletionQuery = or(...this.#hardExpirationColumns.map((column) => lte(sql `${this.resolveTargetColumn(column)} + INTERVAL '${sql.raw(String(column.reflectionData.expirationField.after))} ms'`, TRANSACTION_TIMESTAMP)));
+        if (isDefined(softDeletionQuery)) {
+            await tryIgnoreAsync(async () => await this.deleteManyByQuery(softDeletionQuery));
+        }
+        if (isDefined(hardDeletionQuery)) {
+            await tryIgnoreAsync(async () => await this.hardDeleteManyByQuery(hardDeletionQuery));
+        }
+    }
     async expirationLoop() {
-        const expirationColumns = this.#columnDefinitions.filter((column) => isDefined(column.reflectionData?.expirationField));
-        const softExpirationColumns = expirationColumns.filter((column) => column.reflectionData.expirationField.mode == 'soft');
-        const hardExpirationColumns = expirationColumns.filter((column) => column.reflectionData.expirationField.mode == 'hard');
-        if ((softExpirationColumns.length + hardExpirationColumns.length) == 0) {
+        if (this.#expirationColumns.length == 0) {
             return;
         }
-        const softDeletionQuery = or(...softExpirationColumns.map((column) => lte(sql `${this.resolveTargetColumn(column)} + INTERVAL '${sql.raw(String(column.reflectionData.expirationField.after))} ms'`, TRANSACTION_TIMESTAMP)));
-        const hardDeletionQuery = or(...hardExpirationColumns.map((column) => lte(sql `${this.resolveTargetColumn(column)} + INTERVAL '${sql.raw(String(column.reflectionData.expirationField.after))} ms'`, TRANSACTION_TIMESTAMP)));
         assertDefined(this.#cancellationSignal);
         while (this.#cancellationSignal.isUnset) {
-            if (isDefined(softDeletionQuery)) {
-                await tryIgnoreAsync(async () => await this.deleteManyByQuery(softDeletionQuery));
-            }
-            if (isDefined(hardDeletionQuery)) {
-                await tryIgnoreAsync(async () => await this.hardDeleteManyByQuery(hardDeletionQuery));
-            }
+            await this.processExpirations();
             await cancelableTimeout(30 * millisecondsPerSecond, this.#cancellationSignal);
         }
     }
@@ -114,9 +154,9 @@ let EntityRepository = class EntityRepository extends Transactional {
         const rawScore = (scoreOption != false) ? tsRankCd(tsvector, tsquery, isBoolean(rank) ? undefined : rank) : undefined;
         const score = (isFunction(scoreOption) ? scoreOption(rawScore) : rawScore)?.as(searchScoreColumn);
         const vectorClause = sql `${tsvector} @@ ${tsquery}`;
-        const selection = fromEntries(this.#columnDefinitions.map((column) => [column.name, this.resolveTargetColumn(column)]));
+        const extraSelection = {};
         if (isDefined(score)) {
-            selection[searchScoreColumn] = score;
+            extraSelection[searchScoreColumn] = score;
         }
         if (isDefined(highlight)) {
             const { source, ...headlineOptions } = (isString(highlight) || isInstanceOf(highlight, SQL))
@@ -125,19 +165,14 @@ let EntityRepository = class EntityRepository extends Transactional {
             const document = match(source)
                 .with(P.instanceOf(SQL), (s) => s)
                 .otherwise((paths) => {
-                const columns = this.getColumns(paths);
+                const columns = this.getColumns(toArray(paths));
                 return sql.join(columns, sql ` || ' ' || `);
             });
-            selection[searchHighlightColumn] = tsHeadline(languageSql, document, tsquery, headlineOptions).as(searchHighlightColumn);
+            extraSelection[searchHighlightColumn] = tsHeadline(languageSql, document, tsquery, headlineOptions).as(searchHighlightColumn);
         }
-        const whereClause = isDefined(filter)
-            ? and(this.convertQuery(filter), vectorClause)
-            : vectorClause;
-        let dbQuery = this
-            .applySelect(this.session, selection, options.distinct)
-            .from(this.#table)
-            .where(whereClause)
-            .$dynamic();
+        const whereClause = and(this.convertQuery(filter ?? {}), vectorClause);
+        let dbQuery = this.createBaseQuery(options, extraSelection);
+        dbQuery = dbQuery.where(whereClause);
         if (isDefined(options.offset)) {
             dbQuery = dbQuery.offset(options.offset);
         }
@@ -160,7 +195,7 @@ let EntityRepository = class EntityRepository extends Transactional {
         }
         dbQuery = dbQuery.orderBy(...orderByExpressions);
         const rows = await dbQuery;
-        return await this._mapSearchResults(rows);
+        return await this._mapSearchResults(rows, undefined, { includeSubclasses: options.includeSubclasses });
     }
     async trigramSearch(options) {
         const { query: { $trigram: trigramOptions }, rank, filter } = options;
@@ -177,17 +212,13 @@ let EntityRepository = class EntityRepository extends Transactional {
             : isSimilar(query, searchExpression);
         const distanceColumn = distance(query, searchExpression).as(searchDistanceColumn);
         const score = sql `1 - ${distance(query, searchExpression)}`.as(searchScoreColumn);
-        const selection = fromEntries(this.#columnDefinitions.map((column) => [column.name, this.resolveTargetColumn(column)]));
-        selection[searchDistanceColumn] = distanceColumn;
-        selection[searchScoreColumn] = score;
-        const whereClause = isDefined(filter)
-            ? and(this.convertQuery(filter), trigramClause)
-            : trigramClause;
-        let dbQuery = this
-            .applySelect(this.session, selection, options.distinct)
-            .from(this.#table)
-            .where(whereClause)
-            .$dynamic();
+        const extraSelection = {
+            [searchDistanceColumn]: distanceColumn,
+            [searchScoreColumn]: score,
+        };
+        const whereClause = and(this.convertQuery(filter ?? {}), trigramClause);
+        let dbQuery = this.createBaseQuery(options, extraSelection);
+        dbQuery = dbQuery.where(whereClause);
         if (isDefined(options.offset)) {
             dbQuery = dbQuery.offset(options.offset);
         }
@@ -204,18 +235,18 @@ let EntityRepository = class EntityRepository extends Transactional {
         }
         dbQuery = dbQuery.orderBy(...orderByExpressions);
         const rows = await dbQuery;
-        return await this._mapSearchResults(rows, (rawDistance) => 1 - rawDistance);
+        return await this._mapSearchResults(rows, (rawDistance) => 1 - rawDistance, { includeSubclasses: options.includeSubclasses });
     }
     async paradeDbSearch(options) {
         const { query, score: scoreOption = true, highlight, filter } = options;
         const keyField = this.#table.id;
         const paradeNativeQuery = this.convertQuery(query);
-        const selection = fromEntries(this.#columnDefinitions.map((column) => [column.name, this.resolveTargetColumn(column)]));
+        const extraSelection = {};
         let score;
         if (scoreOption) {
             const rawScore = sql `pdb.score(${keyField})`;
             score = (isFunction(scoreOption) ? scoreOption(rawScore) : rawScore).as(searchScoreColumn);
-            selection[searchScoreColumn] = score;
+            extraSelection[searchScoreColumn] = score;
         }
         if (isDefined(highlight)) {
             const { source, includePositions, ...highlightOptionsAny } = (isString(highlight) || isInstanceOf(highlight, SQL))
@@ -229,19 +260,16 @@ let EntityRepository = class EntityRepository extends Transactional {
                 .map(([key, value]) => sql `${sql.raw(toSnakeCase(key))} => ${sql `${value}`}`);
             const snippetParameters = sql.join([sourceSql, ...highlightParts], sql.raw(', '));
             const highlightSql = sql `pdb.${sql.raw(functionName)}(${snippetParameters})`;
-            selection[searchHighlightColumn] = highlightSql.as(searchHighlightColumn);
+            extraSelection[searchHighlightColumn] = highlightSql.as(searchHighlightColumn);
             if (includePositions == true) {
-                selection[searchHighlightPositionsColumn] = sql `array_to_json(pdb.snippet_positions(${sourceSql}))`.as(searchHighlightPositionsColumn);
+                extraSelection[searchHighlightPositionsColumn] = sql `array_to_json(pdb.snippet_positions(${sourceSql}))`.as(searchHighlightPositionsColumn);
             }
         }
         const whereClause = isDefined(filter)
             ? and(this.convertQuery(filter), paradeNativeQuery)
             : paradeNativeQuery;
-        let dbQuery = this
-            .applySelect(this.session, selection, options.distinct)
-            .from(this.#table)
-            .where(whereClause)
-            .$dynamic();
+        let dbQuery = this.createBaseQuery(options, extraSelection);
+        dbQuery = dbQuery.where(whereClause);
         if (isDefined(options.offset)) {
             dbQuery = dbQuery.offset(options.offset);
         }
@@ -264,7 +292,7 @@ let EntityRepository = class EntityRepository extends Transactional {
         }
         dbQuery = dbQuery.orderBy(...orderByExpressions);
         const rows = await dbQuery;
-        return await this._mapSearchResults(rows);
+        return await this._mapSearchResults(rows, undefined, { includeSubclasses: options.includeSubclasses });
     }
     /**
      * Performs a full-text search and returns entities ranked by relevance.
@@ -283,11 +311,12 @@ let EntityRepository = class EntityRepository extends Transactional {
      * Loads a single entity by its ID.
      * Throws `NotFoundError` if the entity is not found.
      * @param id The ID of the entity to load.
+     * @param options Optional loading options (e.g., withDeleted).
      * @returns A promise that resolves to the loaded entity.
      * @throws {NotFoundError} If the entity with the given ID is not found.
      */
-    async load(id) {
-        const entity = await this.tryLoad(id);
+    async load(id, options) {
+        const entity = await this.tryLoad(id, options);
         if (isUndefined(entity)) {
             throw new NotFoundError(`${this.typeName} ${id} not found.`);
         }
@@ -297,10 +326,11 @@ let EntityRepository = class EntityRepository extends Transactional {
      * Tries to load a single entity by its ID.
      * Returns `undefined` if the entity is not found.
      * @param id The ID of the entity to load.
+     * @param options Optional loading options (e.g., withDeleted).
      * @returns A promise that resolves to the loaded entity or `undefined` if not found.
      */
-    async tryLoad(id) {
-        return await this.tryLoadByQuery(eq(this.#table.id, id));
+    async tryLoad(id, options) {
+        return await this.tryLoadByQuery(eq(this.#table.id, id), options);
     }
     /**
      * Loads a single entity based on a query.
@@ -325,12 +355,11 @@ let EntityRepository = class EntityRepository extends Transactional {
      * @returns A promise that resolves to the loaded entity or `undefined` if not found.
      */
     async tryLoadByQuery(query, options) {
-        const sqlQuery = this.convertQuery(query);
-        let dbQuery = this.session.select()
-            .from(this.#table)
+        const sqlQuery = this.convertQuery(query, options);
+        let dbQuery = this.createBaseQuery(options);
+        dbQuery = dbQuery
             .where(sqlQuery)
-            .limit(1)
-            .$dynamic();
+            .limit(1);
         if (isDefined(options?.offset)) {
             dbQuery = dbQuery.offset(options.offset);
         }
@@ -341,7 +370,7 @@ let EntityRepository = class EntityRepository extends Transactional {
         if (isUndefined(row)) {
             return undefined;
         }
-        return await this.mapToEntity(row);
+        return await this.mapToEntity(row, { includeSubclasses: options?.includeSubclasses });
     }
     /**
      * Loads multiple entities by their IDs.
@@ -350,7 +379,7 @@ let EntityRepository = class EntityRepository extends Transactional {
      * @returns A promise that resolves to an array of loaded entities.
      */
     async loadMany(ids, options) {
-        if (ids.length === 0) {
+        if (ids.length == 0) {
             return [];
         }
         return await this.loadManyByQuery(inArray(this.#table.id, ids), options);
@@ -372,11 +401,9 @@ let EntityRepository = class EntityRepository extends Transactional {
      * @returns A promise that resolves to an array of loaded entities.
      */
     async loadManyByQuery(query, options) {
-        const sqlQuery = this.convertQuery(query);
-        let dbQuery = this.applySelect(this.session, options?.distinct)
-            .from(this.#table)
-            .where(sqlQuery)
-            .$dynamic();
+        const sqlQuery = this.convertQuery(query, options);
+        let dbQuery = this.createBaseQuery(options);
+        dbQuery = dbQuery.where(sqlQuery);
         if (isDefined(options?.offset)) {
             dbQuery = dbQuery.offset(options.offset);
         }
@@ -387,7 +414,7 @@ let EntityRepository = class EntityRepository extends Transactional {
             dbQuery = dbQuery.orderBy(...this.convertOrderBy(options.order));
         }
         const rows = await dbQuery;
-        return await this.mapManyToEntity(rows);
+        return await this.mapManyToEntity(rows, { includeSubclasses: options?.includeSubclasses });
     }
     /**
      * Loads multiple entities based on a query and returns them as an async iterable cursor.
@@ -418,47 +445,56 @@ let EntityRepository = class EntityRepository extends Transactional {
     }
     /**
      * Counts the total number of entities of the repository's type.
+     * @param options Optional counting options (e.g., withDeleted).
      * @returns A promise that resolves to the total count.
      */
-    async count() {
-        const dbQuery = this.session
-            .select({ count: count() })
-            .from(this.#table);
-        const [result] = await dbQuery;
-        return assertDefinedPass(result).count;
+    async count(options) {
+        return await this.countByQuery({}, options);
     }
     /**
      * Counts the number of entities matching a query.
      * @param query The query to filter entities.
+     * @param options Optional counting options (e.g., withDeleted).
      * @returns A promise that resolves to the count of matching entities.
      */
-    async countByQuery(query) {
-        const sqlQuery = this.convertQuery(query);
-        const dbQuery = this.session
+    async countByQuery(query, options) {
+        const sqlQuery = this.convertQuery(query, options);
+        let dbQuery = this.session
             .select({ count: count() })
             .from(this.#table)
-            .where(sqlQuery);
+            .$dynamic();
+        dbQuery = this.applyJoins(dbQuery);
+        dbQuery = dbQuery.where(sqlQuery);
+        if (isDefined(options?.for)) {
+            const lock = isString(options.for) ? { mode: options.for } : options.for;
+            dbQuery = dbQuery.for(lock.mode, { skipLocked: lock.skipLocked, noWait: lock.noWait });
+        }
         const [result] = await dbQuery;
         return assertDefinedPass(result).count;
     }
     /**
      * Checks if an entity with the given ID exists.
      * @param id The ID of the entity to check.
+     * @param options Optional counting options (e.g., withDeleted).
      * @returns A promise that resolves to `true` if the entity exists, `false` otherwise.
      */
-    async has(id) {
-        return await this.hasByQuery(eq(this.#table.id, id));
+    async has(id, options) {
+        return await this.hasByQuery(eq(this.#table.id, id), options);
     }
     /**
      * Checks if any entity matches the given query.
      * @param query The query to filter entities.
+     * @param options Optional counting options (e.g., withDeleted).
      * @returns A promise that resolves to `true` if at least one entity matches the query, `false` otherwise.
      */
-    async hasByQuery(query) {
-        const sqlQuery = this.convertQuery(query);
-        const result = await this.session
+    async hasByQuery(query, options) {
+        const sqlQuery = this.convertQuery(query, options);
+        let dbQuery = this.session
             .select({ value: sql `1` })
             .from(this.#table)
+            .$dynamic();
+        dbQuery = this.applyJoins(dbQuery);
+        const result = await dbQuery
             .where(sqlQuery)
             .limit(1);
         return result.length > 0;
@@ -470,7 +506,7 @@ let EntityRepository = class EntityRepository extends Transactional {
      */
     async hasAll(ids) {
         const uniqueIds = distinct(ids);
-        if (uniqueIds.length === 0) {
+        if (uniqueIds.length == 0) {
             return false;
         }
         const count = await this.countByQuery(inArray(this.#table.id, uniqueIds));
@@ -493,18 +529,80 @@ let EntityRepository = class EntityRepository extends Transactional {
         }
         return await this.mapToEntity(row);
     }
+    async insertCTI(entity) {
+        return await this.transaction(async (transaction) => {
+            const transformContext = await this.getTransformContext();
+            const rows = [];
+            let generatedId;
+            for (const { table, columnDefinitions } of this.#tablesChain) {
+                let columns = await this._mapToTableInsertColumns(entity, transformContext, table, columnDefinitions);
+                if (isDefined(generatedId)) {
+                    columns = { ...columns, id: generatedId };
+                }
+                const [row] = await transaction.pgTransaction
+                    .insert(table)
+                    .values(columns)
+                    .returning();
+                if (isUndefined(generatedId)) {
+                    generatedId = row.id;
+                }
+                rows.push(row);
+            }
+            // Merge rows for mapping
+            const mergedRow = fromEntries(rows.flatMap((row, index) => {
+                const tableName = getTableName(this.#tablesChain[index].table);
+                return [[tableName, row]];
+            }));
+            return await this.mapToEntity(mergedRow);
+        });
+    }
+    async insertManyCTI(entities) {
+        return await this.transaction(async (transaction) => {
+            const transformContext = await this.getTransformContext();
+            const results = {};
+            let generatedIds;
+            for (const { table, columnDefinitions } of this.#tablesChain) {
+                const values = await Promise.all(entities.map(async (entity, index) => {
+                    const columns = await this._mapToTableInsertColumns(entity, transformContext, table, columnDefinitions);
+                    if (isDefined(generatedIds)) {
+                        return { ...columns, id: generatedIds[index] };
+                    }
+                    return columns;
+                }));
+                const rows = await transaction.pgTransaction
+                    .insert(table)
+                    .values(values)
+                    .returning();
+                if (isUndefined(generatedIds)) {
+                    generatedIds = rows.map((row) => row.id);
+                }
+                results[getTableName(table)] = rows;
+            }
+            // Merge rows by index
+            const mergedRows = entities.map((_, index) => {
+                return fromEntries(this.#tablesChain.map(({ table }) => {
+                    const tableName = getTableName(table);
+                    return [tableName, results[tableName][index]];
+                }));
+            });
+            return await this.mapManyToEntity(mergedRows);
+        });
+    }
     /**
      * Inserts a new entity into the database.
      * @param entity The entity to insert.
      * @returns A promise that resolves to the inserted entity.
      */
     async insert(entity) {
-        const columns = await this.mapToInsertColumns(entity);
-        const [row] = await this.session
-            .insert(this.#table)
-            .values(columns)
-            .returning();
-        return await this.mapToEntity(row);
+        if (!this.#isChild) {
+            const columns = await this.mapToInsertColumns(entity);
+            const [row] = await this.session
+                .insert(this.#table)
+                .values(columns)
+                .returning();
+            return await this.mapToEntity(row);
+        }
+        return await this.insertCTI(entity);
     }
     /**
      * Inserts multiple new entities into the database.
@@ -512,12 +610,15 @@ let EntityRepository = class EntityRepository extends Transactional {
      * @returns A promise that resolves to an array of the inserted entities.
      */
     async insertMany(entities) {
-        if (entities.length === 0) {
+        if (entities.length == 0) {
             return [];
         }
-        const columns = await this.mapManyToInsertColumns(entities);
-        const rows = await this.session.insert(this.#table).values(columns).returning();
-        return await this.mapManyToEntity(rows);
+        if (!this.#isChild) {
+            const columns = await this.mapManyToInsertColumns(entities);
+            const rows = await this.session.insert(this.#table).values(columns).returning();
+            return await this.mapManyToEntity(rows);
+        }
+        return await this.insertManyCTI(entities);
     }
     /**
      * Inserts an entity if it does not already exist based on the target columns.
@@ -545,7 +646,7 @@ let EntityRepository = class EntityRepository extends Transactional {
      * @returns A promise that resolves to the inserted or existing entities.
      */
     async insertManyIfNotExists(target, entities) {
-        if (entities.length === 0) {
+        if (entities.length == 0) {
             return [];
         }
         const targetColumns = toArray(target).map((path) => this.getColumn(path));
@@ -559,99 +660,324 @@ let EntityRepository = class EntityRepository extends Transactional {
     }
     /**
      * Inserts an entity or updates it if a conflict occurs based on the target columns.
+     * Throws an error if the entity is not returned (e.g. because of a condition in `wheres`).
      * @param target The column(s) to use for conflict detection.
      * @param entity The entity to insert.
      * @param update Optional update to apply if a conflict occurs. Defaults to the inserted entity's values.
+     * @param wheres Optional conditions for the conflict target and the update.
      * @returns A promise that resolves to the inserted or updated entity.
      */
-    async upsert(target, entity, update) {
-        const targetColumns = toArray(target).map((path) => this.getColumn(path));
-        const columns = await this.mapToInsertColumns(entity);
-        const mappedUpdate = await this.mapUpdate(update ?? entity);
-        const [row] = await this.session
-            .insert(this.#table)
-            .values(columns)
-            .onConflictDoUpdate({
-            target: targetColumns,
-            set: mappedUpdate,
-        })
-            .returning();
-        return await this.mapToEntity(row);
+    async upsert(target, entity, update, wheres) {
+        const result = await this.tryUpsert(target, entity, update, wheres);
+        if (isUndefined(result)) {
+            throw new Error(`${this.typeName} upsert failed to return a row.`);
+        }
+        return result;
+    }
+    async tryUpsertCTI(target, entity, update, wheres) {
+        return await this.transaction(async (transaction) => {
+            const transformContext = await this.getTransformContext();
+            const results = {};
+            let generatedId = entity.id;
+            for (const { table, columnDefinitions } of this.#tablesChain) {
+                const tableColumnNames = columnDefinitions.map((def) => def.name);
+                const tableColumnNamesSet = new Set(tableColumnNames);
+                const filteredTarget = isDefined(wheres?.target) ? this.filterQuery(wheres.target, tableColumnNamesSet) : undefined;
+                const targetQuery = isDefined(filteredTarget) ? this._convertQuery(filteredTarget, table) : undefined;
+                const filteredSet = isDefined(wheres?.set) ? this.filterQuery(wheres.set, tableColumnNamesSet) : undefined;
+                const setQuery = isDefined(filteredSet) ? this._convertQuery(filteredSet, table) : undefined;
+                const columns = await this._mapToTableInsertColumns(entity, transformContext, table, columnDefinitions);
+                const mappedUpdate = await this._mapToTableUpdate(update ?? entity, transformContext, table, columnDefinitions);
+                const targetPaths = toArray(target);
+                const isTargetInTable = targetPaths.every((path) => {
+                    const def = this.#columnDefinitionsMap.get(path);
+                    return isDefined(def) && tableColumnNames.includes(def.name);
+                });
+                const tableTarget = isTargetInTable
+                    ? targetPaths.map((path) => resolveTargetColumn(path, table, this.#columnDefinitionsMap))
+                    : [table.id];
+                const [row] = await transaction.pgTransaction
+                    .insert(table)
+                    .values({ ...columns, ...(isDefined(generatedId) ? { id: generatedId } : {}) })
+                    .onConflictDoUpdate({
+                    target: tableTarget,
+                    set: mappedUpdate,
+                    targetWhere: targetQuery,
+                    setWhere: setQuery,
+                })
+                    .returning();
+                if (isUndefined(row)) {
+                    return undefined;
+                }
+                if (isUndefined(generatedId)) {
+                    generatedId = row['id'];
+                }
+                results[getTableName(table)] = row;
+            }
+            return await this.mapToEntity(results);
+        });
+    }
+    /**
+     * Tries to insert an entity or update it if a conflict occurs based on the target columns.
+     * Returns `undefined` if the entity is not returned (e.g. because of a condition in `wheres`).
+     * @param target The column(s) to use for conflict detection.
+     * @param entity The entity to insert.
+     * @param update Optional update to apply if a conflict occurs. Defaults to the inserted entity's values.
+     * @param wheres Optional conditions for the conflict target and the update.
+     * @returns A promise that resolves to the inserted or updated entity or `undefined`.
+     */
+    async tryUpsert(target, entity, update, wheres) {
+        const targetQuery = isDefined(wheres?.target) ? this.convertQuery(wheres.target) : undefined;
+        const setQuery = isDefined(wheres?.set) ? this.convertQuery(wheres.set) : undefined;
+        if (!this.#isChild) {
+            const targetColumns = toArray(target).map((path) => this.getColumn(path));
+            const columns = await this.mapToInsertColumns(entity);
+            const mappedUpdate = await this.mapUpdate(update ?? entity);
+            const [row] = await this.session
+                .insert(this.#table)
+                .values(columns)
+                .onConflictDoUpdate({
+                target: targetColumns,
+                set: mappedUpdate,
+                targetWhere: targetQuery,
+                setWhere: setQuery,
+            })
+                .returning();
+            if (isUndefined(row)) {
+                return undefined;
+            }
+            return await this.mapToEntity(row);
+        }
+        return await this.tryUpsertCTI(target, entity, update, wheres);
+    }
+    async upsertManyCTI(target, entities, update, wheres) {
+        return await this.transaction(async (transaction) => {
+            const transformContext = await this.getTransformContext();
+            const results = {};
+            let generatedIds = entities.map((e) => e.id).filter(isDefined);
+            if (generatedIds.length != entities.length) {
+                generatedIds = undefined;
+            }
+            for (const { table, columnDefinitions } of this.#tablesChain) {
+                const tableColumnNames = columnDefinitions.map((def) => def.name);
+                const tableColumnNamesSet = new Set(tableColumnNames);
+                const filteredTarget = isDefined(wheres?.target) ? this.filterQuery(wheres.target, tableColumnNamesSet) : undefined;
+                const targetQuery = isDefined(filteredTarget) ? this._convertQuery(filteredTarget, table) : undefined;
+                const filteredSet = isDefined(wheres?.set) ? this.filterQuery(wheres.set, tableColumnNamesSet) : undefined;
+                const setQuery = isDefined(filteredSet) ? this._convertQuery(filteredSet, table) : undefined;
+                const values = await Promise.all(entities.map(async (entity, index) => {
+                    const columns = await this._mapToTableInsertColumns(entity, transformContext, table, columnDefinitions);
+                    if (isDefined(generatedIds)) {
+                        return { ...columns, id: generatedIds[index] };
+                    }
+                    return columns;
+                }));
+                const mappedUpdate = isDefined(update)
+                    ? await this._mapToTableUpdate(update, transformContext, table, columnDefinitions)
+                    : {
+                        ...fromEntries(columnDefinitions.filter((column) => column.name != table.id.name).map((column) => [column.name, sql `excluded.${sql.identifier(resolveTargetColumn(column, table, this.#columnDefinitionsMap).name)}`])),
+                        ...((table == this.#baseTable) ? this._getMetadataUpdate(update) : undefined),
+                    };
+                const targetPaths = toArray(target);
+                const isTargetInTable = targetPaths.every((path) => {
+                    const def = this.#columnDefinitionsMap.get(path);
+                    return isDefined(def) && tableColumnNames.includes(def.name);
+                });
+                const tableTarget = isTargetInTable
+                    ? targetPaths.map((path) => resolveTargetColumn(path, table, this.#columnDefinitionsMap))
+                    : [table.id];
+                const rows = await transaction.pgTransaction
+                    .insert(table)
+                    .values(values)
+                    .onConflictDoUpdate({
+                    target: tableTarget,
+                    set: mappedUpdate,
+                    targetWhere: targetQuery,
+                    setWhere: setQuery,
+                })
+                    .returning();
+                if (isUndefined(generatedIds)) {
+                    generatedIds = rows.map((row) => row.id);
+                }
+                results[getTableName(table)] = rows;
+            }
+            // Merge rows by index
+            // We must ensure that we only include indices that were returned in ALL tables (consistent results)
+            // For upsertMany with conditions, some rows might be skipped in some tables.
+            // However, if it's skipped in the first table, it won't have an ID for the subsequent ones if it was a new ID.
+            // This is quite complex for polymorphic upsertMany with conditions.
+            // Assuming for now that conditions are consistent or only on the base table.
+            const tableNames = this.#tablesChain.map(({ table }) => getTableName(table));
+            const firstTableName = tableNames[0];
+            // Use IDs from the first table to find matching rows in other tables
+            const firstTableRows = results[firstTableName];
+            const mergedRows = [];
+            for (const row of firstTableRows) {
+                const id = row['id'];
+                const mergedRow = { [firstTableName]: row };
+                let allTablesMatched = true;
+                for (let i = 1; i < tableNames.length; i++) {
+                    const tableName = tableNames[i];
+                    const matchingRow = results[tableName].find(r => r['id'] === id);
+                    if (isDefined(matchingRow)) {
+                        mergedRow[tableName] = matchingRow;
+                    }
+                    else {
+                        allTablesMatched = false;
+                        break;
+                    }
+                }
+                if (allTablesMatched) {
+                    mergedRows.push(mergedRow);
+                }
+            }
+            return await this.mapManyToEntity(mergedRows);
+        });
     }
     /**
      * Inserts multiple entities or updates them if a conflict occurs based on the target columns.
      * @param target The column(s) to use for conflict detection.
      * @param entities An array of entities to insert.
      * @param update Optional update to apply if a conflict occurs. Defaults to the inserted entity's values.
+     * @param wheres Optional conditions for the conflict target and the update.
      * @returns A promise that resolves to an array of the inserted or updated entities.
      */
-    async upsertMany(target, entities, update) {
-        if (entities.length === 0) {
+    async upsertMany(target, entities, update, wheres) {
+        if (entities.length == 0) {
             return [];
         }
-        const targetColumns = toArray(target).map((path) => this.getColumn(path));
-        const columns = await this.mapManyToInsertColumns(entities);
-        const mappedUpdate = isDefined(update)
-            ? await this.mapUpdate(update)
-            : {
-                ...this.#upsertManyExcludedMapping,
-                ...this._getMetadataUpdate(update),
-            };
-        const rows = await this.session
-            .insert(this.#table)
-            .values(columns)
-            .onConflictDoUpdate({
-            target: targetColumns,
-            set: mappedUpdate,
-        })
-            .returning();
-        return await this.mapManyToEntity(rows);
+        const targetQuery = isDefined(wheres?.target) ? this.convertQuery(wheres.target) : undefined;
+        const setQuery = isDefined(wheres?.set) ? this.convertQuery(wheres.set) : undefined;
+        if (!this.#isChild) {
+            const targetColumns = toArray(target).map((path) => this.getColumn(path));
+            const columns = await this.mapManyToInsertColumns(entities);
+            const mappedUpdate = isDefined(update)
+                ? await this.mapUpdate(update)
+                : {
+                    ...this.#upsertManyExcludedMapping,
+                    ...this._getMetadataUpdate(update),
+                };
+            const rows = await this.session
+                .insert(this.#table)
+                .values(columns)
+                .onConflictDoUpdate({
+                target: targetColumns,
+                set: mappedUpdate,
+                targetWhere: targetQuery,
+                setWhere: setQuery,
+            })
+                .returning();
+            return await this.mapManyToEntity(rows);
+        }
+        return await this.upsertManyCTI(target, entities, update, wheres);
     }
     /**
      * Updates an entity by its ID.
      * Throws `NotFoundError` if the entity is not found.
      * @param id The ID of the entity to update.
      * @param update The update to apply to the entity.
+     * @param options Optional update options.
      * @returns A promise that resolves to the updated entity.
      * @throws {NotFoundError} If the entity with the given ID is not found.
      */
-    async update(id, update) {
-        const entity = await this.tryUpdate(id, update);
+    async update(id, update, options) {
+        const entity = await this.tryUpdate(id, update, options);
         if (isUndefined(entity)) {
             throw new NotFoundError(`${this.typeName} ${id} not found.`);
         }
         return entity;
     }
+    async tryUpdateCTI(id, update, options) {
+        return await this.transaction(async (transaction) => {
+            const transformContext = await this.getTransformContext();
+            const results = {};
+            for (const { table, columnDefinitions } of this.#tablesChain) {
+                const mappedUpdate = await this._mapToTableUpdate(update, transformContext, table, columnDefinitions);
+                const sqlQuery = (table == this.#baseTable) ? this.convertQuery(eq(table.id, id), options) : eq(table.id, id);
+                if (objectKeys(mappedUpdate).length > 0) {
+                    const [row] = await transaction.pgTransaction
+                        .update(table)
+                        .set(mappedUpdate)
+                        .where(sqlQuery)
+                        .returning();
+                    if (isUndefined(row)) {
+                        return undefined;
+                    }
+                    results[getTableName(table)] = row;
+                }
+                else {
+                    const [row] = await transaction.pgTransaction
+                        .select()
+                        .from(table)
+                        .where(sqlQuery)
+                        .limit(1);
+                    if (isUndefined(row)) {
+                        return undefined;
+                    }
+                    results[getTableName(table)] = row;
+                }
+            }
+            const mergedRow = fromEntries(this.#tablesChain.map(({ table }) => {
+                const tableName = getTableName(table);
+                return [tableName, results[tableName]];
+            }));
+            return await this.mapToEntity(mergedRow);
+        });
+    }
+    async updateManyCTI(query, update) {
+        return await this.transaction(async (transaction) => {
+            const ids = await this.withTransaction(transaction).loadManyByQuery(query).then((entities) => entities.map((entity) => entity.id));
+            if (ids.length == 0) {
+                return [];
+            }
+            const transformContext = await this.getTransformContext();
+            for (const { table, columnDefinitions } of this.#tablesChain) {
+                const mappedUpdate = await this._mapToTableUpdate(update, transformContext, table, columnDefinitions);
+                if (objectEntries(mappedUpdate).length > 0) {
+                    await transaction.pgTransaction
+                        .update(table)
+                        .set(mappedUpdate)
+                        .where(inArray(table.id, ids));
+                }
+            }
+            return await this.loadMany(ids);
+        });
+    }
     /**
      * Tries to update an entity by its ID.
      * Returns `undefined` if the entity is not found.
      * @param id The ID of the entity to update.
      * @param update The update to apply to the entity.
+     * @param options Optional update options.
      * @returns A promise that resolves to the updated entity or `undefined` if not found.
      */
-    async tryUpdate(id, update) {
-        const sqlQuery = this.convertQuery(eq(this.#table.id, id));
-        const mappedUpdate = await this.mapUpdate(update);
-        const [row] = await this.session
-            .update(this.#table)
-            .set(mappedUpdate)
-            .where(sqlQuery)
-            .returning();
-        if (isUndefined(row)) {
-            return undefined;
+    async tryUpdate(id, update, options) {
+        if (!this.#isChild) {
+            const sqlQuery = this.convertQuery(eq(this.#table.id, id), options);
+            const mappedUpdate = await this.mapUpdate(update);
+            const [row] = await this.session
+                .update(this.#table)
+                .set(mappedUpdate)
+                .where(sqlQuery)
+                .returning();
+            if (isUndefined(row)) {
+                return undefined;
+            }
+            return await this.mapToEntity(row);
         }
-        return await this.mapToEntity(row);
+        return await this.tryUpdateCTI(id, update, options);
     }
     /**
      * Updates a single entity matching a query.
      * Throws `NotFoundError` if no entity matches the query.
      * @param query The query to filter entities.
      * @param update The update to apply to the entity.
+     * @param options Optional update options.
      * @returns A promise that resolves to the updated entity.
      * @throws {NotFoundError} If no entity matches the query.
      */
-    async updateByQuery(query, update) {
-        const entity = await this.tryUpdateByQuery(query, update);
+    async updateByQuery(query, update, options) {
+        const entity = await this.tryUpdateByQuery(query, update, options);
         if (isUndefined(entity)) {
             throw new NotFoundError(`${this.typeName} not found.`);
         }
@@ -662,20 +988,30 @@ let EntityRepository = class EntityRepository extends Transactional {
      * Returns `undefined` if no entity matches the query.
      * @param query The query to filter entities.
      * @param update The update to apply to the entity.
+     * @param options Optional update options.
      * @returns A promise that resolves to the updated entity or `undefined` if not found.
      */
-    async tryUpdateByQuery(query, update) {
-        const mappedUpdate = await this.mapUpdate(update);
-        const idQuery = this.getIdLimitQuery(query).for('update');
-        const [row] = await this.session
-            .update(this.#table)
-            .set(mappedUpdate)
-            .where(inArray(this.#table.id, idQuery))
-            .returning();
-        if (isUndefined(row)) {
-            return undefined;
+    async tryUpdateByQuery(query, update, options) {
+        if (!this.#isChild) {
+            const mappedUpdate = await this.mapUpdate(update);
+            const idQuery = this.getIdLimitQuery(query, options).for('update');
+            const [row] = await this.session
+                .update(this.#table)
+                .set(mappedUpdate)
+                .where(inArray(this.#table.id, idQuery))
+                .returning();
+            if (isUndefined(row)) {
+                return undefined;
+            }
+            return await this.mapToEntity(row);
         }
-        return await this.mapToEntity(row);
+        return await this.transaction(async () => {
+            const id = await this.tryLoadByQuery(query, options).then((entity) => entity?.id);
+            if (isUndefined(id)) {
+                return undefined;
+            }
+            return await this.tryUpdate(id, update, options);
+        });
     }
     /**
      * Updates multiple entities by their IDs.
@@ -684,7 +1020,7 @@ let EntityRepository = class EntityRepository extends Transactional {
      * @returns A promise that resolves to an array of the updated entities.
      */
     async updateMany(ids, update) {
-        if (ids.length === 0) {
+        if (ids.length == 0) {
             return [];
         }
         return await this.updateManyByQuery(inArray(this.#table.id, ids), update);
@@ -696,25 +1032,29 @@ let EntityRepository = class EntityRepository extends Transactional {
      * @returns A promise that resolves to an array of the updated entities.
      */
     async updateManyByQuery(query, update) {
-        const sqlQuery = this.convertQuery(query);
-        const mappedUpdate = await this.mapUpdate(update);
-        const rows = await this.session
-            .update(this.#table)
-            .set(mappedUpdate)
-            .where(sqlQuery)
-            .returning();
-        return await this.mapManyToEntity(rows);
+        if (!this.#isChild) {
+            const sqlQuery = this.convertQuery(query);
+            const mappedUpdate = await this.mapUpdate(update);
+            const rows = await this.session
+                .update(this.#table)
+                .set(mappedUpdate)
+                .where(sqlQuery)
+                .returning();
+            return await this.mapManyToEntity(rows);
+        }
+        return await this.updateManyCTI(query, update);
     }
     /**
      * Deletes an entity by its ID (soft delete if metadata is available).
      * Throws `NotFoundError` if the entity is not found.
      * @param id The ID of the entity to delete.
+     * @param options Optional delete options.
      * @param metadataUpdate Optional metadata update to apply during soft delete.
      * @returns A promise that resolves to the deleted entity.
      * @throws {NotFoundError} If the entity with the given ID is not found.
      */
-    async delete(id, metadataUpdate) {
-        const entity = await this.tryDelete(id, metadataUpdate);
+    async delete(id, options, metadataUpdate) {
+        const entity = await this.tryDelete(id, options, metadataUpdate);
         if (isUndefined(entity)) {
             throw new NotFoundError(`${this.typeName} ${id} not found.`);
         }
@@ -724,16 +1064,17 @@ let EntityRepository = class EntityRepository extends Transactional {
      * Tries to delete an entity by its ID (soft delete if metadata is available).
      * Returns `undefined` if the entity is not found.
      * @param id The ID of the entity to delete.
+     * @param options Optional delete options.
      * @param metadataUpdate Optional metadata update to apply during soft delete.
      * @returns A promise that resolves to the deleted entity or `undefined` if not found.
      */
-    async tryDelete(id, metadataUpdate) {
+    async tryDelete(id, options, metadataUpdate) {
         if (!this.hasMetadata) {
-            return await this.tryHardDelete(id);
+            return await this.tryHardDelete(id, options);
         }
-        const sqlQuery = and(isSqlNull(this.#tableWithMetadata.deleteTimestamp), this.convertQuery(eq(this.#table.id, id)));
+        const sqlQuery = and(isSqlNull(this.#baseTableWithMetadata.deleteTimestamp), this.convertQuery(eq(this.#baseTable.id, id), options));
         const [row] = await this.session
-            .update(this.#tableWithMetadata)
+            .update(this.#baseTableWithMetadata)
             .set({
             deleteTimestamp: TRANSACTION_TIMESTAMP,
             attributes: this.getAttributesUpdate(metadataUpdate?.attributes),
@@ -749,12 +1090,13 @@ let EntityRepository = class EntityRepository extends Transactional {
      * Deletes a single entity matching a query (soft delete if metadata is available).
      * Throws `NotFoundError` if no entity matches the query.
      * @param query The query to filter entities.
+     * @param options Optional delete options.
      * @param metadataUpdate Optional metadata update to apply during soft delete.
      * @returns A promise that resolves to the deleted entity.
      * @throws {NotFoundError} If no entity matches the query.
      */
-    async deleteByQuery(query, metadataUpdate) {
-        const entity = await this.tryDeleteByQuery(query, metadataUpdate);
+    async deleteByQuery(query, options, metadataUpdate) {
+        const entity = await this.tryDeleteByQuery(query, options, metadataUpdate);
         if (isUndefined(entity)) {
             throw new NotFoundError(`${this.typeName} not found.`);
         }
@@ -764,17 +1106,18 @@ let EntityRepository = class EntityRepository extends Transactional {
      * Tries to delete a single entity matching a query (soft delete if metadata is available).
      * Returns `undefined` if no entity matches the query.
      * @param query The query to filter entities.
+     * @param options Optional delete options.
      * @param metadataUpdate Optional metadata update to apply during soft delete.
      * @returns A promise that resolves to the deleted entity or `undefined` if not found.
      */
-    async tryDeleteByQuery(query, metadataUpdate) {
+    async tryDeleteByQuery(query, options, metadataUpdate) {
         if (!this.hasMetadata) {
-            return await this.tryHardDeleteByQuery(query);
+            return await this.tryHardDeleteByQuery(query, options);
         }
-        const idQuery = this.getIdLimitQuery(query).for('update');
-        const sqlQuery = and(isSqlNull(this.#tableWithMetadata.deleteTimestamp), inArray(this.#table.id, idQuery));
+        const idQuery = this.getIdLimitQuery(query, options).for('update');
+        const sqlQuery = and(isSqlNull(this.#baseTableWithMetadata.deleteTimestamp), inArray(this.#baseTable.id, idQuery));
         const [row] = await this.session
-            .update(this.#tableWithMetadata)
+            .update(this.#baseTableWithMetadata)
             .set({
             deleteTimestamp: TRANSACTION_TIMESTAMP,
             attributes: this.getAttributesUpdate(metadataUpdate?.attributes),
@@ -789,28 +1132,30 @@ let EntityRepository = class EntityRepository extends Transactional {
     /**
      * Deletes multiple entities by their IDs (soft delete if metadata is available).
      * @param ids An array of entity IDs to delete.
+     * @param options Optional delete options.
      * @param metadataUpdate Optional metadata update to apply during soft delete.
      * @returns A promise that resolves to an array of the deleted entities.
      */
-    async deleteMany(ids, metadataUpdate) {
-        if (ids.length === 0) {
+    async deleteMany(ids, options, metadataUpdate) {
+        if (ids.length == 0) {
             return [];
         }
-        return await this.deleteManyByQuery(inArray(this.#table.id, ids), metadataUpdate);
+        return await this.deleteManyByQuery(inArray(this.#table.id, ids), options, metadataUpdate);
     }
     /**
      * Deletes multiple entities matching a query (soft delete if metadata is available). Already deleted entities are ignored.
      * @param query The query to filter entities.
+     * @param options Optional delete options.
      * @param metadataUpdate Optional metadata update to apply during soft delete.
      * @returns A promise that resolves to an array of the deleted entities.
      */
-    async deleteManyByQuery(query, metadataUpdate) {
+    async deleteManyByQuery(query, options, metadataUpdate) {
         if (!this.hasMetadata) {
-            return await this.hardDeleteManyByQuery(query);
+            return await this.hardDeleteManyByQuery(query, options);
         }
-        const sqlQuery = and(isSqlNull(this.#tableWithMetadata.deleteTimestamp), this.convertQuery(query));
+        const sqlQuery = and(isSqlNull(this.#baseTableWithMetadata.deleteTimestamp), this.convertQuery(query, options));
         const rows = await this.session
-            .update(this.#tableWithMetadata)
+            .update(this.#baseTableWithMetadata)
             .set({
             deleteTimestamp: TRANSACTION_TIMESTAMP,
             attributes: this.getAttributesUpdate(metadataUpdate?.attributes),
@@ -823,11 +1168,12 @@ let EntityRepository = class EntityRepository extends Transactional {
      * Hard deletes an entity by its ID (removes from the database).
      * Throws `NotFoundError` if the entity is not found.
      * @param id The ID of the entity to hard delete.
+     * @param options Optional delete options.
      * @returns A promise that resolves to the hard deleted entity.
      * @throws {NotFoundError} If the entity with the given ID is not found.
      */
-    async hardDelete(id) {
-        const result = await this.tryHardDelete(id);
+    async hardDelete(id, options) {
+        const result = await this.tryHardDelete(id, options);
         if (!result) {
             throw new NotFoundError(`${this.typeName} ${id} not found.`);
         }
@@ -837,12 +1183,13 @@ let EntityRepository = class EntityRepository extends Transactional {
      * Tries to hard delete an entity by its ID (removes from the database).
      * Returns `undefined` if the entity is not found.
      * @param id The ID of the entity to hard delete.
+     * @param options Optional delete options.
      * @returns A promise that resolves to the hard deleted entity or `undefined` if not found.
      */
-    async tryHardDelete(id) {
-        const sqlQuery = this.convertQuery(eq(this.#table.id, id));
+    async tryHardDelete(id, options) {
+        const sqlQuery = this.convertQuery(eq(this.#baseTable.id, id), { withDeleted: true, ...options });
         const [row] = await this.session
-            .delete(this.#table)
+            .delete(this.#baseTable)
             .where(sqlQuery)
             .returning();
         if (isUndefined(row)) {
@@ -854,11 +1201,12 @@ let EntityRepository = class EntityRepository extends Transactional {
      * Hard deletes a single entity matching a query (removes from the database).
      * Throws `NotFoundError` if no entity matches the query.
      * @param query The query to filter entities.
+     * @param options Optional delete options.
      * @returns A promise that resolves to the hard deleted entity.
      * @throws {NotFoundError} If no entity matches the query.
      */
-    async hardDeleteByQuery(query) {
-        const result = await this.tryHardDeleteByQuery(query);
+    async hardDeleteByQuery(query, options) {
+        const result = await this.tryHardDeleteByQuery(query, options);
         if (!result) {
             throw new NotFoundError(`${this.typeName} not found.`);
         }
@@ -868,13 +1216,14 @@ let EntityRepository = class EntityRepository extends Transactional {
      * Tries to hard delete a single entity matching a query (removes from the database).
      * Returns `undefined` if no entity matches the query.
      * @param query The query to filter entities.
+     * @param options Optional delete options.
      * @returns A promise that resolves to the hard deleted entity or `undefined` if not found.
      */
-    async tryHardDeleteByQuery(query) {
-        const idQuery = this.getIdLimitQuery(query).for('update');
-        const sqlQuery = inArray(this.#table.id, idQuery);
+    async tryHardDeleteByQuery(query, options) {
+        const idQuery = this.getIdLimitQuery(query, { withDeleted: true, ...options });
+        const sqlQuery = inArray(this.#baseTable.id, idQuery);
         const [row] = await this.session
-            .delete(this.#table)
+            .delete(this.#baseTable)
             .where(sqlQuery)
             .returning();
         if (isUndefined(row)) {
@@ -885,23 +1234,25 @@ let EntityRepository = class EntityRepository extends Transactional {
     /**
      * Hard deletes multiple entities by their IDs (removes from the database).
      * @param ids An array of entity IDs to hard delete.
+     * @param options Optional delete options.
      * @returns A promise that resolves to an array of the hard deleted entities.
      */
-    async hardDeleteMany(ids) {
-        if (ids.length === 0) {
+    async hardDeleteMany(ids, options) {
+        if (ids.length == 0) {
             return [];
         }
-        return await this.hardDeleteManyByQuery(inArray(this.#table.id, ids));
+        return await this.hardDeleteManyByQuery(inArray(this.#table.id, ids), options);
     }
     /**
      * Hard deletes multiple entities matching a query (removes from the database).
      * @param query The query to filter entities.
+     * @param options Optional delete options.
      * @returns A promise that resolves to an array of the hard deleted entities.
      */
-    async hardDeleteManyByQuery(query) {
-        const sqlQuery = this.convertQuery(query);
+    async hardDeleteManyByQuery(query, options) {
+        const sqlQuery = this.convertQuery(query, { withDeleted: true, ...options });
         const rows = await this.session
-            .delete(this.#table)
+            .delete(this.#baseTable)
             .where(sqlQuery)
             .returning();
         return await this.mapManyToEntity(rows);
@@ -968,25 +1319,56 @@ let EntityRepository = class EntityRepository extends Transactional {
         if (!this.hasMetadata || (options?.withDeleted == true)) {
             return sql;
         }
-        return and(isSqlNull(this.#tableWithMetadata.deleteTimestamp), sql);
+        return and(isSqlNull(this.#baseTableWithMetadata.deleteTimestamp), sql);
+    }
+    _convertQuery(query, table, options) {
+        let sql = convertQuery(query, table, this.#columnDefinitionsMap, { ignorePgTable: true });
+        if (!this.hasMetadata || (options?.withDeleted == true) || (table != this.#baseTable)) {
+            return sql;
+        }
+        return and(isSqlNull(this.#baseTableWithMetadata.deleteTimestamp), sql);
+    }
+    filterQuery(query, tableColumnNames) {
+        if ((query instanceof SQL) || isSQLWrapper(query)) {
+            return query;
+        }
+        const filtered = {};
+        let hasEntries = false;
+        for (const [key, value] of objectEntries(query)) {
+            const columnDef = this.#columnDefinitionsMap.get(key);
+            if (isDefined(columnDef) && tableColumnNames.has(columnDef.name)) {
+                filtered[key] = value;
+                hasEntries = true;
+            }
+            else if (key == '$and' || key == '$or' || key == '$nor') {
+                const subQueries = value.map((q) => this.filterQuery(q, tableColumnNames)).filter(isDefined);
+                if (subQueries.length > 0) {
+                    filtered[key] = subQueries;
+                    hasEntries = true;
+                }
+            }
+        }
+        return hasEntries ? filtered : undefined;
     }
     /**
      * Maps multiple database rows to an array of entities.
      * @param columns An array of database rows.
+     * @param options Optional options, including `includeSubclasses` for polymorphic loading.
      * @returns A promise that resolves to an array of entities.
      */
-    async mapManyToEntity(columns) {
+    async mapManyToEntity(columns, options) {
         const transformContext = await this.getTransformContext();
-        return await this._mapManyToEntity(columns, transformContext);
+        return await this._mapManyToEntity(columns, transformContext, options?.includeSubclasses);
     }
     /**
      * Maps a single database row to an entity.
      * @param columns A database row.
+     * @param options Optional options, including `includeSubclasses` for polymorphic loading.
      * @returns A promise that resolves to an entity.
      */
-    async mapToEntity(columns) {
+    async mapToEntity(columns, options) {
         const transformContext = await this.getTransformContext();
-        return await this._mapToEntity(columns, transformContext);
+        return await this._mapToEntity(columns, transformContext, options?.includeSubclasses);
     }
     /**
      * Maps multiple entity-like objects to database column values for insertion or update.
@@ -1004,7 +1386,7 @@ let EntityRepository = class EntityRepository extends Transactional {
      */
     async mapToColumns(obj) {
         const transformContext = await this.getTransformContext();
-        return await this._mapToColumns(obj, transformContext);
+        return await this._mapToTableColumns(obj, transformContext);
     }
     /**
      * Maps multiple new entity objects to database column values for insertion.
@@ -1037,12 +1419,16 @@ let EntityRepository = class EntityRepository extends Transactional {
      * Gets a Drizzle select query for the ID of a single entity matching the provided query, limited to 1 result.
      * Useful for subqueries in update/delete operations targeting a single entity.
      * @param query The query to filter entities.
+     * @param options Optional options (e.g., withDeleted).
      * @returns A Drizzle select query for the entity ID.
      */
-    getIdLimitQuery(query) {
-        const sqlQuery = this.convertQuery(query);
-        return this.session.select({ id: this.#table.id })
+    getIdLimitQuery(query, options) {
+        const sqlQuery = this.convertQuery(query, options);
+        let dbQuery = this.session.select({ id: this.#table.id })
             .from(this.#table)
+            .$dynamic();
+        dbQuery = this.applyJoins(dbQuery);
+        return dbQuery
             .where(sqlQuery)
             .limit(1);
     }
@@ -1054,7 +1440,7 @@ let EntityRepository = class EntityRepository extends Transactional {
             .with(false, () => applyTo.select(selection))
             .with(true, () => applyTo.selectDistinct(selection))
             .otherwise((targets) => {
-            const ons = targets.map((target) => resolveTargetColumn(target, this.#table, this.#columnDefinitionsMap));
+            const ons = targets.map((target) => this.resolveTargetColumn(target));
             return applyTo.selectDistinctOn(ons, selection);
         });
         return selectBuilder;
@@ -1066,39 +1452,97 @@ let EntityRepository = class EntityRepository extends Transactional {
         if (attributes instanceof SQL) {
             return attributes;
         }
-        return sql `${this.#tableWithMetadata.attributes} || ${JSON.stringify(attributes)}::jsonb`;
-    }
-    async _mapManyToEntity(columns, transformContext) {
-        return await toArrayAsync(mapAsync(columns, async (column) => await this._mapToEntity(column, transformContext)));
-    }
-    async _mapToEntity(columns, transformContext) {
-        const entity = new this.type();
-        for (const def of this.#columnDefinitions) {
-            const rawValue = columns[def.name];
+        return sql `${this.#baseTableWithMetadata.attributes} || ${JSON.stringify(attributes)}::jsonb`;
+    }
+    applyJoins(dbQuery) {
+        return this.#joinedTables.reduce((query, joinedTable) => query.innerJoin(joinedTable, eq(this.#table.id, joinedTable.id)), dbQuery);
+    }
+    getTablesChain(type) {
+        const chain = [];
+        let currentType = type;
+        while (true) {
+            const table = getDrizzleTableFromType(currentType, this.#schema);
+            const columnDefinitions = getTableColumnDefinitions(table);
+            chain.unshift({ table, type: currentType, columnDefinitions });
+            const parentType = reflectionRegistry.getMetadata(currentType)?.parent;
+            if (isNullOrUndefined(parentType) || !isTableOwning(parentType)) {
+                break;
+            }
+            currentType = parentType;
+        }
+        return chain;
+    }
+    async _mapManyToEntity(columns, transformContext, includeSubclasses) {
+        return await toArrayAsync(mapAsync(columns, async (column) => await this._mapToEntity(column, transformContext, includeSubclasses)));
+    }
+    async _mapToEntity(columns, transformContext, includeSubclasses) {
+        const subclasses = (includeSubclasses == true) ? this.#subclasses : (isArray(includeSubclasses) ? includeSubclasses : []);
+        let type = this.type;
+        if (isDefined(this.#inheritanceMetadata)) {
+            const discriminatorColumnName = this.#inheritanceMetadata.discriminatorColumn;
+            const discriminatorValue = columns[discriminatorColumnName];
+            if (isDefined(discriminatorValue)) {
+                const subclassInfo = this.#subclassTablesInfo.find((info) => info.discriminatorValue == discriminatorValue);
+                if (isDefined(subclassInfo) && subclasses.includes(subclassInfo.type)) {
+                    type = subclassInfo.type;
+                }
+                const isCompatible = !this.#isChild
+                    || (discriminatorValue == this.#discriminatorInfo?.value)
+                    || this.#subclassTablesInfo.some((info) => info.discriminatorValue == discriminatorValue);
+                if (!isCompatible) {
+                    throw new Error(`Discriminator mismatch: loaded "${discriminatorValue}" but expected "${this.#discriminatorInfo?.value}" or one of its subclasses.`);
+                }
+            }
+        }
+        const entity = new (type)();
+        const columnDefinitions = (type == this.type)
+            ? this.#columnDefinitions
+            : getColumnDefinitions(getDrizzleTableFromType(type, this.#schema));
+        for (const def of columnDefinitions) {
+            let rawValue = columns[def.name];
+            if (isUndefined(rawValue) && isDefined(def.table)) {
+                const tableName = getTableName(def.table);
+                if (isDefined(columns[tableName])) {
+                    rawValue = columns[tableName][def.name];
+                }
+                else {
+                    // Check if it's a prefixed column from a polymorphic join
+                    const prefixedName = tableName + '_' + def.name;
+                    if (isDefined(columns[prefixedName])) {
+                        rawValue = columns[prefixedName];
+                    }
+                }
+            }
             const transformed = await def.fromDatabase(rawValue, transformContext);
             assignDeep(entity, def.objectPath, transformed);
         }
         return entity;
     }
     async _mapManyToColumns(objects, transformContext) {
-        return await toArrayAsync(mapAsync(objects, async (obj) => await this._mapToColumns(obj, transformContext)));
+        return await toArrayAsync(mapAsync(objects, async (obj) => await this._mapToTableColumns(obj, transformContext)));
     }
-    async _mapToColumns(obj, transformContext) {
+    async _mapToTableColumns(obj, transformContext, definitions = this.#tableColumnDefinitions) {
         const columns = {};
-        for (const def of this.#columnDefinitions) {
+        for (const def of definitions) {
             const rawValue = def.dereferenceObjectPath(obj);
             columns[def.name] = await def.toDatabase(rawValue, transformContext);
         }
         return columns;
     }
-    async _mapManyToInsertColumns(objects, transformContext) {
-        return await toArrayAsync(mapAsync(objects, async (obj) => await this._mapToInsertColumns(obj, transformContext)));
-    }
-    async _mapToInsertColumns(obj, transformContext) {
-        const mapped = await this._mapToColumns(obj, transformContext);
+    async _mapToTableInsertColumns(obj, transformContext, table, definitions) {
+        const columns = await this._mapToTableColumns(obj, transformContext, definitions);
+        // Inject discriminator if applicable
+        if (isDefined(this.#discriminatorInfo)) {
+            const { columnName, value } = this.#discriminatorInfo;
+            const resolvedDefinitions = definitions ?? getTableColumnDefinitions(table);
+            const hasDiscriminatorColumn = isDefined(resolvedDefinitions.find((def) => def.name == columnName));
+            if (hasDiscriminatorColumn) {
+                columns[columnName] = value;
+            }
+        }
         return {
-            ...mapped,
-            ...(this.hasMetadata
+            ...columns,
+            ...(((table == this.#baseTable) && this.hasMetadata)
                 ? {
                     revision: 1,
                     revisionTimestamp: TRANSACTION_TIMESTAMP,
@@ -1107,29 +1551,88 @@ let EntityRepository = class EntityRepository extends Transactional {
                 : undefined),
         };
     }
-    async _mapUpdate(update, transformContext) {
+    async _mapManyToInsertColumns(objects, transformContext) {
+        return await toArrayAsync(mapAsync(objects, async (obj) => await this._mapToInsertColumns(obj, transformContext)));
+    }
+    async _mapToInsertColumns(obj, transformContext) {
+        return await this._mapToTableInsertColumns(obj, transformContext, this.#table);
+    }
+    async _mapToTableUpdate(update, transformContext, table, definitions = this.#tableColumnDefinitions) {
         const mappedUpdate = {};
-        for (const column of this.#columnDefinitions) {
-            const value = column.dereferenceObjectPath(update);
-            if (isUndefined(value)) {
-                continue;
+        for (const columnDef of definitions) {
+            const value = columnDef.dereferenceObjectPath(update);
+            if (isDefined(value)) {
+                mappedUpdate[columnDef.name] = await columnDef.toDatabase(value, transformContext);
             }
-            mappedUpdate[column.name] = await column.toDatabase(value, transformContext);
         }
         return {
             ...mappedUpdate,
-            ...this._getMetadataUpdate(update),
+            ...((table == this.#baseTable) ? this._getMetadataUpdate(update) : undefined),
         };
     }
+    async _mapUpdate(update, transformContext) {
+        return await this._mapToTableUpdate(update, transformContext, this.#table);
+    }
     _getMetadataUpdate(update) {
         return this.hasMetadata
             ? {
                 attributes: this.getAttributesUpdate(update?.metadata?.attributes),
-                revision: sql `${this.#tableWithMetadata.revision} + 1`,
+                revision: sql `${this.#baseTableWithMetadata.revision} + 1`,
                 revisionTimestamp: TRANSACTION_TIMESTAMP,
             }
             : undefined;
     }
+    prepareSubclassJoins(includeSubclassesOption) {
+        const includeSubclasses = (includeSubclassesOption == true)
+            ? this.#subclasses
+            : (isArray(includeSubclassesOption) ? includeSubclassesOption : []);
+        const additionalTablesToJoin = new Map();
+        if (includeSubclasses.length > 0) {
+            for (const subclassInfo of this.#subclassTablesInfo) {
+                if (includeSubclasses.includes(subclassInfo.type)) {
+                    for (const chainInfo of subclassInfo.tablesChain) {
+                        if (!this.#tablesChain.some((t) => t.table == chainInfo.table)) {
+                            additionalTablesToJoin.set(chainInfo.table, chainInfo);
+                        }
+                    }
+                }
+            }
+        }
+        return { includeSubclasses, additionalTablesToJoin };
+    }
+    addSubclassColumnsToSelection(selection, additionalTablesToJoin) {
+        for (const [table, info] of additionalTablesToJoin) {
+            for (const column of info.columnDefinitions) {
+                const tableColumn = table[column.name];
+                if (isDefined(tableColumn)) {
+                    selection[getTableName(table) + '_' + column.name] = tableColumn;
+                }
+            }
+        }
+    }
+    applySubclassJoins(dbQuery, additionalTablesToJoin) {
+        if (additionalTablesToJoin.size > 0) {
+            for (const [table] of additionalTablesToJoin) {
+                dbQuery = dbQuery.leftJoin(table, eq(this.#table.id, table.id));
+            }
+        }
+        return dbQuery;
+    }
+    createBaseQuery(options, extraSelection = {}) {
+        const { additionalTablesToJoin } = this.prepareSubclassJoins(options?.includeSubclasses);
+        const selection = { ...this.#defaultSelection, ...extraSelection };
+        this.addSubclassColumnsToSelection(selection, additionalTablesToJoin);
+        let dbQuery = this.applySelect(this.session, selection, options?.distinct)
+            .from(this.#table)
+            .$dynamic();
+        dbQuery = this.applyJoins(dbQuery);
+        dbQuery = this.applySubclassJoins(dbQuery, additionalTablesToJoin);
+        if (isDefined(options?.for)) {
+            const lock = isString(options.for) ? { mode: options.for } : options.for;
+            dbQuery = dbQuery.for(lock.mode, { skipLocked: lock.skipLocked, noWait: lock.noWait });
+        }
+        return dbQuery;
+    }
     async getTransformContext() {
         if (isUndefined(this.#transformContext)) {
             if (isUndefined(this.#encryptionSecret)) {
@@ -1142,12 +1645,13 @@ let EntityRepository = class EntityRepository extends Transactional {
         }
         return await this.#transformContext;
     }
-    async _mapSearchResults(rows, scoreTransformer = (s) => s) {
+    async _mapSearchResults(rows, scoreTransformer = (s) => s, options) {
         const transformContext = await this.getTransformContext();
         return await toArrayAsync(mapAsync(rows, async (row) => {
-            const { [searchScoreColumn]: rawScore, [searchHighlightColumn]: highlight, [searchHighlightPositionsColumn]: highlightPositions, ...entityRow } = row;
+            const { [searchScoreColumn]: rawScore, [searchHighlightColumn]: highlight, [searchHighlightPositionsColumn]: rawHighlightPositions, ...entityRow } = row;
+            const highlightPositions = isString(rawHighlightPositions) ? JSON.parse(rawHighlightPositions) : rawHighlightPositions;
             return {
-                entity: await this._mapToEntity(entityRow, transformContext),
+                entity: await this._mapToEntity(entityRow, transformContext, options?.includeSubclasses),
                 score: scoreTransformer(rawScore),
                 highlight: highlight,
                 highlightPositions,