DigitalData.Core/DigitalData.Core.Contracts/Application/IServiceMessage.cs

using System.Text.Json.Serialization;

namespace DigitalData.Core.Contracts.Application
{ 
    /// <summary>
    /// Defines a structured format for service messages, categorizing them into success indicators and various types of messages.
    /// This interface segregates messages into client-facing messages and different levels of logging messages, facilitating targeted communications and diagnostics.
    /// Properties are initialized once per instance and cannot be modified afterwards, promoting immutability.
    /// </summary>
    public interface IServiceMessage
    {
        /// <summary>
        /// Gets or sets a value indicating whether the service operation was successful.
        /// </summary>
        bool IsSuccess { get; set; }

        /// <summary>
        /// Represents the list of flags that indicate specific types of statuses or conditions in a service operation.
        /// These flags help in categorizing the state of the operation more granularly, allowing for multiple conditions to be represented simultaneously.
        /// </summary>
        [JsonIgnore]
        public ICollection<Enum> Flags { get; }

        /// <summary>
        /// Checks if any of the current service message's flags matches the specified flag based on their string representations.
        /// This method is useful for conditional logic where the exact string representation of the flag values is crucial.
        /// </summary>
        /// <param name="flag">The flag to check against the current service message's flags.</param>
        /// <returns>true if a flag with a matching string representation exists; otherwise, false.</returns>
        public bool HasFlag(Enum flag) => Flags.Any(f => f.ToString() == flag.ToString());

        /// <summary>
        /// [Obsolete("Deprecated: Use ClientMessages instead.")]
        /// Gets a collection of messages associated with the service operation. These messages can be error descriptions,
        /// success notifications, or other relevant information related to the operation's outcome.
        /// </summary>
        [Obsolete("Deprecated: Use ClientMessages instead.")]
        ICollection<string> Messages { get; init; }

        /// <summary>
        /// Gets a collection of messages intended for client display. This replaces the deprecated 'Messages' property.
        /// </summary>
        ICollection<string> ClientMessages { get; init; }

        /// <summary>
        /// Gets a collection of messages used for tracing program execution at a fine-grained level. These are typically voluminous and detailed.
        /// </summary>
        [JsonIgnore]
        ICollection<string> TraceMessages { get; init; }

        /// <summary>
        /// Gets a collection of messages helpful for debugging during development. These messages are often diagnostic.
        /// </summary>
        [JsonIgnore]
        ICollection<string> DebugMessages { get; init; }

        /// <summary>
        /// Gets a collection of informational messages, less critical than warnings, generally used for non-critical notifications.
        /// </summary>
        [JsonIgnore]
        ICollection<string> InformationMessages { get; init; }

        /// <summary>
        /// Gets a collection of messages indicating potential issues that are not necessarily errors, but which may require attention.
        /// </summary>
        [JsonIgnore]
        ICollection<string> WarningMessages { get; init; }

        /// <summary>
        /// Gets a collection of error messages indicating failures or problems within the service.
        /// </summary>
        [JsonIgnore]
        ICollection<string> ErrorMessages { get; init; }

        /// <summary>
        /// Gets a collection of messages indicating critical issues that require immediate attention.
        /// </summary>
        [JsonIgnore]
        ICollection<string> CriticalMessages { get; init; }

        /// <summary>
        /// A function that translates a message key from a string to its localized or transformed representation.
        /// This property allows for custom translation logic to be applied based on the application's needs.
        /// </summary>
        [JsonIgnore]
        public Func<string, string> KeyTranslator { get; init; }

        /// <summary>
        /// Adds a new message to the appropriate collection based on the message type.
        /// </summary>
        /// <param name="message">The message to add.</param>
        /// <returns>The current instance of IServiceMessage, allowing for method chaining.</returns>
        IServiceMessage WithMessage(string message);

        /// <summary>
        /// Adds a message corresponding to a specified message key to the appropriate collection, facilitating localization and standardization.
        /// </summary>
        /// <param name="messageKey">The enum value representing the message key.</param>
        /// <returns>The current instance of IServiceMessage, allowing for method chaining.</returns>
        IServiceMessage WithMessageKey(Enum messageKey);
    }
}