Skip to content

Effects

Effects are Deepstaging's core abstraction. Every service interaction — database calls, HTTP requests, messaging — flows through effects. One [EffectsModule] attribute gives you composable pipelines, compile-time dependency tracking, automatic observability, and structured error handling.

Quick Start

// 1. Define your service interface
public interface IEmailService
{
    Task SendAsync(string to, string subject, string body);
    Task<bool> ValidateAsync(string email);
}

// 2. Wrap it as an effects module
[EffectsModule(typeof(IEmailService))]
public sealed partial class EmailEffects;

// 3. Create a runtime — local modules are auto-discovered
[Runtime]
public sealed partial class AppRuntime;

The generator produces:

  • IHasEmailService — capability interface for the runtime
  • EmailEffects.EmailService.* — static Eff<RT, A> wrappers per method
  • Error context — failures carry EmailService.{Method} failed automatically
  • OpenTelemetry spans — one per effect invocation when Instrumented = true

Compose service calls:

public static Eff<RT, Unit> SendWelcomeEmail<RT>(string userId)
    where RT : IHasEmailService, IHasUserService =>
    from user   in UserEffects.UserService.GetByIdAsync<RT>(userId)
    from _valid in EmailEffects.EmailService.ValidateAsync<RT>(user.Email)
    from _sent  in EmailEffects.EmailService.SendAsync<RT>(
                       user.Email, "Welcome!", $"Hello {user.Name}")
    select unit;

What's Next

Page Description
Composition Eff<RT, A> type, from/select syntax, operators, collection traversal
Error Handling Auto-inferred error context, .MapFail(), HTTP response mapping
Resilience [Retry], [Timeout], [CircuitBreaker], [Recover] — declarative policies
Attributes [EffectsModule], [Capability] — properties, rules, examples
Generated Code Capability interfaces and effect method generation

Diagnostics

ID Severity Description
DSEFX01 Error EffectsModule class must be partial
DSEFX02 Warning EffectsModule class should be sealed
DSEFX03 Warning EffectsModule target should be an interface
DSEFX04 Error Duplicate EffectsModule target type
DSEFX05 Error Excluded method not found on target
DSEFX06 Error IncludeOnly method not found on target
DSEFX07 Warning EffectsModule target has no methods
DSEFX08 Error [Recover] fallback method not found or has incompatible return type
DSEFX09 Error [Recover] must specify either Fallback or Default, not both or neither