Table of Contents

Class MessageResultExtensions

Namespace
Excalibur.Dispatch
Assembly
Excalibur.Dispatch.Abstractions.dll

Extension methods for functional composition on IMessageResult<T>.

public static class MessageResultExtensions
Inheritance
MessageResultExtensions
Inherited Members

Remarks

These extensions enable railway-oriented programming patterns for message results, allowing cleaner code with Map, Bind, and Match patterns instead of verbose null checking.

Map preserves the dispatch metadata while transforming the value. A short-circuited Map or Bind preserves the original error, validation, authorization and disposition. A successful Bind returns the next operation's result, including that operation's metadata.

Example usage:

var result = await dispatcher
    .DispatchAsync<GetOrderAction, Order>(action, ct)
    .Map(order => new OrderDto(order))
    .Match(
        onSuccess: dto => Ok(dto),
        onFailure: problem => Problem(problem));

Methods

BindAsync<TIn, TOut>(IMessageResult<TIn>, Func<TIn, Task<IMessageResult<TOut>>>)

Chains result operations using an async binder function.

public static Task<IMessageResult<TOut>> BindAsync<TIn, TOut>(this IMessageResult<TIn> result, Func<TIn, Task<IMessageResult<TOut>>> binder)

Parameters

result IMessageResult<TIn>

The message result to chain.

binder Func<TIn, Task<IMessageResult<TOut>>>

The async function that returns a new result based on the success value.

Returns

Task<IMessageResult<TOut>>

A task representing the result of the binder function if the input was successful; otherwise, a failed result with the original ProblemDetails.

Type Parameters

TIn

The type of the input value.

TOut

The type of the output value.

Exceptions

ArgumentNullException

Thrown when result or binder is null.

Bind<TIn, TOut>(IMessageResult<TIn>, Func<TIn, IMessageResult<TOut>>)

Chains result operations, allowing composition of result-returning functions.

public static IMessageResult<TOut> Bind<TIn, TOut>(this IMessageResult<TIn> result, Func<TIn, IMessageResult<TOut>> binder)

Parameters

result IMessageResult<TIn>

The message result to chain.

binder Func<TIn, IMessageResult<TOut>>

The function that returns a new result based on the success value.

Returns

IMessageResult<TOut>

The result of the binder function if the input was successful; otherwise, a failed result with the original ProblemDetails.

Type Parameters

TIn

The type of the input value.

TOut

The type of the output value.

Exceptions

ArgumentNullException

Thrown when result or binder is null.

Bind<TIn, TOut>(Task<IMessageResult<TIn>>, Func<TIn, IMessageResult<TOut>>)

Chains result operations on an async result using a sync binder function.

public static Task<IMessageResult<TOut>> Bind<TIn, TOut>(this Task<IMessageResult<TIn>> resultTask, Func<TIn, IMessageResult<TOut>> binder)

Parameters

resultTask Task<IMessageResult<TIn>>

The task representing the message result to chain.

binder Func<TIn, IMessageResult<TOut>>

The function that returns a new result based on the success value.

Returns

Task<IMessageResult<TOut>>

A task representing the result of the binder function if the input was successful; otherwise, a failed result with the original ProblemDetails.

Type Parameters

TIn

The type of the input value.

TOut

The type of the output value.

Exceptions

ArgumentNullException

Thrown when resultTask or binder is null.

GetValueOrDefault<T>(IMessageResult<T>, T?)

Returns the success value or the specified default value.

public static T? GetValueOrDefault<T>(this IMessageResult<T> result, T? defaultValue = default)

Parameters

result IMessageResult<T>

The message result.

defaultValue T

The default value to return if the result is not successful.

Returns

T

The ReturnValue if successful and non-null; otherwise, defaultValue.

Type Parameters

T

The type of the value.

Exceptions

ArgumentNullException

Thrown when result is null.

GetValueOrThrow<T>(IMessageResult<T>)

Returns the success value or throws an exception with ProblemDetails information.

public static T GetValueOrThrow<T>(this IMessageResult<T> result)

Parameters

result IMessageResult<T>

The message result.

Returns

T

The ReturnValue.

Type Parameters

T

The type of the value.

Remarks

Use this method when you need the value and want to fail fast with a clear error. The thrown exception includes the IMessageProblemDetails in its Data dictionary.

Example usage:

var order = result.GetValueOrThrow(); // Throws if not successful

Exceptions

ArgumentNullException

Thrown when result is null.

InvalidOperationException

Thrown when the result is not successful or the return value is null. The exception message contains details from the ProblemDetails.

GetValueOrThrow<T>(Task<IMessageResult<T>>)

Returns the success value from an async result or throws an exception.

public static Task<T> GetValueOrThrow<T>(this Task<IMessageResult<T>> resultTask)

Parameters

resultTask Task<IMessageResult<T>>

The task representing the message result.

Returns

Task<T>

A task representing the ReturnValue.

Type Parameters

T

The type of the value.

Exceptions

ArgumentNullException

Thrown when resultTask is null.

InvalidOperationException

Thrown when the result is not successful or the return value is null.

MapAsync<TIn, TOut>(IMessageResult<TIn>, Func<TIn, Task<TOut>>)

Transforms the success value using an async mapping function.

public static Task<IMessageResult<TOut>> MapAsync<TIn, TOut>(this IMessageResult<TIn> result, Func<TIn, Task<TOut>> mapper)

Parameters

result IMessageResult<TIn>

The message result to transform.

mapper Func<TIn, Task<TOut>>

The async function to transform the success value.

Returns

Task<IMessageResult<TOut>>

A task representing a new IMessageResult<T> with the transformed value if successful; otherwise, a failed result with the original ProblemDetails.

Type Parameters

TIn

The type of the input value.

TOut

The type of the output value.

Exceptions

ArgumentNullException

Thrown when result or mapper is null.

Map<TIn, TOut>(IMessageResult<TIn>, Func<TIn, TOut>)

Transforms the success value using the specified mapping function.

public static IMessageResult<TOut> Map<TIn, TOut>(this IMessageResult<TIn> result, Func<TIn, TOut> mapper)

Parameters

result IMessageResult<TIn>

The message result to transform.

mapper Func<TIn, TOut>

The function to transform the success value.

Returns

IMessageResult<TOut>

A new IMessageResult<T> with the transformed value if successful; otherwise, a failed result with the original ProblemDetails.

Type Parameters

TIn

The type of the input value.

TOut

The type of the output value.

Exceptions

ArgumentNullException

Thrown when result or mapper is null.

Map<TIn, TOut>(Task<IMessageResult<TIn>>, Func<TIn, TOut>)

Transforms the success value of an async result using the specified mapping function.

public static Task<IMessageResult<TOut>> Map<TIn, TOut>(this Task<IMessageResult<TIn>> resultTask, Func<TIn, TOut> mapper)

Parameters

resultTask Task<IMessageResult<TIn>>

The task representing the message result to transform.

mapper Func<TIn, TOut>

The function to transform the success value.

Returns

Task<IMessageResult<TOut>>

A task representing a new IMessageResult<T> with the transformed value if successful; otherwise, a failed result with the original ProblemDetails.

Type Parameters

TIn

The type of the input value.

TOut

The type of the output value.

Exceptions

ArgumentNullException

Thrown when resultTask or mapper is null.

MatchAsync<TIn, TOut>(IMessageResult<TIn>, Func<TIn, Task<TOut>>, Func<IMessageProblemDetails?, Task<TOut>>)

Pattern matches on the result, executing the appropriate async handler.

public static Task<TOut> MatchAsync<TIn, TOut>(this IMessageResult<TIn> result, Func<TIn, Task<TOut>> onSuccess, Func<IMessageProblemDetails?, Task<TOut>> onFailure)

Parameters

result IMessageResult<TIn>

The message result to match on.

onSuccess Func<TIn, Task<TOut>>

The async function to execute when the result is successful.

onFailure Func<IMessageProblemDetails, Task<TOut>>

The async function to execute when the result is a failure.

Returns

Task<TOut>

A task representing the result of either onSuccess or onFailure.

Type Parameters

TIn

The type of the input value.

TOut

The type of the output value.

Exceptions

ArgumentNullException

Thrown when result, onSuccess, or onFailure is null.

Match<TIn, TOut>(IMessageResult<TIn>, Func<TIn, TOut>, Func<IMessageProblemDetails?, TOut>)

Pattern matches on the result, executing the appropriate handler.

public static TOut Match<TIn, TOut>(this IMessageResult<TIn> result, Func<TIn, TOut> onSuccess, Func<IMessageProblemDetails?, TOut> onFailure)

Parameters

result IMessageResult<TIn>

The message result to match on.

onSuccess Func<TIn, TOut>

The function to execute when the result is successful.

onFailure Func<IMessageProblemDetails, TOut>

The function to execute when the result is a failure.

Returns

TOut

The result of either onSuccess or onFailure.

Type Parameters

TIn

The type of the input value.

TOut

The type of the output value.

Exceptions

ArgumentNullException

Thrown when result, onSuccess, or onFailure is null.

Match<TIn, TOut>(Task<IMessageResult<TIn>>, Func<TIn, TOut>, Func<IMessageProblemDetails?, TOut>)

Pattern matches on an async result, executing the appropriate handler.

public static Task<TOut> Match<TIn, TOut>(this Task<IMessageResult<TIn>> resultTask, Func<TIn, TOut> onSuccess, Func<IMessageProblemDetails?, TOut> onFailure)

Parameters

resultTask Task<IMessageResult<TIn>>

The task representing the message result to match on.

onSuccess Func<TIn, TOut>

The function to execute when the result is successful.

onFailure Func<IMessageProblemDetails, TOut>

The function to execute when the result is a failure.

Returns

Task<TOut>

A task representing the result of either onSuccess or onFailure.

Type Parameters

TIn

The type of the input value.

TOut

The type of the output value.

Exceptions

ArgumentNullException

Thrown when resultTask, onSuccess, or onFailure is null.

TapAsync<T>(IMessageResult<T>, Func<T, Task>)

Executes an async side effect on success without modifying the result.

public static Task<IMessageResult<T>> TapAsync<T>(this IMessageResult<T> result, Func<T, Task> action)

Parameters

result IMessageResult<T>

The message result.

action Func<T, Task>

The async action to execute on the success value.

Returns

Task<IMessageResult<T>>

A task representing the original result unchanged.

Type Parameters

T

The type of the value.

Exceptions

ArgumentNullException

Thrown when result or action is null.

Tap<T>(IMessageResult<T>, Action<T>)

Executes a side effect on success without modifying the result.

public static IMessageResult<T> Tap<T>(this IMessageResult<T> result, Action<T> action)

Parameters

result IMessageResult<T>

The message result.

action Action<T>

The action to execute on the success value.

Returns

IMessageResult<T>

The original result unchanged.

Type Parameters

T

The type of the value.

Remarks

This method is useful for logging, metrics, or other side effects that should not alter the result chain.

Exceptions

ArgumentNullException

Thrown when result or action is null.

Tap<T>(Task<IMessageResult<T>>, Action<T>)

Executes a side effect on an async result without modifying it.

public static Task<IMessageResult<T>> Tap<T>(this Task<IMessageResult<T>> resultTask, Action<T> action)

Parameters

resultTask Task<IMessageResult<T>>

The task representing the message result.

action Action<T>

The action to execute on the success value.

Returns

Task<IMessageResult<T>>

A task representing the original result unchanged.

Type Parameters

T

The type of the value.

Exceptions

ArgumentNullException

Thrown when resultTask or action is null.