xDataService/Interfaces/IXBaseRepository.cs

using System;
using System.Collections.Generic;
using System.Linq;
using System.Linq.Expressions;
using System.Threading;
using System.Threading.Tasks;
using Microsoft.EntityFrameworkCore.Query;
using xModels.Base;
using xModels.Dtos;

namespace xDataService.Interfaces
{
    /// <summary>
    /// Base Repository Pattern Contracts in XDashboard's Data Service ...
    /// use for Data Manipulation ...
    /// </summary>
    /// <typeparam name="T"></typeparam>
    /// <typeparam name="TKey"></typeparam>
    public interface IXBaseRepository<T, TKey> : IDisposable
    where T : XBaseEntity<TKey>
    {
        //
        #region Add ...
        /// <summary>
        /// add a new Entity ...
        /// </summary>
        /// <param name="item"></param>
        /// <param name="saveChanges"></param>
        /// <param name="cancellationToken"></param>
        /// <returns></returns>
        Task<T> AddAsync(
            T item,
            bool saveChanges = true,
            CancellationToken cancellationToken = default
        );

        /// <summary>
        /// add or update an Entity (add if not exists/update if exists) ...
        /// </summary>
        /// <param name="item"></param>
        /// <param name="saveChanges"></param>
        /// <param name="cancellationToken"></param>
        /// <returns></returns>
        Task<T> AddOrUpdateAsync(
            T item,
            bool saveChanges = true,
            CancellationToken cancellationToken = default
        );

        /// <summary>
        /// add a range of new Entities ...
        /// </summary>
        /// <param name="items"></param>
        /// <param name="saveChanges"></param>
        /// <param name="cancellationToken"></param>
        /// <returns></returns>
        Task AddRangeAsync(
            IEnumerable<T> items,
            bool saveChanges = true,
            CancellationToken cancellationToken = default
        );
        #endregion

        //
        #region Update ...
        /// <summary>
        /// Update an Entity values ...
        /// </summary>
        /// <param name="id"></param>
        /// <param name="item"></param>
        /// <param name="saveChanges"></param>
        /// <param name="cancellationToken"></param>
        /// <returns></returns>
        Task<T> UpdateAsync(
            TKey id,
            T item,
            bool saveChanges = true,
            CancellationToken cancellationToken = default
        );

        /// <summary>
        /// Update a range of Entities ...
        /// </summary>
        /// <param name="items"></param>
        /// <param name="saveChanges"></param>
        /// <param name="cancellationToken"></param>
        /// <returns></returns>
        Task<bool> UpdateRangeAsync(
            IEnumerable<T> items,
            bool saveChanges = true,
            CancellationToken cancellationToken = default
        );
        #endregion

        //
        #region Remove ...
        /// <summary>
        /// remove an Entity by it's Id ...
        /// </summary>
        /// <param name="id"></param>
        /// <param name="softDelete"></param>
        /// <param name="saveChanges"></param>
        /// <param name="cancellationToken"></param>
        /// <returns></returns>
        Task<T> RemoveAsync(
            TKey id,
            bool softDelete = true,
            bool saveChanges = true,
            CancellationToken cancellationToken = default
        );

        /// <summary>
        /// remove an Entity ...
        /// </summary>
        /// <param name="item"></param>
        /// <param name="softDelete"></param>
        /// <param name="saveChanges"></param>
        /// <param name="cancellationToken"></param>
        /// <returns></returns>
        Task<T> RemoveAsync(
            T item,
            bool softDelete = true,
            bool saveChanges = true,
            CancellationToken cancellationToken = default
        );

        /// <summary>
        /// remove a range of exists Entities ...
        /// </summary>
        /// <param name="items"></param>
        /// <param name="softDelete"></param>
        /// <param name="saveChanges"></param>
        /// <param name="cancellationToken"></param>
        /// <returns></returns>
        Task RemoveRangeAsync(
            IEnumerable<T> items,
            bool softDelete = true,
            bool saveChanges = true,
            CancellationToken cancellationToken = default
        );
        #endregion

        //
        #region Count ...
        /// <summary>
        /// count all exists Entities ...
        /// </summary>
        /// <param name="ignoreSoftDeleteds"></param>
        /// <param name="cancellationToken"></param>
        /// <returns></returns>
        Task<int> CountAsync(
            bool ignoreSoftDeleteds = true,
            CancellationToken cancellationToken = default
        );

        /// <summary>
        /// count all exists Entities Pages by providing page size ...
        /// </summary>
        /// <param name="pageSize"></param>
        /// <param name="totalItems"></param>
        /// <param name="ignoreSoftDeleteds"></param>
        /// <param name="cancellationToken"></param>
        /// <returns></returns>
        Task<int> PagesCountAsync(
            int pageSize,
            int? totalItems = null,
            bool ignoreSoftDeleteds = true,
            CancellationToken cancellationToken = default
        );
        #endregion

        //
        #region Retrieve ...
        /// <summary>
        /// retrieve whole items as queryable ...
        /// </summary>
        /// <param name="asNoTracking">a flag for Tracking behaviour</param>
        /// <param name="predicate">an Expression for Filter Items ...</param>
        /// <param name="orderBuilder">an Order Builder expression for Ordering Query ...</param>
        /// <param name="includeBuilder">an Include Builder expression for Including Navigation Properties ...</param>
        /// <returns></returns>
        IQueryable<T> AsQueryable(
            bool asNoTracking = true,
            Expression<Func<T, bool>> predicate = null,
            Func<IQueryable<T>, IOrderedQueryable<T>> orderBuilder = null,
            Func<IQueryable<T>, IIncludableQueryable<T, object>> includeBuilder = null
        );

        /// <summary>
        /// retrieve an Entity by it's Id ...
        /// </summary>
        /// <param name="id"></param>
        /// <param name="ignoreSoftDeleteds"></param>
        /// <param name="includeBuilder"></param>
        /// <param name="cancellationToken"></param>
        /// <returns></returns>
        Task<T> GetAsync(
            TKey id,
            bool ignoreSoftDeleteds = true,
            Func<IQueryable<T>, IIncludableQueryable<T, object>> includeBuilder = null,
            CancellationToken cancellationToken = default
        );

        /// <summary>
        /// retrieve all exists Entities ...
        /// </summary>
        /// <param name="ignoreSoftDeleteds"></param>
        /// <param name="orderBuilder"></param>
        /// <param name="includeBuilder"></param>
        /// <param name="cancellationToken"></param>
        /// <returns></returns>
        Task<IEnumerable<T>> GetAllAsync(
            bool ignoreSoftDeleteds = true,
            Func<IQueryable<T>, IOrderedQueryable<T>> orderBuilder = null,
            Func<IQueryable<T>, IIncludableQueryable<T, object>> includeBuilder = null,
            CancellationToken cancellationToken = default
        );

        /// <summary>
        /// retrieve all exists Entities
        /// as Async Enumerable ...
        /// </summary>
        /// <param name="ignoreSoftDeleteds"></param>
        /// <param name="orderBuilder"></param>
        /// <param name="includeBuilder"></param>
        /// <returns></returns>
        IAsyncEnumerable<T> GetAllAsAsyncEnumerable(
            bool ignoreSoftDeleteds = true,
            Func<IQueryable<T>, IOrderedQueryable<T>> orderBuilder = null,
            Func<IQueryable<T>, IIncludableQueryable<T, object>> includeBuilder = null
        );

        /// <summary>
        /// find an Entity by providing a Conditional Expression ...
        /// </summary>
        /// <param name="predicate"></param>
        /// <param name="ignoreSoftDeleteds"></param>
        /// <param name="includeBuilder"></param>
        /// <param name="cancellationToken"></param>
        /// <returns></returns>
        Task<T> FindOneAsync(
            Expression<Func<T, bool>> predicate,
            bool ignoreSoftDeleteds = true,
            Func<IQueryable<T>, IIncludableQueryable<T, object>> includeBuilder = null,
            CancellationToken cancellationToken = default
        );

        /// <summary>
        /// find a collection of Entities by proving a Conditional Expression ...
        /// </summary>
        /// <param name="predicate"></param>
        /// <param name="ignoreSoftDeleteds"></param>
        /// <param name="orderBuilder"></param>
        /// <param name="includeBuilder"></param>
        /// <param name="cancellationToken"></param>
        /// <returns></returns>
        Task<IEnumerable<T>> FindManyAsync(
            Expression<Func<T, bool>> predicate,
            bool ignoreSoftDeleteds = true,
            Func<IQueryable<T>, IOrderedQueryable<T>> orderBuilder = null,
            Func<IQueryable<T>, IIncludableQueryable<T, object>> includeBuilder = null,
            CancellationToken cancellationToken = default
        );

        /// <summary>
        /// retrieve Entities based on XQuery Pagination structure ...
        /// </summary>
        /// <param name="query"></param>
        /// <param name="ignoreSoftDeleteds"></param>
        /// <param name="predicate"></param>
        /// <param name="orderBuilder"></param>
        /// <param name="includeBuilder"></param>
        /// <param name="cancellationToken"></param>
        /// <returns></returns>
        Task<XQueryResult<T>> QueryAsync(
            XQuery query,
            bool ignoreSoftDeleteds = true,
            Expression<Func<T, bool>> predicate = null,
            Func<IQueryable<T>, IOrderedQueryable<T>> orderBuilder = null,
            Func<IQueryable<T>, IIncludableQueryable<T, object>> includeBuilder = null,
            CancellationToken cancellationToken = default
        );
        #endregion

        //
        #region Exists ...
        /// <summary>
        /// Check an Entity exists or not ...
        /// </summary>
        /// <param name="id"></param>
        /// <param name="ignoreSoftDeleteds"></param>
        /// <param name="cancellationToken"></param>
        /// <returns></returns>
        Task<bool> IsExistsAsync(
            TKey id,
            bool ignoreSoftDeleteds = true,
            CancellationToken cancellationToken = default
        );
        #endregion

        //
        #region Unit Of Work ...
        /// <summary>
        /// Save all unsaved Transactions on DbContext ...
        /// used fo Unit Of Works Design Pattern ...
        /// </summary>
        /// <param name="cancellationToken"></param>
        /// <returns></returns>
        Task<int> SaveChangesAsync(
            CancellationToken cancellationToken = default
        );
        #endregion

        //
        #region Key ...
        /// <summary>
        /// Retrieve Key of Entity ...
        /// </summary>
        /// <param name="item"></param>
        /// <returns></returns>
        TKey GetKey(T item);

        /// <summary>
        /// Set Key of Entity ...
        /// </summary>
        /// <param name="item"></param>
        /// <param name="id"></param>
        void SetKey(
            ref T item,
            TKey id
        );

        /// <summary>
        /// Handle Checking Key ...
        /// </summary>
        /// <param name="item"></param>
        /// <param name="cancellationToken"></param>
        /// <returns></returns>
        Task<T> HandleKeyAsync(
            T item,
            CancellationToken cancellationToken = default
        );
        #endregion

        //
        #region Detach ...
        /// <summary>
        /// Detach an Entity ...
        /// </summary>
        /// <param name="item"></param>
        void Detach(T item);

        /// <summary>
        /// Detach an Enumerable of Entities ...
        /// </summary>
        /// <param name="items"></param>
        void Detach(IEnumerable<T> items);

        /// <summary>
        /// Detach a Query Result of Entity ...
        /// </summary>
        /// <param name="query"></param>
        void Detach(XQueryResult<T> query);
        #endregion
    }
}