JSON Serialization Support (#13)

* Adding Option.ParseEnum

* JSON serialization unit tests

* OptionJsonConverter

* ResultJsonConverter

* Accurately reflecting that a default instance of Result may have a null Err value.

* Updating README

* NumericOptionJsonConverter

* Updating version number

Author: jtmueller

README.md

@@ -4,3 +4,44 @@ Option and Result types for C#, inspired by Rust
 [![CI](https://github.com/jtmueller/RustyOptions/actions/workflows/build-and-test.yml/badge.svg)](https://github.com/jtmueller/RustyOptions/actions/workflows/build-and-test.yml) 
 [![CodeQL](https://github.com/jtmueller/RustyOptions/actions/workflows/codeql-analysis.yml/badge.svg)](https://github.com/jtmueller/RustyOptions/actions/workflows/codeql-analysis.yml) 
 [![codecov](https://codecov.io/gh/jtmueller/RustyOptions/branch/main/graph/badge.svg?token=M81EJH4ZEI)](https://codecov.io/gh/jtmueller/RustyOptions)
+
+
+## Avoid Null-Reference Errors
+
+The C# [nullable reference types](https://learn.microsoft.com/en-us/dotnet/csharp/nullable-references) feature is useful,
+but it's entirely optional, and the warnings it produces are easily ignored.
+
+RustyOptions uses the type system to:
+ - Make it impossible to access a possibly-missing value without first checking if the value is present.
+ - Clearly express your intent in the API you build. If a method might not return a value, or might return an error message instead of a value, you can express this in the return type where it can't be missed.
+
+
+## Safely Chain Together Fallible Methods
+
+```csharp
+var output = Option.Parse<int>(userInput)
+    .AndThen(ValidateRange)
+    .OrElse(() => defaultsByGroup.GetValueOrNone(user.GroupId))
+    .MapOr(PillWidget.Render, string.Empty);
+```
+
+The example above does the following:
+ 1. Attempts to parse the user input into an integer.
+ 2. If the parsing succeeds, passes the resulting number to the `ValidateRange` method, which returns `Some(parsedInput)`
+    if the parsed input is within the valid range, or `None` if it falls outside the valid range.
+ 3. If either steps 1 or 2 fail, we attempt to do a dictionary lookup to get a default value using the current user's group ID.
+ 4. If at the end we have a value, we render it to a string. Otherwise, we set `output` to an empty string.
+
+
+## Uses Modern .NET Features
+
+For performance and convenience:
+ - Supports parsing any type that implements `IParsable<T>` or `ISpanParsable<T>` (.NET 7 and above only)
+ - The `NumericOption<T>` type supports generic math for any contained type that implements `INumber<T>` (.NET 7 and above only)
+ - Supports `async` and `IAsyncEnumerable<T>`.
+ - Supports nullable type annotations.
+ - Supports serialization and deserialization with `System.Text.Json`.
+ - `IEquatable<T>` and `IComparable<T>` allow `Option` and `Result` types to be easily compared and sorted.
+ - `IFormattable` and `ISpanFormattable` allow `Option` and `Result` to efficiently format their content.
+ - `Option` and `Result` can be efficiently converted to `ReadOnlySpan<T>` or `IEnumerable<T>` for easier interop with existing code.
+ - Convenient extension methods for working with dictionaries (`GetValueOrNone`), collections (`FirstOrNone`), enums (`Option.ParseEnum`) and more.

src/RustyOptions.Tests/JsonSerializationTests.cs

@@ -0,0 +1,283 @@
+using System.Globalization;
+using System.Text.Json;
+
+namespace RustyOptions.Tests;
+
+public class JsonSerializationTests
+{
+    private const string DtoString = "2019-09-07T15:50:00-04:00";
+    private static readonly DateTimeOffset DtoParsed = DateTimeOffset.Parse("2019-09-07T15:50:00-04:00", CultureInfo.InvariantCulture);
+    private static readonly JsonSerializerOptions JsonOpts = new() { PropertyNamingPolicy = JsonNamingPolicy.CamelCase };
+
+    [Fact]
+    public void CanParseOptionsAllSome()
+    {
+        var parsed = JsonSerializer.Deserialize<ClassWithOptions>(OptionsAllSome, JsonOpts);
+
+        Assert.NotNull(parsed);
+        Assert.Equal(42, parsed.Foo);
+        Assert.Equal(Option.Some(17), parsed.Bar);
+        Assert.Equal(Option.Some("Frank"), parsed.Name);
+        Assert.Equal(Option.Some(DtoParsed), parsed.LastUpdated);
+    }
+
+    [Fact]
+    public void CanParseOptionsAllMissing()
+    {
+        var parsed = JsonSerializer.Deserialize<ClassWithOptions>(OptionsAllMissing, JsonOpts);
+
+        Assert.NotNull(parsed);
+        Assert.Equal(42, parsed.Foo);
+        Assert.Equal(Option.None<int>(), parsed.Bar);
+        Assert.Equal(Option.None<string>(), parsed.Name);
+        Assert.Equal(Option.None<DateTimeOffset>(), parsed.LastUpdated);
+    }
+
+    [Fact]
+    public void CanParseOptionsAllNull()
+    {
+        var parsed = JsonSerializer.Deserialize<ClassWithOptions>(OptionsAllNull, JsonOpts);
+
+        Assert.NotNull(parsed);
+        Assert.Equal(42, parsed.Foo);
+        Assert.Equal(Option.None<int>(), parsed.Bar);
+        Assert.Equal(Option.None<string>(), parsed.Name);
+        Assert.Equal(Option.None<DateTimeOffset>(), parsed.LastUpdated);
+    }
+
+    [Fact]
+    public void CanSerializeOptionsAllSome()
+    {
+        var sut = new ClassWithOptions
+        {
+            Foo =  42,
+            Bar = Option.Some(17),
+            Name = Option.Some("Frank"),
+            LastUpdated = Option.Some(DtoParsed)
+        };
+
+        var serialized = JsonSerializer.Serialize(sut, JsonOpts);
+
+        Assert.Equal(OptionsAllSome, serialized);
+    }
+
+    [Fact]
+    public void CanSerializeOptionsAllNone()
+    {
+        var sut = new ClassWithOptions
+        {
+            Foo = 42,
+            Bar = Option.None<int>(),
+            Name = Option.None<string>(),
+            LastUpdated = Option.None<DateTimeOffset>()
+        };
+
+        var serialized = JsonSerializer.Serialize(sut, JsonOpts);
+
+        Assert.Equal(OptionsAllNull, serialized);
+    }
+
+#if NET7_0_OR_GREATER
+
+    [Fact]
+    public void CanParseNumericOptionsAllSome()
+    {
+        var parsed = JsonSerializer.Deserialize<ClassWithNumbers>(NumericOptionsAllSome, JsonOpts);
+
+        Assert.NotNull(parsed);
+        Assert.Equal(42, parsed.Foo);
+        Assert.Equal(NumericOption.Some(17), parsed.Bar);
+        Assert.Equal(NumericOption.Some(3.14), parsed.Baz);
+        Assert.Equal(NumericOption.Some((byte)255), parsed.Quux);
+    }
+
+    [Fact]
+    public void CanParseNumericOptionsAllMissing()
+    {
+        var parsed = JsonSerializer.Deserialize<ClassWithNumbers>(NumericOptionsAllMissing, JsonOpts);
+
+        Assert.NotNull(parsed);
+        Assert.Equal(42, parsed.Foo);
+        Assert.Equal(NumericOption.None<int>(), parsed.Bar);
+        Assert.Equal(NumericOption.None<double>(), parsed.Baz);
+        Assert.Equal(NumericOption.None<byte>(), parsed.Quux);
+    }
+
+    [Fact]
+    public void CanParseNumericOptionsAllNull()
+    {
+        var parsed = JsonSerializer.Deserialize<ClassWithNumbers>(NumericOptionsAllNull, JsonOpts);
+
+        Assert.NotNull(parsed);
+        Assert.Equal(42, parsed.Foo);
+        Assert.Equal(NumericOption.None<int>(), parsed.Bar);
+        Assert.Equal(NumericOption.None<double>(), parsed.Baz);
+        Assert.Equal(NumericOption.None<byte>(), parsed.Quux);
+    }
+
+    [Fact]
+    public void CanSerializeNumericOptionsAllSome()
+    {
+        var sut = new ClassWithNumbers
+        {
+            Foo = 42,
+            Bar = NumericOption.Some(17),
+            Baz = NumericOption.Some(3.14),
+            Quux = NumericOption.Some((byte)255)
+        };
+
+        var serialized = JsonSerializer.Serialize(sut, JsonOpts);
+
+        Assert.Equal(NumericOptionsAllSome, serialized);
+    }
+
+    [Fact]
+    public void CanSerializeNumericOptionsAllNone()
+    {
+        var sut = new ClassWithNumbers
+        {
+            Foo = 42,
+            Bar = NumericOption.None<int>(),
+            Baz = NumericOption.None<double>(),
+            Quux = NumericOption.None<byte>()
+        };
+
+        var serialized = JsonSerializer.Serialize(sut, JsonOpts);
+
+        Assert.Equal(NumericOptionsAllNull, serialized);
+    }
+
+#endif
+
+    [Fact]
+    public void CanParseResultOk()
+    {
+        var parsed = JsonSerializer.Deserialize<ClassWithResult>(ResultOk, JsonOpts);
+
+        Assert.NotNull(parsed);
+        Assert.Equal(42, parsed.Foo);
+        Assert.Equal(Result.Ok(75), parsed.CurrentCount);
+    }
+
+    [Fact]
+    public void CanParseResultErr()
+    {
+        var parsed = JsonSerializer.Deserialize<ClassWithResult>(ResultErr, JsonOpts);
+
+        Assert.NotNull(parsed);
+        Assert.Equal(42, parsed.Foo);
+        Assert.Equal(Result.Err<int>("not found!"), parsed.CurrentCount);
+    }
+
+    [Fact]
+    public void CanParseResultMissing()
+    {
+        var parsed = JsonSerializer.Deserialize<ClassWithResult>(ResultMissing, JsonOpts);
+
+        Assert.NotNull(parsed);
+        Assert.Equal(42, parsed.Foo);
+
+        // A default instance of the Result struct will be in the Err state, but the err value will be
+        // the default value for TErr, and therefore possibly null.
+        Assert.True(parsed.CurrentCount.IsErr(out var err) && err is null);
+    }
+
+    [Fact]
+    public void CanParseResultNull()
+    {
+        Assert.Throws<JsonException>(() => JsonSerializer.Deserialize<ClassWithResult>(ResultNull, JsonOpts));
+    }
+
+    [Fact]
+    public void CanSerializeResultOk()
+    {
+        var sut = new ClassWithResult
+        {
+            Foo = 42,
+            CurrentCount = Result.Ok(75)
+        };
+
+        var serialized = JsonSerializer.Serialize(sut, JsonOpts);
+
+        Assert.Equal(ResultOk, serialized);
+    }
+
+    [Fact]
+    public void CanSerializeResultErr()
+    {
+        var sut = new ClassWithResult
+        {
+            Foo = 42,
+            CurrentCount = Result.Err<int>("not found!")
+        };
+
+        var serialized = JsonSerializer.Serialize(sut, JsonOpts);
+
+        Assert.Equal(ResultErr, serialized);
+    }
+
+    private const string OptionsAllSome = $$"""
+        {"foo":42,"bar":17,"name":"Frank","lastUpdated":"{{DtoString}}"}
+        """;
+
+    private const string OptionsAllMissing = """
+        { "foo": 42 }
+        """;
+
+    private const string OptionsAllNull = """
+        {"foo":42,"bar":null,"name":null,"lastUpdated":null}
+        """;
+
+    private const string NumericOptionsAllSome = """
+        {"foo":42,"bar":17,"baz":3.14,"quux":255}
+        """;
+
+    private const string NumericOptionsAllMissing = """
+        { "foo": 42 }
+        """;
+
+    private const string NumericOptionsAllNull = """
+        {"foo":42,"bar":null,"baz":null,"quux":null}
+        """;
+
+    private const string ResultOk = """
+        {"foo":42,"currentCount":{"ok":75}}
+        """;
+
+    private const string ResultErr = """
+        {"foo":42,"currentCount":{"err":"not found!"}}
+        """;
+
+    private const string ResultMissing = """
+        { "foo": 42 }
+        """;
+
+    private const string ResultNull = """
+        { "foo": 42, "currentCount": null }
+        """;
+
+    private sealed record ClassWithOptions
+    {
+        public int Foo { get; set; }
+        public Option<int> Bar { get; set; }
+        public Option<string> Name { get; set; }
+        public Option<DateTimeOffset> LastUpdated { get; set; }
+    }
+
+    private sealed record ClassWithResult
+    {
+        public int Foo { get; set; }
+        public Result<int, string> CurrentCount { get; set; }
+    }
+
+#if NET7_0_OR_GREATER
+    private sealed record ClassWithNumbers
+    {
+        public int Foo { get; set; }
+        public NumericOption<int> Bar { get; set; }
+        public NumericOption<double> Baz { get; set; }
+        public NumericOption<byte> Quux { get; set; }
+    }
+#endif
+}
+

src/RustyOptions.Tests/OptionTests.cs

@@ -442,4 +442,19 @@ private sealed class NotFormattable
         public override string ToString() => Value.ToString();
 #pragma warning restore CA1305 // Specify IFormatProvider
     }
+
+    [Theory]
+    [InlineData("Blue", false, ConsoleColor.Blue)]
+    [InlineData("red", true, ConsoleColor.Red)]
+    [InlineData("darkYellow", true, ConsoleColor.DarkYellow)]
+    [InlineData("Darkred", false, null)]
+    [InlineData("foo", true, null)]
+    [InlineData("9", false, ConsoleColor.Blue)]
+    [InlineData("797", false, (ConsoleColor)797)]
+    [InlineData(null, true, null)]
+    public void CanParseEnums(string name, bool ignoreCase, ConsoleColor? expected)
+    {
+        Assert.Equal(Option.Create(expected), Option.ParseEnum<ConsoleColor>(name, ignoreCase));
+        Assert.Equal(Option.Create(expected), Option.ParseEnum<ConsoleColor>(name.AsSpan(), ignoreCase));
+    }
 }

src/RustyOptions.Tests/ResultAsyncTests.cs

@@ -229,28 +229,28 @@ public async Task CanOrElseAsync(object source, object mapper, Result<int, strin
     {
         switch ((source, mapper))
         {
-            case (Result<int, string> src, Func<string, ValueTask<Result<int, string>>> mpr):
+            case (Result<int, string> src, Func<string?, ValueTask<Result<int, string>>> mpr):
                 Assert.Equal(expected, await src.OrElseAsync(mpr));
                 break;
-            case (Result<int, string> src, Func<string, Task<Result<int, string>>> mpr):
+            case (Result<int, string> src, Func<string?, Task<Result<int, string>>> mpr):
                 Assert.Equal(expected, await src.OrElseAsync(mpr));
                 break;
-            case (ValueTask<Result<int, string>> src, Func<string, Result<int, string>> mpr):
+            case (ValueTask<Result<int, string>> src, Func<string?, Result<int, string>> mpr):
                 Assert.Equal(expected, await src.OrElseAsync(mpr));
                 break;
-            case (Task<Result<int, string>> src, Func<string, Result<int, string>> mpr):
+            case (Task<Result<int, string>> src, Func<string?, Result<int, string>> mpr):
                 Assert.Equal(expected, await src.OrElseAsync(mpr));
                 break;
-            case (ValueTask<Result<int, string>> src, Func<string, ValueTask<Result<int, string>>> mpr):
+            case (ValueTask<Result<int, string>> src, Func<string?, ValueTask<Result<int, string>>> mpr):
                 Assert.Equal(expected, await src.OrElseAsync(mpr));
                 break;
-            case (Task<Result<int, string>> src, Func<string, ValueTask<Result<int, string>>> mpr):
+            case (Task<Result<int, string>> src, Func<string?, ValueTask<Result<int, string>>> mpr):
                 Assert.Equal(expected, await src.OrElseAsync(mpr));
                 break;
-            case (ValueTask<Result<int, string>> src, Func<string, Task<Result<int, string>>> mpr):
+            case (ValueTask<Result<int, string>> src, Func<string?, Task<Result<int, string>>> mpr):
                 Assert.Equal(expected, await src.OrElseAsync(mpr));
                 break;
-            case (Task<Result<int, string>> src, Func<string, Task<Result<int, string>>> mpr):
+            case (Task<Result<int, string>> src, Func<string?, Task<Result<int, string>>> mpr):
                 Assert.Equal(expected, await src.OrElseAsync(mpr));
                 break;