xDataService/Interfaces/IXBaseReferencedProvider.cs

using System.Collections.Generic;
using System.Threading;
using System.Threading.Tasks;
using xDataService.Models;
using xModels.Dtos;

namespace xDataService.Interfaces
{
    /// <summary>
    /// in Some Cases we have Entities Which Can Referenced for Specified 
    /// Provider and Types ...
    /// this interface Globaly introduce all available Actions for those ...
    /// 
    /// TKey: type of Provider Models Keys ...
    /// TModel: type of Dto which Referenced ...
    /// </summary>
    public interface IXBaseReferencedProvider<TModel, TKey>
    {
        //
        #region Props ...
        /// <summary>
        /// Provider Identifier ...
        /// </summary>
        string Provider { get; }
        #endregion

        //
        #region Referenced Actions ...
        /// <summary>
        /// Get Specified Indexed Reference for Specific Provided ID ...
        /// </summary>
        /// <param name="providedForId"></param>
        /// <param name="forIndex"></param>
        /// <param name="cancellationToken"></param>
        /// <returns></returns>
        Task<TModel> GetReference(
            TKey providedForId,
            int forIndex = 0,
            CancellationToken cancellationToken = default
        );

        /// <summary>
        /// Retrieve all Exists References of Specific Provided ID ...
        /// </summary>
        /// <param name="providedForId"></param>
        /// <param name="cancellationToken"></param>
        /// <returns></returns>
        Task<IEnumerable<TModel>> GetAllReferences(
            TKey providedForId,
            CancellationToken cancellationToken = default
        );

        /// <summary>
        /// Extract all Referencing Models for Specified Key ...
        /// </summary>
        /// <param name="providedForId"></param>
        /// <param name="cancellationToken"></param>
        /// <returns></returns> 
        Task<IEnumerable<XReference<TKey>>> GetAllReferencings(
            TKey providedForId,
            CancellationToken cancellationToken = default
        );

        /// <summary>
        /// Count References ...
        /// </summary>
        /// <param name="providedForId"></param>
        /// <param name="cancellationToken"></param>
        /// <returns></returns>
        Task<int> CountReferences(
            TKey providedForId,
            CancellationToken cancellationToken = default
        );

        /// <summary>
        /// Retrieve References of Specific Provided ID as Query ...
        /// </summary>
        /// <param name="query"></param>
        /// <param name="providedForId"></param>
        /// <param name="cancellationToken"></param>
        /// <returns></returns>
        Task<XQueryResult<TModel>> QueryReferences(
            XQuery query,
            TKey providedForId,
            CancellationToken cancellationToken = default
        );

        /// <summary>
        /// Add Reference a Model to Specific Provided ID ...
        /// </summary>
        /// <param name="model"></param>
        /// <param name="providedForId"></param>
        /// <param name="connectionId"></param>
        /// <param name="cancellationToken"></param>
        /// <returns></returns>
        Task<bool> AddReference(
            TModel model,
            TKey providedForId,
            string connectionId = null,
            CancellationToken cancellationToken = default
        );

        /// <summary>
        /// Add Reference a Model to Specific XRefence<TKey/> ...
        /// </summary>
        /// <param name="model"></param>
        /// <param name="reference"></param>
        /// <param name="connectionId"></param>
        /// <param name="cancellationToken"></param>
        /// <returns></returns>
        Task<bool> AddReference(
            TModel model,
            XReference<TKey> reference,
            string connectionId = null,
            CancellationToken cancellationToken = default
        );

        /// <summary>
        /// Remove Reference a Model for Specific Provided ID ...
        /// </summary>
        /// <param name="model"></param>
        /// <param name="providedForId"></param>
        /// <param name="connectionId"></param>
        /// <param name="cancellationToken"></param>
        /// <returns></returns>
        Task<bool> RemoveReference(
            TModel model,
            TKey providedForId,
            string connectionId = null,
            CancellationToken cancellationToken = default
        );

        /// <summary>
        /// Remove Reference a Model for Specific XRefence<TKey/> ...
        /// </summary>
        /// <param name="model"></param>
        /// <param name="reference"></param>
        /// <param name="connectionId"></param>
        /// <param name="cancellationToken"></param>
        /// <returns></returns>
        Task<bool> RemoveReference(
            TModel model,
            XReference<TKey> reference,
            string connectionId = null,
            CancellationToken cancellationToken = default
        );

        /// <summary>
        /// Remove All References to Specified Key ...
        /// </summary>
        /// <param name="providedForId"></param>
        /// <param name="connectionId"></param>
        /// <param name="cancellationToken"></param>
        /// <returns></returns>
        Task<bool> RemoveReferences(
            TKey providedForId,
            string connectionId = null,
            CancellationToken cancellationToken = default
        );
        #endregion
    }
}