Introduced new "GetRequiredType" extension methods for "JObject"

Author: abjerner

src/Skybrud.Essentials/Json/Newtonsoft/Exceptions/JsonException.cs

@@ -0,0 +1,23 @@
+using System;
+
+namespace Skybrud.Essentials.Json.Newtonsoft.Exceptions;
+
+/// <summary>
+/// Class representing an exception related to the JSON.net implementation.
+/// </summary>
+public class JsonException : Exception {
+
+    /// <summary>
+    /// Initializes a new instance based on the specified <paramref name="message"/>.
+    /// </summary>
+    /// <param name="message">The exception message.</param>
+    public JsonException(string message) : base(message) { }
+
+    /// <summary>
+    /// Initializes a new instance based on the specified <paramref name="message"/> and <paramref name="innerException"/>.
+    /// </summary>
+    /// <param name="message">The exception message.</param>
+    /// <param name="innerException">The inner exception, if any.</param>
+    public JsonException(string message, Exception? innerException) : base(message, innerException) { }
+
+}

src/Skybrud.Essentials/Json/Newtonsoft/Exceptions/JsonPropertyNotFoundException.cs

@@ -0,0 +1,41 @@
+using Newtonsoft.Json.Linq;
+
+namespace Skybrud.Essentials.Json.Newtonsoft.Exceptions;
+
+/// <summary>
+/// Exception thrown when a required JSON property was not found.
+/// </summary>
+public class JsonPropertyNotFoundException : JsonException {
+
+    /// <summary>
+    /// Gets a reference to the JSON object.
+    /// </summary>
+    public new JObject Source { get; }
+
+    /// <summary>
+    /// Gets the name of the property.
+    /// </summary>
+    public string PropertyName { get; }
+
+    /// <summary>
+    /// Initializes a new exception based on the specified <paramref name="source"/> and <paramref name="propertyName"/>.
+    /// </summary>
+    /// <param name="source">A reference to the JSON object where the property was expected.</param>
+    /// <param name="propertyName">The name of the property.</param>
+    public JsonPropertyNotFoundException(JObject source, string propertyName) : base($"JSON property with name '{propertyName}' not found.") {
+        Source = source;
+        PropertyName = propertyName;
+    }
+
+    /// <summary>
+    /// Initializes a new exception based on the specified <paramref name="source"/> and <paramref name="propertyName"/>.
+    /// </summary>
+    /// <param name="source">A reference to the JSON object where the property was expected.</param>
+    /// <param name="propertyName">The name of the property.</param>
+    /// <param name="message">The exception message.</param>
+    public JsonPropertyNotFoundException(JObject source, string propertyName, string message) : base(message) {
+        Source = source;
+        PropertyName = propertyName;
+    }
+
+}

src/Skybrud.Essentials/Json/Newtonsoft/Extensions/NewtonsoftJsonObjectExtensions.Boolean.cs

@@ -1,5 +1,7 @@
-using System.Diagnostics.CodeAnalysis;
+using System;
+using System.Diagnostics.CodeAnalysis;
 using Newtonsoft.Json.Linq;
+using Skybrud.Essentials.Json.Newtonsoft.Exceptions;
 using Skybrud.Essentials.Json.Newtonsoft.Parsing;
 
 namespace Skybrud.Essentials.Json.Newtonsoft.Extensions;
@@ -124,4 +126,36 @@ public static bool TryGetBooleanByPath(this JObject? json, string path, [NotNull
         return JsonTokenUtils.TryGetBoolean(json?.SelectToken(path), out result);
     }
 
+    /// <summary>
+    /// Returns the <see cref="bool"/> value of the property with the specified <paramref name="propertyName"/>. If a
+    /// matching property isn't found, or the value doesn't match a valid <see cref="bool"/>, an exception is thrown
+    /// instead.
+    /// </summary>
+    /// <param name="json">The parent JSON object.</param>
+    /// <param name="propertyName">The name of the property.</param>
+    /// <returns>The <see cref="bool"/> value.</returns>
+    /// <exception cref="JsonPropertyNotFoundException">If a property matching <paramref name="propertyName"/> isn't found.</exception>
+    /// <exception cref="JsonException">If the property is found, but the value doesn't match a <see cref="bool"/>.</exception>
+    public static bool GetRequiredBoolean(this JObject json, string propertyName) {
+        JProperty property = json.Property(propertyName) ?? throw new JsonPropertyNotFoundException(json, propertyName);
+        if (!JsonTokenUtils.TryGetBoolean(property.Value, out bool result)) throw new JsonException($"The value of the '{propertyName}' property doesn't match a valid boolean value.");
+        return result;
+    }
+
+    /// <summary>
+    /// Returns the value of the property with the specified <paramref name="propertyName"/>. If a matching property is
+    /// found, the value is converted using <paramref name="callback"/>. If not found, an exception will be thrown instead.
+    /// </summary>
+    /// <param name="json">The parent JSON object.</param>
+    /// <param name="propertyName">The name of the property.</param>
+    /// <param name="callback">A callback function used for converting the <see cref="bool"/> value to <typeparamref name="TResult"/>.</param>
+    /// <returns>The property value as an instance of <typeparamref name="TResult"/>.</returns>
+    /// <exception cref="JsonPropertyNotFoundException">If a property matching <paramref name="propertyName"/> isn't found.</exception>
+    /// <exception cref="JsonException">If the property is found, but the value doesn't match a <see cref="bool"/>.</exception>
+    public static TResult GetRequiredBoolean<TResult>(this JObject json, string propertyName, Func<bool, TResult> callback) where TResult : notnull {
+        JProperty property = json.Property(propertyName) ?? throw new JsonPropertyNotFoundException(json, propertyName);
+        if (!JsonTokenUtils.TryGetBoolean(property.Value, out bool result)) throw new JsonException($"The value of the '{propertyName}' property doesn't match a valid boolean value.");
+        return callback(result);
+    }
+
 }

src/Skybrud.Essentials/Json/Newtonsoft/Extensions/NewtonsoftJsonObjectExtensions.Double.cs

@@ -1,6 +1,7 @@
 using System;
 using System.Diagnostics.CodeAnalysis;
 using Newtonsoft.Json.Linq;
+using Skybrud.Essentials.Json.Newtonsoft.Exceptions;
 using Skybrud.Essentials.Json.Newtonsoft.Parsing;
 
 namespace Skybrud.Essentials.Json.Newtonsoft.Extensions;
@@ -174,4 +175,36 @@ public static double[] GetDoubleArrayByPath(this JObject? json, string path) {
         return JsonTokenUtils.GetDoubleArray(json?.SelectToken(path));
     }
 
+    /// <summary>
+    /// Returns the <see cref="double"/> value of the property with the specified <paramref name="propertyName"/>. If a
+    /// matching property isn't found, or the value doesn't match a valid <see cref="double"/>, an exception is thrown
+    /// instead.
+    /// </summary>
+    /// <param name="json">The parent JSON object.</param>
+    /// <param name="propertyName">The name of the property.</param>
+    /// <returns>The <see cref="double"/> value.</returns>
+    /// <exception cref="JsonPropertyNotFoundException">If a property matching <paramref name="propertyName"/> isn't found.</exception>
+    /// <exception cref="JsonException">If the property is found, but the value doesn't match a <see cref="double"/>.</exception>
+    public static double GetRequiredDouble(this JObject json, string propertyName) {
+        JProperty property = json.Property(propertyName) ?? throw new JsonPropertyNotFoundException(json, propertyName);
+        if (!JsonTokenUtils.TryGetDouble(property.Value, out double result)) throw new JsonException($"The value of the '{propertyName}' property doesn't match a valid double value.");
+        return result;
+    }
+
+    /// <summary>
+    /// Returns the value of the property with the specified <paramref name="propertyName"/>. If a matching property is
+    /// found, the value is converted using <paramref name="callback"/>. If not found, an exception will be thrown instead.
+    /// </summary>
+    /// <param name="json">The parent JSON object.</param>
+    /// <param name="propertyName">The name of the property.</param>
+    /// <param name="callback">A callback function used for converting the <see cref="double"/> value to <typeparamref name="TResult"/>.</param>
+    /// <returns>The <see cref="double"/> value.</returns>
+    /// <exception cref="JsonPropertyNotFoundException">If a property matching <paramref name="propertyName"/> isn't found.</exception>
+    /// <exception cref="JsonException">If the property is found, but the value doesn't match a <see cref="double"/>.</exception>
+    public static TResult GetRequiredDouble<TResult>(this JObject json, string propertyName, Func<double, TResult> callback) where TResult : notnull {
+        JProperty property = json.Property(propertyName) ?? throw new JsonPropertyNotFoundException(json, propertyName);
+        if (!JsonTokenUtils.TryGetDouble(property.Value, out double result)) throw new JsonException($"The value of the '{propertyName}' property doesn't match a valid double value.");
+        return callback(result);
+    }
+
 }

src/Skybrud.Essentials/Json/Newtonsoft/Extensions/NewtonsoftJsonObjectExtensions.Enum.cs

@@ -1,5 +1,6 @@
 using System;
 using Newtonsoft.Json.Linq;
+using Skybrud.Essentials.Json.Newtonsoft.Exceptions;
 using Skybrud.Essentials.Json.Newtonsoft.Parsing;
 
 namespace Skybrud.Essentials.Json.Newtonsoft.Extensions;
@@ -63,4 +64,39 @@ public static T GetEnumByPath<T>(this JObject? json, string path, T fallback) wh
         return JsonTokenUtils.GetEnum(json?.SelectToken(path), fallback);
     }
 
+    /// <summary>
+    /// Returns the enum value of the property with the specified <paramref name="propertyName"/>. If a matching
+    /// property isn't found, or the value doesn't match a valid <typeparamref name="TEnum"/>, an exception is thrown
+    /// instead.
+    /// </summary>
+    /// <typeparam name="TEnum">The type of the enum.</typeparam>
+    /// <param name="json">The parent JSON object.</param>
+    /// <param name="propertyName">The name of the property.</param>
+    /// <returns>The enum value.</returns>
+    /// <exception cref="JsonPropertyNotFoundException">If a property matching <paramref name="propertyName"/> isn't found.</exception>
+    /// <exception cref="JsonException">If the property is found, but the value doesn't match a <see cref="double"/>.</exception>
+    public static TEnum GetRequiredEnum<TEnum>(this JObject json, string propertyName) where TEnum : struct, Enum {
+        JProperty property = json.Property(propertyName) ?? throw new JsonPropertyNotFoundException(json, propertyName);
+        return JsonTokenUtils.GetEnumOrNull<TEnum>(property.Value) ?? throw new JsonException($"The value of the '{propertyName}' property doesn't match a value of enum '{typeof(Enum)}'.");
+    }
+
+    /// <summary>
+    /// Returns the value of the property with the specified <paramref name="propertyName"/>. If a matching property is
+    /// found, the value is converted using <paramref name="callback"/>. If not found, or the value doesn't match a
+    /// valid <typeparamref name="TEnum"/>, an exception will be thrown instead.
+    /// </summary>
+    /// <typeparam name="TEnum">The type of the enum.</typeparam>
+    /// <typeparam name="TResult">The type of the result.</typeparam>
+    /// <param name="json">The parent JSON object.</param>
+    /// <param name="propertyName">The name of the property.</param>
+    /// <param name="callback">A callback function used for converting the <see cref="double"/> value to <typeparamref name="TResult"/>.</param>
+    /// <returns>The property value as an instance of <typeparamref name="TResult"/>.</returns>
+    /// <exception cref="JsonPropertyNotFoundException">If a property matching <paramref name="propertyName"/> isn't found.</exception>
+    /// <exception cref="JsonException">If the property is found, but the value doesn't match a <see cref="double"/>.</exception>
+    public static TResult GetRequiredEnum<TEnum, TResult>(this JObject json, string propertyName, Func<TEnum, TResult> callback) where TEnum : struct, Enum {
+        JProperty property = json.Property(propertyName) ?? throw new JsonPropertyNotFoundException(json, propertyName);
+        if (JsonTokenUtils.GetEnumOrNull<TEnum>(property.Value) is not {} value) throw new JsonException($"The value of the '{propertyName}' property doesn't match a value of enum '{typeof(Enum)}'.");
+        return callback(value);
+    }
+
 }

src/Skybrud.Essentials/Json/Newtonsoft/Extensions/NewtonsoftJsonObjectExtensions.Float.cs

@@ -1,6 +1,7 @@
 using System;
 using System.Diagnostics.CodeAnalysis;
 using Newtonsoft.Json.Linq;
+using Skybrud.Essentials.Json.Newtonsoft.Exceptions;
 using Skybrud.Essentials.Json.Newtonsoft.Parsing;
 
 namespace Skybrud.Essentials.Json.Newtonsoft.Extensions;
@@ -174,4 +175,36 @@ public static float[] GetFloatArrayByPath(this JObject? json, string path) {
         return JsonTokenUtils.GetFloatArray(json?.SelectToken(path));
     }
 
+    /// <summary>
+    /// Returns the <see cref="float"/> value of the property with the specified <paramref name="propertyName"/>. If a
+    /// matching property isn't found, or the value doesn't match a valid <see cref="float"/>, an exception is thrown
+    /// instead.
+    /// </summary>
+    /// <param name="json">The parent JSON object.</param>
+    /// <param name="propertyName">The name of the property.</param>
+    /// <returns>The <see cref="float"/> value.</returns>
+    /// <exception cref="JsonPropertyNotFoundException">If a property matching <paramref name="propertyName"/> isn't found.</exception>
+    /// <exception cref="JsonException">If the property is found, but the value doesn't match a <see cref="float"/>.</exception>
+    public static float GetRequiredFloat(this JObject json, string propertyName) {
+        JProperty property = json.Property(propertyName) ?? throw new JsonPropertyNotFoundException(json, propertyName);
+        if (!JsonTokenUtils.TryGetFloat(property.Value, out float result)) throw new JsonException($"The value of the '{propertyName}' property doesn't match a valid float value.");
+        return result;
+    }
+
+    /// <summary>
+    /// Returns the value of the property with the specified <paramref name="propertyName"/>. If a matching property is
+    /// found, the value is converted using <paramref name="callback"/>. If not found, an exception will be thrown instead.
+    /// </summary>
+    /// <param name="json">The parent JSON object.</param>
+    /// <param name="propertyName">The name of the property.</param>
+    /// <param name="callback">A callback function used for converting the 64-bit integer value to <typeparamref name="TResult"/>.</param>
+    /// <returns>The <see cref="float"/> value.</returns>
+    /// <exception cref="JsonPropertyNotFoundException">If a property matching <paramref name="propertyName"/> isn't found.</exception>
+    /// <exception cref="JsonException">If the property is found, but the value doesn't match a 64-bit integer.</exception>
+    public static TResult GetRequiredFloat<TResult>(this JObject json, string propertyName, Func<float, TResult> callback) where TResult : notnull {
+        JProperty property = json.Property(propertyName) ?? throw new JsonPropertyNotFoundException(json, propertyName);
+        if (!JsonTokenUtils.TryGetFloat(property.Value, out float result)) throw new JsonException($"The value of the '{propertyName}' property doesn't match a valid float value.");
+        return callback(result);
+    }
+
 }

src/Skybrud.Essentials/Json/Newtonsoft/Extensions/NewtonsoftJsonObjectExtensions.Guid.cs

@@ -1,6 +1,7 @@
 using System;
 using System.Diagnostics.CodeAnalysis;
 using Newtonsoft.Json.Linq;
+using Skybrud.Essentials.Json.Newtonsoft.Exceptions;
 using Skybrud.Essentials.Json.Newtonsoft.Parsing;
 
 namespace Skybrud.Essentials.Json.Newtonsoft.Extensions;
@@ -179,4 +180,24 @@ public static Guid[] GetGuidArrayByPath(this JObject? json, string path) {
         return JsonTokenUtils.GetGuidArray(json?.SelectToken(path));
     }
 
+    /// <summary>
+    /// Returns the GUID value of the property with the specified <paramref name="propertyName"/>. If a matching property isn't found, or the value isn't a valid GUID, an exception is thrown instead.
+    /// </summary>
+    /// <param name="json">The parent JSON object.</param>
+    /// <param name="propertyName">The name of the property.</param>
+    /// <returns>The <see cref="Guid"/>> value.</returns>
+    /// <exception cref="JsonPropertyNotFoundException">If a property matching <paramref name="propertyName"/> isn't found.</exception>
+    /// <exception cref="JsonException">If the property is found, but the value doesn't match a <see cref="Guid"/>.</exception>
+    public static Guid GetRequiredGuid(this JObject json, string propertyName) {
+        JProperty property = json.Property(propertyName) ?? throw new JsonPropertyNotFoundException(json, propertyName);
+        if (!JsonTokenUtils.TryGetGuid(property.Value, out Guid result)) throw new JsonException($"The value of the '{propertyName}' property is not a valid GUID.");
+        return result;
+    }
+
+    public static TResult GetRequiredGuid<TResult>(this JObject json, string propertyName, Func<Guid, TResult> callback) where TResult : notnull {
+        JProperty property = json.Property(propertyName) ?? throw new JsonPropertyNotFoundException(json, propertyName);
+        if (!JsonTokenUtils.TryGetGuid(property.Value, out Guid result)) throw new JsonException($"The value of the '{propertyName}' property is not a valid GUID.");
+        return callback(result);
+    }
+
 }

src/Skybrud.Essentials/Json/Newtonsoft/Extensions/NewtonsoftJsonObjectExtensions.Int16.cs

@@ -1,6 +1,7 @@
 using System;
 using System.Diagnostics.CodeAnalysis;
 using Newtonsoft.Json.Linq;
+using Skybrud.Essentials.Json.Newtonsoft.Exceptions;
 using Skybrud.Essentials.Json.Newtonsoft.Parsing;
 
 namespace Skybrud.Essentials.Json.Newtonsoft.Extensions;
@@ -174,4 +175,36 @@ public static short[] GetInt16ArrayByPath(this JObject? json, string path) {
         return JsonTokenUtils.GetInt16Array(json?.SelectToken(path));
     }
 
+    /// <summary>
+    /// Returns the signed 16-bit integer value of the property with the specified <paramref name="propertyName"/>. If
+    /// a matching property isn't found, or the value doesn't match a valid signed 16-bit integer, an exception is
+    /// thrown instead.
+    /// </summary>
+    /// <param name="json">The parent JSON object.</param>
+    /// <param name="propertyName">The name of the property.</param>
+    /// <returns>The signed 16-bit integer value.</returns>
+    /// <exception cref="JsonPropertyNotFoundException">If a property matching <paramref name="propertyName"/> isn't found.</exception>
+    /// <exception cref="JsonException">If the property is found, but the value doesn't match a signed 16-bit integer.</exception>
+    public static int GetRequiredInt16(this JObject json, string propertyName) {
+        JProperty property = json.Property(propertyName) ?? throw new JsonPropertyNotFoundException(json, propertyName);
+        if (!JsonTokenUtils.TryGetInt16(property.Value, out short result)) throw new JsonException($"The value of the '{propertyName}' property doesn't match a valid 16-bit integer value.");
+        return result;
+    }
+
+    /// <summary>
+    /// Returns the value of the property with the specified <paramref name="propertyName"/>. If a matching property is
+    /// found, the value is converted using <paramref name="callback"/>. If not found, an exception will be thrown instead.
+    /// </summary>
+    /// <param name="json">The parent JSON object.</param>
+    /// <param name="propertyName">The name of the property.</param>
+    /// <param name="callback">A callback function used for converting the signed 16-bit integer value to <typeparamref name="TResult"/>.</param>
+    /// <returns>The signed 16-bit integer value.</returns>
+    /// <exception cref="JsonPropertyNotFoundException">If a property matching <paramref name="propertyName"/> isn't found.</exception>
+    /// <exception cref="JsonException">If the property is found, but the value doesn't match a signed 16-bit integer.</exception>
+    public static TResult GetRequiredInt16<TResult>(this JObject json, string propertyName, Func<int, TResult> callback) where TResult : notnull {
+        JProperty property = json.Property(propertyName) ?? throw new JsonPropertyNotFoundException(json, propertyName);
+        if (!JsonTokenUtils.TryGetInt16(property.Value, out short result)) throw new JsonException($"The value of the '{propertyName}' property doesn't match a valid 16-bit integer value.");
+        return callback(result);
+    }
+
 }