JorgeCostaMacia.ValueObject 6.0.4

JorgeCostaMacia.ValueObject

Immutable, type-safe value objects — primitives (int, long, float, double, decimal, bool, byte, string, Guid, DateTime, UTC DateTime), semantic strings (email, URL, IP, JSON), numeric/date ranges, and paging/ordering — each with the three-verb creation surface (constructor hydrates, From(...) converts unvalidated, Create(...) fabricates validated) and value equality. Every type ships a FluentValidation validator and a typed validation exception.

Install

dotnet add package JorgeCostaMacia.ValueObject

Usage

using JorgeCostaMacia.ValueObject.Domain;

EmailValueObject email = EmailValueObject.Create("user@host.com");   // validated: nothing invalid escapes Create
EmailValueObject draft = EmailValueObject.From("  user@host.com ");  // normalized but UNVALIDATED (composites' path)
string raw = email.Value;                                            // access the underlying value explicitly
string same = email;                                                 // or implicitly (VO -> primitive operator)

UuidValueObject id = UuidValueObject.Create(Guid.NewGuid());
DateTimeUtcValueObject when = DateTimeUtcValueObject.Create(DateTime.UtcNow);   // tags Utc kind; convert wall-clock at the call site

The three-verb creation surface

Each value object exposes exactly three ways in, on its natural primitive (convert other types at the call site):

• new X(value) — hydrates raw, no normalization, no validation. Reserved for infrastructure (ORMs, deserializers — the EF converters use it).
• X.From(value) — converts: normalizes and materializes, unvalidated. Composites build their parts through it so the whole object validates in one pass.
• X.Create(value) — fabricates validated: runs the type's validator and throws its typed …ValidationException (with the complete failure list) on violation.

Each type's validator also assembles itself: EmailValueObjectValidator.Create() chains the Create() of the validators it composes — or take the constructor and inject the composition via DI:

EmailValueObjectValidator.Create().ValidateAndThrow(email);   // throws EmailValueObjectValidationException on failure

Deriving your own value object

Derive from the matching base and keep the type inside the contract — a public hydration constructor plus your own From and Create (the inherited ones return the base type, so re-declare them with new static returning yours), each on the natural primitive:

public sealed record ClientName : StringValueObject
{
    public ClientName(string value) : base(value) { }                       // hydration ctor

    public new static ClientName From(string value) => new(Convert(value)); // Convert is the base's protected cleanser

    public new static ClientName Create(string value)
    {
        ClientName vo = From(value);
        ClientNameValidator.Create().ValidateAndThrow(vo);                  // your FluentValidation validator
        return vo;
    }
}

This surface is required, not optional: the ecosystem depends on it — the EF converters rehydrate through the constructor, deserializers too — so every value object here carries it and a contract test keeps it that way.

Register the validators

services.AddValueObjectContext();   // registers every IValidator<…> for the value objects

Requirements

One of the following SDKs: .NET 8 / 9 / 10 (.NET 10 recommended).

Depends on JorgeCostaMacia.Exception and FluentValidation.

About

JorgeCostaMacia.ValueObject is part of shared-net — a set of foundational, self-contained .NET packages, each scoped to a single concern and reusable across your bounded contexts.

• Repository: github.com/JorgeCostaMacia/shared-net
• Issues & requests: open an issue
• Contributing: CONTRIBUTING.md
• Security: report a vulnerability

Author: Jorge Costa Maciá

• LinkedIn
• GitHub
• Bitbucket