@tstdl/base 0.92.123 → 0.92.125

package/orm/server/repository.d.ts

@@ -1,51 +1,142 @@
 import { SQL } from 'drizzle-orm';
-import { PgTransaction as DrizzlePgTransaction, type PgColumn, type PgInsertValue, type PgQueryResultHKT, type PgUpdateSetSource } from 'drizzle-orm/pg-core';
+import type { PgColumn, PgInsertValue, PgUpdateSetSource } from 'drizzle-orm/pg-core';
 import { type Resolvable, resolveArgumentType } from '../../injector/interfaces.js';
-import type { DeepPartial, OneOrMany, Paths, Record, Type } from '../../types.js';
+import type { DeepPartial, OneOrMany, Paths, Type } from '../../types.js';
 import type { UntaggedDeep } from '../../types/index.js';
 import { Entity, type EntityMetadataAttributes, type EntityType, type EntityWithoutMetadata } from '../entity.js';
 import type { Query } from '../query.js';
-import type { EntityMetadataUpdate, EntityUpdate, LoadManyOptions, LoadOptions, NewEntity, Order } from '../repository.types.js';
-import { Database } from './database.js';
-import { type Transaction, type TransactionConfig } from './transaction.js';
+import type { EntityMetadataUpdate, EntityUpdate, LoadManyOptions, LoadOptions, NewEntity, Order, TargetColumnPaths } from '../repository.types.js';
+import { Transactional } from './transactional.js';
 import type { ColumnDefinition, PgTableFromType, TransformContext } from './types.js';
-type PgTransaction = DrizzlePgTransaction<PgQueryResultHKT, Record, Record>;
 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;
 }
-export type TransactionHandler<T extends EntityRepository<any>, R> = (repository: T, transaction: Transaction) => Promise<R>;
+type EntityRepositoryContext = {
+    type: EntityType;
+    table: PgTableFromType;
+    columnDefinitions: ColumnDefinition[];
+    columnDefinitionsMap: Map<string, ColumnDefinition>;
+    encryptionSecret: Uint8Array | undefined;
+    transformContext: TransformContext | Promise<TransformContext> | undefined;
+};
 type InferSelect<T extends Entity | EntityWithoutMetadata = Entity | EntityWithoutMetadata> = PgTableFromType<EntityType<T>>['$inferSelect'];
-export declare class EntityRepository<T extends Entity | EntityWithoutMetadata = EntityWithoutMetadata> implements Resolvable<EntityType<T>> {
+export declare class EntityRepository<T extends Entity | EntityWithoutMetadata = EntityWithoutMetadata> extends Transactional<EntityRepositoryContext> implements Resolvable<EntityType<T>> {
     #private;
     readonly type: EntityType<T>;
     readonly typeName: string;
-    readonly session: Database | PgTransaction;
-    readonly isInTransaction: boolean;
     readonly hasMetadata: boolean;
+    /**
+     * Gets the Drizzle table definition for the entity type.
+     */
     get table(): PgTableFromType<EntityType<T>>;
-    protected get isFork(): boolean;
     readonly [resolveArgumentType]: EntityType<T>;
-    constructor();
-    withOptionalTransaction(transaction: Transaction | undefined): this;
-    withTransaction(transaction: Transaction): this;
-    startTransaction(config?: TransactionConfig): Promise<Transaction>;
-    useTransaction<R>(transaction: Transaction | undefined, handler: TransactionHandler<this, R>): Promise<R>;
-    transaction<R>(handler: TransactionHandler<this, R>, config?: TransactionConfig): Promise<R>;
+    protected getTransactionalContextData(): EntityRepositoryContext;
+    /**
+     * 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.
+     */
     load(id: string): 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.
+     * @returns A promise that resolves to the loaded entity or `undefined` if not found.
+     */
     tryLoad(id: string): Promise<T | undefined>;
+    /**
+     * 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.
+     */
     loadByQuery(query: Query<T>, options?: LoadOptions<T>): Promise<T>;
+    /**
+     * 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.
+     */
     tryLoadByQuery(query: Query<T>, options?: LoadOptions<T>): Promise<T | undefined>;
+    /**
+     * 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.
+     */
     loadMany(ids: string[], options?: LoadManyOptions<T>): Promise<T[]>;
+    /**
+     * 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.
+     */
     loadManyCursor(ids: string[], options?: LoadManyOptions<T>): AsyncIterableIterator<T>;
+    /**
+     * 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.
+     */
     loadManyByQuery(query: Query<T>, options?: LoadManyOptions<T>): Promise<T[]>;
+    /**
+     * 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.
+     */
     loadManyByQueryCursor(query: Query<T>, options?: LoadManyOptions<T>): AsyncIterableIterator<T>;
+    /**
+     * 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.
+     */
     loadAll(options?: LoadManyOptions<T>): Promise<T[]>;
+    /**
+     * 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.
+     */
     loadAllCursor(options?: LoadManyOptions<T>): AsyncIterableIterator<T>;
+    /**
+     * Counts the total number of entities of the repository's type.
+     * @returns A promise that resolves to the total count.
+     */
     count(): Promise<number>;
+    /**
+     * 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.
+     */
     countByQuery(query: Query<T>): Promise<number>;
+    /**
+     * 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.
+     */
     has(id: string): Promise<boolean>;
+    /**
+     * 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.
+     */
     hasByQuery(query: Query<T>): Promise<boolean>;
+    /**
+     * 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.
+     */
     hasAll(ids: string[]): Promise<boolean>;
     /**
      * Tries to insert using ON CONFLICT DO NOTHING
@@ -53,40 +144,243 @@ export declare class EntityRepository<T extends Entity | EntityWithoutMetadata =
      * @returns entity if inserted, undefined on conflict
      */
     tryInsert(entity: NewEntity<T>): Promise<T | undefined>;
+    /**
+     * Inserts a new entity into the database.
+     * @param entity The entity to insert.
+     * @returns A promise that resolves to the inserted entity.
+     */
     insert(entity: NewEntity<T>): Promise<T>;
+    /**
+     * 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.
+     */
     insertMany(entities: NewEntity<T>[]): Promise<T[]>;
+    /**
+     * 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.
+     */
     upsert(target: OneOrMany<Paths<UntaggedDeep<T>>>, entity: NewEntity<T>, update?: EntityUpdate<T>): Promise<T>;
+    /**
+     * 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.
+     */
     upsertMany(target: OneOrMany<Paths<UntaggedDeep<T>>>, entities: NewEntity<T>[], update?: EntityUpdate<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.
+     * @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>;
+    /**
+     * 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.
+     */
     tryUpdate(id: string, update: EntityUpdate<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.
+     * @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>;
+    /**
+     * 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.
+     */
     tryUpdateByQuery(query: Query<T>, update: EntityUpdate<T>): Promise<T | undefined>;
+    /**
+     * 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.
+     */
     updateMany(ids: string[], update: EntityUpdate<T>): Promise<T[]>;
+    /**
+     * 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.
+     */
     updateManyByQuery(query: Query<T>, update: EntityUpdate<T>): Promise<T[]>;
+    /**
+     * 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.
+     */
     delete(id: string, 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 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>;
+    /**
+     * 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.
+     */
     deleteByQuery(query: Query<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 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>;
+    /**
+     * 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.
+     */
     deleteMany(ids: string[], metadataUpdate?: EntityMetadataUpdate): Promise<T[]>;
+    /**
+     * 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.
+     */
     deleteManyByQuery(query: Query<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.
+     * @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>;
+    /**
+     * 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.
+     */
     tryHardDelete(id: string): 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.
+     * @returns A promise that resolves to the hard deleted entity.
+     * @throws {NotFoundError} If no entity matches the query.
+     */
     hardDeleteByQuery(query: Query<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.
+     * @returns A promise that resolves to the hard deleted entity or `undefined` if not found.
+     */
     tryHardDeleteByQuery(query: Query<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.
+     * @returns A promise that resolves to an array of the hard deleted entities.
+     */
     hardDeleteMany(ids: string[]): Promise<T[]>;
+    /**
+     * 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.
+     */
     hardDeleteManyByQuery(query: Query<T>): Promise<T[]>;
-    getColumn(pathOrColumn: Paths<UntaggedDeep<T>> | ColumnDefinition): PgColumn;
+    /**
+     * 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: TargetColumnPaths<T> | ColumnDefinition): PgColumn;
+    getColumns(pathOrColumns: (TargetColumnPaths<T> | ColumnDefinition)[]): PgColumn[];
+    /**
+     * 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: Order<T>): SQL[];
+    /**
+     * 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: Query<T>, options?: {
         withDeleted?: boolean;
     }): 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.
+     */
     mapManyToEntity(columns: InferSelect[]): Promise<T[]>;
+    /**
+     * Maps a single database row to an entity.
+     * @param columns A database row.
+     * @returns A promise that resolves to an entity.
+     */
     mapToEntity(columns: InferSelect): Promise<T>;
+    /**
+     * 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.
+     */
     mapManyToColumns(objects: (DeepPartial<T> | NewEntity<T>)[]): Promise<PgInsertValue<PgTableFromType>[]>;
+    /**
+     * 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.
+     */
     mapToColumns(obj: DeepPartial<T> | NewEntity<T>): Promise<PgInsertValue<PgTableFromType>>;
+    /**
+     * 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.
+     */
     mapManyToInsertColumns(objects: (DeepPartial<T> | NewEntity<T>)[]): Promise<PgInsertValue<PgTableFromType>[]>;
+    /**
+     * 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.
+     */
     mapToInsertColumns(obj: DeepPartial<T> | NewEntity<T>): Promise<PgInsertValue<PgTableFromType>>;
+    /**
+     * 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.
+     */
     mapUpdate(update: EntityUpdate<T>): Promise<PgUpdateSetSource<PgTableFromType>>;
+    /**
+     * 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: Query<T>): Omit<import("drizzle-orm/pg-core").PgSelectBase<string, {
         id: PgColumn<{
             name: string;
@@ -176,6 +470,18 @@ export declare class EntityRepository<T extends Entity | EntityWithoutMetadata =
     }>, "where" | "limit">;
     protected getTransformContext(): Promise<TransformContext>;
 }
+/**
+ * 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 declare function injectRepository<T extends Entity | EntityWithoutMetadata>(type: EntityType<T>): EntityRepository<T>;
+/**
+ * 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 declare function getRepository<T extends Entity | EntityWithoutMetadata>(type: EntityType<T>): Type<EntityRepository<T>>;
 export {};