Trellis.Primitives 3.0.0-alpha.100

Primitive Value Objects

Infrastructure and ready-to-use implementations for primitive value objects with source code generation, eliminating boilerplate code and primitive obsession in domain-driven design applications.

Installation

Install both packages via NuGet:

dotnet add package Trellis.Primitives
dotnet add package Trellis.Primitives.Generator

Important: Both packages are required:

• Trellis.Primitives — Base classes and 12 ready-to-use value objects
• Trellis.Primitives.Generator — Source generator for Required* derivatives

Quick Start

RequiredString

Create strongly-typed string value objects using source code generation:

public partial class TrackingId : RequiredString<TrackingId>
{
}

// The source generator automatically creates:
// - TryCreate(string?, string? fieldName = null) -> Result<TrackingId>
// - Parse / TryParse (IParsable<T>)
// - explicit operator TrackingId(string)

var result = TrackingId.TryCreate("TRK-12345");
if (result.IsSuccess)
    Console.WriteLine(result.Value); // TRK-12345

// With custom field name for validation errors
var result2 = TrackingId.TryCreate(input, "shipment.trackingId");

Optional: enforce length constraints with [StringLength]:

[StringLength(50)]
public partial class FirstName : RequiredString<FirstName> { }

[StringLength(500, MinimumLength = 10)]
public partial class Description : RequiredString<Description> { }

RequiredGuid

Use NewUniqueV7() for time-ordered, sortable identifiers — GUID V7 provides the same benefits as ULIDs (sequential, timestamp-embedded) with the standard System.Guid type.

public partial class EmployeeId : RequiredGuid<EmployeeId>
{
}

var employeeId = EmployeeId.NewUniqueV7(); // Time-ordered, sortable
var result = EmployeeId.TryCreate(guid);
var result2 = EmployeeId.TryCreate("550e8400-e29b-41d4-a716-446655440000");

RequiredInt and RequiredDecimal

public partial class Quantity : RequiredInt<Quantity> { }
public partial class Price : RequiredDecimal<Price> { }

var qty = Quantity.TryCreate(10);
var price = Price.TryCreate(99.99m);

Ready-to-Use Value Objects

var email = EmailAddress.TryCreate("user@example.com");
var url = Url.TryCreate("https://example.com/path");
var phone = PhoneNumber.TryCreate("+14155551234");
var pct = Percentage.TryCreate(15.5m);
var money = Money.TryCreate(99.99m, "USD");

RequiredEnum

Type-safe enumerations that replace C# enums with full-featured classes:

public partial class OrderState : RequiredEnum<OrderState>
{
    public static readonly OrderState Draft = new();
    public static readonly OrderState Confirmed = new();
    public static readonly OrderState Shipped = new();
}

var result = OrderState.TryCreate("Confirmed");
// result.Value == OrderState.Confirmed

ASP.NET Core Integration

Value objects implementing IScalarValue work seamlessly with ASP.NET Core:

// 1. Register in Program.cs
builder.Services
    .AddControllers()
    .AddScalarValueValidation();

// 2. Use in DTOs
public record CreateUserDto
{
    public FirstName FirstName { get; init; } = null!;
    public EmailAddress Email { get; init; } = null!;
    public Maybe<Url> Website { get; init; } // Optional — null → Maybe.None
}

// 3. Controllers get automatic validation
[HttpPost]
public IActionResult Create(CreateUserDto dto)
{
    // All value objects validated on deserialization!
    return Ok(dto);
}

See Trellis.Asp for full ASP.NET Core integration.

Generated Code Features

• TryCreate methods returning Result<T> with optional fieldName parameter
• IParsable<T> implementation (Parse/TryParse)
• Explicit cast operators
• Property name inference for error messages (class name → camelCase)
• JSON serialization via ParsableJsonConverter<T>
• OpenTelemetry activity tracing support

Best Practices

1. Use partial classes — Required for source code generation
2. Leverage generated methods — Use TryCreate for safe parsing
3. Use the fieldName parameter — Better validation error messages in APIs
4. Prefer specific types over primitives — EmployeeId is more expressive than Guid
5. Use meaningful names — Class name becomes part of error messages

Related Packages

• Trellis.Primitives.Generator — Source generator (required companion)
• Trellis.Results — Core Result<T> type
• Trellis.DomainDrivenDesign — Entity and aggregate patterns
• Trellis.Asp — ASP.NET Core integration

License

MIT — see LICENSE for details.