Philiprehberger.ValueOf 0.2.0

Philiprehberger.ValueOf

Strongly-typed value objects with built-in validation and JSON support — eliminate primitive obsession.

Installation

dotnet add package Philiprehberger.ValueOf

Usage

Define a custom value object

using Philiprehberger.ValueOf;

public class EmailAddress : ValueOf<string, EmailAddress>
{
    protected override void Validate()
    {
        if (string.IsNullOrWhiteSpace(Value) || !Value.Contains('@'))
            throw new ValueOfValidationException(typeof(EmailAddress), "Invalid email address.");
    }
}

Create and use instances

var email = EmailAddress.From("user@example.com");
string raw = email;                    // implicit conversion to string
var copy = (EmailAddress)"a@b.com";    // explicit conversion from string

Console.WriteLine(email);              // "user@example.com"
Console.WriteLine(email == copy);      // False

Built-in types

var name = NonEmptyString.From("Alice");
var count = PositiveInt.From(42);
var rate = Percentage.From(99.5m);

// Validation throws on invalid values
NonEmptyString.From("");     // throws ValueOfValidationException
PositiveInt.From(-1);        // throws ValueOfValidationException
Percentage.From(101m);       // throws ValueOfValidationException

Non-throwing creation with TryFrom

using Philiprehberger.ValueOf;

if (PositiveInt.TryFrom(userInput, out var positive))
{
    Console.WriteLine($"Got {positive!.Value}");
}
else
{
    Console.WriteLine("Invalid value, no exception raised.");
}

Additional built-in types

using Philiprehberger.ValueOf;

var clicks = NonNegativeInt.From(0);
var ratio = UnitInterval.From(0.75m);          // 0 ≤ value ≤ 1
var name = NonEmptyTrimmedString.From("  hi "); // stores "hi"

JSON serialization

using System.Text.Json;

var options = new JsonSerializerOptions();
options.Converters.Add(new ValueOfJsonConverterFactory());

var json = JsonSerializer.Serialize(email, options);   // "\"user@example.com\""
var back = JsonSerializer.Deserialize<EmailAddress>(json, options);

API

ValueOf<TValue, TSelf>

ValueOfJsonConverterFactory

ValueOfValidationException

Built-in Types

ValueOfAttribute

Marker attribute for decorating value object types. Reserved for future source generator support.

Development

dotnet build src/Philiprehberger.ValueOf.csproj --configuration Release

Support

If you find this project useful:

⭐ Star the repo

🐛 Report issues

💡 Suggest features

❤️ Sponsor development

🌐 All Open Source Projects

💻 GitHub Profile

🔗 LinkedIn Profile

License

MIT