/// <summary>
///     Discriminated union representing either a success value or a <see cref = "PsemError"/>.
/// </summary>
/// <typeparam name = "T">The success value type.</typeparam>
[SuppressMessage("Design", "CA1000:Do not declare static members on generic types", Justification = "Success/Failure factory methods are the standard pattern for Result types.")]
public readonly record struct Result<T>
{
#region Fields
    private readonly T? _value;
    private readonly PsemError? _error;
#endregion
#region Properties
    /// <summary>Gets a value indicating whether this result represents success.</summary>
    public bool IsSuccess { get; }
    /// <summary>Gets a value indicating whether this result represents failure.</summary>
    public bool IsFailure => !IsSuccess;
    /// <summary>Gets the success value. Throws if the result is a failure.</summary>
    /// <exception cref = "InvalidOperationException">The result is a failure.</exception>
    public T Value => IsSuccess ? _value! : throw new InvalidOperationException($"Cannot access Value on a failed result: {_error}");
    /// <summary>Gets the error. Throws if the result is a success.</summary>
    /// <exception cref = "InvalidOperationException">The result is a success.</exception>
    public PsemError Error => IsFailure ? _error!.Value : throw new InvalidOperationException("Cannot access Error on a successful result.");

#endregion
#region Constructors
    private Result(T value)
    {
        _value = value;
        _error = null;
        IsSuccess = true;
    }

    private Result(PsemError error)
    {
        _value = default;
        _error = error;
        IsSuccess = false;
    }

#endregion
#region Factory Methods
    /// <summary>Creates a successful result containing the specified value.</summary>
    public static Result<T> Success(T value) => new(value);
    /// <summary>Creates a failed result containing the specified error.</summary>
    public static Result<T> Failure(PsemError error) => new(error);
#endregion
#region Operators
    /// <summary>Implicitly converts a value to a successful result.</summary>
    public static implicit operator Result<T>(T value) => Success(value);
    /// <summary>Implicitly converts a <see cref = "PsemError"/> to a failed result.</summary>
    public static implicit operator Result<T>(PsemError error) => Failure(error);
    /// <summary>Named alternate for the implicit conversion from <typeparamref name = "T"/> to <see cref = "Result{T}"/>.</summary>
    public static Result<T> ToResult(T value) => Success(value);
    /// <summary>Named alternate for the implicit conversion from <see cref = "PsemError"/> to <see cref = "Result{T}"/>.</summary>
    public static Result<T> FromError(PsemError error) => Failure(error);
#endregion
#region Methods
    /// <summary>Pattern matches on the result, invoking the appropriate function.</summary>
    public TResult Match<TResult>(Func<T, TResult> onSuccess, Func<PsemError, TResult> onFailure)
    {
        ArgumentNullException.ThrowIfNull(onSuccess);
        ArgumentNullException.ThrowIfNull(onFailure);
        return IsSuccess ? onSuccess(_value!) : onFailure(_error!.Value);
    }

    /// <summary>Maps the success value using the specified function.</summary>
    public Result<TNew> Map<TNew>(Func<T, TNew> map)
    {
        ArgumentNullException.ThrowIfNull(map);
        return IsSuccess ? Result<TNew>.Success(map(_value!)) : Result<TNew>.Failure(_error!.Value);
    }

    /// <summary>Flat maps the success value using the specified function.</summary>
    public Result<TNew> Bind<TNew>(Func<T, Result<TNew>> bind)
    {
        ArgumentNullException.ThrowIfNull(bind);
        return IsSuccess ? bind(_value!) : Result<TNew>.Failure(_error!.Value);
    }

    /// <inheritdoc/>
    public override string ToString() => IsSuccess ? $"Success({_value})" : $"Failure({_error})";
#endregion
}