From 812698b5e81818bb81e3d7b2f92a746a15ac3942 Mon Sep 17 00:00:00 2001
From: Matthew Layton <matthew.layton@live.co.uk>
Date: Fri, 31 Jan 2025 12:02:00 +0000
Subject: [PATCH] Added `ToOptional` and `ToOptionalAsync` methods that work
 with reference types and value types, and renamed `ToSuccessResult` and
 `ToSuccessResultAsync` to `ToSuccess` and `ToSuccessAsync` respectively.

---
 Directory.Build.props                         |   6 +-
 .../ObjectExtensionTests.cs                   | 120 +++++++++++++++++-
 OnixLabs.Core/Extensions.Object.cs            |  40 +++++-
 3 files changed, 155 insertions(+), 11 deletions(-)

diff --git a/Directory.Build.props b/Directory.Build.props
index 094a495..9ca331a 100644
--- a/Directory.Build.props
+++ b/Directory.Build.props
@@ -8,8 +8,8 @@
         <NeutralLanguage>en</NeutralLanguage>
         <Copyright>Copyright © ONIXLabs 2020</Copyright>
         <RepositoryUrl>https://github.com/onix-labs/onixlabs-dotnet</RepositoryUrl>
-        <Version>11.3.0</Version>
-        <PackageVersion>11.3.0</PackageVersion>
-        <AssemblyVersion>11.3.0</AssemblyVersion>
+        <Version>12.0.0</Version>
+        <PackageVersion>12.0.0</PackageVersion>
+        <AssemblyVersion>12.0.0</AssemblyVersion>
     </PropertyGroup>
 </Project>
diff --git a/OnixLabs.Core.UnitTests/ObjectExtensionTests.cs b/OnixLabs.Core.UnitTests/ObjectExtensionTests.cs
index 8c4a0cc..8d73668 100644
--- a/OnixLabs.Core.UnitTests/ObjectExtensionTests.cs
+++ b/OnixLabs.Core.UnitTests/ObjectExtensionTests.cs
@@ -225,29 +225,137 @@ public void ToStringOrNullShouldProduceExpectedResultWhenObjectIsNotNull()
         Assert.Equal(expected, actual);
     }
 
-    [Fact(DisplayName = "ToSuccessResult should produce the expected result")]
-    public void ToSuccessResultShouldProduceTheExpectedResult()
+    [Fact(DisplayName = "ToOptional should produce the expected result when using a non-null reference type")]
+    public void ToOptionalShouldProduceExpectedResultWhenUsingNonNullReferenceType()
     {
         // Given
         const string expected = "abc";
 
         // When
-        Result<string> result = expected.ToSuccessResult();
+        Optional<string> optional = expected.ToOptional();
+
+        // Then
+        Some<string> some = Assert.IsType<Some<string>>(optional);
+        Assert.Equal(expected, some.Value);
+    }
+
+    [Fact(DisplayName = "ToOptional should produce the expected result when using a null reference type")]
+    public void ToOptionalShouldProduceExpectedResultWhenUsingNullReferenceType()
+    {
+        // Given
+        const string? expected = null;
+
+        // When
+        Optional<string> optional = expected.ToOptional();
+
+        // Then
+        Assert.IsType<None<string>>(optional);
+    }
+
+    [Fact(DisplayName = "ToOptional should produce the expected result when using a non-null value type")]
+    public void ToOptionalShouldProduceExpectedResultWhenUsingNonNullValueType()
+    {
+        // Given
+        const int expected = 123;
+
+        // When
+        Optional<int> optional = expected.ToOptional();
+
+        // Then
+        Some<int> some = Assert.IsType<Some<int>>(optional);
+        Assert.Equal(expected, some.Value);
+    }
+
+    [Fact(DisplayName = "ToOptional should produce the expected result when using a null value type")]
+    public void ToOptionalShouldProduceExpectedResultWhenUsingNullValueType()
+    {
+        // Given
+        int? expected = null;
+
+        // When
+        Optional<int> optional = expected.ToOptional();
+
+        // Then
+        Assert.IsType<None<int>>(optional);
+    }
+
+    [Fact(DisplayName = "ToOptionalAsync should produce the expected result when using a non-null reference type")]
+    public async Task ToOptionalAsyncShouldProduceExpectedResultWhenUsingNonNullReferenceType()
+    {
+        // Given
+        const string expected = "abc";
+
+        // When
+        Optional<string> optional = await Task.FromResult<string?>(expected).ToOptionalAsync();
+
+        // Then
+        Some<string> some = Assert.IsType<Some<string>>(optional);
+        Assert.Equal(expected, some.Value);
+    }
+
+    [Fact(DisplayName = "ToOptionalAsync should produce the expected result when using a null reference type")]
+    public async Task ToOptionalAsyncShouldProduceExpectedResultWhenUsingNullReferenceType()
+    {
+        // Given
+        const string? expected = null;
+
+        // When
+        Optional<string> optional = await Task.FromResult(expected).ToOptionalAsync();
+
+        // Then
+        Assert.IsType<None<string>>(optional);
+    }
+
+    [Fact(DisplayName = "ToOptionalAsync should produce the expected result when using a non-null value type")]
+    public async Task ToOptionalAsyncShouldProduceExpectedResultWhenUsingNonNullValueType()
+    {
+        // Given
+        const int expected = 123;
+
+        // When
+        Optional<int> optional = await Task.FromResult(expected).ToOptionalAsync();
+
+        // Then
+        Some<int> some = Assert.IsType<Some<int>>(optional);
+        Assert.Equal(expected, some.Value);
+    }
+
+    [Fact(DisplayName = "ToOptionalAsync should produce the expected result when using a null value type")]
+    public async Task ToOptionalAsyncShouldProduceExpectedResultWhenUsingNullValueType()
+    {
+        // Given
+        int? expected = null;
+
+        // When
+        Optional<int> optional = await Task.FromResult(expected).ToOptionalAsync();
+
+        // Then
+        Assert.IsType<None<int>>(optional);
+    }
+
+    [Fact(DisplayName = "ToSuccess should produce the expected result")]
+    public void ToSuccessShouldProduceTheExpectedResult()
+    {
+        // Given
+        const string expected = "abc";
+
+        // When
+        Result<string> result = expected.ToSuccess();
 
         // Then
         Success<string> success = Assert.IsType<Success<string>>(result);
         Assert.Equal(expected, success.Value);
     }
 
-    [Fact(DisplayName = "ToSuccessResultAsync should produce the expected result")]
-    public async Task ToSuccessResultAsyncShouldProduceTheExpectedResult()
+    [Fact(DisplayName = "ToSuccessAsync should produce the expected result")]
+    public async Task ToSuccessAsyncShouldProduceTheExpectedResult()
     {
         // Given
         const string expected = "abc";
 
         // When
         Task<string> task = Task.FromResult(expected);
-        Result<string> result = await task.ToSuccessResultAsync();
+        Result<string> result = await task.ToSuccessAsync();
 
         // Then
         Success<string> success = Assert.IsType<Success<string>>(result);
diff --git a/OnixLabs.Core/Extensions.Object.cs b/OnixLabs.Core/Extensions.Object.cs
index 5d38c67..37a9145 100644
--- a/OnixLabs.Core/Extensions.Object.cs
+++ b/OnixLabs.Core/Extensions.Object.cs
@@ -173,13 +173,49 @@ public static string ToRecordString(this object? value)
     /// <returns>Returns a <see cref="String"/> representation of the current <see cref="Object"/>, or a string literal null if the current object is <see langword="null"/>.</returns>
     public static string ToStringOrNull(this object? value) => value?.ToString() ?? Null;
 
+    /// <summary>
+    /// Obtains an <see cref="Optional{T}"/> representation of the current <see cref="Object"/>.
+    /// </summary>
+    /// <param name="value">The <see cref="Object"/> to wrap as an <see cref="Optional{T}"/> value.</param>
+    /// <typeparam name="T">The underlying type of the value.</typeparam>
+    /// <returns>Returns an <see cref="Optional{T}"/> representation of the current <see cref="Object"/>.</returns>
+    public static Optional<T> ToOptional<T>(this T? value) where T : notnull => Optional<T>.Of(value);
+
+    /// <summary>
+    /// Obtains an <see cref="Optional{T}"/> representation of the current <see cref="Object"/>.
+    /// </summary>
+    /// <param name="value">The <see cref="Object"/> to wrap as an <see cref="Optional{T}"/> value.</param>
+    /// <typeparam name="T">The underlying type of the value.</typeparam>
+    /// <returns>Returns an <see cref="Optional{T}"/> representation of the current <see cref="Object"/>.</returns>
+    public static Optional<T> ToOptional<T>(this T? value) where T : struct => Optional<T>.Of(value);
+
+    /// <summary>
+    /// Asynchronously obtains an <see cref="Optional{T}"/> representation of the current <see cref="Object"/>.
+    /// </summary>
+    /// <param name="value">The <see cref="Object"/> to wrap as an <see cref="Optional{T}"/> value.</param>
+    /// /// <param name="token">The cancellation token that can be used to cancel long-running tasks.</param>
+    /// <typeparam name="T">The underlying type of the value.</typeparam>
+    /// <returns>Returns an <see cref="Optional{T}"/> representation of the current <see cref="Object"/>.</returns>
+    public static async Task<Optional<T>> ToOptionalAsync<T>(this Task<T?> value, CancellationToken token = default) where T : notnull =>
+        Optional<T>.Of(await value.WaitAsync(token).ConfigureAwait(false));
+
+    /// <summary>
+    /// Asynchronously obtains an <see cref="Optional{T}"/> representation of the current <see cref="Object"/>.
+    /// </summary>
+    /// <param name="value">The <see cref="Object"/> to wrap as an <see cref="Optional{T}"/> value.</param>
+    /// /// <param name="token">The cancellation token that can be used to cancel long-running tasks.</param>
+    /// <typeparam name="T">The underlying type of the value.</typeparam>
+    /// <returns>Returns an <see cref="Optional{T}"/> representation of the current <see cref="Object"/>.</returns>
+    public static async Task<Optional<T>> ToOptionalAsync<T>(this Task<T?> value, CancellationToken token = default) where T : struct =>
+        Optional<T>.Of(await value.WaitAsync(token).ConfigureAwait(false));
+
     /// <summary>
     /// Obtains a <see cref="Success{T}"/> representation of the current <see cref="Object"/>.
     /// </summary>
     /// <param name="value">The <see cref="Object"/> to wrap as a <see cref="Success{T}"/> result.</param>
     /// <typeparam name="T">The underlying type of the value.</typeparam>
     /// <returns>Returns a <see cref="Success{T}"/> representation of the current <see cref="Object"/>.</returns>
-    public static Result<T> ToSuccessResult<T>(this T value) => Result<T>.Success(value);
+    public static Success<T> ToSuccess<T>(this T value) => Result<T>.Success(value);
 
     /// <summary>
     /// Asynchronously obtains a <see cref="Success{T}"/> representation of the current <see cref="Object"/>.
@@ -188,6 +224,6 @@ public static string ToRecordString(this object? value)
     /// <param name="token">The cancellation token that can be used to cancel long-running tasks.</param>
     /// <typeparam name="T">The underlying type of the value.</typeparam>
     /// <returns>Returns a <see cref="Success{T}"/> representation of the current <see cref="Object"/>.</returns>
-    public static async Task<Result<T>> ToSuccessResultAsync<T>(this Task<T> value, CancellationToken token = default) =>
+    public static async Task<Success<T>> ToSuccessAsync<T>(this Task<T> value, CancellationToken token = default) =>
         Result<T>.Success(await value.WaitAsync(token).ConfigureAwait(false));
 }