Interface IStreamTransformHandler<TInput, TOutput>
Defines a handler that transforms an input stream into an output stream.
public interface IStreamTransformHandler<in TInput, out TOutput> where TInput : IDispatchDocument
Type Parameters
TInputThe type of input documents in the stream.
TOutputThe 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
inputIAsyncEnumerable<TInput>The input stream of documents to transform.
cancellationTokenCancellationTokenThe 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).