DigitalData.Core/DigitalData.Core.Contracts/Application/ICRUDService.cs

using DigitalData.Core.Contracts.Infrastructure;

namespace DigitalData.Core.Contracts.Application
{
    /// <summary>
    /// Defines the contract for CRUD operations at the service level using Data Transfer Objects (DTOs) for entities of type TEntity,
    /// wrapped in an IServiceResult to encapsulate the outcome of the operation, including success, data, and error messages.
    /// </summary>
    /// <typeparam name="TCRUDRepository">The repository type that provides CRUD operations for entities of type TEntity.</typeparam>
    /// <typeparam name="TCreateDto">The type of the Data Transfer Object this service works with to create new entity.</typeparam>
    /// <typeparam name="TReadDto">The type of the Data Transfer Object this service works with to read new entity.</typeparam>
    /// <typeparam name="TUpdateDto">The type of the Data Transfer Object this service works with to update new entity.</typeparam>
    /// <typeparam name="TEntity">The type of the entity this service maps to.</typeparam>
    /// <typeparam name="TId">The type of the identifier for the entity.</typeparam>
    public interface ICRUDService<TCRUDRepository, TCreateDto, TReadDto, TUpdateDto, TEntity, TId> : IServiceBase
        where TCRUDRepository : ICRUDRepository<TEntity, TId> where TCreateDto : class where TReadDto : class where TUpdateDto : class where TEntity : class
    {
        /// <summary>
        /// Creates a new entity based on the provided DTO and returns the result wrapped in an IServiceResult,
        /// including the created entity on success or an error message on failure.
        /// </summary>
        /// <param name="createDto">The createDto to create a new entity from.</param>
        /// <returns>An IServiceResult containing the id of created entity or an error message.</returns>
        Task<IServiceResult<TId>> CreateAsync(TCreateDto createDto);

        /// <summary>
        /// Retrieves an entity by its identifier and returns its readDTO representation wrapped in an IServiceResult,
        /// including the readDTO on success or null and an error message on failure.
        /// </summary>
        /// <param name="id">The identifier of the entity to retrieve.</param>
        /// <returns>An IServiceResult containing the readDTO representing the found entity or null, with an appropriate message.</returns>
        Task<IServiceResult<TReadDto>> ReadByIdAsync(TId id);

        /// <summary>
        /// Retrieves all entities and returns their readDTO representations wrapped in an IServiceResult,
        /// including a collection of readDTOs on success or an error message on failure.
        /// </summary>
        /// <returns>An IServiceResult containing a collection of readDTOs representing all entities or an error message.</returns>
        Task<IServiceResult<IEnumerable<TReadDto>>> ReadAllAsync();

        /// <summary>
        /// Updates an existing entity based on the provided updateDTO and returns the result wrapped in an IServiceMessage,
        /// indicating the success or failure of the operation, including the error messages on failure.
        /// </summary>
        /// <param name="updateDto">The updateDTO with updated values for the entity.</param>
        /// <returns>An IServiceMessage indicating the outcome of the update operation, with an appropriate message.</returns>
        Task<IServiceMessage> UpdateAsync(TUpdateDto updateDto);

        /// <summary>
        /// Deletes an entity by its identifier and returns the result wrapped in an IServiceMessage,
        /// indicating the success or failure of the operation, including the error messages on failure.
        /// </summary>
        /// <param name="id">The identifier of the entity to delete.</param>
        /// <returns>An IServiceMessage indicating the outcome of the delete operation, with an appropriate message.</returns>
        Task<IServiceMessage> DeleteAsyncById(TId id);

        /// <summary>
        /// Asynchronously checks if an entity with the specified identifier exists within the data store.
        /// </summary>
        /// <param name="id">The identifier of the entity to check.</param>
        /// <returns>A task that represents the asynchronous operation. The task result contains a boolean value indicating whether the entity exists.</returns>
        Task<bool> HasEntity(TId id);

        /// <summary>
        /// Handles exceptions that occur within service actions. This method should log the exception
        /// and return an String that contains information about the error, which can then be sent to the client.
        /// The implementation should determine the appropriate level of detail to include in the error message
        /// based on security and usability considerations.
        /// </summary>
        /// <param name="ex">The exception that occurred during the controller action.</param>
        /// <returns>An string instance representing the outcome of the error handling process.
        /// This includes a flag indicating the operation was unsuccessful and any relevant error messages.</returns>
        string HandleException(Exception ex);
    }
}