@tstdl/base 0.92.122 → 0.92.124

package/orm/server/repository.js

@@ -5,16 +5,11 @@ 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;
 };
-var __metadata = (this && this.__metadata) || function (k, v) {
-    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
-};
-import { asc, count, desc, eq, inArray, isSQLWrapper, SQL, sql } from 'drizzle-orm';
-import { PgTransaction as DrizzlePgTransaction } from 'drizzle-orm/pg-core';
-import { createContextProvider } from '../../context/context.js';
+import { and, asc, count, desc, eq, inArray, isNull, isSQLWrapper, SQL, sql } from 'drizzle-orm';
+import { match } from 'ts-pattern';
 import { NotFoundError } from '../../errors/not-found.error.js';
 import { Singleton } from '../../injector/decorators.js';
-import { Injector } from '../../injector/index.js';
-import { inject, injectArgument, runInInjectionContext } from '../../injector/inject.js';
+import { inject, injectArgument } from '../../injector/inject.js';
 import { resolveArgumentType } from '../../injector/interfaces.js';
 import { Schema } from '../../schema/schema.js';
 import { toArray } from '../../utils/array/array.js';
@@ -26,80 +21,55 @@ import { fromDeepObjectEntries, fromEntries, objectEntries } from '../../utils/o
 import { assertDefinedPass, isArray, isDefined, isString, isUndefined } from '../../utils/type-guards.js';
 import { Entity } from '../entity.js';
 import { TRANSACTION_TIMESTAMP } from '../sqls.js';
-import { Database } from './database.js';
-import { getColumnDefinitions, getDrizzleTableFromType } from './drizzle/schema-converter.js';
+import { getColumnDefinitions, getColumnDefinitionsMap, getDrizzleTableFromType } from './drizzle/schema-converter.js';
 import { convertQuery } from './query-converter.js';
 import { ENCRYPTION_SECRET } from './tokens.js';
-import { DrizzleTransaction } from './transaction.js';
+import { getTransactionalContextData, isInTransactionalContext, Transactional } from './transactional.js';
 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');
-const { getCurrentEntityRepositoryContext, runInEntityRepositoryContext, isInEntityRepositoryContext } = createContextProvider('EntityRepository');
-let EntityRepository = class EntityRepository {
-    #context = getCurrentEntityRepositoryContext() ?? {};
-    #injector = inject(Injector);
-    #repositoryConstructor;
-    #withTransactionCache = new WeakMap();
-    #encryptionSecret = isInEntityRepositoryContext() ? this.#context.encryptionSecret : inject(ENCRYPTION_SECRET, undefined, { optional: true });
+let EntityRepository = class EntityRepository extends Transactional {
+    #context = isInTransactionalContext() ? getTransactionalContextData(this) : {};
+    #encryptionSecret = isInTransactionalContext() ? this.#context.encryptionSecret : inject(ENCRYPTION_SECRET, undefined, { optional: true });
     #transformContext = this.#context.transformContext;
     type = this.#context.type ?? injectArgument(this, { optional: true }) ?? assertDefinedPass(this.constructor[entityTypeToken], '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;
     #columnDefinitions = this.#context.columnDefinitions ?? getColumnDefinitions(this.#table);
-    #columnDefinitionsMap = this.#context.columnDefinitionsMap ?? new Map(this.#columnDefinitions.map((column) => [column.objectPath.path, column]));
-    session = this.#context.session ?? inject(Database);
-    isInTransaction = this.session instanceof DrizzlePgTransaction;
+    #columnDefinitionsMap = this.#context.columnDefinitionsMap ?? getColumnDefinitionsMap(this.#table);
     hasMetadata = typeExtends(this.type, Entity);
+    /**
+     * Gets the Drizzle table definition for the entity type.
+     */
     get table() {
         return this.#table;
     }
-    get isFork() {
-        return this.isInTransaction;
-    }
-    constructor() {
-        this.#repositoryConstructor = new.target;
-    }
-    withOptionalTransaction(transaction) {
-        if (isUndefined(transaction)) {
-            return this;
-        }
-        return this.withTransaction(transaction);
-    }
-    withTransaction(transaction) {
-        if (this.#withTransactionCache.has(transaction)) {
-            return this.#withTransactionCache.get(transaction);
-        }
+    getTransactionalContextData() {
         const context = {
             type: this.type,
             table: this.#table,
             columnDefinitions: this.#columnDefinitions,
             columnDefinitionsMap: this.#columnDefinitionsMap,
-            session: transaction.transaction,
             encryptionSecret: this.#encryptionSecret,
-            transformContext: this.#transformContext
+            transformContext: this.#transformContext,
         };
-        const repositoryWithTransaction = runInInjectionContext(this.#injector, () => runInEntityRepositoryContext(context, () => new this.#repositoryConstructor()));
-        this.#withTransactionCache.set(transaction, repositoryWithTransaction);
-        return repositoryWithTransaction;
-    }
-    async startTransaction(config) {
-        return DrizzleTransaction.create(this.session, config);
-    }
-    async useTransaction(transaction, handler) {
-        if (isUndefined(transaction)) {
-            return this.transaction(handler);
-        }
-        const repository = this.withTransaction(transaction);
-        return transaction.use(async () => handler(repository, transaction));
-    }
-    async transaction(handler, config) {
-        const transaction = await DrizzleTransaction.create(this.session, config);
-        const repository = this.withTransaction(transaction);
-        return transaction.use(async () => handler(repository, transaction));
+        return context;
     }
+    /**
+     * Loads a single entity by its ID.
+     * Throws `NotFoundError` if the entity is not found.
+     * @param id The ID of the entity to load.
+     * @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);
         if (isUndefined(entity)) {
@@ -107,9 +77,23 @@ let EntityRepository = class EntityRepository {
         }
         return entity;
     }
+    /**
+     * 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.
+     * @returns A promise that resolves to the loaded entity or `undefined` if not found.
+     */
     async tryLoad(id) {
         return this.tryLoadByQuery(eq(this.#table.id, id));
     }
+    /**
+     * Loads a single entity based on a query.
+     * Throws `NotFoundError` if no entity matches the query.
+     * @param query The query to filter entities.
+     * @param options Optional loading options (e.g., offset, order).
+     * @returns A promise that resolves to the loaded entity.
+     * @throws {NotFoundError} If no entity matches the query.
+     */
     async loadByQuery(query, options) {
         const entity = await this.tryLoadByQuery(query, options);
         if (isUndefined(entity)) {
@@ -117,6 +101,13 @@ let EntityRepository = class EntityRepository {
         }
         return entity;
     }
+    /**
+     * Tries to load a single entity based on a query.
+     * Returns `undefined` if no entity matches the query.
+     * @param query The query to filter entities.
+     * @param options Optional loading options (e.g., offset, order).
+     * @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()
@@ -133,46 +124,97 @@ let EntityRepository = class EntityRepository {
         }
         return this.mapToEntity(row);
     }
+    /**
+     * Loads multiple entities by their IDs.
+     * @param ids An array of entity IDs to load.
+     * @param options Optional loading options (e.g., offset, limit, order).
+     * @returns A promise that resolves to an array of loaded entities.
+     */
     async loadMany(ids, options) {
         return this.loadManyByQuery(inArray(this.#table.id, ids), options);
     }
+    /**
+     * Loads multiple entities by their IDs and returns them as an async iterable cursor.
+     * @param ids An array of entity IDs to load.
+     * @param options Optional loading options (e.g., offset, limit, order).
+     * @returns An async iterable iterator of loaded entities.
+     */
     async *loadManyCursor(ids, options) {
         const entities = await this.loadMany(ids, options);
         yield* entities;
     }
+    /**
+     * Loads multiple entities based on a query.
+     * @param query The query to filter entities.
+     * @param options Optional loading options (e.g., offset, limit, order).
+     * @returns A promise that resolves to an array of loaded entities.
+     */
     async loadManyByQuery(query, options) {
         const sqlQuery = this.convertQuery(query);
-        let dbQuery = this.session.select()
+        let dbQuery = match(options?.distinct ?? false)
+            .with(false, () => this.session.select())
+            .with(true, () => this.session.selectDistinct())
+            .otherwise((targets) => {
+            const ons = targets.map((target) => isString(target) ? this.getColumn(target) : target);
+            return this.session.selectDistinctOn(ons);
+        })
             .from(this.#table)
+            .$dynamic();
+        dbQuery = dbQuery
             .where(sqlQuery)
-            .orderBy()
             .offset(options?.offset)
-            .limit(options?.limit)
-            .$dynamic();
+            .limit(options?.limit);
         if (isDefined(options?.order)) {
             dbQuery = dbQuery.orderBy(...this.convertOrderBy(options.order));
         }
         const rows = await dbQuery;
         return this.mapManyToEntity(rows);
     }
+    /**
+     * Loads multiple entities based on a query and returns them as an async iterable cursor.
+     * @param query The query to filter entities.
+     * @param options Optional loading options (e.g., offset, limit, order).
+     * @returns An async iterable iterator of loaded entities.
+     */
     async *loadManyByQueryCursor(query, options) {
         const entities = await this.loadManyByQuery(query, options);
         yield* entities;
     }
+    /**
+     * Loads all entities of the repository's type.
+     * @param options Optional loading options (e.g., offset, limit, order).
+     * @returns A promise that resolves to an array of all entities.
+     */
     async loadAll(options) {
         return this.loadManyByQuery({}, options);
     }
+    /**
+     * Loads all entities of the repository's type and returns them as an async iterable cursor.
+     * @param options Optional loading options (e.g., offset, limit, order).
+     * @returns An async iterable iterator of all entities.
+     */
     async *loadAllCursor(options) {
         const entities = await this.loadAll(options);
         yield* entities;
     }
+    /**
+     * Counts the total number of entities of the repository's type.
+     * @returns A promise that resolves to the total count.
+     */
     async count() {
+        const sqlQuery = this.convertQuery({});
         const dbQuery = this.session
             .select({ count: count() })
-            .from(this.#table);
+            .from(this.#table)
+            .where(sqlQuery);
         const [result] = await dbQuery;
         return assertDefinedPass(result).count;
     }
+    /**
+     * Counts the number of entities matching a query.
+     * @param query The query to filter entities.
+     * @returns A promise that resolves to the count of matching entities.
+     */
     async countByQuery(query) {
         const sqlQuery = this.convertQuery(query);
         const dbQuery = this.session
@@ -182,9 +224,19 @@ let EntityRepository = class EntityRepository {
         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.
+     * @returns A promise that resolves to `true` if the entity exists, `false` otherwise.
+     */
     async has(id) {
         return this.hasByQuery(eq(this.#table.id, id));
     }
+    /**
+     * Checks if any entity matches the given query.
+     * @param query The query to filter entities.
+     * @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 dbQuery = this.session
@@ -193,10 +245,17 @@ let EntityRepository = class EntityRepository {
         const [result] = await dbQuery;
         return assertDefinedPass(result).exists;
     }
+    /**
+     * Checks if all entities with the given IDs exist.
+     * @param ids An array of entity IDs to check.
+     * @returns A promise that resolves to `true` if all entities exist, `false` otherwise.
+     */
     async hasAll(ids) {
+        const sqlQuery = this.convertQuery({});
         const result = await this.session
             .select({ contains: sql `array_agg(${this.#table.id}) @> ${ids}`.as('contains') })
-            .from(this.#table);
+            .from(this.#table)
+            .where(sqlQuery);
         return assertDefinedPass(result[0]).contains;
     }
     /**
@@ -216,6 +275,11 @@ let EntityRepository = class EntityRepository {
         }
         return this.mapToEntity(row);
     }
+    /**
+     * 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
@@ -224,11 +288,23 @@ let EntityRepository = class EntityRepository {
             .returning();
         return this.mapToEntity(row);
     }
+    /**
+     * Inserts multiple new entities into the database.
+     * @param entities An array of entities to insert.
+     * @returns A promise that resolves to an array of the inserted entities.
+     */
     async insertMany(entities) {
         const columns = await this.mapManyToInsertColumns(entities);
         const rows = await this.session.insert(this.#table).values(columns).returning();
         return this.mapManyToEntity(rows);
     }
+    /**
+     * Inserts an entity or updates it if a conflict occurs based on the target columns.
+     * @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.
+     * @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);
@@ -238,11 +314,18 @@ let EntityRepository = class EntityRepository {
             .values(columns)
             .onConflictDoUpdate({
             target: targetColumns,
-            set: mappedUpdate
+            set: mappedUpdate,
         })
             .returning();
         return this.mapToEntity(row);
     }
+    /**
+     * 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.
+     * @returns A promise that resolves to an array of the inserted or updated entities.
+     */
     async upsertMany(target, entities, update) {
         const targetColumns = toArray(target).map((path) => this.getColumn(path));
         const columns = await this.mapManyToInsertColumns(entities);
@@ -250,18 +333,26 @@ let EntityRepository = class EntityRepository {
             ? await this.mapUpdate(update)
             : {
                 ...fromEntries(this.#columnDefinitions.map((column) => [column.name, sql `excluded.${sql.identifier(this.getColumn(column).name)}`])),
-                ...this._getMetadataUpdate(update)
+                ...this._getMetadataUpdate(update),
             };
         const rows = await this.session
             .insert(this.#table)
             .values(columns)
             .onConflictDoUpdate({
             target: targetColumns,
-            set: mappedUpdate
+            set: mappedUpdate,
         })
             .returning();
         return this.mapManyToEntity(rows);
     }
+    /**
+     * 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.
+     * @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);
         if (isUndefined(entity)) {
@@ -269,18 +360,34 @@ let EntityRepository = class EntityRepository {
         }
         return entity;
     }
+    /**
+     * 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.
+     * @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(eq(this.#table.id, id))
+            .where(sqlQuery)
             .returning();
         if (isUndefined(row)) {
             return undefined;
         }
         return this.mapToEntity(row);
     }
+    /**
+     * 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.
+     * @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);
         if (isUndefined(entity)) {
@@ -288,6 +395,13 @@ let EntityRepository = class EntityRepository {
         }
         return entity;
     }
+    /**
+     * Tries to update a single entity matching a query.
+     * Returns `undefined` if no entity matches the query.
+     * @param query The query to filter entities.
+     * @param update The update to apply to the entity.
+     * @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.getIdLimitSelect(query);
@@ -301,9 +415,21 @@ let EntityRepository = class EntityRepository {
         }
         return this.mapToEntity(row);
     }
+    /**
+     * Updates multiple entities by their IDs.
+     * @param ids An array of entity IDs to update.
+     * @param update The update to apply to the entities.
+     * @returns A promise that resolves to an array of the updated entities.
+     */
     async updateMany(ids, update) {
         return this.updateManyByQuery(inArray(this.#table.id, ids), update);
     }
+    /**
+     * Updates multiple entities matching a query.
+     * @param query The query to filter entities.
+     * @param update The update to apply to the entities.
+     * @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);
@@ -314,6 +440,14 @@ let EntityRepository = class EntityRepository {
             .returning();
         return this.mapManyToEntity(rows);
     }
+    /**
+     * 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 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);
         if (isUndefined(entity)) {
@@ -321,23 +455,39 @@ let EntityRepository = class EntityRepository {
         }
         return entity;
     }
+    /**
+     * 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 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) {
         if (!this.hasMetadata) {
             return this.tryHardDelete(id);
         }
+        const sqlQuery = this.convertQuery(eq(this.#table.id, id));
         const [row] = await this.session
             .update(this.#tableWithMetadata)
             .set({
             deleteTimestamp: TRANSACTION_TIMESTAMP,
-            attributes: this.getAttributesUpdate(metadataUpdate?.attributes)
+            attributes: this.getAttributesUpdate(metadataUpdate?.attributes),
         })
-            .where(eq(this.#table.id, id))
+            .where(sqlQuery)
             .returning();
         if (isUndefined(row)) {
             return undefined;
         }
         return this.mapToEntity(row);
     }
+    /**
+     * 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 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);
         if (isUndefined(entity)) {
@@ -345,6 +495,13 @@ let EntityRepository = class EntityRepository {
         }
         return entity;
     }
+    /**
+     * 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 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) {
         if (!this.hasMetadata) {
             return this.tryHardDeleteByQuery(query);
@@ -354,7 +511,7 @@ let EntityRepository = class EntityRepository {
             .update(this.#tableWithMetadata)
             .set({
             deleteTimestamp: TRANSACTION_TIMESTAMP,
-            attributes: this.getAttributesUpdate(metadataUpdate?.attributes)
+            attributes: this.getAttributesUpdate(metadataUpdate?.attributes),
         })
             .where(inArray(this.#table.id, idQuery.for('update')))
             .returning();
@@ -363,9 +520,21 @@ let EntityRepository = class EntityRepository {
         }
         return this.mapToEntity(row);
     }
+    /**
+     * Deletes multiple entities by their IDs (soft delete if metadata is available).
+     * @param ids An array of entity IDs to delete.
+     * @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) {
         return this.deleteManyByQuery(inArray(this.#table.id, ids), metadataUpdate);
     }
+    /**
+     * Deletes multiple entities matching a query (soft delete if metadata is available).
+     * @param query The query to filter entities.
+     * @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) {
         if (!this.hasMetadata) {
             return this.hardDeleteManyByQuery(query);
@@ -375,12 +544,19 @@ let EntityRepository = class EntityRepository {
             .update(this.#tableWithMetadata)
             .set({
             deleteTimestamp: TRANSACTION_TIMESTAMP,
-            attributes: this.getAttributesUpdate(metadataUpdate?.attributes)
+            attributes: this.getAttributesUpdate(metadataUpdate?.attributes),
         })
             .where(sqlQuery)
             .returning();
         return this.mapManyToEntity(rows);
     }
+    /**
+     * 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.
+     * @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);
         if (!result) {
@@ -388,16 +564,30 @@ let EntityRepository = class EntityRepository {
         }
         return result;
     }
+    /**
+     * 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.
+     * @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));
         const [row] = await this.session
             .delete(this.#table)
-            .where(eq(this.#table.id, id))
+            .where(sqlQuery)
             .returning();
         if (isUndefined(row)) {
             return undefined;
         }
         return this.mapToEntity(row);
     }
+    /**
+     * 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.
+     * @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);
         if (!result) {
@@ -405,6 +595,12 @@ let EntityRepository = class EntityRepository {
         }
         return result;
     }
+    /**
+     * 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.
+     * @returns A promise that resolves to the hard deleted entity or `undefined` if not found.
+     */
     async tryHardDeleteByQuery(query) {
         const idQuery = this.getIdLimitSelect(query);
         const [row] = await this.session
@@ -416,9 +612,19 @@ let EntityRepository = class EntityRepository {
         }
         return this.mapToEntity(row);
     }
+    /**
+     * Hard deletes multiple entities by their IDs (removes from the database).
+     * @param ids An array of entity IDs to hard delete.
+     * @returns A promise that resolves to an array of the hard deleted entities.
+     */
     async hardDeleteMany(ids) {
         return this.hardDeleteManyByQuery(inArray(this.#table.id, ids));
     }
+    /**
+     * Hard deletes multiple entities matching a query (removes from the database).
+     * @param query The query to filter entities.
+     * @returns A promise that resolves to an array of the hard deleted entities.
+     */
     async hardDeleteManyByQuery(query) {
         const sqlQuery = this.convertQuery(query);
         const rows = await this.session
@@ -427,6 +633,11 @@ let EntityRepository = class EntityRepository {
             .returning();
         return this.mapManyToEntity(rows);
     }
+    /**
+     * Retrieves the Drizzle PgColumn for a given object path or column definition.
+     * @param pathOrColumn The object path or column definition.
+     * @returns The corresponding PgColumn.
+     */
     getColumn(pathOrColumn) {
         if (isString(pathOrColumn)) {
             const columnName = assertDefinedPass(this.#columnDefinitionsMap.get(pathOrColumn), `Could not map ${pathOrColumn} to column.`).name;
@@ -434,6 +645,14 @@ let EntityRepository = class EntityRepository {
         }
         return this.#table[pathOrColumn.name];
     }
+    getColumns(pathOrColumns) {
+        return pathOrColumns.map((column) => this.getColumn(column));
+    }
+    /**
+     * Converts an Order object to an array of Drizzle SQL order expressions.
+     * @param order The order object.
+     * @returns An array of SQL order expressions.
+     */
     convertOrderBy(order) {
         if (isArray(order)) {
             return order.map((item) => {
@@ -453,37 +672,89 @@ let EntityRepository = class EntityRepository {
             return direction == 'asc' ? asc(column) : desc(column);
         });
     }
-    convertQuery(query) {
-        return convertQuery(query, this.#table, this.#columnDefinitionsMap);
+    /**
+     * Converts a Query object to a Drizzle SQL where clause.
+     * Automatically filters out soft-deleted entities unless `withDeleted` is true.
+     * @param query The query object.
+     * @param options Optional options, including `withDeleted` to include soft-deleted entities.
+     * @returns A Drizzle SQL condition.
+     */
+    convertQuery(query, options) {
+        let sql = convertQuery(query, this.#table, this.#columnDefinitionsMap);
+        if (!this.hasMetadata || (options?.withDeleted == true)) {
+            return sql;
+        }
+        return and(isNull(this.#tableWithMetadata.deleteTimestamp), sql);
     }
+    /**
+     * Maps multiple database rows to an array of entities.
+     * @param columns An array of database rows.
+     * @returns A promise that resolves to an array of entities.
+     */
     async mapManyToEntity(columns) {
         const transformContext = await this.getTransformContext();
         return this._mapManyToEntity(columns, transformContext);
     }
+    /**
+     * Maps a single database row to an entity.
+     * @param columns A database row.
+     * @returns A promise that resolves to an entity.
+     */
     async mapToEntity(columns) {
         const transformContext = await this.getTransformContext();
         return this._mapToEntity(columns, transformContext);
     }
+    /**
+     * Maps multiple entity-like objects to database column values for insertion or update.
+     * @param objects An array of entity-like objects.
+     * @returns A promise that resolves to an array of database column values.
+     */
     async mapManyToColumns(objects) {
         const transformContext = await this.getTransformContext();
         return this._mapManyToColumns(objects, transformContext);
     }
+    /**
+     * Maps a single entity-like object to database column values for insertion or update.
+     * @param obj An entity-like object.
+     * @returns A promise that resolves to database column values.
+     */
     async mapToColumns(obj) {
         const transformContext = await this.getTransformContext();
         return this._mapToColumns(obj, transformContext);
     }
+    /**
+     * Maps multiple new entity objects to database column values for insertion.
+     * @param objects An array of new entity objects.
+     * @returns A promise that resolves to an array of database column values for insertion.
+     */
     async mapManyToInsertColumns(objects) {
         const transformContext = await this.getTransformContext();
         return this._mapManyToInsertColumns(objects, transformContext);
     }
+    /**
+     * Maps a new entity object to database column values for insertion.
+     * @param obj A new entity object.
+     * @returns A promise that resolves to database column values for insertion.
+     */
     async mapToInsertColumns(obj) {
         const transformContext = await this.getTransformContext();
         return this._mapToInsertColumns(obj, transformContext);
     }
+    /**
+     * Maps an entity update object to database column values for updating.
+     * @param update The entity update object.
+     * @returns A promise that resolves to database column values for updating.
+     */
     async mapUpdate(update) {
         const transformContext = await this.getTransformContext();
         return this._mapUpdate(update, transformContext);
     }
+    /**
+     * 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.
+     * @returns A Drizzle select query for the entity ID.
+     */
     getIdLimitQuery(query) {
         return this.getIdLimitSelect(query);
     }
@@ -531,9 +802,9 @@ let EntityRepository = class EntityRepository {
                 ? {
                     revision: 1,
                     revisionTimestamp: TRANSACTION_TIMESTAMP,
-                    createTimestamp: TRANSACTION_TIMESTAMP
+                    createTimestamp: TRANSACTION_TIMESTAMP,
                 }
-                : undefined)
+                : undefined),
         };
     }
     async _mapUpdate(update, transformContext) {
@@ -547,7 +818,7 @@ let EntityRepository = class EntityRepository {
         }
         return {
             ...mappedUpdate,
-            ...this._getMetadataUpdate(update)
+            ...this._getMetadataUpdate(update),
         };
     }
     _getMetadataUpdate(update) {
@@ -555,7 +826,7 @@ let EntityRepository = class EntityRepository {
             ? {
                 attributes: this.getAttributesUpdate(update?.metadata?.attributes),
                 revision: sql `${this.#tableWithMetadata.revision} + 1`,
-                revisionTimestamp: TRANSACTION_TIMESTAMP
+                revisionTimestamp: TRANSACTION_TIMESTAMP,
             }
             : undefined;
     }
@@ -580,19 +851,30 @@ let EntityRepository = class EntityRepository {
     }
 };
 EntityRepository = __decorate([
-    Singleton(),
-    __metadata("design:paramtypes", [])
+    Singleton()
 ], EntityRepository);
 export { EntityRepository };
+/**
+ * Injects an EntityRepository instance for the specified entity type.
+ * @template T The entity type.
+ * @param type The entity type.
+ * @returns An EntityRepository instance for the specified type.
+ */
 export function injectRepository(type) {
     return inject((EntityRepository), type);
 }
+/**
+ * Gets or creates a singleton EntityRepository class for the specified entity type.
+ * @template T The entity type.
+ * @param type The entity type.
+ * @returns A singleton EntityRepository class for the specified type.
+ */
 export function getRepository(type) {
     const className = `${type.name}Service`;
     const entityRepositoryClass = {
         [className]: class extends EntityRepository {
             static [entityTypeToken] = type;
-        }
+        },
     }[className];
     Singleton()(entityRepositoryClass);
     return entityRepositoryClass;