DigitalData.Core/DigitalData.Core.Contracts/Application/IResponseService.cs

namespace DigitalData.Core.Contracts.Application
{
    /// <summary>
    /// Defines the base functionality for a service, including creating service messages and results.
    /// </summary>
    public interface IResponseService
    {
        #region WITHOUT_MESSAGE

        /// <summary>
        /// Creates a simple service message indicating success or failure without any additional messages.
        /// </summary>
        /// <param name="isSuccess">Indicates if the operation was successful.</param>
        /// <returns>A service message indicating the outcome of the operation without any messages.</returns>
        IServiceMessage CreateMessage(bool isSuccess);

        /// <summary>
        /// Creates a service result with the specified data and a success flag, without any additional messages.
        /// </summary>
        /// <typeparam name="T">The type of data the service result will contain.</typeparam>
        /// <param name="data">The data for the service result.</param>
        /// <param name="isSuccess">Indicates if the operation was successful.</param>
        /// <returns>A service result containing the data and indicating the outcome of the operation without any messages.</returns>
        IServiceResult<T> CreateResult<T>(T? data, bool isSuccess);

        /// <summary>
        /// Creates a service message indicating a successful operation without any messages.
        /// </summary>
        /// <returns>A service message indicating a successful operation.</returns>
        IServiceMessage Successful();

        /// <summary>
        /// Creates a service message indicating a failed operation without any messages.
        /// </summary>
        /// <returns>A service message indicating a failed operation.</returns>
        IServiceMessage Failed();

        /// <summary>
        /// Creates a successful service result with the specified data, without any messages.
        /// </summary>
        /// <typeparam name="T">The type of data the service result will contain.</typeparam>
        /// <param name="data">The data to include in the service result.</param>
        /// <returns>A successful service result containing the data, indicating a successful operation without any messages.</returns>
        IServiceResult<T> Successful<T>(T data);

        /// <summary>
        /// Creates a failed service result, optionally including data, without any messages.
        /// </summary>
        /// <typeparam name="T">The type of data the service result can contain.</typeparam>
        /// <param name="data">Optional data to include in the failed service result.</param>
        /// <returns>A failed service result, which may or may not contain data, indicating a failed operation without any messages.</returns>
        IServiceResult<T> Failed<T>(T? data = default);

        #endregion
        #region WITH_STRING_MESSAGE

        /// <summary>
        /// Creates a service message.
        /// </summary>
        /// <param name="isSuccess">Indicates if the operation was successful.</param>
        /// <param name="messages">The messages associated with the operation.</param>
        /// <returns>A service message indicating the outcome of the operation and any associated messages.</returns>
        IServiceMessage CreateMessage(bool isSuccess, params string[] messages);

        /// <summary>
        /// Creates a service result with the specified data.
        /// </summary>
        /// <typeparam name="T">The type of data the service result will contain.</typeparam>
        /// <param name="data">The data for the service result.</param>
        /// <param name="isSuccess">Indicates if the operation was successful.</param>
        /// <param name="messages">The messages associated with the operation.</param>
        /// <returns>A service result containing the data and indicating the outcome of the operation.</returns>
        IServiceResult<T> CreateResult<T>(T? data, bool isSuccess, params string[] messages);

        /// <summary>
        /// Creates a successful service message.
        /// </summary>
        /// <param name="messages">The success messages.</param>
        /// <returns>A successful service message.</returns>
        IServiceMessage Successful(params string[] messages);

        /// <summary>
        /// Creates a failed service message.
        /// </summary>
        /// <param name="messages">The failure messages.</param>
        /// <returns>A failed service message.</returns>
        IServiceMessage Failed(params string[] messages);

        /// <summary>
        /// Creates a successful service result with the specified data.
        /// </summary>
        /// <typeparam name="T">The type of data the service result will contain.</typeparam>
        /// <param name="data">The data to include in the service result.</param>
        /// <param name="messages">The success messages.</param>
        /// <returns>A successful service result containing the data.</returns>
        IServiceResult<T> Successful<T>(T data, params string[] messages);

        /// <summary>
        /// Creates a failed service result, optionally including data.
        /// </summary>
        /// <typeparam name="T">The type of data the service result can contain.</typeparam>
        /// <param name="data">Optional data to include in the failed service result.</param>
        /// <param name="messages">The failure messages.</param>
        /// <returns>A failed service result, which may or may not contain data.</returns>
        IServiceResult<T> Failed<T>(T? data = default, params string[] messages);

        /// <summary>
        /// Creates a failed service result without explicitly including data, using only failure messages.
        /// </summary>
        /// <remarks>
        /// This overload is useful when you want to indicate a failure without the need to return any specific data,
        /// but still want to provide details about the failure through messages.
        /// </remarks>
        /// <typeparam name="T">The type of data the service result can contain. The result will contain the default value for this type.</typeparam>
        /// <param name="messages">An array of failure messages associated with the operation. These provide detail about why the operation failed.</param>
        /// <returns>A failed service result. The data part of the result will be set to the default value for the specified type.</returns>
        IServiceResult<T> Failed<T>(params string[] messages);

        #endregion
        #region WITH_ENUM_MESSAGE

        /// <summary>
        /// Creates a service message using enumeration values.
        /// </summary>
        /// <param name="isSuccess">Indicates if the operation was successful.</param>
        /// <param name="messages">The enumeration values associated with the operation.</param>
        /// <returns>A service message indicating the outcome of the operation and any associated enumeration values.</returns>
        IServiceMessage CreateMessage(bool isSuccess, params Enum[] messages);

        /// <summary>
        /// Creates a service result with the specified data and enumeration values for messages.
        /// </summary>
        /// <typeparam name="T">The type of data the service result will contain.</typeparam>
        /// <param name="data">The data for the service result.</param>
        /// <param name="isSuccess">Indicates if the operation was successful.</param>
        /// <param name="messages">The enumeration values associated with the operation.</param>
        /// <returns>A service result containing the data and indicating the outcome of the operation with enumeration values.</returns>
        IServiceResult<T> CreateResult<T>(T? data, bool isSuccess, params Enum[] messages);

        /// <summary>
        /// Creates a successful service message using enumeration values.
        /// </summary>
        /// <param name="messages">The success enumeration values.</param>
        /// <returns>A successful service message.</returns>
        IServiceMessage Successful(params Enum[] messages);

        /// <summary>
        /// Creates a failed service message using enumeration values.
        /// </summary>
        /// <param name="messages">The failure enumeration values.</param>
        /// <returns>A failed service message.</returns>
        IServiceMessage Failed(params Enum[] messages);

        /// <summary>
        /// Creates a successful service result with the specified data, using enumeration values for messages.
        /// </summary>
        /// <typeparam name="T">The type of data the service result will contain.</typeparam>
        /// <param name="data">The data to include in the service result.</param>
        /// <param name="messages">The success enumeration values.</param>
        /// <returns>A successful service result containing the data.</returns>
        IServiceResult<T> Successful<T>(T data, params Enum[] messages);

        /// <summary>
        /// Creates a failed service result, optionally including data, using enumeration values for messages.
        /// </summary>
        /// <typeparam name="T">The type of data the service result can contain.</typeparam>
        /// <param name="data">Optional data to include in the failed service result.</param>
        /// <param name="messages">The failure enumeration values.</param>
        /// <returns>A failed service result, which may or may not contain data.</returns>
        IServiceResult<T> Failed<T>(T? data = default, params Enum[] messages);

        /// <summary>
        /// Creates a failed service result without explicitly including data, using only enumeration values for failure messages.
        /// </summary>
        /// <remarks>
        /// This overload is useful when you want to indicate a failure without the need to return any specific data,
        /// but still want to provide details about the failure through enumeration values.
        /// </remarks>
        /// <typeparam name="T">The type of data the service result can contain. The result will contain the default value for this type.</typeparam>
        /// <param name="messages">An array of enumeration values associated with the operation. These provide detail about why the operation failed.</param>
        /// <returns>A failed service result. The data part of the result will be set to the default value for the specified type.</returns>
        IServiceResult<T> Failed<T>(params Enum[] messages);
        #endregion
    }
}