Class TraverseExtensions

Namespace

Trellis

Assembly

Trellis.Core.dll

Transforms a collection of items into a Result containing a collection, short-circuiting on the first failure. Useful for processing collections where each item can fail independently.

public static class TraverseExtensions

Inheritance

object

TraverseExtensions

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Examples

// Validate all items in a collection
var items = new[] { "item1", "item2", "item3" };
var result = items.Traverse(item => ValidateItem(item));

// Process collection asynchronously with cancellation
var orderIds = new[] { "order1", "order2", "order3" };
var orders = await orderIds.TraverseAsync(
    async (id, ct) => await FetchOrderAsync(id, ct),
    cancellationToken
);

// If any item fails, the entire operation fails with that error
// If all succeed, returns Success with IReadOnlyList of all results

Methods

Sequence(IEnumerable<Result<Unit>>)

Sequences a collection of no-payload Result<Unit> values into a single Result<Unit>. Short-circuits on the first failure.

public static Result<Unit> Sequence(this IEnumerable<Result<Unit>> source)

Parameters

source IEnumerable<Result<Unit>>

Source collection of results.

Returns

Result<Unit>

Success if every item succeeds; otherwise the first failure.

Remarks

First-failure-wins semantics, matching Traverse<TIn, TOut>(IEnumerable<TIn>, Func<TIn, Result<TOut>>). For per-field validation aggregation, use the Validate builder.

Exceptions

ArgumentNullException

Thrown when source is null.

Sequence<T>(IEnumerable<Result<T>>)

Sequences a collection of Result<TValue> into a single Result containing all values in source order. Short-circuits on the first failure.

public static Result<IReadOnlyList<T>> Sequence<T>(this IEnumerable<Result<T>> source)

Parameters

source IEnumerable<Result<T>>

Source collection of results.

Returns

Result<IReadOnlyList<T>>

Success carrying all values in order if every item succeeds; otherwise the first failure.

Type Parameters

T

Type of value carried by each result.

Examples

// Aggregate per-item Result<Money> subtotals, then sum the values.
var subtotalsResult = lineItems
    .Select(item => item.ComputeSubtotal())   // IEnumerable<Result<Money>>
    .Sequence();                                // Result<IReadOnlyList<Money>>

var totalResult = subtotalsResult.Bind(Money.Sum);

Remarks

Sequence is the identity-selector form of Traverse<TIn, TOut>(IEnumerable<TIn>, Func<TIn, Result<TOut>>): source.Sequence() ≡ source.Traverse(x => x). Use it when you already have an IEnumerable<T> of Results — typically the output of a Select over a function that returns Result<TValue>.

Failure semantics are first-failure-wins (matching Traverse<TIn, TOut>(IEnumerable<TIn>, Func<TIn, Result<TOut>>) and the current first-failure-wins design). For per-field validation aggregation, use the Validate builder which accumulates into a single Error.UnprocessableContent.

Exceptions

ArgumentNullException

Thrown when source is null.

TraverseAsync<TIn>(IEnumerable<TIn>, Func<TIn, CancellationToken, Task<Result<Unit>>>, CancellationToken)

Asynchronously transforms a collection of items using a no-payload Result<Unit> selector. Short-circuits on the first failure. Returns Result<Unit> (no collected values).

public static Task<Result<Unit>> TraverseAsync<TIn>(this IEnumerable<TIn> source, Func<TIn, CancellationToken, Task<Result<Unit>>> selector, CancellationToken cancellationToken = default)

Parameters

source IEnumerable<TIn>

selector Func<TIn, CancellationToken, Task<Result<Unit>>>

cancellationToken CancellationToken

Returns

Task<Result<Unit>>

Type Parameters

TIn

TraverseAsync<TIn, TOut>(IEnumerable<TIn>, Func<TIn, CancellationToken, Task<Result<TOut>>>, CancellationToken)

Asynchronously transforms a collection of items into a Result containing all transformed items. Short-circuits on the first failure. Supports cancellation.

public static Task<Result<IReadOnlyList<TOut>>> TraverseAsync<TIn, TOut>(this IEnumerable<TIn> source, Func<TIn, CancellationToken, Task<Result<TOut>>> selector, CancellationToken cancellationToken = default)

Parameters

source IEnumerable<TIn>

Source collection to transform.

selector Func<TIn, CancellationToken, Task<Result<TOut>>>

Async transformation function with cancellation support.

cancellationToken CancellationToken

Cancellation token to observe.

Returns

Task<Result<IReadOnlyList<TOut>>>

Task producing Success with all items if all succeed; otherwise the first failure.

Type Parameters

TIn

Type of input items.

TOut

Type of output items.

Exceptions

ArgumentNullException

Thrown when source or selector is null.

TraverseAsync<TIn, TOut>(IEnumerable<TIn>, Func<TIn, CancellationToken, ValueTask<Result<TOut>>>, CancellationToken)

Asynchronously transforms a collection of items using ValueTask with cancellation support. Short-circuits on the first failure.

public static ValueTask<Result<IReadOnlyList<TOut>>> TraverseAsync<TIn, TOut>(this IEnumerable<TIn> source, Func<TIn, CancellationToken, ValueTask<Result<TOut>>> selector, CancellationToken cancellationToken = default)

Parameters

source IEnumerable<TIn>

Source collection to transform.

selector Func<TIn, CancellationToken, ValueTask<Result<TOut>>>

Async transformation function with cancellation support.

cancellationToken CancellationToken

Cancellation token to observe.

Returns

ValueTask<Result<IReadOnlyList<TOut>>>

ValueTask producing Success with all items if all succeed; otherwise the first failure.

Type Parameters

TIn

Type of input items.

TOut

Type of output items.

Exceptions

ArgumentNullException

Thrown when source or selector is null.

TraverseAsync<TIn, TOut>(IEnumerable<TIn>, Func<TIn, Task<Result<TOut>>>)

Asynchronously transforms a collection of items into a Result containing all transformed items. Short-circuits on the first failure.

public static Task<Result<IReadOnlyList<TOut>>> TraverseAsync<TIn, TOut>(this IEnumerable<TIn> source, Func<TIn, Task<Result<TOut>>> selector)

Parameters

source IEnumerable<TIn>

Source collection to transform.

selector Func<TIn, Task<Result<TOut>>>

Async transformation function returning a Result.

Returns

Task<Result<IReadOnlyList<TOut>>>

Task producing Success with all items if all succeed; otherwise the first failure.

Type Parameters

TIn

Type of input items.

TOut

Type of output items.

Exceptions

ArgumentNullException

Thrown when source or selector is null.

TraverseAsync<TIn, TOut>(IEnumerable<TIn>, Func<TIn, ValueTask<Result<TOut>>>)

Asynchronously transforms a collection of items using ValueTask for zero-allocation scenarios. Short-circuits on the first failure.

public static ValueTask<Result<IReadOnlyList<TOut>>> TraverseAsync<TIn, TOut>(this IEnumerable<TIn> source, Func<TIn, ValueTask<Result<TOut>>> selector)

Parameters

source IEnumerable<TIn>

Source collection to transform.

selector Func<TIn, ValueTask<Result<TOut>>>

Async transformation function returning a Result.

Returns

ValueTask<Result<IReadOnlyList<TOut>>>

ValueTask producing Success with all items if all succeed; otherwise the first failure.

Type Parameters

TIn

Type of input items.

TOut

Type of output items.

Exceptions

ArgumentNullException

Thrown when source or selector is null.

Traverse<TIn, TOut>(IEnumerable<TIn>, Func<TIn, Result<TOut>>)

Transforms a collection of items into a Result containing all transformed items. Short-circuits on the first failure.

public static Result<IReadOnlyList<TOut>> Traverse<TIn, TOut>(this IEnumerable<TIn> source, Func<TIn, Result<TOut>> selector)

Parameters

source IEnumerable<TIn>

Source collection to transform.

selector Func<TIn, Result<TOut>>

Transformation function returning a Result.

Returns

Result<IReadOnlyList<TOut>>

Success with all items if all succeed; otherwise the first failure.

Type Parameters

TIn

Type of input items.

TOut

Type of output items.

Exceptions

ArgumentNullException

Thrown when source or selector is null.