@decaf-ts/db-decorators/lib/repository/BaseRepository.d.ts

Agnostic database decorators and repository

import { IRepository } from "../interfaces/IRepository";
import { Constructor, Model } from "@decaf-ts/decorator-validation";
import { Context } from "./Context";
import { RepositoryFlags } from "./types";
/**
 * @description Base repository implementation providing CRUD operations for models.
 * @summary The BaseRepository class serves as a foundation for repository implementations, providing
 * abstract and concrete methods for creating, reading, updating, and deleting model instances.
 * It handles operation lifecycles including prefix and suffix operations, and enforces decorators.
 * @template M - The model type extending Model
 * @template F - The repository flags type, defaults to RepositoryFlags
 * @template C - The context type, defaults to Context<F>
 * @param {Constructor<M>} clazz - The constructor for the model class
 * @class BaseRepository
 * @example
 * class UserModel extends Model {
 *   @id()
 *   id: string;
 *
 *   @required()
 *   name: string;
 * }
 *
 * class UserRepository extends BaseRepository<UserModel> {
 *   constructor() {
 *     super(UserModel);
 *   }
 *
 *   async create(model: UserModel): Promise<UserModel> {
 *     // Implementation
 *     return model;
 *   }
 *
 *   async read(key: string): Promise<UserModel> {
 *     // Implementation
 *     return new UserModel({ id: key, name: 'User' });
 *   }
 *
 *   async update(model: UserModel): Promise<UserModel> {
 *     // Implementation
 *     return model;
 *   }
 *
 *   async delete(key: string): Promise<UserModel> {
 *     // Implementation
 *     const model = await this.read(key);
 *     return model;
 *   }
 * }
 *
 * @mermaid
 * sequenceDiagram
 *   participant C as Client
 *   participant R as Repository
 *   participant P as Prefix Methods
 *   participant D as Database
 *   participant S as Suffix Methods
 *   participant V as Validators/Decorators
 *
 *   Note over C,V: Create Operation
 *   C->>R: create(model)
 *   R->>P: createPrefix(model)
 *   P->>V: enforceDBDecorators(ON)
 *   P->>D: Database operation
 *   D->>S: createSuffix(model)
 *   S->>V: enforceDBDecorators(AFTER)
 *   S->>C: Return model
 *
 *   Note over C,V: Read Operation
 *   C->>R: read(key)
 *   R->>P: readPrefix(key)
 *   P->>V: enforceDBDecorators(ON)
 *   P->>D: Database operation
 *   D->>S: readSuffix(model)
 *   S->>V: enforceDBDecorators(AFTER)
 *   S->>C: Return model
 *
 *   Note over C,V: Update Operation
 *   C->>R: update(model)
 *   R->>P: updatePrefix(model)
 *   P->>V: enforceDBDecorators(ON)
 *   P->>D: Database operation
 *   D->>S: updateSuffix(model)
 *   S->>V: enforceDBDecorators(AFTER)
 *   S->>C: Return model
 *
 *   Note over C,V: Delete Operation
 *   C->>R: delete(key)
 *   R->>P: deletePrefix(key)
 *   P->>V: enforceDBDecorators(ON)
 *   P->>D: Database operation
 *   D->>S: deleteSuffix(model)
 *   S->>V: enforceDBDecorators(AFTER)
 *   S->>C: Return model
 */
export declare abstract class BaseRepository<M extends Model<boolean>, F extends RepositoryFlags = RepositoryFlags, C extends Context<F> = Context<F>> implements IRepository<M, F, C> {
    private readonly _class;
    private _pk;
    private _pkProps;
    /**
     * @description Gets the model class constructor.
     * @summary Retrieves the constructor for the model class associated with this repository.
     * Throws an error if no class definition is found.
     * @return {Constructor<M>} The constructor for the model class
     */
    get class(): Constructor<M>;
    /**
     * @description Gets the primary key property name of the model.
     * @summary Retrieves the name of the property that serves as the primary key for the model.
     * If not already determined, it finds the primary key using the model's decorators.
     * @return The name of the primary key property
     */
    get pk(): keyof M;
    /**
     * @description Gets the primary key properties.
     * @summary Retrieves the properties associated with the primary key of the model.
     * If not already determined, it triggers the pk getter to find the primary key properties.
     * @return {any} The properties of the primary key
     */
    protected get pkProps(): any;
    protected constructor(clazz?: Constructor<M>);
    /**
     * @description Creates a new model instance in the repository.
     * @summary Persists a new model instance to the underlying data store.
     * This method must be implemented by concrete repository classes.
     * @param {M} model - The model instance to create
     * @param {any[]} args - Additional arguments for the create operation
     * @return {Promise<M>} A promise that resolves to the created model instance
     */
    abstract create(model: M, ...args: any[]): Promise<M>;
    /**
     * @description Creates multiple model instances in the repository.
     * @summary Persists multiple model instances to the underlying data store by calling
     * the create method for each model in the array.
     * @param {M[]} models - The array of model instances to create
     * @param {any[]} args - Additional arguments for the create operation
     * @return {Promise<M[]>} A promise that resolves to an array of created model instances
     */
    createAll(models: M[], ...args: any[]): Promise<M[]>;
    /**
     * @description Prepares a model for creation and executes pre-creation operations.
     * @summary Processes a model before it is created in the data store. This includes
     * creating a context, instantiating a new model instance, and enforcing any decorators
     * that should be applied before creation.
     * @param {M} model - The model instance to prepare for creation
     * @param {any[]} args - Additional arguments for the create operation
     * @return A promise that resolves to an array containing the prepared model and context arguments
     */
    protected createPrefix(model: M, ...args: any[]): Promise<any[]>;
    /**
     * @description Processes a model after creation and executes post-creation operations.
     * @summary Finalizes a model after it has been created in the data store. This includes
     * enforcing any decorators that should be applied after creation.
     * @param {M} model - The model instance that was created
     * @param {C} context - The context for the operation
     * @return {Promise<M>} A promise that resolves to the processed model instance
     */
    protected createSuffix(model: M, context: C): Promise<M>;
    /**
     * @description Prepares multiple models for creation and executes pre-creation operations.
     * @summary Processes multiple models before they are created in the data store. This includes
     * creating a context, instantiating new model instances, and enforcing any decorators
     * that should be applied before creation for each model.
     * @param {M[]} models - The array of model instances to prepare for creation
     * @param {any[]} args - Additional arguments for the create operation
     * @return  A promise that resolves to an array containing the prepared models and context arguments
     */
    protected createAllPrefix(models: M[], ...args: any[]): Promise<any[]>;
    /**
     * @description Processes multiple models after creation and executes post-creation operations.
     * @summary Finalizes multiple models after they have been created in the data store. This includes
     * enforcing any decorators that should be applied after creation for each model.
     * @param {M[]} models - The array of model instances that were created
     * @param {C} context - The context for the operation
     * @return {Promise<M[]>} A promise that resolves to the array of processed model instances
     */
    protected createAllSuffix(models: M[], context: C): Promise<M[]>;
    /**
     * @description Retrieves a model instance from the repository by its primary key.
     * @summary Fetches a model instance from the underlying data store using its primary key.
     * This method must be implemented by concrete repository classes.
     * @param {string | number} key - The primary key of the model to retrieve
     * @param {any[]} args - Additional arguments for the read operation
     * @return {Promise<M>} A promise that resolves to the retrieved model instance
     */
    abstract read(key: string | number, ...args: any[]): Promise<M>;
    /**
     * @description Retrieves multiple model instances from the repository by their primary keys.
     * @summary Fetches multiple model instances from the underlying data store using their primary keys
     * by calling the read method for each key in the array.
     * @param {string[] | number[]} keys - The array of primary keys of the models to retrieve
     * @param {any[]} args - Additional arguments for the read operation
     * @return {Promise<M[]>} A promise that resolves to an array of retrieved model instances
     */
    readAll(keys: string[] | number[], ...args: any[]): Promise<M[]>;
    /**
     * @description Processes a model after retrieval and executes post-read operations.
     * @summary Finalizes a model after it has been retrieved from the data store. This includes
     * enforcing any decorators that should be applied after reading.
     * @param {M} model - The model instance that was retrieved
     * @param {C} context - The context for the operation
     * @return {Promise<M>} A promise that resolves to the processed model instance
     */
    protected readSuffix(model: M, context: C): Promise<M>;
    /**
     * @description Prepares for reading a model and executes pre-read operations.
     * @summary Processes a key before a model is read from the data store. This includes
     * creating a context, instantiating a new model instance with the key, and enforcing any decorators
     * that should be applied before reading.
     * @param {string} key - The primary key of the model to read
     * @param {any[]} args - Additional arguments for the read operation
     * @return A promise that resolves to an array containing the key and context arguments
     */
    protected readPrefix(key: string, ...args: any[]): Promise<any[]>;
    /**
     * @description Prepares for reading multiple models and executes pre-read operations.
     * @summary Processes multiple keys before models are read from the data store. This includes
     * creating a context, instantiating new model instances with the keys, and enforcing any decorators
     * that should be applied before reading for each key.
     * @param {string[] | number[]} keys - The array of primary keys of the models to read
     * @param {any[]} args - Additional arguments for the read operation
     * @return A promise that resolves to an array containing the keys and context arguments
     */
    protected readAllPrefix(keys: string[] | number[], ...args: any[]): Promise<any[]>;
    /**
     * @description Processes multiple models after retrieval and executes post-read operations.
     * @summary Finalizes multiple models after they have been retrieved from the data store. This includes
     * enforcing any decorators that should be applied after reading for each model.
     * @param {M[]} models - The array of model instances that were retrieved
     * @param {C} context - The context for the operation
     * @return {Promise<M[]>} A promise that resolves to the array of processed model instances
     */
    protected readAllSuffix(models: M[], context: C): Promise<M[]>;
    /**
     * @description Updates an existing model instance in the repository.
     * @summary Updates an existing model instance in the underlying data store.
     * This method must be implemented by concrete repository classes.
     * @param {M} model - The model instance to update
     * @param {any[]} args - Additional arguments for the update operation
     * @return {Promise<M>} A promise that resolves to the updated model instance
     */
    abstract update(model: M, ...args: any[]): Promise<M>;
    /**
     * @description Updates multiple model instances in the repository.
     * @summary Updates multiple model instances in the underlying data store by calling
     * the update method for each model in the array.
     * @param {M[]} models - The array of model instances to update
     * @param {any[]} args - Additional arguments for the update operation
     * @return {Promise<M[]>} A promise that resolves to an array of updated model instances
     */
    updateAll(models: M[], ...args: any): Promise<M[]>;
    /**
     * @description Processes a model after update and executes post-update operations.
     * @summary Finalizes a model after it has been updated in the data store. This includes
     * enforcing any decorators that should be applied after updating.
     * @param {M} model - The model instance that was updated
     * @param {C} context - The context for the operation
     * @return {Promise<M>} A promise that resolves to the processed model instance
     */
    protected updateSuffix(model: M, context: C): Promise<M>;
    /**
     * @description Prepares a model for update and executes pre-update operations.
     * @summary Processes a model before it is updated in the data store. This includes
     * creating a context, validating the primary key, retrieving the existing model,
     * and enforcing any decorators that should be applied before updating.
     * @param {M} model - The model instance to prepare for update
     * @param {any[]} args - Additional arguments for the update operation
     * @return A promise that resolves to an array containing the prepared model and context arguments
     */
    protected updatePrefix(model: M, ...args: any[]): Promise<any[]>;
    /**
     * @description Prepares multiple models for update and executes pre-update operations.
     * @summary Processes multiple models before they are updated in the data store. This includes
     * creating a context, instantiating new model instances, and enforcing any decorators
     * that should be applied before updating for each model.
     * @param {M[]} models - The array of model instances to prepare for update
     * @param {any[]} args - Additional arguments for the update operation
     * @return A promise that resolves to an array containing the prepared models and context arguments
     */
    protected updateAllPrefix(models: M[], ...args: any[]): Promise<any[]>;
    /**
     * @description Processes multiple models after update and executes post-update operations.
     * @summary Finalizes multiple models after they have been updated in the data store. This includes
     * enforcing any decorators that should be applied after updating for each model.
     * @param {M[]} models - The array of model instances that were updated
     * @param {C} context - The context for the operation
     * @return {Promise<M[]>} A promise that resolves to the array of processed model instances
     */
    protected updateAllSuffix(models: M[], context: C): Promise<M[]>;
    /**
     * @description Deletes a model instance from the repository by its primary key.
     * @summary Removes a model instance from the underlying data store using its primary key.
     * This method must be implemented by concrete repository classes.
     * @param {string | number} key - The primary key of the model to delete
     * @param {any[]} args - Additional arguments for the delete operation
     * @return {Promise<M>} A promise that resolves to the deleted model instance
     */
    abstract delete(key: string | number, ...args: any[]): Promise<M>;
    /**
     * @description Deletes multiple model instances from the repository by their primary keys.
     * @summary Removes multiple model instances from the underlying data store using their primary keys
     * by calling the delete method for each key in the array.
     * @param {string[] | number[]} keys - The array of primary keys of the models to delete
     * @param {any[]} args - Additional arguments for the delete operation
     * @return {Promise<M[]>} A promise that resolves to an array of deleted model instances
     */
    deleteAll(keys: string[] | number[], ...args: any[]): Promise<M[]>;
    /**
     * @description Processes a model after deletion and executes post-delete operations.
     * @summary Finalizes a model after it has been deleted from the data store. This includes
     * enforcing any decorators that should be applied after deletion.
     * @param {M} model - The model instance that was deleted
     * @param {C} context - The context for the operation
     * @return {Promise<M>} A promise that resolves to the processed model instance
     */
    protected deleteSuffix(model: M, context: C): Promise<M>;
    /**
     * @description Prepares for deleting a model and executes pre-delete operations.
     * @summary Processes a key before a model is deleted from the data store. This includes
     * creating a context, retrieving the model to be deleted, and enforcing any decorators
     * that should be applied before deletion.
     * @param {any} key - The primary key of the model to delete
     * @param {any[]} args - Additional arguments for the delete operation
     * @return A promise that resolves to an array containing the key and context arguments
     */
    protected deletePrefix(key: any, ...args: any[]): Promise<any[]>;
    /**
     * @description Prepares for deleting multiple models and executes pre-delete operations.
     * @summary Processes multiple keys before models are deleted from the data store. This includes
     * creating a context, retrieving the models to be deleted, and enforcing any decorators
     * that should be applied before deletion for each model.
     * @param {string[] | number[]} keys - The array of primary keys of the models to delete
     * @param {any[]} args - Additional arguments for the delete operation
     * @return A promise that resolves to an array containing the keys and context arguments
     */
    protected deleteAllPrefix(keys: string[] | number[], ...args: any[]): Promise<any[]>;
    /**
     * @description Processes multiple models after deletion and executes post-delete operations.
     * @summary Finalizes multiple models after they have been deleted from the data store. This includes
     * enforcing any decorators that should be applied after deletion for each model.
     * @param {M[]} models - The array of model instances that were deleted
     * @param {C} context - The context for the operation
     * @return {Promise<M[]>} A promise that resolves to the array of processed model instances
     */
    protected deleteAllSuffix(models: M[], context: C): Promise<M[]>;
    /**
     * @description Merges two model instances into a new instance.
     * @summary Creates a new model instance by combining properties from an old model and a new model.
     * Properties from the new model override properties from the old model if they are defined.
     * @param {M} oldModel - The original model instance
     * @param {M} model - The new model instance with updated properties
     * @return {M} A new model instance with merged properties
     */
    protected merge(oldModel: M, model: M): M;
    /**
     * @description Returns a string representation of the repository.
     * @summary Creates a string that identifies this repository by the name of its model class.
     * @return {string} A string representation of the repository
     */
    toString(): string;
}