diff --git a/ReflectorNet/ReflectorNet.csproj b/ReflectorNet/ReflectorNet.csproj index 02ee5c2..e2b691e 100644 --- a/ReflectorNet/ReflectorNet.csproj +++ b/ReflectorNet/ReflectorNet.csproj @@ -9,7 +9,7 @@ com.IvanMurzak.ReflectorNet - 2.4.2 + 2.5.0 Ivan Murzak Copyright © Ivan Murzak 2025 ReflectorNet is an advanced .NET reflection toolkit designed for AI-driven scenarios. Effortlessly search for C# methods using natural language queries, invoke any method by supplying arguments as JSON, and receive results as JSON. The library also provides a powerful API to inspect, modify, and manage in-memory object instances dynamically via JSON data. Ideal for automation, testing, and AI integration workflows. diff --git a/ReflectorNet/src/Utils/Json/JsonSerializer.cs b/ReflectorNet/src/Utils/Json/JsonSerializer.cs index fc7bd0f..5342d41 100644 --- a/ReflectorNet/src/Utils/Json/JsonSerializer.cs +++ b/ReflectorNet/src/Utils/Json/JsonSerializer.cs @@ -7,6 +7,7 @@ using System; using System.Text.Json; +using System.Text.Json.Nodes; using System.Text.Json.Serialization; using System.Text.Json.Serialization.Metadata; using com.IvanMurzak.ReflectorNet.Json; @@ -81,8 +82,8 @@ public JsonSerializer(Reflector reflector) PropertyNameCaseInsensitive = true, WriteIndented = true, TypeInfoResolver = JsonTypeInfoResolver.Combine( - new DefaultJsonTypeInfoResolver() - ), + new DefaultJsonTypeInfoResolver() + ), Converters = { // Individual primitive type converters @@ -152,6 +153,8 @@ public void ClearConverters() jsonSerializerOptions.Converters.Clear(); } + #region Serialize + /// /// Serializes an object to a JSON string representation using the configured JsonSerializerOptions. /// This method provides comprehensive serialization with support for complex types, custom converters, @@ -172,6 +175,47 @@ public string Serialize(object? data, JsonSerializerOptions? options = null) value: data, options: options ?? jsonSerializerOptions); + /// + /// Serializes an object to a JSON string with explicit type specification. + /// This overload is useful when the runtime type differs from the declared type + /// or when you need to control serialization based on a specific type's contract. + /// + /// The object to serialize. Can be null. + /// The type to use for serialization contract resolution. + /// Optional JsonSerializerOptions to override default settings. If null, uses instance configuration. + /// A JSON string representation of the object. + public string Serialize(object? value, Type inputType, JsonSerializerOptions? options = null) + => System.Text.Json.JsonSerializer.Serialize( + value: value, + inputType: inputType, + options: options ?? jsonSerializerOptions); + + /// + /// Serializes an object to a JsonDocument representation, providing a read-only JSON DOM + /// optimized for efficient querying and traversal without modification. + /// + /// The object to serialize. Can be null. + /// Optional JsonSerializerOptions to override default settings. If null, uses instance configuration. + /// A JsonDocument containing the serialized object structure. + public JsonDocument SerializeToDocument(object? value, JsonSerializerOptions? options = null) + => System.Text.Json.JsonSerializer.SerializeToDocument( + value: value, + options: options ?? jsonSerializerOptions); + + /// + /// Serializes an object to a JsonDocument with explicit type specification, + /// providing a read-only JSON DOM with controlled type contract resolution. + /// + /// The object to serialize. Can be null. + /// The type to use for serialization contract resolution. + /// Optional JsonSerializerOptions to override default settings. If null, uses instance configuration. + /// A JsonDocument containing the serialized object structure. + public JsonDocument SerializeToDocument(object? value, Type inputType, JsonSerializerOptions? options = null) + => System.Text.Json.JsonSerializer.SerializeToDocument( + value: value, + inputType: inputType, + options: options ?? jsonSerializerOptions); + /// /// Serializes an object to a JsonElement representation, providing a structured JSON DOM /// for programmatic manipulation and analysis. This method is useful when you need to @@ -184,35 +228,116 @@ public JsonElement SerializeToElement(object data, JsonSerializerOptions? option => System.Text.Json.JsonSerializer.SerializeToElement(data, options ?? jsonSerializerOptions); /// - /// Deserializes a JSON string to the specified generic type with comprehensive error handling - /// and type safety. This method provides strongly-typed deserialization with support for - /// custom converters and ReflectorNet-specific types. + /// Serializes an object to a JsonNode representation, providing a mutable JSON DOM + /// that can be programmatically modified before final serialization or further processing. /// - /// The target type for deserialization. - /// The JSON string to deserialize. + /// The object to serialize. Can be null. /// Optional JsonSerializerOptions to override default settings. If null, uses instance configuration. - /// The deserialized object of type T, or null if deserialization fails or JSON represents null. - public T? Deserialize(string json, JsonSerializerOptions? options = null) - => System.Text.Json.JsonSerializer.Deserialize( - json: json, + /// A JsonNode containing the serialized object structure, or null if value is null. + public JsonNode? SerializeToNode(object? value, JsonSerializerOptions? options = null) + => System.Text.Json.JsonSerializer.SerializeToNode( + value: value, options: options ?? jsonSerializerOptions); /// - /// Deserializes a JsonElement to the specified generic type with intelligent null handling - /// and default value generation. This method integrates with Reflector's default value - /// system to provide appropriate fallbacks when JsonElement is null or invalid. + /// Serializes an object to a JsonNode with explicit type specification, + /// providing a mutable JSON DOM with controlled type contract resolution. /// - /// The target type for deserialization. - /// The Reflector instance used for default value generation. - /// The JsonElement to deserialize. Can be null. + /// The object to serialize. Can be null. + /// The type to use for serialization contract resolution. /// Optional JsonSerializerOptions to override default settings. If null, uses instance configuration. - /// The deserialized object of type T, or the default value for T if JsonElement is null. - public T? Deserialize(Reflector reflector, JsonElement? jsonElement, JsonSerializerOptions? options = null) - => jsonElement.HasValue - ? System.Text.Json.JsonSerializer.Deserialize( - element: jsonElement.Value, - options: options ?? jsonSerializerOptions) - : reflector.GetDefaultValue(); + /// A JsonNode containing the serialized object structure, or null if value is null. + public JsonNode? SerializeToNode(object? value, Type inputType, JsonSerializerOptions? options = null) + => System.Text.Json.JsonSerializer.SerializeToNode( + value: value, + inputType: inputType, + options: options ?? jsonSerializerOptions); + + /// + /// Serializes an object to a UTF-8 encoded byte array, providing efficient binary + /// JSON representation suitable for network transmission or storage scenarios. + /// + /// The object to serialize. Can be null. + /// Optional JsonSerializerOptions to override default settings. If null, uses instance configuration. + /// A UTF-8 encoded byte array containing the JSON representation. + public byte[] SerializeToUtf8Bytes(object? value, JsonSerializerOptions? options = null) + => System.Text.Json.JsonSerializer.SerializeToUtf8Bytes( + value: value, + options: options ?? jsonSerializerOptions); + + /// + /// Serializes an object to a UTF-8 encoded byte array with explicit type specification, + /// providing efficient binary JSON representation with controlled type contract resolution. + /// + /// The object to serialize. Can be null. + /// The type to use for serialization contract resolution. + /// Optional JsonSerializerOptions to override default settings. If null, uses instance configuration. + /// A UTF-8 encoded byte array containing the JSON representation. + public byte[] SerializeToUtf8Bytes(object? value, Type inputType, JsonSerializerOptions? options = null) + => System.Text.Json.JsonSerializer.SerializeToUtf8Bytes( + value: value, + inputType: inputType, + options: options ?? jsonSerializerOptions); + + #endregion + + #region Deserialize + + /// + /// Deserializes a JsonDocument to the specified type, providing deserialization + /// from a read-only JSON DOM structure. + /// + /// The JsonDocument to deserialize. + /// The target Type for deserialization. + /// Optional JsonSerializerOptions to override default settings. If null, uses instance configuration. + /// The deserialized object of the specified type. + public object? Deserialize(JsonDocument document, Type returnType, JsonSerializerOptions? options = null) + => System.Text.Json.JsonSerializer.Deserialize( + document: document, + returnType: returnType, + options: options ?? jsonSerializerOptions); + + /// + /// Deserializes a JsonElement to the specified type, providing deserialization + /// from an immutable JSON DOM element with dynamic type resolution. + /// + /// The JsonElement to deserialize. + /// The target Type for deserialization. + /// Optional JsonSerializerOptions to override default settings. If null, uses instance configuration. + /// The deserialized object of the specified type. + public object? Deserialize(JsonElement element, Type returnType, JsonSerializerOptions? options = null) + => System.Text.Json.JsonSerializer.Deserialize( + element: element, + returnType: returnType, + options: options ?? jsonSerializerOptions); + + /// + /// Deserializes a JsonNode to the specified type, providing deserialization + /// from a mutable JSON DOM structure. + /// + /// The JsonNode to deserialize. Can be null. + /// The target Type for deserialization. + /// Optional JsonSerializerOptions to override default settings. If null, uses instance configuration. + /// The deserialized object of the specified type. + public object? Deserialize(JsonNode? node, Type returnType, JsonSerializerOptions? options = null) + => System.Text.Json.JsonSerializer.Deserialize( + node: node, + returnType: returnType, + options: options ?? jsonSerializerOptions); + + /// + /// Deserializes a UTF-8 encoded byte span to the specified type, providing efficient + /// binary deserialization without string allocation overhead. + /// + /// The UTF-8 encoded JSON bytes to deserialize. + /// The target Type for deserialization. + /// Optional JsonSerializerOptions to override default settings. If null, uses instance configuration. + /// The deserialized object of the specified type. + public object? Deserialize(ReadOnlySpan utf8Json, Type returnType, JsonSerializerOptions? options = null) + => System.Text.Json.JsonSerializer.Deserialize( + utf8Json: utf8Json, + returnType: returnType, + options: options ?? jsonSerializerOptions); /// /// Deserializes a JsonElement to the specified type with intelligent null handling @@ -232,6 +357,20 @@ public JsonElement SerializeToElement(object data, JsonSerializerOptions? option options: options ?? jsonSerializerOptions) : reflector.GetDefaultValue(type); + /// + /// Deserializes from a Utf8JsonReader to the specified type, providing efficient + /// streaming deserialization for large JSON documents or performance-critical scenarios. + /// + /// The Utf8JsonReader positioned at the JSON content to deserialize. + /// The target Type for deserialization. + /// Optional JsonSerializerOptions to override default settings. If null, uses instance configuration. + /// The deserialized object of the specified type. + public object? Deserialize(ref Utf8JsonReader reader, Type returnType, JsonSerializerOptions? options = null) + => System.Text.Json.JsonSerializer.Deserialize( + reader: ref reader, + returnType: returnType, + options: options ?? jsonSerializerOptions); + /// /// Deserializes a JSON string to the specified type with dynamic type resolution. /// This method provides runtime type deserialization capabilities for scenarios @@ -248,17 +387,86 @@ public JsonElement SerializeToElement(object data, JsonSerializerOptions? option options: options ?? jsonSerializerOptions); /// - /// Deserializes from a Utf8JsonReader to the specified type, providing efficient - /// streaming deserialization for large JSON documents or performance-critical scenarios. + /// Deserializes a JsonElement to the specified generic type with intelligent null handling + /// and default value generation. This method integrates with Reflector's default value + /// system to provide appropriate fallbacks when JsonElement is null or invalid. /// - /// The Utf8JsonReader positioned at the JSON content to deserialize. - /// The target Type for deserialization. + /// The target type for deserialization. + /// The Reflector instance used for default value generation. + /// The JsonElement to deserialize. Can be null. /// Optional JsonSerializerOptions to override default settings. If null, uses instance configuration. - /// The deserialized object of the specified type. - public object? Deserialize(ref Utf8JsonReader reader, Type returnType, JsonSerializerOptions? options = null) - => System.Text.Json.JsonSerializer.Deserialize( - reader: ref reader, - returnType: returnType, + /// The deserialized object of type T, or the default value for T if JsonElement is null. + public T? Deserialize(Reflector reflector, JsonElement? jsonElement, JsonSerializerOptions? options = null) + => jsonElement.HasValue + ? System.Text.Json.JsonSerializer.Deserialize( + element: jsonElement.Value, + options: options ?? jsonSerializerOptions) + : reflector.GetDefaultValue(); + + /// + /// Deserializes a JSON string to the specified generic type with comprehensive error handling + /// and type safety. This method provides strongly-typed deserialization with support for + /// custom converters and ReflectorNet-specific types. + /// + /// The target type for deserialization. + /// The JSON string to deserialize. + /// Optional JsonSerializerOptions to override default settings. If null, uses instance configuration. + /// The deserialized object of type T, or null if deserialization fails or JSON represents null. + public T? Deserialize(string json, JsonSerializerOptions? options = null) + => System.Text.Json.JsonSerializer.Deserialize( + json: json, + options: options ?? jsonSerializerOptions); + + /// + /// Deserializes a JsonDocument to the specified generic type, providing strongly-typed + /// deserialization from a read-only JSON DOM structure. + /// + /// The target type for deserialization. + /// The JsonDocument to deserialize. + /// Optional JsonSerializerOptions to override default settings. If null, uses instance configuration. + /// The deserialized object of type TValue. + public TValue? Deserialize(JsonDocument document, JsonSerializerOptions? options = null) + => System.Text.Json.JsonSerializer.Deserialize( + document: document, + options: options ?? jsonSerializerOptions); + + /// + /// Deserializes a JsonElement to the specified generic type, providing strongly-typed + /// deserialization from an immutable JSON DOM element. + /// + /// The target type for deserialization. + /// The JsonElement to deserialize. + /// Optional JsonSerializerOptions to override default settings. If null, uses instance configuration. + /// The deserialized object of type TValue. + public TValue? Deserialize(JsonElement element, JsonSerializerOptions? options = null) + => System.Text.Json.JsonSerializer.Deserialize( + element: element, + options: options ?? jsonSerializerOptions); + + /// + /// Deserializes a JsonNode to the specified generic type, providing strongly-typed + /// deserialization from a mutable JSON DOM structure. + /// + /// The target type for deserialization. + /// The JsonNode to deserialize. Can be null. + /// Optional JsonSerializerOptions to override default settings. If null, uses instance configuration. + /// The deserialized object of type TValue. + public TValue? Deserialize(JsonNode? node, JsonSerializerOptions? options = null) + => System.Text.Json.JsonSerializer.Deserialize( + node: node, + options: options ?? jsonSerializerOptions); + + /// + /// Deserializes a UTF-8 encoded byte span to the specified generic type, providing efficient + /// binary deserialization with strong typing and without string allocation overhead. + /// + /// The target type for deserialization. + /// The UTF-8 encoded JSON bytes to deserialize. + /// Optional JsonSerializerOptions to override default settings. If null, uses instance configuration. + /// The deserialized object of type TValue. + public TValue? Deserialize(ReadOnlySpan utf8Json, JsonSerializerOptions? options = null) + => System.Text.Json.JsonSerializer.Deserialize( + utf8Json: utf8Json, options: options ?? jsonSerializerOptions); /// @@ -273,5 +481,7 @@ public JsonElement SerializeToElement(object data, JsonSerializerOptions? option => System.Text.Json.JsonSerializer.Deserialize( reader: ref reader, options: options ?? jsonSerializerOptions); + + #endregion } } \ No newline at end of file