@decaf-ts/db-decorators 0.6.1 → 0.6.3

package/lib/esm/repository/BaseRepository.d.ts

@@ -2,38 +2,360 @@ 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, 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;
 }