Table of Contents

Interface IStreamTransformHandler<TInput, TOutput>

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

Defines a handler that transforms an input stream into an output stream.

public interface IStreamTransformHandler<in TInput, out TOutput> where TInput : IDispatchDocument

Type Parameters

TInput

The type of input documents in the stream.

TOutput

The type of output items produced by the transformation.

Extension Methods

Examples

public class EnrichmentHandler : IStreamTransformHandler<CustomerRecord, EnrichedCustomer>
{
    private readonly IExternalService _service;

    public EnrichmentHandler(IExternalService service) => _service = service;

    public async IAsyncEnumerable<EnrichedCustomer> HandleAsync(
        IAsyncEnumerable<CustomerRecord> input,
        [EnumeratorCancellation] CancellationToken cancellationToken)
    {
        await foreach (var record in input.WithCancellation(cancellationToken)
            .ConfigureAwait(false))
        {
            var enriched = await _service.EnrichAsync(record, cancellationToken)
                .ConfigureAwait(false);
            yield return enriched;
        }
    }
}

Remarks

Implement this interface for stream-to-stream transformations where an input stream is transformed into an output stream. This enables composable streaming pipelines with memory-efficient processing. Common use cases include:

  • Data enrichment: augmenting records with additional data from external sources
  • Format conversion: transforming records from one format to another
  • Filtering: selecting records that match specific criteria
  • Aggregation: grouping or summarizing input records into output summaries
  • Batching: combining multiple input items into batch outputs
  • Flattening: expanding single inputs into multiple outputs

The contravariant in modifier on TInput allows handlers to accept streams of derived document types. The covariant out modifier on TOutput enables returning streams of derived types where base types are expected.

Transform handlers can be chained together to form streaming pipelines where the output of one handler becomes the input to the next, without materializing intermediate results.

Handlers are resolved from dependency injection and should be registered with scoped lifetime to maintain state within a single stream processing operation.

Methods

HandleAsync(IAsyncEnumerable<TInput>, CancellationToken)

Transforms the input stream into an output stream asynchronously.

IAsyncEnumerable<out TOutput> HandleAsync(IAsyncEnumerable<in TInput> input, CancellationToken cancellationToken)

Parameters

input IAsyncEnumerable<TInput>

The input stream of documents to transform.

cancellationToken CancellationToken

The cancellation token to observe throughout the transformation.

Returns

IAsyncEnumerable<TOutput>

An asynchronous stream of transformed output items.

Remarks

Implementations should consume the input stream incrementally and yield outputs as they become available. This enables efficient pipeline processing without materializing intermediate collections.

Apply the [EnumeratorCancellation] attribute to the cancellation token parameter when implementing this method. Use WithCancellation(cancellationToken) when iterating the input stream to ensure proper cancellation propagation.

Transformations may produce zero, one, or multiple outputs per input item depending on the transformation logic (filtering, one-to-one, or one-to-many mapping).