improved examples

Author: PawelGerr

docs

@@ -137,7 +137,7 @@ public IActionResult RoundTrip([FromBody] BoundaryWithJsonConverter boundary)
    }
 
    [HttpGet("enddate/{endDate}")]
-   public IActionResult RoundTripGet(EndDate endDate)
+   public IActionResult RoundTripGet(OpenEndDate endDate)
    {
       if (!ModelState.IsValid)
          return BadRequest(ModelState);
@@ -148,7 +148,7 @@ public IActionResult RoundTripGet(EndDate endDate)
    }
 
    [HttpPost("enddate")]
-   public IActionResult RoundTripPost([FromBody] EndDate endDate)
+   public IActionResult RoundTripPost([FromBody] OpenEndDate endDate)
    {
       if (!ModelState.IsValid)
          return BadRequest(ModelState);

samples/Thinktecture.Runtime.Extensions.AspNetCore.Samples/Controllers/DemoController.cs

@@ -175,8 +175,8 @@ private static Task StartMinimalWebApiAsync(ILoggerFactory loggerFactory)
       routeGroup.MapPost("otherProductName", ([FromBody] OtherProductName name) => name);
       routeGroup.MapPost("boundary", ([FromBody] BoundaryWithJsonConverter boundary) => boundary);
 
-      routeGroup.MapGet("enddate/{date}", (EndDate date) => date);
-      routeGroup.MapPost("enddate", ([FromBody] EndDate date) => date);
+      routeGroup.MapGet("enddate/{date}", (OpenEndDate date) => date);
+      routeGroup.MapPost("enddate", ([FromBody] OpenEndDate date) => date);
 
       return app.StartAsync();
    }

samples/Thinktecture.Runtime.Extensions.AspNetCore.Samples/Program.cs

@@ -10,12 +10,12 @@ public class Product
    public ProductName Name { get; private set; }
    public ProductCategory Category { get; private set; }
    public ProductType ProductType { get; private set; }
-   public EndDate EndDate { get; set; }
+   public OpenEndDate EndDate { get; set; }
 
    private Boundary? _boundary;
    public Boundary Boundary => _boundary ?? throw new InvalidOperationException("Boundary is not loaded.");
 
-   private Product(Guid id, ProductName name, ProductCategory category, ProductType productType, EndDate endDate)
+   private Product(Guid id, ProductName name, ProductCategory category, ProductType productType, OpenEndDate endDate)
    {
       Id = id;
       Name = name;
@@ -30,7 +30,7 @@ public Product(
       ProductCategory category,
       ProductType productType,
       Boundary boundary,
-      EndDate endDate = default)
+      OpenEndDate endDate = default)
       : this(id, name, category, productType, endDate)
    {
       _boundary = boundary;

samples/Thinktecture.Runtime.Extensions.EntityFrameworkCore.Samples/Product.cs

@@ -43,7 +43,7 @@ private static async Task DoDatabaseRequestsAsync(IServiceProvider serviceProvid
       var logger = scope.ServiceProvider.GetRequiredService<ILogger<Program>>();
       var ctx = scope.ServiceProvider.GetRequiredService<ProductsDbContext>();
 
-      var today = (EndDate)DateOnly.FromDateTime(DateTime.Today);
+      var today = OpenEndDate.Create(DateTime.Today);
 
       await InsertProductAsync(ctx, new Product(Guid.NewGuid(), ProductName.Create("Apple"), ProductCategory.Fruits, ProductType.Groceries, Boundary.Create(1, 2), today));
 
@@ -75,7 +75,7 @@ private static async Task DoDatabaseRequestsAsync(IServiceProvider serviceProvid
       logger.LogInformation("Products with End Data > Today: {@Products}", products);
 
       var product = ctx.Products.Single();
-      product.EndDate = EndDate.Infinite;
+      product.EndDate = OpenEndDate.Infinite;
       await ctx.SaveChangesAsync();
 
       // same query as the previous one but now "EndDate" equals "infinite" and (infinite > today) evaluates to true

samples/Thinktecture.Runtime.Extensions.EntityFrameworkCore.Samples/Program.cs

@@ -1,3 +1,6 @@
+using System;
+using System.ComponentModel.DataAnnotations;
+using System.Text.Json;
 using Serilog;
 
 namespace Thinktecture.Unions;
@@ -8,6 +11,7 @@ public static void Demo(ILogger logger)
    {
       DemoForAdHocUnions(logger);
       DemoForUnions(logger);
+      DemoForJurisdiction(logger);
    }
 
    private static void DemoForAdHocUnions(ILogger logger)
@@ -177,4 +181,47 @@ void Print<T>(Result<T> r)
                   success: s => logger.Information("[Switch] Success: {Success}", s));
       }
    }
+
+   private static void DemoForJurisdiction(ILogger logger)
+   {
+      logger.Information("""
+
+
+                         ==== Demo for Jurisdiction ====
+
+                         """);
+
+      // Creating different jurisdictions
+      var district = Jurisdiction.District.Create("District 42");
+      var country = Jurisdiction.Country.Create("DE");
+      var unknown = Jurisdiction.Unknown.Instance;
+
+      // Comparing jurisdictions
+      var district42 = Jurisdiction.District.Create("DISTRICT 42");
+      logger.Information("district == district42: {IsEqual}", district == district42); // true
+
+      var district43 = Jurisdiction.District.Create("District 43");
+      logger.Information("district == district43: {IsEqual}", district == district43); // false
+
+      logger.Information("unknown == Jurisdiction.Unknown.Instance: {IsEqual}", unknown == Jurisdiction.Unknown.Instance); // true
+
+      // Validation examples
+      try
+      {
+         var invalidJuristiction = Jurisdiction.Country.Create("DEU"); // Throws ValidationException
+      }
+      catch (ValidationException ex)
+      {
+         logger.Information(ex.Message); // "ISO code must be exactly 2 characters long."
+      }
+
+      var description = district.Switch(
+         country: c => $"Country: {c}",
+         federalState: s => $"Federal state: {s}",
+         district: d => $"District: {d}",
+         unknown: _ => "Unknown"
+      );
+
+      logger.Information(description);
+   }
 }

samples/Thinktecture.Runtime.Extensions.Samples/Unions/DiscriminatedUnionsDemos.cs

@@ -0,0 +1,46 @@
+namespace Thinktecture.Unions;
+
+[Union]
+public abstract partial class Jurisdiction
+{
+   [ValueObject<string>(KeyMemberName = "IsoCode")]
+   [ValueObjectKeyMemberEqualityComparer<ComparerAccessors.StringOrdinalIgnoreCase, string>] // case-insensitive comparison
+   [ValueObjectKeyMemberComparer<ComparerAccessors.StringOrdinalIgnoreCase, string>]
+   public partial class Country : Jurisdiction
+   {
+      static partial void ValidateFactoryArguments(ref ValidationError? validationError, ref string isoCode)
+      {
+         if (string.IsNullOrWhiteSpace(isoCode))
+         {
+            validationError = new ValidationError("ISO code is required.");
+            isoCode = string.Empty;
+            return;
+         }
+
+         isoCode = isoCode.Trim();
+
+         if (isoCode.Length != 2)
+            validationError = new ValidationError("ISO code must be exactly 2 characters long.");
+      }
+   }
+
+   /// <summary>
+   /// Let's assume that the federal state is represented by an number.
+   /// </summary>
+   [ValueObject<int>(KeyMemberName = "Number")]
+   public partial class FederalState : Jurisdiction;
+
+   [ValueObject<string>(KeyMemberName = "Name")]
+   [ValueObjectKeyMemberEqualityComparer<ComparerAccessors.StringOrdinalIgnoreCase, string>] // case-insensitive comparison
+   [ValueObjectKeyMemberComparer<ComparerAccessors.StringOrdinalIgnoreCase, string>]
+   public partial class District : Jurisdiction;
+
+   /// <summary>
+   /// The complex type adds appropriate equality comparison(i.e. it checks for type only).
+   /// </summary>
+   [ComplexValueObject]
+   public partial class Unknown : Jurisdiction
+   {
+      public static readonly Unknown Instance = new();
+   }
+}

samples/Thinktecture.Runtime.Extensions.Samples/Unions/Jurisdiction.cs

@@ -0,0 +1,87 @@
+using System;
+using System.Text.Json;
+using System.Text.Json.Serialization;
+
+namespace Thinktecture.Unions;
+
+
+
+public partial class JurisdictionJsonConverter : JsonConverter<Jurisdiction>
+{
+   public override Jurisdiction? Read(
+      ref Utf8JsonReader reader,
+      Type typeToConvert,
+      JsonSerializerOptions options)
+   {
+      if (!reader.Read()    // read StartObject
+          || !reader.Read() // read PropertyName
+          || !Discriminator.TryGet(reader.GetString(), out var discriminator))
+         throw new JsonException();
+
+      var jurisdiction = discriminator.ReadJurisdiction(ref reader, options);
+
+      if (!reader.Read()) // read EndObject
+         throw new JsonException();
+
+      return jurisdiction;
+   }
+
+   public override void Write(
+      Utf8JsonWriter writer,
+      Jurisdiction value,
+      JsonSerializerOptions options)
+   {
+      value.Switch(
+         (writer, options),
+         country: static (state, country) =>
+            WriteJurisdiction(state.writer, state.options, country, Discriminator.Country),
+         federalState: static (state, federalState) =>
+            WriteJurisdiction(state.writer, state.options, federalState, Discriminator.FederalState),
+         district: static (state, district) =>
+            WriteJurisdiction(state.writer, state.options, district, Discriminator.District),
+         unknown: static (state, unknown) =>
+            WriteJurisdiction(state.writer, state.options, unknown, Discriminator.Unknown)
+      );
+   }
+
+   private static void WriteJurisdiction<T>(
+      Utf8JsonWriter writer,
+      JsonSerializerOptions options,
+      T jurisdiction,
+      string discriminator
+   )
+      where T : Jurisdiction
+   {
+      writer.WriteStartObject();
+
+      writer.WriteString("$type", discriminator);
+
+      writer.WritePropertyName(options.PropertyNamingPolicy?.ConvertName("value") ?? "value");
+      JsonSerializer.Serialize(writer, jurisdiction, options);
+
+      writer.WriteEndObject();
+   }
+
+   [SmartEnum<string>]
+   internal partial class Discriminator
+   {
+      public static readonly Discriminator Country = new("Country", ReadJurisdiction<Jurisdiction.Country>);
+      public static readonly Discriminator FederalState = new("FederalState", ReadJurisdiction<Jurisdiction.FederalState>);
+      public static readonly Discriminator District = new("District", ReadJurisdiction<Jurisdiction.District>);
+      public static readonly Discriminator Unknown = new("Unknown", ReadJurisdiction<Jurisdiction.Unknown>);
+
+      [UseDelegateFromConstructor]
+      public partial Jurisdiction? ReadJurisdiction(ref Utf8JsonReader reader, JsonSerializerOptions options);
+
+      private static Jurisdiction? ReadJurisdiction<T>(
+         ref Utf8JsonReader reader,
+         JsonSerializerOptions options)
+         where T : Jurisdiction
+      {
+         if (!reader.Read() || !reader.Read()) // read PropertyName and value
+            throw new JsonException();
+
+         return JsonSerializer.Deserialize<T>(ref reader, options);
+      }
+   }
+}

samples/Thinktecture.Runtime.Extensions.Samples/Unions/ResultJsonConverter.cs

@@ -0,0 +1,77 @@
+using System;
+using System.Globalization;
+
+namespace Thinktecture.ValueObjects;
+
+[ValueObject<DateOnly>(SkipKeyMember = true,                                                          // We implement the key member "Date" ourselves
+                       KeyMemberName = nameof(Date),                                                  // Source Generator needs to know the name we've chosen
+                       DefaultInstancePropertyName = "Infinite",                                      // "EndDate.Infinite" represent an open-ended end date
+                       EqualityComparisonOperators = OperatorsGeneration.DefaultWithKeyTypeOverloads, // for comparison with DateOnly without implicit cast
+                       ComparisonOperators = OperatorsGeneration.DefaultWithKeyTypeOverloads,
+                       AllowDefaultStructs = true,
+                       SkipToString = true)]
+public partial struct OpenEndDate
+{
+   private readonly DateOnly? _date;
+
+   // can be public as well
+   private DateOnly Date
+   {
+      get => _date ?? DateOnly.MaxValue;
+      init => _date = value;
+   }
+
+   /// <summary>
+   /// Gets a value indicating whether the current date represents December 31st of any year.
+   /// </summary>
+   public bool IsEndOfYear => this != Infinite && Date is (_, 12, 31);
+
+   /// <summary>
+   /// Creates an open-ended date with the specified year, month and day.
+   /// </summary>
+   public static OpenEndDate Create(int year, int month, int day)
+   {
+      return Create(new DateOnly(year, month, day));
+   }
+
+   /// <summary>
+   /// Creates an open-ended date from <see cref="DateTime"/>.
+   /// </summary>
+   public static OpenEndDate Create(DateTime dateTime)
+   {
+      return Create(dateTime.Year, dateTime.Month, dateTime.Day);
+   }
+
+   static partial void ValidateFactoryArguments(
+      ref ValidationError? validationError,
+      ref DateOnly date
+   )
+   {
+      if (date == DateOnly.MinValue)
+         validationError = new ValidationError("The end date cannot be DateOnly.MinValue.");
+   }
+
+   /// <summary>
+   /// Adjusts the current date to the last day of the month.
+   /// </summary>
+   public OpenEndDate MoveToEndOfMonth()
+   {
+      if (this == Infinite)
+         return this;
+
+      var days = DateTime.DaysInMonth(Date.Year, Date.Month);
+
+      return days == Date.Day
+                ? this
+                : Create(Date.Year, Date.Month, days);
+   }
+
+   /// <summary>
+   /// Converts a nullable DateOnly to an open-ended date.
+   /// </summary>
+   public static explicit operator OpenEndDate(DateOnly? date) =>
+      date is null ? Infinite : Create(date.Value);
+
+   public override string ToString() =>
+      this == Infinite ? "Infinite" : Date.ToString("O", CultureInfo.InvariantCulture);
+}