Core.BluePrint.Packages/Core.Blueprint.Mongo/Contracts/ICollectionRepository.cs

using MongoDB.Driver;
using System.Linq.Expressions;

namespace Core.Blueprint.Mongo
{
    /// <summary>
    /// Interface for performing CRUD operations and queries on MongoDB collections.
    /// The <typeparamref name="TDocument"/> represents the type of documents in the collection,
    /// which must implement the <see cref="IDocument"/> interface.
    /// </summary>
    /// <typeparam name="TDocument">The type of document in the MongoDB collection, must implement <see cref="IDocument"/>.</typeparam>
    public interface ICollectionsRepository<TDocument> where TDocument : IDocument
    {
        /// <summary>
        /// Retrieves all documents from the collection as an enumerable queryable result.
        /// </summary>
        /// <returns>A <see cref="ValueTask"/> containing an <see cref="IEnumerable{TDocument}"/> representing the collection's documents.</returns>
        ValueTask<IEnumerable<TDocument>> AsQueryable();

        /// <summary>
        /// Filters the documents in the collection by the provided filter expression.
        /// </summary>
        /// <param name="filterExpression">An expression used to filter the documents based on the provided condition.</param>
        /// <returns>A <see cref="Task"/> representing the asynchronous operation, with a result of an <see cref="IEnumerable{TDocument}"/> of filtered documents.</returns>
        Task<IEnumerable<TDocument>> FilterBy(
            Expression<Func<TDocument, bool>> filterExpression);

        /// <summary>
        /// Filters the documents in the collection by the provided filter expression and projects them to a different type.
        /// </summary>
        /// <typeparam name="TProjected">The type to project the documents into.</typeparam>
        /// <param name="filterExpression">An expression used to filter the documents.</param>
        /// <param name="projectionExpression">An expression used to project the filtered documents into the <typeparamref name="TProjected"/> type.</param>
        /// <returns>An <see cref="IEnumerable{TProjected}"/> representing the projected documents.</returns>
        IEnumerable<TProjected> FilterBy<TProjected>(
            Expression<Func<TDocument, bool>> filterExpression,
            Expression<Func<TDocument, TProjected>> projectionExpression);

        /// <summary>
        /// Filters documents in the collection based on the provided MongoDB filter definition.
        /// </summary>
        /// <param name="filterDefinition">A filter definition for MongoDB query.</param>
        /// <returns>A task that represents the asynchronous operation. The task result contains a list of documents that match the filter.</returns>
        Task<IEnumerable<TDocument>> FilterByMongoFilterAsync(FilterDefinition<TDocument> filterDefinition);

        /// <summary>
        /// Finds a single document by the provided filter expression.
        /// </summary>
        /// <param name="filterExpression">An expression used to filter the documents.</param>
        /// <returns>The first matching <see cref="TDocument"/> or null if no match is found.</returns>
        TDocument FindOne(Expression<Func<TDocument, bool>> filterExpression);

        /// <summary>
        /// Asynchronously finds a single document by the provided filter expression.
        /// </summary>
        /// <param name="filterExpression">An expression used to filter the documents.</param>
        /// <returns>A <see cref="Task"/> representing the asynchronous operation, with the matching <see cref="TDocument"/> or null.</returns>
        Task<TDocument> FindOneAsync(Expression<Func<TDocument, bool>> filterExpression);

        /// <summary>
        /// Finds a document by its identifier.
        /// </summary>
        /// <param name="id">The identifier of the document.</param>
        /// <returns>The document with the provided identifier or null if not found.</returns>
        TDocument FindById(string id);

        /// <summary>
        /// Asynchronously finds a document by its identifier.
        /// </summary>
        /// <param name="id">The identifier of the document.</param>
        /// <returns>A <see cref="Task"/> representing the asynchronous operation, with the matching <see cref="TDocument"/> or null.</returns>
        Task<TDocument> FindByIdAsync(string id);

        /// <summary>
        /// Inserts a single document into the collection.
        /// </summary>
        /// <param name="document">The document to insert.</param>
        void InsertOne(TDocument document);

        /// <summary>
        /// Asynchronously inserts a single document into the collection.
        /// </summary>
        /// <param name="document">The document to insert.</param>
        /// <returns>A <see cref="Task"/> representing the asynchronous operation.</returns>
        Task InsertOneAsync(TDocument document);

        /// <summary>
        /// Inserts multiple documents into the collection.
        /// </summary>
        /// <param name="documents">The collection of documents to insert.</param>
        void InsertMany(ICollection<TDocument> documents);

        /// <summary>
        /// Asynchronously inserts multiple documents into the collection.
        /// </summary>
        /// <param name="documents">The collection of documents to insert.</param>
        /// <returns>A <see cref="Task"/> representing the asynchronous operation.</returns>
        Task InsertManyAsync(ICollection<TDocument> documents);

        /// <summary>
        /// Replaces an existing document with a new one.
        /// </summary>
        /// <param name="document">The document to replace the existing one.</param>
        void ReplaceOne(TDocument document);

        /// <summary>
        /// Asynchronously replaces an existing document with a new one.
        /// </summary>
        /// <param name="document">The document to replace the existing one.</param>
        /// <returns>A <see cref="Task"/> representing the asynchronous operation.</returns>
        Task ReplaceOneAsync(TDocument document);

        /// <summary>
        /// Deletes a single document by the provided filter expression.
        /// </summary>
        /// <param name="filterExpression">An expression used to filter the documents to delete.</param>
        void DeleteOne(Expression<Func<TDocument, bool>> filterExpression);

        /// <summary>
        /// Asynchronously deletes a single document by the provided filter expression.
        /// </summary>
        /// <param name="filterExpression">An expression used to filter the documents to delete.</param>
        /// <returns>A <see cref="Task"/> representing the asynchronous operation.</returns>
        Task<TDocument> DeleteOneAsync(Expression<Func<TDocument, bool>> filterExpression);

        /// <summary>
        /// Deletes a single document by its identifier.
        /// </summary>
        /// <param name="id">The identifier of the document to delete.</param>
        void DeleteById(string id);

        /// <summary>
        /// Asynchronously deletes a single document by its identifier.
        /// </summary>
        /// <param name="id">The identifier of the document to delete.</param>
        /// <returns>A <see cref="Task"/> representing the asynchronous operation.</returns>
        Task DeleteByIdAsync(string id);

        /// <summary>
        /// Deletes multiple documents that match the provided filter expression.
        /// </summary>
        /// <param name="filterExpression">An expression used to filter the documents to delete.</param>
        void DeleteMany(Expression<Func<TDocument, bool>> filterExpression);

        /// <summary>
        /// Asynchronously deletes multiple documents that match the provided filter expression.
        /// </summary>
        /// <param name="filterExpression">An expression used to filter the documents to delete.</param>
        /// <returns>A <see cref="Task"/> representing the asynchronous operation.</returns>
        Task DeleteManyAsync(Expression<Func<TDocument, bool>> filterExpression);

        /// <summary>
        /// Executes an aggregation pipeline and returns the first document in the result asynchronously.
        /// </summary>
        /// <typeparam name="TOutput">The type of the output document you expect from the pipeline.</typeparam>
        /// <param name="pipeline">The aggregation pipeline definition to execute.</param>
        /// <returns>The first document from the aggregation result, or null if none found.</returns>
        Task<TOutput> FindOnePipelineAsync<TOutput>(PipelineDefinition<TDocument, TOutput> pipeline);
    }
}