feat(json): added orNull variants for serialization functions

Added safer `orNull` alternatives for various JSON serialization and deserialization methods to gracefully handle exceptions and invalid data. Updated deprecated methods to reference these new utilities.

Author: lsafer-meemer

module-extkt-json/src/commonMain/kotlin/ExtensionSerialization.kt

@@ -16,70 +16,93 @@
 package org.cufy.json
 
 import kotlinx.serialization.SerializationException
-import kotlinx.serialization.encodeToString
 import kotlinx.serialization.json.*
-import kotlin.Result.Companion.failure
-import kotlin.Result.Companion.success
+
+private const val DEP_MSG = "Serialization extensions for json util is confusing"
 
 // JsonElement <= String
 
-@Deprecated("Use the new name", ReplaceWith("decodeJson(json)"))
-fun String.decodeJsonString(json: Json = Json): JsonElement = decodeJson(json)
+@Deprecated(DEP_MSG, ReplaceWith("json.parseToJsonElement(this)"))
+fun String.decodeJsonString(json: Json = Json): JsonElement =
+    json.parseToJsonElement(this)
 
-@Deprecated("Use the new name", ReplaceWith("decodeJsonOrNull(json)"))
-fun String.decodeJsonStringOrNull(json: Json = Json): JsonElement? = decodeJsonOrNull(json)
+@Deprecated(DEP_MSG, ReplaceWith("json.parseToJsonElementOrNull(this)"))
+fun String.decodeJsonStringOrNull(json: Json = Json): JsonElement? =
+    json.parseToJsonElementOrNull(this)
 
 /**
  * Deserializes [this] JSON string into a corresponding [JsonElement] representation.
  *
  * @throws [SerializationException] if the given string is not a valid JSON
  */
-fun String.decodeJson(json: Json = Json): JsonElement {
-    return json.parseToJsonElement(this)
-}
+@Deprecated(DEP_MSG, ReplaceWith("json.parseToJsonElement(this)"))
+fun String.decodeJson(json: Json = Json): JsonElement =
+    json.parseToJsonElement(this)
 
 /**
  * Tries to deserialize [this] JSON string into a corresponding [JsonElement] representation.
  * Returns `null` when on failure.
  */
-fun String.decodeJsonOrNull(json: Json = Json): JsonElement? {
-    return try {
-        json.parseToJsonElement(this)
-    } catch (_: SerializationException) {
-        return null
-    }
-}
+@Deprecated(DEP_MSG, ReplaceWith("json.parseToJsonElementOrNull(this)"))
+fun String.decodeJsonOrNull(json: Json = Json): JsonElement? =
+    json.parseToJsonElementOrNull(this)
 
 /**
  * Tries to deserialize [this] JSON string into a corresponding [JsonElement] representation.
  */
-fun String.decodeJsonCatching(json: Json = Json): Result<JsonElement> {
-    return try {
-        success(json.parseToJsonElement(this))
-    } catch (e: SerializationException) {
-        failure(e)
-    }
-}
+@Deprecated(DEP_MSG, ReplaceWith("runCatching { json.parseToJsonElement(this) }"))
+fun String.decodeJsonCatching(json: Json = Json): Result<JsonElement> =
+    runCatching { json.parseToJsonElement(this) }
+
+// JsonObject <= String
+
+/**
+ * Deserializes [this] JSON string into a corresponding [JsonObject] representation.
+ *
+ * @throws [SerializationException] if the given string is not a valid JSON
+ * @throws [ClassCastException] if the given value was not serialized to JsonObject.
+ */
+@Deprecated(DEP_MSG, ReplaceWith("json.parseToJsonElement(this).asJsonObject"))
+fun String.decodeJsonObject(json: Json = Json): JsonObject =
+    json.parseToJsonElement(this).asJsonObject
+
+/**
+ * Tries to deserialize [this] JSON string into a corresponding [JsonObject] representation.
+ * Returns `null` when on failure.
+ */
+@Deprecated(DEP_MSG, ReplaceWith("json.parseToJsonElementOrNull(this)?.asJsonObjectOrNull"))
+fun String.decodeJsonObjectOrNull(json: Json = Json): JsonObject? =
+    json.parseToJsonElementOrNull(this)?.asJsonObjectOrNull
+
+/**
+ * Tries to deserialize [this] JSON string into a corresponding [JsonObject] representation.
+ */
+@Deprecated(DEP_MSG, ReplaceWith("runCatching { json.parseToJsonElement(this).asJsonObject }"))
+fun String.decodeJsonObjectCatching(json: Json = Json): Result<JsonObject> =
+    runCatching { json.parseToJsonElement(this).asJsonObject }
 
 // JsonElement => String
 
-@Deprecated("Use the new name", ReplaceWith("encodeToString(json)"))
-fun JsonElement.encodeToJsonString(json: Json = Json): String = encodeToString(json)
+@Deprecated(DEP_MSG, ReplaceWith("json.encodeToString(this)"))
+fun JsonElement.encodeToJsonString(json: Json = Json): String =
+    json.encodeToString(this)
 
 /**
  * Serializes [this] [JsonElement] representation into JSON string.
  */
-fun JsonElement.encodeToString(json: Json = Json): String {
-    return json.encodeToString(this)
-}
+@Deprecated(DEP_MSG, ReplaceWith("json.encodeToString(this)"))
+fun JsonElement.encodeToString(json: Json = Json): String =
+    json.encodeToString(this)
 
 // T <= String
 
-@Deprecated("Use the new name", ReplaceWith("deserializeJson<T>(json)"))
-inline fun <reified T> String.deserializeJsonString(json: Json = Json): T = deserializeJson(json)
+@Deprecated(DEP_MSG, ReplaceWith("json.decodeFromString<T>(this)"))
+inline fun <reified T> String.deserializeJsonString(json: Json = Json): T =
+    json.decodeFromString<T>(this)
 
-@Deprecated("Use the new name", ReplaceWith("deserializeJsonOrNull<T>(json)"))
-inline fun <reified T> String.deserializeJsonStringOrNull(json: Json = Json): T? = deserializeJsonOrNull(json)
+@Deprecated(DEP_MSG, ReplaceWith("json.decodeFromStringOrNull<T>(this)"))
+inline fun <reified T> String.deserializeJsonStringOrNull(json: Json = Json): T? =
+    json.decodeFromStringOrNull<T>(this)
 
 /**
  * Decodes and deserializes [this] string to the value of type [T] using deserializer
@@ -88,46 +111,36 @@ inline fun <reified T> String.deserializeJsonStringOrNull(json: Json = Json): T?
  * @throws SerializationException in case of any decoding-specific error
  * @throws IllegalArgumentException if the decoded input is not a valid instance of [T]
  */
-inline fun <reified T> String.deserializeJson(json: Json = Json): T {
-    return json.decodeFromString(this)
-}
+@Deprecated(DEP_MSG, ReplaceWith("json.decodeFromString<T>(this)"))
+inline fun <reified T> String.deserializeJson(json: Json = Json): T =
+    json.decodeFromString<T>(this)
 
 /**
  * Decodes and deserializes [this] string to the value of type [T] using deserializer
  * retrieved from the reified type parameter.
  * Returns `null` when on failure.
  */
-inline fun <reified T> String.deserializeJsonOrNull(json: Json = Json): T? {
-    return try {
-        json.decodeFromString(this)
-    } catch (_: SerializationException) {
-        null
-    } catch (_: IllegalArgumentException) {
-        null
-    }
-}
+@Deprecated(DEP_MSG, ReplaceWith("json.decodeFromStringOrNull<T>(this)"))
+inline fun <reified T> String.deserializeJsonOrNull(json: Json = Json): T? =
+    json.decodeFromStringOrNull<T>(this)
 
 /**
  * Decodes and deserializes [this] string to the value of type [T] using deserializer
  * retrieved from the reified type parameter.
  */
-inline fun <reified T> String.deserializeJsonCatching(json: Json = Json): Result<T> {
-    return try {
-        success(json.decodeFromString<T>(this))
-    } catch (e: SerializationException) {
-        failure(e)
-    } catch (e: IllegalArgumentException) {
-        failure(e)
-    }
-}
+@Deprecated(DEP_MSG, ReplaceWith("runCatching { json.decodeFromString<T>(this) }"))
+inline fun <reified T> String.deserializeJsonCatching(json: Json = Json): Result<T> =
+    runCatching { json.decodeFromString<T>(this) }
 
 // T <= JsonElement
 
-@Deprecated("Use the new name", ReplaceWith("deserialize<T>(json)"))
-inline fun <reified T> JsonElement.deserializeJsonElement(json: Json = Json): T = deserialize(json)
+@Deprecated(DEP_MSG, ReplaceWith("json.decodeFromJsonElement<T>(this)"))
+inline fun <reified T> JsonElement.deserializeJsonElement(json: Json = Json): T =
+    json.decodeFromJsonElement<T>(this)
 
-@Deprecated("Use the new name", ReplaceWith("deserializeOrNull<T>(json)"))
-inline fun <reified T> JsonElement.deserializeJsonElementOrNull(json: Json = Json): T? = deserializeOrNull(json)
+@Deprecated("Use the new name", ReplaceWith("json.decodeFromJsonElementOrNull<T>(this)"))
+inline fun <reified T> JsonElement.deserializeJsonElementOrNull(json: Json = Json): T? =
+    json.decodeFromJsonElementOrNull<T>(this)
 
 /**
  * Deserializes [this] json element into a value of type [T] using a deserializer retrieved
@@ -136,38 +149,26 @@ inline fun <reified T> JsonElement.deserializeJsonElementOrNull(json: Json = Jso
  * @throws [SerializationException] if the given JSON element is not a valid JSON input for the type [T]
  * @throws [IllegalArgumentException] if the decoded input cannot be represented as a valid instance of type [T]
  */
-inline fun <reified T> JsonElement.deserialize(json: Json = Json): T {
-    return json.decodeFromJsonElement(this)
-}
+@Deprecated(DEP_MSG, ReplaceWith("json.decodeFromJsonElement<T>(this)"))
+inline fun <reified T> JsonElement.deserialize(json: Json = Json): T =
+    json.decodeFromJsonElement<T>(this)
 
 /**
  * Deserializes [this] json element into a value of type [T] using a deserializer retrieved
  * from reified type parameter.
  * Returns `null` when on failure.
  */
-inline fun <reified T> JsonElement.deserializeOrNull(json: Json = Json): T? {
-    return try {
-        json.decodeFromJsonElement(this)
-    } catch (_: SerializationException) {
-        null
-    } catch (_: IllegalArgumentException) {
-        null
-    }
-}
+@Deprecated(DEP_MSG, ReplaceWith("json.decodeFromJsonElementOrNull<T>(this)"))
+inline fun <reified T> JsonElement.deserializeOrNull(json: Json = Json): T? =
+    json.decodeFromJsonElementOrNull<T>(this)
 
 /**
  * Deserializes [this] json element into a value of type [T] using a deserializer retrieved
  * from reified type parameter.
  */
-inline fun <reified T> JsonElement.deserializeCatching(json: Json = Json): Result<T> {
-    return try {
-        success(json.decodeFromJsonElement<T>(this))
-    } catch (e: SerializationException) {
-        failure(e)
-    } catch (e: IllegalArgumentException) {
-        failure(e)
-    }
-}
+@Deprecated(DEP_MSG, ReplaceWith("runCatching { json.decodeFromJsonElement<T>(this) }"))
+inline fun <reified T> JsonElement.deserializeCatching(json: Json = Json): Result<T> =
+    runCatching { json.decodeFromJsonElement<T>(this) }
 
 // T => String
 
@@ -177,36 +178,24 @@ inline fun <reified T> JsonElement.deserializeCatching(json: Json = Json): Resul
  * @throws SerializationException in case of any encoding-specific error
  * @throws IllegalArgumentException if the encoded input does not comply format's specification
  */
-inline fun <reified T> T.serializeToJsonString(json: Json = Json): String {
-    return json.encodeToString(this)
-}
+@Deprecated(DEP_MSG, ReplaceWith("json.encodeToString<T>(this)"))
+inline fun <reified T> T.serializeToJsonString(json: Json = Json): String =
+    json.encodeToString<T>(this)
 
 /**
  * Serializes and encodes [this] to string using serializer retrieved from the reified type parameter.
  * Returns `null` when on failure.
  */
-inline fun <reified T> T.serializeToJsonStringOrNull(json: Json = Json): String? {
-    return try {
-        json.encodeToString(this)
-    } catch (_: SerializationException) {
-        null
-    } catch (_: IllegalArgumentException) {
-        null
-    }
-}
+@Deprecated(DEP_MSG, ReplaceWith("json.encodeToStringOrNull<T>(this)"))
+inline fun <reified T> T.serializeToJsonStringOrNull(json: Json = Json): String? =
+    json.encodeToStringOrNull<T>(this)
 
 /**
  * Serializes and encodes [this] to string using serializer retrieved from the reified type parameter.
  */
-inline fun <reified T> T.serializeToJsonStringCatching(json: Json = Json): Result<String> {
-    return try {
-        success(json.encodeToString(this))
-    } catch (e: SerializationException) {
-        failure(e)
-    } catch (e: IllegalArgumentException) {
-        failure(e)
-    }
-}
+@Deprecated(DEP_MSG, ReplaceWith("runCatching { json.encodeToString<T>(this) }"))
+inline fun <reified T> T.serializeToJsonStringCatching(json: Json = Json): Result<String> =
+    runCatching { json.encodeToString<T>(this) }
 
 // T => JsonElement
 
@@ -216,34 +205,26 @@ inline fun <reified T> T.serializeToJsonStringCatching(json: Json = Json): Resul
  *
  * @throws [SerializationException] if the given value cannot be serialized to JSON.
  */
-inline fun <reified T> T.serializeToJsonElement(json: Json = Json): JsonElement {
-    return json.encodeToJsonElement(this)
-}
+@Deprecated(DEP_MSG, ReplaceWith("json.encodeToJsonElement<T>(this)"))
+inline fun <reified T> T.serializeToJsonElement(json: Json = Json): JsonElement =
+    json.encodeToJsonElement<T>(this)
 
 /**
  * Serializes the [this] into an equivalent [JsonElement] using a serializer retrieved
  * from reified type parameter.
  * Returns `null` when on failure.
  */
-inline fun <reified T> T.serializeToJsonElementOrNull(json: Json = Json): JsonElement? {
-    return try {
-        return json.encodeToJsonElement(this)
-    } catch (_: SerializationException) {
-        null
-    }
-}
+@Deprecated(DEP_MSG, ReplaceWith("json.encodeToJsonElementOrNull<T>(this)"))
+inline fun <reified T> T.serializeToJsonElementOrNull(json: Json = Json): JsonElement? =
+    json.encodeToJsonElementOrNull<T>(this)
 
 /**
  * Serializes the [this] into an equivalent [JsonElement] using a serializer retrieved
  * from reified type parameter.
  */
-inline fun <reified T> T.serializeToJsonElementCatching(json: Json = Json): Result<JsonElement> {
-    return try {
-        success(json.encodeToJsonElement(this))
-    } catch (e: SerializationException) {
-        failure(e)
-    }
-}
+@Deprecated(DEP_MSG, ReplaceWith("runCatching { json.encodeToJsonElement<T>(this) }"))
+inline fun <reified T> T.serializeToJsonElementCatching(json: Json = Json): Result<JsonElement> =
+    runCatching { json.encodeToJsonElement<T>(this) }
 
 // T => JsonObject
 
@@ -254,24 +235,23 @@ inline fun <reified T> T.serializeToJsonElementCatching(json: Json = Json): Resu
  * @throws [SerializationException] if the given value cannot be serialized to JSON.
  * @throws [ClassCastException] if the given value was not serialized to JsonObject.
  */
-inline fun <reified T> T.serializeToJsonObject(json: Json = Json): JsonObject {
-    return serializeToJsonElement(json) as JsonObject
-}
+@Deprecated(DEP_MSG, ReplaceWith("json.encodeToJsonElement<T>(this).asJsonObject"))
+inline fun <reified T> T.serializeToJsonObject(json: Json = Json): JsonObject =
+    json.encodeToJsonElement<T>(this).asJsonObject
 
 /**
  * Serializes the [this] into an equivalent [JsonObject] using a serializer retrieved
  * from reified type parameter.
  * Returns `null` when on failure.
  */
-inline fun <reified T> T.serializeToJsonObjectOrNull(json: Json = Json): JsonObject? {
-    return serializeToJsonElementOrNull(json) as? JsonObject
-}
+@Deprecated(DEP_MSG, ReplaceWith("json.encodeToJsonElementOrNull<T>(this)?.asJsonObjectOrNull"))
+inline fun <reified T> T.serializeToJsonObjectOrNull(json: Json = Json): JsonObject? =
+    json.encodeToJsonElementOrNull<T>(this)?.asJsonObjectOrNull
 
 /**
  * Serializes the [this] into an equivalent [JsonObject] using a serializer retrieved
  * from reified type parameter.
  */
-inline fun <reified T> T.serializeToJsonObjectCatching(json: Json = Json): Result<JsonObject> {
-    return serializeToJsonElementCatching(json)
-        .mapCatching { it as JsonObject }
-}
+@Deprecated(DEP_MSG, ReplaceWith("runCatching { json.encodeToJsonElement<T>(this).asJsonObject }"))
+inline fun <reified T> T.serializeToJsonObjectCatching(json: Json = Json): Result<JsonObject> =
+    runCatching { json.encodeToJsonElement<T>(this).asJsonObject }