@tstdl/base 0.93.87 → 0.93.90

package/orm/server/repository.d.ts

@@ -1,23 +1,15 @@
 import { SQL, type SQLWrapper } from 'drizzle-orm';
-import type { PgColumn, PgInsertValue, PgSelectBuilder, PgUpdateSetSource, SelectedFields } from 'drizzle-orm/pg-core';
+import type { AnyPgTable, PgColumn, PgInsertValue, PgSelectBuilder, PgUpdateSetSource, SelectedFields } from 'drizzle-orm/pg-core';
 import { afterResolve, resolveArgumentType, type Resolvable } from '../../injector/interfaces.js';
 import type { DeepPartial, Function, OneOrMany, Record, SimplifyObject, Type, TypedOmit } from '../../types/index.js';
 import { Entity, type BaseEntity, type EntityMetadataAttributes, type EntityType } from '../entity.js';
 import type { ParadeSearchQuery, Query, TrigramSearchQuery, TsVectorSearchQuery } from '../query/index.js';
-import type { EntityMetadataUpdate, EntityUpdate, LoadManyOptions, LoadOptions, NewEntity, Order, SearchOptions, SearchResult, TargetColumn, TargetColumnPath } from '../repository.types.js';
+import type { CountOptions, DeleteOptions, EntityMetadataUpdate, EntityUpdate, HasOptions, LoadManyOptions, LoadOptions, NewEntity, Order, SearchOptions, SearchResult, TargetColumn, TargetColumnPath, UpdateOptions } from '../repository.types.js';
 import type { Database } from './database.js';
 import type { PgTransaction } from './transaction.js';
 import { Transactional } from './transactional.js';
 import type { ColumnDefinition, PgTableFromType, TransformContext } from './types.js';
 export declare const repositoryType: unique symbol;
-/**
- * Configuration class for EntityRepository.
- * Specifies the database schema to be used.
- */
-export declare class EntityRepositoryConfig {
-    /** The name of the database schema. */
-    schema: string;
-}
 type EntityRepositoryContext = {
     type: EntityType;
     table: PgTableFromType;
@@ -38,6 +30,11 @@ export declare class EntityRepository<T extends BaseEntity = BaseEntity> extends
     get table(): PgTableFromType<EntityType<T>>;
     readonly [resolveArgumentType]: EntityType<T>;
     [afterResolve](): void;
+    /**
+     * Processes expired entities (soft or hard delete) based on metadata.
+     * Exposed primarily for testing, but can be used in other scenarios as needed.
+     */
+    processExpirations(): Promise<void>;
     private expirationLoop;
     protected getTransactionalContextData(): EntityRepositoryContext;
     protected tsVectorSearch(options: SearchOptions<T> & {
@@ -60,17 +57,19 @@ export declare class EntityRepository<T extends BaseEntity = BaseEntity> extends
      * 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.
      */
-    load(id: string): Promise<T>;
+    load(id: string, options?: LoadOptions<T>): Promise<T>;
     /**
      * 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.
      */
-    tryLoad(id: string): Promise<T | undefined>;
+    tryLoad(id: string, options?: LoadOptions<T>): Promise<T | undefined>;
     /**
      * Loads a single entity based on a query.
      * Throws `NotFoundError` if no entity matches the query.
@@ -130,27 +129,31 @@ export declare class EntityRepository<T extends BaseEntity = BaseEntity> extends
     loadAllCursor(options?: LoadManyOptions<T>): AsyncIterableIterator<T>;
     /**
      * 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.
      */
-    count(): Promise<number>;
+    count(options?: CountOptions<T>): Promise<number>;
     /**
      * 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.
      */
-    countByQuery(query: Query<T>): Promise<number>;
+    countByQuery(query: Query<T>, options?: CountOptions<T>): Promise<number>;
     /**
      * 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.
      */
-    has(id: string): Promise<boolean>;
+    has(id: string, options?: HasOptions<T>): Promise<boolean>;
     /**
      * 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.
      */
-    hasByQuery(query: Query<T>): Promise<boolean>;
+    hasByQuery(query: Query<T>, options?: HasOptions<T>): Promise<boolean>;
     /**
      * Checks if all entities with the given IDs exist.
      * @param ids An array of entity IDs to check.
@@ -163,6 +166,8 @@ export declare class EntityRepository<T extends BaseEntity = BaseEntity> extends
      * @returns entity if inserted, undefined on conflict
      */
     tryInsert(entity: NewEntity<T>): Promise<T | undefined>;
+    private insertCTI;
+    private insertManyCTI;
     /**
      * Inserts a new entity into the database.
      * @param entity The entity to insert.
@@ -191,54 +196,84 @@ export declare class EntityRepository<T extends BaseEntity = BaseEntity> extends
     insertManyIfNotExists(target: OneOrMany<TargetColumnPath<T>>, entities: NewEntity<T>[]): Promise<T[]>;
     /**
      * 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.
      */
-    upsert(target: OneOrMany<TargetColumnPath<T>>, entity: NewEntity<T>, update?: EntityUpdate<T>): Promise<T>;
+    upsert(target: OneOrMany<TargetColumnPath<T>>, entity: NewEntity<T>, update?: EntityUpdate<T>, wheres?: {
+        target?: Query<T>;
+        set?: Query<T>;
+    }): Promise<T>;
+    private tryUpsertCTI;
+    /**
+     * 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`.
+     */
+    tryUpsert(target: OneOrMany<TargetColumnPath<T>>, entity: NewEntity<T>, update?: EntityUpdate<T>, wheres?: {
+        target?: Query<T>;
+        set?: Query<T>;
+    }): Promise<T | undefined>;
+    private upsertManyCTI;
     /**
      * 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.
      */
-    upsertMany(target: OneOrMany<TargetColumnPath<T>>, entities: NewEntity<T>[], update?: EntityUpdate<T>): Promise<T[]>;
+    upsertMany(target: OneOrMany<TargetColumnPath<T>>, entities: NewEntity<T>[], update?: EntityUpdate<T>, wheres?: {
+        target?: Query<T>;
+        set?: Query<T>;
+    }): Promise<T[]>;
     /**
      * 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.
      */
-    update(id: string, update: EntityUpdate<T>): Promise<T>;
+    update(id: string, update: EntityUpdate<T>, options?: UpdateOptions<T>): Promise<T>;
+    private tryUpdateCTI;
+    private updateManyCTI;
     /**
      * 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.
      */
-    tryUpdate(id: string, update: EntityUpdate<T>): Promise<T | undefined>;
+    tryUpdate(id: string, update: EntityUpdate<T>, options?: UpdateOptions<T>): Promise<T | undefined>;
     /**
      * 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.
      */
-    updateByQuery(query: Query<T>, update: EntityUpdate<T>): Promise<T>;
+    updateByQuery(query: Query<T>, update: EntityUpdate<T>, options?: UpdateOptions<T>): Promise<T>;
     /**
      * 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.
+     * @param options Optional update options.
      * @returns A promise that resolves to the updated entity or `undefined` if not found.
      */
-    tryUpdateByQuery(query: Query<T>, update: EntityUpdate<T>): Promise<T | undefined>;
+    tryUpdateByQuery(query: Query<T>, update: EntityUpdate<T>, options?: UpdateOptions<T>): Promise<T | undefined>;
     /**
      * Updates multiple entities by their IDs.
      * @param ids An array of entity IDs to update.
@@ -257,92 +292,104 @@ export declare class EntityRepository<T extends BaseEntity = BaseEntity> extends
      * 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.
      */
-    delete(id: string, metadataUpdate?: EntityMetadataUpdate): Promise<T>;
+    delete(id: string, options?: DeleteOptions<T>, metadataUpdate?: EntityMetadataUpdate): Promise<T>;
     /**
      * 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.
      */
-    tryDelete(id: string, metadataUpdate?: EntityMetadataUpdate): Promise<T | undefined>;
+    tryDelete(id: string, options?: DeleteOptions<T>, metadataUpdate?: EntityMetadataUpdate): Promise<T | undefined>;
     /**
      * 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.
      */
-    deleteByQuery(query: Query<T>, metadataUpdate?: EntityMetadataUpdate): Promise<T>;
+    deleteByQuery(query: Query<T>, options?: DeleteOptions<T>, metadataUpdate?: EntityMetadataUpdate): Promise<T>;
     /**
      * 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.
      */
-    tryDeleteByQuery(query: Query<T>, metadataUpdate?: EntityMetadataUpdate): Promise<T | undefined>;
+    tryDeleteByQuery(query: Query<T>, options?: DeleteOptions<T>, metadataUpdate?: EntityMetadataUpdate): Promise<T | undefined>;
     /**
      * 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.
      */
-    deleteMany(ids: string[], metadataUpdate?: EntityMetadataUpdate): Promise<T[]>;
+    deleteMany(ids: string[], options?: DeleteOptions<T>, metadataUpdate?: EntityMetadataUpdate): Promise<T[]>;
     /**
      * 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.
      */
-    deleteManyByQuery(query: Query<T>, metadataUpdate?: EntityMetadataUpdate): Promise<T[]>;
+    deleteManyByQuery(query: Query<T>, options?: DeleteOptions<T>, metadataUpdate?: EntityMetadataUpdate): Promise<T[]>;
     /**
      * 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.
      */
-    hardDelete(id: string): Promise<T>;
+    hardDelete(id: string, options?: DeleteOptions<T>): Promise<T>;
     /**
      * 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.
      */
-    tryHardDelete(id: string): Promise<T | undefined>;
+    tryHardDelete(id: string, options?: DeleteOptions<T>): Promise<T | undefined>;
     /**
      * 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.
      */
-    hardDeleteByQuery(query: Query<T>): Promise<T>;
+    hardDeleteByQuery(query: Query<T>, options?: DeleteOptions<T>): Promise<T>;
     /**
      * 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.
      */
-    tryHardDeleteByQuery(query: Query<T>): Promise<T | undefined>;
+    tryHardDeleteByQuery(query: Query<T>, options?: DeleteOptions<T>): Promise<T | undefined>;
     /**
      * 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.
      */
-    hardDeleteMany(ids: string[]): Promise<T[]>;
+    hardDeleteMany(ids: string[], options?: DeleteOptions<T>): Promise<T[]>;
     /**
      * 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.
      */
-    hardDeleteManyByQuery(query: Query<T>): Promise<T[]>;
+    hardDeleteManyByQuery(query: Query<T>, options?: DeleteOptions<T>): Promise<T[]>;
     /**
      * Resolves a target column from an object path or column definition to a Drizzle SQL wrapper.
      * @param target The object path or column definition.
@@ -376,18 +423,26 @@ export declare class EntityRepository<T extends BaseEntity = BaseEntity> extends
     convertQuery(query: Query<T>, options?: {
         withDeleted?: boolean;
     }): SQL;
+    private _convertQuery;
+    private filterQuery;
     /**
      * 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.
      */
-    mapManyToEntity(columns: InferSelect[]): Promise<T[]>;
+    mapManyToEntity(columns: InferSelect[], options?: {
+        includeSubclasses?: boolean | EntityType[];
+    }): Promise<T[]>;
     /**
      * 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.
      */
-    mapToEntity(columns: InferSelect): Promise<T>;
+    mapToEntity(columns: InferSelect, options?: {
+        includeSubclasses?: boolean | EntityType[];
+    }): Promise<T>;
     /**
      * Maps multiple entity-like objects to database column values for insertion or update.
      * @param objects An array of entity-like objects.
@@ -422,9 +477,12 @@ export declare class EntityRepository<T extends BaseEntity = BaseEntity> extends
      * 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: Query<T>): Omit<import("drizzle-orm/pg-core").PgSelectBase<string, {
+    getIdLimitQuery(query: Query<T>, options?: {
+        withDeleted?: boolean;
+    }): import("drizzle-orm/pg-core").PgSelectBase<string, {
         id: PgColumn<{
             name: string;
             tableName: string;
@@ -442,7 +500,7 @@ export declare class EntityRepository<T extends BaseEntity = BaseEntity> extends
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
-    }, "partial", globalThis.Record<string, "not-null">, false, "limit" | "where", {
+    }, "partial", globalThis.Record<string, "not-null">, true, never, {
         id: string;
     }[], {
         id: PgColumn<{
@@ -462,20 +520,36 @@ export declare class EntityRepository<T extends BaseEntity = BaseEntity> extends
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
-    }>, "limit" | "where">;
+    }>;
     applySelect<TApplyTo extends Record<'select' | 'selectDistinct' | 'selectDistinctOn', Function<any[], PgSelectBuilder<any, any>>>>(applyTo: TApplyTo, distinct?: boolean | TargetColumn<T>[]): PgSelectBuilder<undefined, ReturnType<TApplyTo['selectDistinct']> extends PgSelectBuilder<any, infer TResult> ? TResult : never>;
     applySelect<TApplyTo extends Record<'select' | 'selectDistinct' | 'selectDistinctOn', Function<any[], PgSelectBuilder<any, any>>>, TSelection extends SelectedFields>(applyTo: TApplyTo, selection: TSelection, distinct?: boolean | TargetColumn<T>[]): PgSelectBuilder<TSelection, ReturnType<TApplyTo['selectDistinct']> extends PgSelectBuilder<any, infer TResult> ? TResult : never>;
     protected getAttributesUpdate(attributes: SQL | EntityMetadataAttributes | undefined): SQL<unknown> | undefined;
-    protected _mapManyToEntity(columns: InferSelect[], transformContext: TransformContext): Promise<T[]>;
-    protected _mapToEntity(columns: InferSelect, transformContext: TransformContext): Promise<T>;
+    private applyJoins;
+    private getTablesChain;
+    protected _mapManyToEntity(columns: InferSelect[], transformContext: TransformContext, includeSubclasses?: boolean | EntityType[]): Promise<T[]>;
+    protected _mapToEntity(columns: InferSelect, transformContext: TransformContext, includeSubclasses?: boolean | EntityType[]): Promise<T>;
     protected _mapManyToColumns(objects: (DeepPartial<T> | NewEntity<T>)[], transformContext: TransformContext): Promise<PgInsertValue<PgTableFromType>[]>;
-    protected _mapToColumns(obj: DeepPartial<T> | NewEntity<T>, transformContext: TransformContext): Promise<PgInsertValue<PgTableFromType>>;
+    protected _mapToTableColumns(obj: DeepPartial<T> | NewEntity<T>, transformContext: TransformContext, definitions?: ColumnDefinition[]): Promise<PgInsertValue<PgTableFromType>>;
+    protected _mapToTableInsertColumns(obj: DeepPartial<T> | NewEntity<T>, transformContext: TransformContext, table: PgTableFromType, definitions?: ColumnDefinition[]): Promise<PgInsertValue<PgTableFromType>>;
     protected _mapManyToInsertColumns(objects: (DeepPartial<T> | NewEntity<T>)[], transformContext: TransformContext): Promise<PgInsertValue<PgTableFromType>[]>;
     protected _mapToInsertColumns(obj: DeepPartial<T> | NewEntity<T>, transformContext: TransformContext): Promise<PgInsertValue<PgTableFromType>>;
+    protected _mapToTableUpdate(update: EntityUpdate<T>, transformContext: TransformContext, table: AnyPgTable, definitions?: ColumnDefinition[]): Promise<PgUpdateSetSource<PgTableFromType>>;
     protected _mapUpdate(update: EntityUpdate<T>, transformContext: TransformContext): Promise<PgUpdateSetSource<PgTableFromType>>;
     protected _getMetadataUpdate(update?: EntityUpdate<T>): PgUpdateSetSource<PgTableFromType<EntityType<Entity>>> | undefined;
+    private prepareSubclassJoins;
+    private addSubclassColumnsToSelection;
+    private applySubclassJoins;
+    protected createBaseQuery(options?: TypedOmit<LoadManyOptions<T>, 'order'>, extraSelection?: SelectedFields): import("drizzle-orm/pg-core").PgSelectBase<string, {
+        [x: string]: SQL<unknown> | SQL.Aliased<unknown> | import("drizzle-orm").Subquery<string, globalThis.Record<string, unknown>> | PgColumn<import("drizzle-orm").ColumnBaseConfig<import("drizzle-orm").ColumnDataType, string>, {}, {}> | import("drizzle-orm/pg-core").PgTable<import("drizzle-orm/pg-core").TableConfig> | import("drizzle-orm").SelectedFieldsFlat<PgColumn<import("drizzle-orm").ColumnBaseConfig<import("drizzle-orm").ColumnDataType, string>, {}, {}>>;
+    }, "partial", globalThis.Record<string, "not-null">, true, never, {
+        [x: string]: unknown;
+    }[], {
+        [x: string]: never;
+    }>;
     protected getTransformContext(): Promise<TransformContext>;
-    protected _mapSearchResults(rows: Record[], scoreTransformer?: (rawScore: any) => number | undefined): Promise<SearchResult<T>[]>;
+    protected _mapSearchResults(rows: Record[], scoreTransformer?: (rawScore: any) => number | undefined, options?: {
+        includeSubclasses?: boolean | EntityType[];
+    }): Promise<SearchResult<T>[]>;
 }
 /**
  * Injects an EntityRepository instance for the specified entity type.