Nuntius 0.1.0

Nuntius

Nuntius (Latin): messenger

Nuntius is a small, opinionated, open‑source C# library inspired by MediatR, designed to cover only a minimal, carefully chosen subset of its features.

What Nuntius Is

• A simple mediator / message dispatcher
• Focused on the most common use cases
• Easy to read, debug, and extend
• Designed to feel at home in modern C# codebases

What Nuntius Is Not

• A full MediatR replacement
• A plugin‑heavy or pipeline‑driven system

Nuntius deliberately implements only a small subset of MediatR concepts, and this scope is intentional and permanent.

Usage

Register Nuntius in your DI container (typically in Program.cs) and let it scan for your handlers:

using Microsoft.Extensions.DependencyInjection;

var services = new ServiceCollection();

services.AddNuntius(cfg => cfg
    .RegisterServicesFromAssemblyContaining<Program>());

You can customise the handler lifetime and default publishing strategy via the builder:

services.AddNuntius(cfg => cfg
    .RegisterServicesFromAssemblyContaining<Program>()
    .WithLifetime(ServiceLifetime.Scoped)
    .WithPublishStrategy(ParallelPublishStrategy.Instance));

Point to point communication

Nuntius supports the use case of point-to-point communication via requests and handlers. Two types of request + handler pairs are supported: those without a return value, and those with a return value.

You can create a request + handler pair without a return value:

using Nuntius;

public sealed record CreateUser(string Email) : IRequest;

public sealed class CreateUserHandler : IRequestHandler<CreateUser>
{
    public ValueTask Handle(CreateUser request, CancellationToken ct)
    {
        // ...create the user...
        return ValueTask.CompletedTask;
    }
}

If you need a return value, you can create a request + handler pair with a response type:

using Nuntius;

public sealed record Ping(string Message) : IRequest<string>;

public sealed class PingHandler : IRequestHandler<Ping, string>
{
    public ValueTask<string> Handle(Ping request, CancellationToken ct)
        => ValueTask.FromResult($"Pong: {request.Message}");
}

Finally, resolve IMediator and send the request:

var provider = services.BuildServiceProvider();

var mediator = provider.GetRequiredService<IMediator>();
await mediator.Send(new CreateUser("user@example.com"));

var result = await mediator.Send(new Ping("hello"));

You can also send the request using the ISender interface:

var provider = services.BuildServiceProvider();

var sender = provider.GetRequiredService<ISender>();
await sender.Send(new CreateUser("user@example.com"));

var result = await sender.Send(new Ping("hello"));

Pub-sub communication

Nuntius supports the use case of pub-sub communication via notifications and handlers.

You can create a notification with one or more handlers:

public sealed record UserCreated(string Email) : INotification { }

public sealed class EmailSender : INotificationHandler<UserCreated>
{
    public ValueTask Handle(UserCreated notification, CancellationToken ct)
    {
        // ...send a confirmation email...
        return ValueTask.CompletedTask;
    }
}

public sealed class UserWorkspaceCreator : INotificationHandler<UserCreated>
{
    public ValueTask Handle(UserCreated notification, CancellationToken ct)
    {
        // ...create user workspace...
        return ValueTask.CompletedTask;
    }
}

Finally, resolve IMediator and publish the notification:

var provider = services.BuildServiceProvider();

var mediator = provider.GetRequiredService<IMediator>();
await mediator.Publish(new UserCreated("user@example.com"));

You can also publish the notification using the IPublisher interface:

var provider = services.BuildServiceProvider();

var publisher = provider.GetRequiredService<IPublisher>();
await publisher.Publish(new UserCreated("user@example.com"));

You can register zero or more handlers for each notification type. If no handlers are registered for a notification type, publishing it will have no effect.

Publishing strategies

Nuntius ships with three built-in publishing strategies that control how notification handlers are executed:

The default strategy is set at registration time via WithPublishStrategy(). You can also override it per-call:

await mediator.Publish(new UserCreated("user@example.com"), ParallelPublishStrategy.Instance);

⚠️ Thread-safety note for ParallelPublishStrategy

Notification handlers are resolved from the current DI scope before they are passed to the strategy. When multiple handlers share a scoped dependency that is not thread-safe (e.g. an Entity Framework DbContext), ParallelPublishStrategy will execute those handlers concurrently on the same instance, which can lead to race conditions.

If your handlers have non-thread-safe scoped dependencies, prefer SequentialPublishStrategy or ensure thread safety in your handlers.

When to Use Nuntius

Nuntius is a good fit if you:

• Like the mediator pattern
• Are looking for a simple way to implement the CQRS pattern
• Want fewer abstractions
• Prefer small, understandable libraries
• Don’t need every MediatR feature

If you need advanced pipelines, behaviors, or extensive extension points, MediatR is likely the better choice.

If you need a full message bus with support for sagas and message persistence, OpenSleigh can be a good alternative.