Event Queue Module¶

The Event Queue module generates in-process event queues backed by System.Threading.Channels.Channel<T>. It produces BackgroundService workers, effect module methods, and DI registration — all from a pair of attributes.

Event Queue is a general-purpose in-process pub/sub mechanism suitable for domain events, aggregate events, or any scenario where components within the same process need to communicate asynchronously.

Looking for cross-service integration events?

If your events need stable wire names, type registries, and external transport support (e.g., Azure Service Bus), use [IntegrationEventQueue] instead.

Quick Start¶

using Deepstaging.EventQueue;
using LanguageExt;

// Define the queue
[EventQueue(QueueName = "orders", Capacity = 1000, MaxConcurrency = 4)]
public static partial class OrderEvents;

// Define event types — plain records, no attributes required
public record OrderPlaced(string OrderId, string CustomerId);
public record OrderCancelled(string OrderId, string Reason);

// Define handlers targeting a runtime
[EventQueueHandler<AppRuntime>(QueueName = "orders")]
public static class OrderEventHandlers
{
    public static Eff<AppRuntime, Unit> Handle(OrderPlaced evt) =>
        from _ in NotificationEffects.Send<AppRuntime>(
            $"Order {evt.OrderId} placed by {evt.CustomerId}")
        select unit;

    public static Eff<AppRuntime, Unit> Handle(OrderCancelled evt) =>
        from _ in AuditEffects.Record<AppRuntime>(
            "OrderCancelled", evt.OrderId)
        select unit;
}

The generator produces:

Effect methods — OrderEvents.Enqueue(...), OrderEvents.EnqueueWithAck(...), OrderEvents.EnqueueAndWait(...)
Channel worker — a BackgroundService that reads from the channel and dispatches to handlers
DI registration — services.AddOrderEventsQueue()

Features¶

Feature	Description
Channel-backed queues	`System.Threading.Channels` — bounded or unbounded
Concurrency control	`MaxConcurrency` — sequential, limited, or unlimited
Eff-wrapped enqueue	`Enqueue`, `EnqueueWithAck`, `EnqueueAndWait`
BackgroundService worker	Auto-generated worker with dispatch and tracing
Transport abstraction	`IEventTransport<T>` — swap channel for external transport
DI registration	`AddXxxQueue()` with optional `EventQueueOptions<T>`
Testability	Inject `EventQueueChannel<T>` directly, drain events in tests

Sub-Pages¶

Page	Description
Attributes	`[EventQueue]` and `[EventQueueHandler<TRuntime>]` reference
Generated Code	Runtime types, enqueue strategies, concurrency, testing
Effects	Generated effect methods and composition patterns

Diagnostics¶

ID	Severity	Description
DSEQ01	Error	EventQueue class must be `partial`
DSEQ02	Warning	EventQueue class should be `static`
DSEQ03	Error	EventQueueHandler class must be `static`
DSEQ04	Warning	EventQueueHandler has no handler methods
DSEQ05	Error	EventQueueHandler references unknown queue name