Jacobi.ValueObject 1.1.0

Value Object

Read more on what a Value Object is here (wikipedia).

*) Currently Jacobi.ValueObject only supports single values - one field.

The assumption in the implementation is:

• A ValueObject is immutable. The code generation adds the readonly modifier (so you don't have to).
• A ValueObject is compared by content/value - not by reference. Basic struct behavior in dotnet.
• A valid ValueObject never contains a value of null. So do not specify nullable types as 'datatype'.

Usage

Add a (package) reference to Jacobi.ValueObject.

using Jacobi.ValueObject;

The ValueObjectAttribte works on both partial struct and partial record struct declarations.

• partial struct: The IEquatable<ValueObject> interface is automatically added and implemented.
• partial record struct: The IEquatable<ValueObject> interface is added and implemented by the compiler (because record).

Two attribute syntax variations:

[ValueObject<Guid>]
public partial record struct ProductId;

[ValueObject(typeof(Guid))]
public partial struct ProductId;

We call the Guid the 'datatype' and the ProductId the 'ValueObject'.

Minimal effort:

[ValueObject<Guid>]
public partial struct ProductId;

...

var prodId = new ProductId(Guid.NewGuid());

Using Options to manage what code (support) is generated.

[ValueObject<Guid>(Options = ValueObjectOptions.Parsable)]
public partial record struct ProductId;

...

var prodId = ProductId.Parse("<guid>", null); // no format provider

Implement validation by providing a static bool IsValid(<datatype> value) method. You determine the accessibility (public, internal, private).

[ValueObject<Guid>]
public partial record struct ProductId
{
    public static bool IsValid(Guid id) => id != Guid.Empty;
}

...

var prodId = new ProductId(Guid.Empty);   // <- will throw

Options

As an alternative there is also an option to declare the interfaces explicitly and forgo specifying options.

The folowing interfaces are supported:

Note that IEquatable<ValueObject> is always present. Either generated by the compiler when using a record struct or by Jacobi.ValueObject when using struct.

Methods

Implement a static bool IsValid(<datatype> value) method in your ValueObject and it will be detected and used when constructing new instances.

[ValueObject<Guid>]
public partial record struct ProductId
{
    // public, internal or private - you decide
    public static bool IsValid(Guid id) => id != Guid.Empty;
}

Declare a public static partial bool From(<datatype> value); partial method (no implementation) in your ValueObject and it will be detected and implemented similar to specifying the ExplicitFrom option.

[ValueObject<Guid>]
public partial record struct ProductId
{
    public static partial ProductId From(Guid id);
}

Exceptions

The Jacobi.ValueObject.ValueObjectException is throw in these circumstances.

• The default (parameterless) constructor of the ValueObject is called.
• The Value property is accessed while the instance of the ValueObject was not correctly initialized.
• If the ValueObject implements the IsValid static method and the value fails the test.

Project File

To see the generated source files for the value objects, add to your .csproj project file:

<PropertyGroup>
  <EmitCompilerGeneratedFiles>true</EmitCompilerGeneratedFiles>
</PropertyGroup>

Compiler Errors

CSXXXX Compiler errors caused by you not following the rules 😃

• Do not specify a default constructor. So do NOT do this: public partial record struct ProductId()
• Do not use the ToString option and also implement a string ToString() override in your ValueObject.

Generated Code

Here is an example of the code that will be generated when all options and features are active. Note that there are slight differences between a struct and a record struct -most notably IEquatable<ValueObject>.

The comments in the code (normally not generated) serve as a short explanation for the sets of members.

The YourNamespace and YourValueObject symbols are the namespace and value object type names you have chosen. The 'datatype' in this sample is int.

namespace YourNamespace
{
    [System.CodeDom.Compiler.GeneratedCode("Jacobi.ValueObject.Generator", "1.1.0.0")]
    [System.Diagnostics.DebuggerDisplay("Value = {Value}")]
    readonly partial struct YourValueObject : System.IEquatable<YourValueObject>, System.IEquatable<int>, System.IComparable<YourValueObject>, System.IComparable<int>, System.IParsable<ValObj>, System.ISpanParsable<ValObj>
    {
        public YourValueObject() => throw new Jacobi.ValueObject.ValueObjectException("Do not call the default constructor for ValueObject 'YourValueObject'.");
        private readonly int? _value;
        public int Value => _value ?? throw new Jacobi.ValueObject.ValueObjectException("ValueObject 'YourValueObject' was not initialized with a valid value.");
        
        // Constructor (public)
        public YourValueObject(int value) => _value = value;
        
        // Constructor when 'static bool IsValid(int value)' is detected
        public YourValueObject(int value) { if (YourValueObject.IsValid(value)) _value = value; else throw new Jacobi.ValueObject.ValueObjectException($"Validation Failed. The value '{value}' is not valid for Value Object 'YourValueObject'."); }
        public static bool Try(int value, out YourValueObject valueObject) { if (YourValueObject.IsValid(value)) { valueObject = new(value); return true; } valueObject = default; return false; }
        
        // implicit
        public static implicit operator int(YourValueObject value) => value.Value;
        public static implicit operator YourValueObject(int value) => new(value);
        
        // explicit
        public static YourValueObject From(int value) => new(value);
        public override string ToString() => Value.ToString();
        
        // IEquatable<ValueObject> (only for struct)
        public bool Equals(ValObj value) => Value.Equals(value.Value);
        public static bool operator ==(ValObj valueObject, ValObj value) => valueObject.Equals(value);
        public static bool operator !=(ValObj valueObject, ValObj value) => !valueObject.Equals(value);

        // IEquatable<datatype> (implicit)
        public bool Equals(int value) => Value.Equals(value);
        public static bool operator ==(YourValueObject valueObject, int value) => valueObject.Equals(value);
        public static bool operator !=(YourValueObject valueObject, int value) => !valueObject.Equals(value);
        
        // IComparable<ValueObject>
        public int CompareTo(YourValueObject value) => Value.CompareTo(value.Value);
        public static bool operator >(YourValueObject value1, YourValueObject value2) => value1.CompareTo(value2) > 0;
        public static bool operator <(YourValueObject value1, YourValueObject value2) => value1.CompareTo(value2) < 0;
        public static bool operator >=(YourValueObject value1, YourValueObject value2) => value1.CompareTo(value2) >= 0;
        public static bool operator <=(YourValueObject value1, YourValueObject value2) => value1.CompareTo(value2) <= 0;
        
        // IComparable<datatype> (implicit)
        public int CompareTo(int value) => Value.CompareTo(value);
        public static bool operator >(YourValueObject value1, int value2) => value1.CompareTo(value2) > 0;
        public static bool operator <(YourValueObject value1, int value2) => value1.CompareTo(value2) < 0;
        public static bool operator >=(YourValueObject value1, int value2) => value1.CompareTo(value2) >= 0;
        public static bool operator <=(YourValueObject value1, int value2) => value1.CompareTo(value2) <= 0;
        
        // IParsable<ValueObject>
        public static YourValueObject Parse(string? str, System.IFormatProvider? formatProvider) => new(int.Parse(str, formatProvider));
        public static bool TryParse(string? str, System.IFormatProvider? formatProvider, out YourValueObject result)
        {
            if (int.TryParse(str, formatProvider, out var dtResult)) { result = new (dtResult); return true; }
            result = default; return false;
        }
        // ISpanParsable<ValueObject>
        public static YourValueObject Parse(System.ReadOnlySpan<char> str, System.IFormatProvider? formatProvider) => new(int.Parse(str, formatProvider));
        public static bool TryParse(System.ReadOnlySpan<char> str, System.IFormatProvider? formatProvider, out YourValueObject result)
        {
            if (int.TryParse(str, formatProvider, out var dtResult)) { result = new (dtResult); return true; }
            result = default; return false;
        }
    }
}

Unsupported

• Json Serialization (System.Text.Json or Newtonsoft.Json)
• AspNet (TypeConvertor)
• EFcore (ValueConvertor)

For now, you have to write these yourself.