Yoyoyopo5.ValueWrapper 1.1.2

Yoyoyopo5.ValueWrapper

Eliminate primitive obsession in your codebase without unnecessary heap allocations or boilerplate. ValueWrapper makes it easy.

Usage

Create a Wrapper Type

[Wrapper<string>]
public readonly partial record struct ColorName; 

Generally, wrappers should be record struct types, but a wrapper can be any partial type and can wrap any type:

public record Person(string Name, uint Age);

[Wrapper<Person>]
public partial class InactivePerson;

Use Cases

Reduce Bugs with Constrained Signatures

Turn runtime exceptions into compile-time errors:

Before:

void UpdateColorBuggy(string colorName) { }
string username = "xX_username_Xx";

...

UpdateColorBuggy(username); // Compiles with bug!

After:

// I can only take a ColorName type.
void UpdateColor(ColorName color) { }
Username username = new("xX_username_Xx");

...

UpdateColor(username); // Compiler error! 

Create Enumerations

Have a set of possible values? Don't use an enum, use a wrapper with static definitions:

[Wrapper<string>]
public readonly partial record struct ReportStatus
{
    public static ReportStatus Accepted { get; } = new("accepted");
    public static ReportStatus Rejected { get; } = new("rejected");
    public static ReportStatus Unknown { get; } = new("unknown");

    public string Value { get; }
    private ReportStatus(string value) => Value = value;

    internal static ReportStatus Create(string value) => new(value);
}

You can also create unbounded value sets:

[Wrapper<string>]
public readonly partial record struct ColorName(string Value)
{
    public static ColorName SkyBlue { get; } = new("sky_blue");
    public static ColorName EggplantPurple { get; } = new("eggplant_purple");
}

ColorName _customColor = new("very_red");

Add Validation

Wrapper types can be used to put validation at the type level, instead of littered around your codebase:

[Wrapper<int>]
public readonly partial record struct EvenNumber
{
    public int Value { get; private init; }

    public static EvenNumber? ParseOrNull(int value)
        => value switch 
        {
            _ when value % 2 != 0 => null,
            _ => new() { Value = value }
        };

    internal static EvenNumber Create(int value)
        => ParseOrNull(value) is EvenNumber even ? even : throw new ArgumentException("value must be even.");
} 

Create Bounded Extensions

Don't extend primitives; extend wrappers instead:

public static BadExtensions
{
    public static decimal ConvertToMiles(this decimal kilometers) { }
}

[Wrapper<decimal>]
public partial record Kilometers;

[Wrapper<decimal>]
public partial record Miles;

public static KilometersExtensions
{
    public static Miles ConvertToMiles(this Kilometers kilometers) { }
}

Wrapper Features

Value Property

A required Value property is created by default:

ColorName color = new() { Value = "red" };
string name = color.Value;

Explicit In, Implicit Out

Wrapper types can be freely used as their wrapped type (but not the other way around).

ColorName color = new() { Value = "orange" };
string.IsNullOrEmpty(color);

ColorName badColor = "orange" // Does not compile!

ToString() Passthrough

ColorName color = new() { Value = "red" };
Console.WriteLine(color); // "red"

System.Text.Json Passthrough

ColorName color = new() { Value = "green" };
string json = JsonSerializer.Serialize(color);
Console.WriteLine(json); // "green"

ColorName deserializedColor = JsonSerializer.Deserialize<ColorName>(json);
Console.WriteLine(deserializedColor); // "green"

TypeConverter Support

A TypeConverter is added to the wrapper that can create the wrapper to and from its wrapped type. Conversion from string is also supported via TypeConverter passthrough.

This allows wrappers to be used as their wrapped type in many scenarios, like IConfigurationBinder binding or ASP.NET Core query parameter binding.

Nested Wrappers

Wrappers inside other classes are supported, as long as each containing class is marked partial:

public partial class Container
{
    [Wrapper<int>]
    private readonly partial record struct Cents;
}

Wrapper Customization

Record Primary Constructor

A record primary constructor can define the Value property, meaning the required property will not be automatically generated:

[Wrapper<Guid>]
public partial record UserId(Guid Value);

Disable Required Value Property

You can also disable the required property manually:

[Wrapper<double>]
public readonly partial record struct FeetPerSecond
{
    public double Value { get; init; }
}

Override Wrapper Features

You can override any generated wrapper behavior:

[Wrapper<string>]
[JsonConverter(typeof(IdeaConverter))] // Disables the default WrapperJsonConverter
public partial class Idea(string Value)
{
    public string? Value { get; set; } // Overrides the default Value property
    public override string ToString() => "Nobody can know!" // Overrides the ToString passthrough
    public static implicit operator string(Idea idea) => "Hey, that's my idea!" // Overrides the implicit out operator
}

Override JSON Creation Behavior

Think you need a custom JsonConverter? Maybe not! The converter will use a constructor with a single wrapped type parameter:

[Wrapper<int>]
public partial record NegativeNumber 
{
    public int Value { get; }

    public NegativeNumber(int value)
    {
        if (value > 0)
            throw new ArgumentException("Number must be negative!");
        Value = value;
    }
}

Don't like constructors? No problem. You can configure the static Create(value) method, and the default WrapperJsonConverter will use it:

[Wrapper<int>]
public readonly partial record struct NegativeNumber
{
    public int Value { get; private init; }

    public static NegativeNumber Create(int value)
        => value switch 
        {
            _ when value > 0 => throw new ArgumentException("Number must be negative!"),
            _ => new() { Value = value }
        };
}

Benchmarks (v1.1.2)

ToString Passthrough

Wrapped struct

Wrapped double

Wrapped string

System.Text.Json Round-Trip

Non-built-in wrapped types incur a penalty.

Wrapped struct

Wrapped double

Wrapped string

System.Text.Json Round-Trip Dictionary with Wrapper Keys

TypeConverter Round-Trip (to/from string)

Wrapped struct

Wrapped double

Wrapped string

Source Generator