CodoMetis.TypeKit.Generators 2.0.0

CodoMetis.TypeKit.Generators

Compile-time generation of value objects and closed sets (smart enums) for CodoMetis.TypeKit, built on Metalama. One line becomes a complete value object, with its JSON converter, parsing, formatting, comparison, type converter and query companions, each applying the one Create you wrote.

dotnet add package CodoMetis.TypeKit.Generators

Reference it in the project that declares value objects. Projects that reference that one, directly or further down, inherit the generators without referencing the package themselves. Metalama.Framework flows with it, because the fabric that applies the aspects runs in every one of those projects. No Metalama license key is needed, there or here: the generators build on Metalama's Open Source edition.

How this compares with Vogen, Thinktecture.Runtime.Extensions and StronglyTypedId, and when one of them is the better choice: How it compares.

Built with Metalama

This package exists in this form because of Metalama. A transitive fabric finds every type that implements a TypeKit contract, in the project that references this package and in every project that references that one, so a value object is declared by its interface and nothing else. Templates write the generated members as ordinary C#, which you can read (see "Reading the generated code"). A declaration that cannot be generated fails the build with its name on it (see "Build errors") instead of compiling to less than it appears to. Thanks to the Metalama team.

Declaring a value object

using CodoMetis.TypeKit;
using CodoMetis.TypeKit.ValueObjects;

public readonly partial record struct OrderId : IValue<Guid>;

public readonly partial record struct Quantity : IValue<int>;

public enum EmailFault { Blank, NoAt, TooLong }

public readonly partial record struct Email : IValidatedValue<Email, string, EmailFault>
{
    public static Result<Email, EmailFault> Create(string value)
    {
        if (string.IsNullOrWhiteSpace(value)) return Result.Error(EmailFault.Blank);

        var trimmed = value.Trim();
        if (!trimmed.Contains('@')) return Result.Error(EmailFault.NoAt);
        if (trimmed.Length > 254) return Result.Error(EmailFault.TooLong);

        return new Email(trimmed);   // the private constructor is generated
    }
}

A value object is a readonly partial record struct, or a sealed partial record class when it has to be a reference type. IValue<T> wraps any T; IValidatedValue<TSelf, T, TFault> adds Create, the one method you write, and every generated way in applies it.

A validated value object has no From. Its ways in are Create, TryFrom and FromKnownGood, so nothing that looks harmless throws on input: the one factory that throws says in its name that the caller vouches for the value, and its exception names the call site, never the value. The fault Create returns is what every refusal reports, in that exception, in the JSON converter's JsonException and in Parse's FormatException.

A value object may be declared inside another type. Order.Id is generated like any other, and its companion class is OrderIdExtensions, named after the whole nesting chain so that Order.Id and Customer.Id do not collide.

var id = OrderId.New();                          // a version 7 Guid
var quantity = Quantity.From(3);

Result<Email, EmailFault> created = Email.Create(input);       // says what to fix
Option<Email> maybe = Email.TryFrom(input);                    // is it valid?
Email known = Email.FromKnownGood("ops@example.com");          // yours to guarantee; throws otherwise

int three = quantity.Value;                      // 3
bool same = quantity == Quantity.From(3);        // true, value equality
string text = quantity.ToString();               // "3"

What can be wrapped

Any non-generic class, struct or enum, with the exceptions CMTK1005 lists. The generated members follow what the wrapped type offers: parsing where it can be parsed, formatting where it formats, and comparison where it is comparable. Numbers, bool, char, string, Guid, DateTime, DateTimeOffset, DateOnly, TimeOnly and enums have all of it; a Uri has no ordering, and neither do NodaTime's OffsetDateTime, ZonedDateTime, Period and Interval, and Interval also has no type converter to parse through. An enum parses as Enum.TryParse does, case-sensitively: a name, a comma-separated list of names, or a number, which need not name a member.

A generic wrapped type, a tuple included, is refused (CMTK1005): a List<T> or an ImmutableArray<T> compares by reference, so the value object would not have value equality. Wrap a type of your own that does.

What is generated

Every generated way into a validated value object goes through Create. Two paths skip it, both for values the application wrote itself: the explicit materializer, which the EF Core satellite reads a column through, and StoredJsonConverterFactory, registered only on the options that read the application's own JSON. Inside the type, your own members can reach the private constructor, which applies no rules, because Create needs it: call it from Create only. For another way in, write a static method that calls From or Create.

default(Email) is not one of those ways, and the analyzer refuses it (CMTK0001), but an array slot or a JSON document without the property can still produce it (CMTK0005, and "A missing property" below). Its Value is the wrapped type's default: Guid.Empty for an OrderId, and null for an Email despite its string type.

Your own members

A value object may declare its own TryFrom, FromKnownGood, Revalidate, CompareTo(TSelf) and ToString(); each is kept, and what depends on it is derived from it. Any other member or attribute the generators introduce, written by hand, is CMTK1011, which names it: a plain value object's From, Value, Parse and TryParse, MinValue/MaxValue, [JsonConverter] or [TypeConverter], the interfaces the generators implement, and IConvertible where they generate it. So is an explicit implementation of a member of an interface they implement, such as IParsable<TSelf>.Parse or IFormattable.ToString: every caller through the interface would reach it rather than the generated member, and a generic T.Parse would skip Create. Create is declared once, public static, and never as an explicit interface implementation. The generated code cannot call an explicit one; and beside a public one, generic code calling T.Create would reach the explicit one's rules, not those every generated way in applies.

To change what a value object prints, declare ToString(): a record's PrintMembers(StringBuilder) is CMTK1011 without it, since the generated ToString() prints the wrapped value and never calls it.

What a base record declares counts as the value object's own. Its sealed ToString() is the seam, since C# keeps it in every derived record; one that is not sealed is CMTK1011, because the generated ToString() would replace it: declare ToString() in the value object, or seal the base's. Its PrintMembers, its explicit implementations of the interfaces the generators implement, and an IConvertible on it are refused as they are on the value object.

Equality is the wrapped value's, as the ordering, the JSON and the column are, so a hand-written Equals(TSelf), GetHashCode(), IEquatable<TSelf>.Equals, or operator == or != between two of the type, is CMTK1011: it would make values equal that sort apart. To make values that differ only in form equal, such as "abc" and "ABC", normalise them in Create (a plain value object becomes an IValidatedValue for that), so that equal values hold the same wrapped value.

An [Obsolete] on a value object, or on a type it is nested in, is copied to its {TSelf}Extensions class, which names the value object outside it: with error: true that use failed the build.

A value object holds its wrapped value and nothing else. Its JSON, parsing, type converter and column carry that value alone, while a record's equality compares every field, so any other instance state would be lost on a round trip or make equal values unequal. An instance field, an auto-property, a required member or a field-like event, declared or inherited from a base record, is CMTK1012. A property computed from Value without a backing field, and anything static or const, is fine.

A value that must not be printed

A value object over a secret declares ToString(). No formatting interface is generated then, so interpolation, string.Format, Convert.ToString, a record that holds it and every Microsoft.Extensions.Logging path print what it says, [LogProperties] included:

public sealed partial record ApiKey : IValue<string>
{
    public override string ToString() => "ApiKey(***)";
}

• Still carrying the value, since they are conversions and not display: its JSON, the type converter and the database column; and the debugger, which shows ToString() but expands Value.
• Serilog reads the public Value where it destructures ({@Key}, or a record holding one), past ToString(). CodoMetis.TypeKit.Serilog logs every value object as what it prints instead.
• Microsoft.Extensions.Compliance: classify the logging method's parameter. A DataClassificationAttribute on the value object's type makes the logging generator report LOGGEN035 and generate nothing for the method.

Closed sets

An enum names its members and nothing else: a switch over one is never proven complete (C# only warns about a missing discard), a member carries no data, and the names are integers on the wire unless a converter says otherwise. A closed set is a sealed class whose every instance is a named member, declared as a public static readonly field, with constant data through a private constructor where the members carry some:

public sealed partial class OrderStatus : IClosedSet<OrderStatus>
{
    public static readonly OrderStatus Open = new();
    public static readonly OrderStatus Shipped = new();
    public static readonly OrderStatus Cancelled = new();
}

public sealed partial class Tier : IClosedSet<Tier>
{
    public static readonly Tier Basic = new(1, null);
    public static readonly Tier Premium = new(2, "Priority support.");

    private Tier(int rank, string? perk) { Rank = rank; Perk = perk; }

    public int Rank { get; }
    public string? Perk { get; }
}

The generators add Name from the field's name, QualifiedName (OrderStatus.Open), All in declaration order and read-only, Match with one required delegate per member named after it, TryParse and Parse by name, each ordinal or ignoring case when asked, ToString(), a JSON converter that writes the name and reads the member itself back, and a private parameterless constructor where the type declares none:

var label = status.Match(open: () => "Open", shipped: () => "On its way", cancelled: () => "Cancelled");   // every member, or it does not compile
var names = OrderStatus.All.Select(s => s.Name);                  // Open Shipped Cancelled
var same = OrderStatus.Parse("Shipped") == OrderStatus.Shipped;   // True, members are singletons
var json = JsonSerializer.Serialize(Tier.Premium);                // "Premium"

Members are singletons, so equality is reference equality, and a member added later fails every Match until it is handled. Every parameter of Match has the same type, so an argument by position would follow the declaration order and swap branches when two members are reordered: the analyzer requires every argument named (CMTK0012), and its code fix names them. Match checks every delegate for null before it picks one. Parse and the JSON converter refuse an unknown name with an exception naming the set, never the input, and a set is a dictionary key in JSON by its name too. Parse(name, ignoreCase: true) and TryParse(name, ignoreCase: true, out member) accept any casing. JSON, the type converter, IParsable and a bound route or query parameter stay ordinal, since what is stored or sent is the name as it is: a header or a query string a client typed in any casing is bound as a string and parsed with ignoreCase: true. IParsable<TSelf> is implemented explicitly, for generic code that parses through T.Parse, and a type converter reads and writes the name, so the configuration binder, MVC and anything else that reads a string through TypeDescriptor bind a set. The binder's source generator reads no type converter (dotnet/runtime#83599): under it, as under Native AOT, bind the name as a string and Parse it. The EF Core satellite maps a closed set to a text column of the member's name, and the ASP.NET Core satellite describes it as a string enum of the names, with nothing registered per set. A set whose members are faults declares IFaultSet<TSelf>, a FaultKind and an optional description per member, and the ASP.NET Core satellite answers it by kind.

Each member is initialized with new where it is declared (CMTK1019), and never written again (CMTK0013, the analyzer's: a member assigned in the static constructor would hold an instance named and listed as another), and the constructors are private (CMTK1016); a record is refused (CMTK1020). A member may not take the name of a generated member, nor differ from another's only in case (Open and open), since TryParse(name, ignoreCase: true) could not tell them apart (CMTK1021). A ToString() written by hand is kept, and the name is still what JSON, parsing and the column use. An overload of a generated method with another signature, such as Parse(int rank), is kept too. Any other generated member written by hand is CMTK1011. An instance the set's own code creates beside its members has no name, so reading its name throws rather than writing a null. A JSON null reads as null, as for any class, unless the serializer's RespectNullableAnnotations refuses it.

JSON

The wire format is the wrapped value's, so an OrderId is a string and a Quantity a number:

JsonSerializer.Serialize(new Order(OrderId.New(), Quantity.From(3)));
// {"Id":"0199a3f4-1c00-7000-8000-000000000001","Quantity":3}

JsonSerializer.Deserialize<Email>("\"not an address\"");   // JsonException naming Email and NoAt, not the text
JsonSerializer.Deserialize<Dictionary<OrderId, int>>(json); // value objects work as dictionary keys

The bytes are the serializer's own for the wrapped type under the same options, as a value and as a dictionary key: a converter your options register for the wrapped type, number handling, an enum converter and DictionaryKeyPolicy all apply as they do to the wrapped type. Replacing a Guid property by an OrderId therefore changes no JSON, and a test compares the two for every wrapped-type family under several sets of options. One addition: a DateTime is written as UTC, a Local one converted and an Unspecified one taken as UTC with its digits kept.

One exception: number handling given by an attribute rather than by the options. A [JsonNumberHandling] on the containing type reaches the number properties the serializer writes itself, and a value object's converter never sees it: under [JsonNumberHandling(WriteAsString | AllowReadingFromString)], record Dto(int Count) writes {"Count":"5"} and reads "5", while record Dto(Quantity Count) writes {"Count":5} and refuses "5" with a JsonException. On the property itself the serializer refuses the attribute for any type but a number (InvalidOperationException). Set the number handling on the options, or on a source-generated context's [JsonSourceGenerationOptions], which do reach the value object.

Numbers and dates are read as strictly as the serializer reads the wrapped type. What it cannot read is a JsonException naming the value object and the wrapped type ("Quantity could not read the JSON value as Int32."), with no inner exception that could carry the text; ASP.NET Core answers it with 400. NodaTime types use NodaTime's converters when NodaTime.Serialization.SystemTextJson is referenced and the options have none of their own. For JSON the application stored itself, see StoredJsonConverterFactory in the base package.

A JSON null is refused for a struct value object. A sealed partial record reads it as null, as any class does, since the serializer calls no converter for it; RespectNullableAnnotations = true on the options makes it refuse null for a property that is not declared nullable.

A missing property is not refused either: the serializer calls no converter for a property the document lacks, and leaves it default. Mark the property required, or set RespectRequiredConstructorParameters = true for a record's constructor parameters.

With a source-generated JsonSerializerContext (and so under Native AOT), list the value objects, not the types they wrap. The context sees a value object's converter and never what it wraps, so the converter builds that contract itself, as the serializer would: a converter on your options first, then the wrapped type's [JsonConverter], then the serializer's built-in converter. An enum is the exception: a context's UseStringEnumConverter does not reach an enum the context does not list, so an enum-backed value object is written as a number unless you list the enum ([JsonSerializable(typeof(DayOfWeek))]) or name its converter ([JsonSourceGenerationOptions(Converters = [typeof(JsonStringEnumConverter<DayOfWeek>)])]). Everything generated is trim- and AOT-safe, and the consumer smoke test publishes it with Native AOT.

Parsing and formatting

Quantity.Parse("3", null);                     // Quantity 3
Quantity.TryParse("x", null, out _);           // false
Email.Parse("nobody", null);                   // FormatException naming Email and NoAt

var de     = CultureInfo.GetCultureInfo("de-DE");
var text   = Amount.From(1.5m).ToString();                 // "1.5", whatever the current culture
var german = Amount.From(1.5m).ToString("N2", de);         // "1,50"
var shown  = $"{Amount.From(1.5m)}";                       // "1.5"

A null IFormatProvider means the invariant culture in every generated Parse, TryParse, ToString and TryFormat, so the text does not depend on the culture the process runs in: ToString() is the wrapped type's own default text under the invariant culture, and the type converter and $"{x}" write the same. It reads back as the same value wherever the wrapped type's own does: numbers (float, double and Half included), BigInteger, Guid, DateOnly, TimeSpan, Version, Uri, enums and strings. It does not for TimeOnly, DateTime and DateTimeOffset, whose default text drops what the invariant culture's short patterns drop: TimeOnly(3, 4, 5, 123) prints 03:04, a DateTime loses its fraction of a second and its Kind, a DateTimeOffset its fraction. Format those with "O" (x.ToString("O", null)), which a TimeOnly and a DateTimeOffset read back exactly, or keep them in their JSON form, which a DateTime reads back as the UTC instant it wrote. A provider that is given is used as given where the wrapped type's parsing and formatting take one; a Uri, a NodaTime type and a type parsed through a constructor or a provider-less Parse ignore it.

Text the wrapped type cannot read is a FormatException naming the value object and the wrapped type ("Quantity could not read the input as Int32."), an overflow included, with no inner exception: the wrapped type's own message quotes the input. A refusal by Create names the fault instead. The one place the input still appears is System.Text.Json's own: a refused dictionary key ends the JsonException's Path. TryParse answers false for both, and lets anything else through as Parse does: an exception Create throws is a bug to see, not text to refuse.

A default instance, which CMTK0001 keeps out of your own code but EF Core, MVC and serializers can make, formats as "" over a reference type, as it always did over a string.

Comparison

CompareTo and the operators follow the wrapped type's ordering, ordinal for a string. To order differently, declare CompareTo(TSelf) yourself: it is kept, and the object overload, the operators and the interfaces are derived from it. Any other hand-written comparison member, an explicit implementation of IComparable<TSelf>, IComparable or IComparisonOperators included, is an error (CMTK1008), so in memory every comparison agrees with your CompareTo.

A database cannot run it: it orders the column by the wrapped value. The type then carries [HandWrittenOrdering], and an EF Core query that compares, orders, or takes the Min or Max of it is refused, naming the value object, rather than answered in the column's order (CodoMetis.TypeKit.EntityFrameworkCore). Compare or order by .Value where the wrapped value's order is meant.

Build errors

A declaration that cannot be generated is an error, so no type is left half-generated:

The analyzers that come with the base package add CMTK0001 to CMTK0013; see CodoMetis.TypeKit.Analyzers.

Reading the generated code

Set <MetalamaEmitCompilerTransformedFiles>true</MetalamaEmitCompilerTransformedFiles> in the project and read obj/Debug/net10.0/metalama/: every generated member is there as ordinary C#.