Skip to content

API.md

Latest commit

 

History

History
130 lines (89 loc) · 2.53 KB

API.md

File metadata and controls

130 lines (89 loc) · 2.53 KB

API Reference

Error codes

Defining codes

public sealed class UserErrors : ErrorCategory
{
    public static readonly ErrorCode NotFound = new("USER_001", "User not found");
    public static readonly ErrorCode InvalidEmail = new("USER_002", "Invalid email");
}

Registering codes

var registry = new ErrorCodeRegistry();
registry.RegisterCategory<UserErrors>();

Async registry access

var registry = new ErrorCodeRegistry();
await registry.TryRegisterAsync(UserErrors.NotFound, cancellationToken);

Errors

Creating errors

var error = AppError.From(UserErrors.NotFound)
    .WithContext("id", userId);

Error context

var error = AppError.From(UserErrors.InvalidEmail)
    .WithContext(new ErrorContext("email", address));

Metadata payload

var error = AppError.From(UserErrors.InvalidEmail)
    .WithMetadata("traceId", traceId);

Result pattern

Success and failure

Result<User> result = user;
Result failed = AppError.From(UserErrors.NotFound);

Throw on failure

result.ThrowIfFailure();

Problem Details

Mapping to RFC 7807

var details = ErrorProblemDetails.FromError(error, status: 400);

JSON serialization

var json = ErrorProblemDetailsJson.Serialize(details);
var roundTrip = ErrorProblemDetailsJson.Deserialize(json);

Error reporting

Publishing errors to observers

services.AddErrorKit();

var hub = provider.GetRequiredService<IErrorHub>();
hub.RegisterObserver(new ConsoleObserver());

var reporter = provider.GetRequiredService<IErrorReporter>();
reporter.Report(error);

Publishing errors to async observers

services.AddErrorKit();

var hub = provider.GetRequiredService<IErrorHub>();
hub.RegisterAsyncObserver(new TelemetryObserver());

var reporter = provider.GetRequiredService<IErrorReporter>();
await reporter.ReportAsync(error, cancellationToken);

Exception bridge

Converting errors to exceptions

var bridge = provider.GetRequiredService<IErrorExceptionBridge>();
throw bridge.ToException(error);

Converting exceptions to errors

var bridge = provider.GetRequiredService<IErrorExceptionBridge>();
var error = bridge.FromException(exception);

Async error factory

Creating errors asynchronously

var factory = provider.GetRequiredService<IAsyncErrorFactory>();
var error = await factory.CreateAsync(UserErrors.NotFound, cancellationToken: cancellationToken);