Namespace Trellis

Classes

AggregateETagExtensions

Extension methods for ETag-based optimistic concurrency validation on aggregate results. Two modes are available — the service owner chooses which to use:

OptionalETag<T>(Result<T>, EntityTagValue[]?) — If-Match is optional (skips if absent)
RequireETag<T>(Result<T>, EntityTagValue[]?) — If-Match is required (428 if absent)

AggregateError: Represents an aggregate of multiple errors that occurred together. Use this when multiple independent errors need to be returned as a single failure result.

Aggregate<TId>: Base class for aggregate roots in Domain-Driven Design. An aggregate is a cluster of domain objects (entities and value objects) that form a consistency boundary. The aggregate root is the only entry point for modifications and ensures all invariants within the boundary are maintained.

BadRequestError: Represents a bad request error indicating the request was malformed or syntactically invalid. Use this for requests that cannot be processed due to syntax errors, missing required data, or malformed content. Maps to HTTP 400 Bad Request.

BindExtensions: Provides extension methods for binding (chaining) operations over Result values.

BindExtensionsAsync: Provides asynchronous extension methods for binding (chaining) operations over Result values.

BindZipExtensions: Extension methods that bind a function to a Result and zip the original value with the new value into a tuple. Enables sequential accumulation of values through a pipeline.

BindZipExtensionsAsync: Async BindZip extensions where both input and function are async (Task).

CheckExtensions: Provides extension methods for running validation functions on Result values while preserving the original value on success. If the check fails, its failure is returned.

CheckExtensionsAsync: Async Check extensions where BOTH input and check function are async (Task).

CheckIfExtensions: Provides conditional check extension methods for Result values. The check function is only invoked when the condition or predicate is true; otherwise the original result passes through unchanged.

CheckIfExtensionsAsync: Async CheckIf extensions where BOTH input and check function are async (Task).

CombineErrorExtensions: Combine errors into one. If both the errors types are ValidationError, the validation errors will be merged. Otherwise, the errors will be wrapped into an AggregateError.

CombineExtensions: Combines two or more Result<TValue> into one tuple containing all the Results.

CombineExtensionsAsync: Combines two or more Result<TValue> into one tuple containing all the Results.

ConflictError: Represents a conflict error indicating the request conflicts with the current state of the resource. Use this when an operation cannot be completed due to a conflict with existing data or state. Maps to HTTP 409 Conflict.

ContentTooLargeError: Represents a content too large error when the server refuses a request because the content is larger than the server is willing or able to process. Maps to HTTP 413 Content Too Large (formerly Request Entity Too Large).

DiscardExtensions: Provides extension methods for explicitly discarding a Result value. Use when the outcome is intentionally ignored (e.g., best-effort operations). This is the idiomatic alternative to _ = result; and suppresses TRLS001 without requiring pragma directives.

DiscardTaskExtensions: Provides async extension methods for explicitly discarding a Task-wrapped Result value.

DiscardValueTaskExtensions: Provides async extension methods for explicitly discarding a ValueTask-wrapped Result value.

DomainError: Represents a domain or business rule violation. Use this for errors that occur when domain logic or business rules prevent an operation from completing. Maps to HTTP 422 Unprocessable Entity.

EnsureAllExtensions: Provides extension methods for ensuring multiple conditions on Result values simultaneously. Unlike Ensure<TValue>(Result<TValue>, Func<TValue, bool>, Error) which short-circuits on the first failure, EnsureAll runs ALL checks and accumulates errors into a single combined error.

EnsureAllExtensionsAsync: Provides asynchronous extension methods for EnsureAll validation accumulation on Result values.

EnsureExtensions: Provides extension methods for ensuring conditions on Result values. If conditions fail, the result is converted to a failure with the specified error.

EnsureExtensionsAsync: Async Ensure extensions where BOTH input and predicates are async (Task).

EntityTagValue: Represents an RFC 9110 §8.8.1 entity tag (ETag) value with explicit weak/strong semantics.

Entity<TId>: Base class for entities in Domain-Driven Design. An entity is a domain object defined by its identity rather than its attributes. Two entities with different attributes but the same ID are considered equal.

EnumValueAttribute: Specifies the canonical symbolic value for a RequiredEnum<TSelf> member.

Error: Base class for all error types in the functional DDD library. Errors represent failure states and contain structured information about what went wrong.

FlattenValidationErrorsExtensions: Extension methods for extracting ValidationError data from failed results.

ForbiddenError: Represents a forbidden error when an authenticated user lacks permission to access a resource. Use this when the user is authenticated but does not have the required authorization or role. Maps to HTTP 403 Forbidden.

GetValueOrDefaultExtensions: Terminal extraction methods for Result values.

GoneError: Represents a permanent removal error when a resource is no longer available and no forwarding address is known. This condition is expected to be permanent. Use this instead of NotFoundError when the server knows the resource previously existed and has been intentionally removed. Maps to HTTP 410 Gone.

MapExtensions: Provides extension methods for mapping (transforming) values inside Result objects.

MapExtensionsAsync: Provides asynchronous extension methods for mapping (transforming) values inside Result objects.

MapIfExtensions: Conditionally transforms the value inside a Result when a condition or predicate is met.

MapOnFailureExtensions: Provides extension methods for transforming errors in failed Results while leaving successful Results unchanged.

MatchErrorExtensions: Pattern matching helpers for discriminating specific error types in Result. Allows matching on specific error types (ValidationError, NotFoundError, etc.) rather than treating all errors the same.

MatchErrorExtensionsAsync: Asynchronous pattern matching helpers for discriminating specific error types in Result.

MatchExtensions: Pattern matching helpers (Match / Switch) for Result.

MatchExtensionsAsync: Asynchronous pattern matching helpers for Result.

Maybe: Contains static methods to create a Maybe<T> object.

MaybeChooseExtensions: Extension methods for filtering and unwrapping Maybe<T> collections.

MaybeCollectionExtensions: Extension methods for safely querying collections, returning Maybe<T> instead of throwing.

MaybeExtensions: Provides extension methods for converting Maybe<T> instances to Result<TValue> objects and for wrapping values in a Result<TValue>.

MaybeExtensionsAsync: Provides asynchronous extension methods for converting Maybe<T> instances to Result<TValue>.

MaybeLinqExtensions: Provides LINQ query expression support for Maybe types, enabling C# query syntax for optional value composition.

MethodNotAllowedError: Represents a method not allowed error when the HTTP method is not supported for the target resource. Maps to HTTP 405 Method Not Allowed.

NotAcceptableError: Represents a not acceptable error when the server cannot produce a representation that matches the client's stated preferences (e.g., Accept, Accept-Language). Maps to HTTP 406 Not Acceptable.

NotFoundError: Represents a "not found" error when a requested resource does not exist. Use this when an entity, record, or resource cannot be located. Maps to HTTP 404 Not Found.

NullableExtensions: Extension methods for converting nullable values to Result types. Provides a convenient way to handle null checking with Railway Oriented Programming.

NullableExtensionsAsync: Asynchronous extension methods for converting nullable values to Result types.

ParsableJsonConverter<T>: A JSON converter for value objects that implement IParsable<TSelf>. Enables automatic serialization and deserialization of parsable value objects in ASP.NET Core APIs and System.Text.Json scenarios.

PreconditionFailedError: Represents a precondition failure per RFC 9110 §13.1.1. The server will not perform the request because a condition in the request headers (e.g., If-Match, If-None-Match) evaluated to false. Maps to HTTP 412 Precondition Failed.

PreconditionRequiredError: Represents a precondition required error per RFC 6585 §3. The server requires the request to be conditional — the client must include a precondition header (e.g., If-Match) to proceed. Maps to HTTP 428 Precondition Required.

PrimitiveValueObjectTrace: Provides OpenTelemetry activity tracing for Trellis primitive value object operations. Enables monitoring and diagnostics of value object creation, validation, and parsing activities.

PrimitiveValueObjectTraceProviderBuilderExtensions: Provides extension methods for configuring OpenTelemetry tracing for Trellis primitive value objects.

RailwayTrackAttribute: Indicates which railway track an operation executes on. This metadata can be used by IDE extensions, analyzers, and documentation generators.

RangeAttribute: Specifies the minimum and maximum allowed values for numeric value objects (RequiredInt<TSelf>, RequiredDecimal<TSelf>, RequiredLong<TSelf>).

RangeNotSatisfiableError: Represents a range not satisfiable error when the server cannot serve the requested byte range for a resource. Maps to HTTP 416 Range Not Satisfiable.

RateLimitError: Represents a rate limiting error when too many requests have been made. Use this when a client has exceeded their request quota or rate limit. Maps to HTTP 429 Too Many Requests.

RecoverExtensions: Provides extension methods for recovering from failures with a fallback value. Unlike RecoverOnFailureExtensions which requires a function returning a Result, Recover takes a simple fallback value and always produces a success.

RecoverExtensionsAsync: Provides asynchronous extension methods for recovering from failures with a fallback value.

RecoverOnFailureExtensions: Provides extension methods for recovering from failed results by executing fallback operations.

RecoverOnFailureExtensionsAsync: Provides asynchronous extension methods for recovering from failed results.

RepresentationMetadata: Carries HTTP representation metadata (RFC 9110 §8) through Trellis response mappers. Used to emit ETag, Last-Modified, Vary, Content-Language, Content-Location, and Accept-Ranges response headers consistently across MVC and Minimal API responses (200, 201, 206, 304).

RepresentationMetadata.Builder: Fluent builder for constructing RepresentationMetadata instances.

RequiredBool<TSelf>: Base class for creating strongly-typed boolean value objects that distinguish between false (an explicit value) and null/missing (no value provided).

RequiredDateTime<TSelf>: Base class for creating strongly-typed DateTime value objects that prevent primitive obsession for dates. Rejects MinValue as the "empty" equivalent.

RequiredDecimal<TSelf>: Base class for creating strongly-typed decimal value objects that must be explicitly provided. Provides a foundation for monetary amounts, percentages, and other domain concepts represented by decimals.

RequiredEnumJsonConverter<TRequiredEnum>: JSON converter for RequiredEnum<TSelf> types. Serializes to the string value and deserializes from string value.

RequiredEnum<TSelf>: Base class for creating strongly-typed, behavior-rich enumeration value objects. Enum value objects are a DDD pattern that replaces C# enums with full-featured classes.

RequiredGuid<TSelf>: Base class for creating strongly-typed GUID value objects that cannot have the default (empty) GUID value. Provides a foundation for entity identifiers and other domain concepts represented by GUIDs.

RequiredInt<TSelf>: Base class for creating strongly-typed integer value objects that must be explicitly provided. Provides a foundation for entity identifiers, counts, and other domain concepts represented by integers.

RequiredLong<TSelf>: Base class for creating strongly-typed long integer value objects. Provides a foundation for large identifiers, sequence numbers, and other domain concepts represented by long integers.

RequiredString<TSelf>: Base class for creating strongly-typed string value objects that cannot be null or empty. Provides a foundation for domain primitives like names, descriptions, codes, and other textual concepts.

ResultDebugExtensions: Debug extension methods for inspecting Result values during development. These methods execute only in DEBUG builds and become no-ops in RELEASE builds (with zero overhead).

ResultDebugExtensionsAsync: Debug-only async extension methods for inspecting Result values during development. These methods are only available in DEBUG builds and are automatically excluded from RELEASE builds. Debug information is written to dedicated Activity spans for OpenTelemetry compatibility.

ResultDebugSettings: Controls runtime behavior of ResultDebugExtensions methods (Debug, DebugDetailed, DebugWithStack, DebugOnSuccess, DebugOnFailure).

ResultLinqExtensions: Provides LINQ query expression support for Result types, enabling C# query syntax for functional operations.

ResultsTraceProviderBuilderExtensions: Extension methods for configuring OpenTelemetry tracing for Railway Oriented Programming operations.

RetryAfterValue: Represents an RFC 9110 §10.2.3 Retry-After value, which can be either a delay in seconds or an absolute HTTP-date indicating when the client may retry.

ScalarValueObject<TSelf, T>: Base class for value objects that wrap a single scalar value. Provides a strongly-typed wrapper around primitive types with domain semantics.

ServiceUnavailableError: Represents a temporary service unavailability error. Use this when the service is temporarily unable to handle the request due to maintenance or overload. Maps to HTTP 503 Service Unavailable.

Specification<T>: Base class for the Specification pattern. Encapsulates a business rule as a composable, storage-agnostic expression tree.

StringExtensions: String manipulation helpers for value object field name normalization.

StringLengthAttribute: Specifies the minimum and maximum length of characters that are allowed in a RequiredString<TSelf>-derived value object.

TapExtensions: Provides extension methods for executing side effects on successful Results without changing the Result.

TapExtensionsAsync: Provides asynchronous extension methods for executing side effects on successful Results without changing the Result.

TapOnFailureExtensions: Provides extension methods for executing side effects on failed Results without changing the Result.

TapOnFailureExtensionsAsync: Provides asynchronous extension methods for executing side effects on failed Results without changing the Result.

ToMaybeExtensions: Provides extension methods for converting Result{T} to Maybe{T}. Success results become Some(value), failure results become None.

ToMaybeExtensionsAsync: Provides asynchronous extension methods for converting Result{T} to Maybe{T}.

TraverseExtensions: Transforms a collection of items into a Result containing a collection, short-circuiting on the first failure. Useful for processing collections where each item can fail independently.

UnauthorizedError: Represents an authorization error when authentication is required but not provided. Use this when a user is not authenticated (not logged in) and must authenticate to access the resource. Maps to HTTP 401 Unauthorized.

UnexpectedError: Represents an unexpected system error or exception. Use this for infrastructure failures, unhandled exceptions, or system-level errors. Maps to HTTP 500 Internal Server Error.

UnsupportedMediaTypeError: Represents an unsupported media type error when the server refuses a request because the content type is not supported for the target resource. Maps to HTTP 415 Unsupported Media Type.

ValidationError: Represents validation errors for one or more fields. Used when input data fails business rules or constraints.

ValueObject: Base class for value objects in Domain-Driven Design. A value object represents a descriptive aspect of the domain with no conceptual identity. Value objects are immutable, defined by their attributes, and support structural equality.

WhenExtensions: Conditionally executes an operation based on a predicate, maintaining the railway. Useful for executing operations only when certain conditions are met without breaking the Result chain.

WhenExtensionsAsync: Asynchronous conditional execution operations for Result.

Structs

Maybe<T>: Represents domain-level optionality — a value that was either provided or intentionally omitted. Unlike Nullable<T> (value types only) or T? (annotation only for reference types), Maybe<T> is a real generic type that works uniformly with both value and reference types and composes with Result<TValue> pipelines.

Result: Static Combine methods for combining multiple independent Result values without chaining.

Result<TValue>: Represents either a successful computation (with a value) or a failure (with an Error).

Unit: Represents the absence of a meaningful value, used for operations that have no return value. This is the functional programming equivalent of void, but as a proper type that can be used with generics.

ValidationError.FieldError: Represents an error for a specific field, which may have multiple detail messages.

Interfaces

IAggregate: Defines the contract for an aggregate root in Domain-Driven Design. An aggregate is a cluster of domain objects that can be treated as a single unit for data changes.

IDomainEvent: Represents a domain event - a record of something significant that happened in the business domain. Domain events capture state changes and business occurrences that domain experts care about.

IEntity: Non-generic interface for all entities in Domain-Driven Design. Provides automatic timestamp tracking — CreatedAt records when the entity was first persisted, and LastModified tracks the most recent change.

IFailureFactory<TSelf>: Enables construction of a failure result of the implementing type from an Error. Implemented by Result<TValue> to support generic pipeline behaviors that need to construct failure results without knowing the inner type parameter.

IFormattableScalarValue<TSelf, TPrimitive>: Extended interface for scalar value objects that support culture-sensitive string parsing. Use for numeric and date types where IFormatProvider matters for parsing.

IResult: Non-generic base interface for result types, exposing success/failure state and error information.

IResult<TValue>: Generic interface for result types, providing typed access to the success value.

IScalarValue<TSelf, TPrimitive>: Interface for scalar value objects that can be created with validation. Enables automatic ASP.NET Core model binding and JSON serialization.

Enums

TrackBehavior: Defines which railway track an operation runs on in Railway-Oriented Programming.