ActDim.Practix.Json 1.4.0

ActDim.Practix.Json

ActDim.Practix.Json is a JSON serialization abstraction layer for .NET built on System.Text.Json (STJ). It implements IJsonSerializer, IStringSerializer, IBinarySerializer, and IStreamSerializer through a single CoreJsonSerializer with a rich API covering string/stream/byte serialization (sync and async), JSON merging, deep cloning, object population, and patching. The default options are tuned to match Newtonsoft.Json (Json.NET) behavior out of the box, making migration painless while retaining the speed and low allocation profile of modern STJ.

Why ActDim.Practix.Json? (Painless Newtonsoft.Json Migration)

Migrating legacy codebases from Newtonsoft.Json to standard System.Text.Json is notoriously difficult due to STJ's strict type rules, lack of permissive string parsing, handling of object as JsonElement, and missing declarative policies.

ActDim.Practix.Json bridges this gap by providing full behavioral compatibility with Newtonsoft.Json out of the box while retaining the speed and low memory allocation of modern System.Text.Json.

Default Options: STJ vs Newtonsoft.Json vs Practix.Json

Full API Surface

Beyond basic Serialize/Deserialize, CoreJsonSerializer provides operations commonly needed in production but missing from raw STJ:

• Stream serialization (sync and async) - direct Stream I/O without intermediate string allocation
• Byte array serialization - UTF-8 bytes with optional encoding transcoding
• JSON merging (MergeAndSerialize) - merge multiple object graphs into a single JSON document with configurable array and null handling
• Deep cloning (Clone<T>) - serialize-deserialize round-trip clone
• Object population (Populate<T>) - mutate an existing instance from JSON using compiled Expression Tree property setters
• Patching (Patch<T>) - apply a partial JSON string onto an existing object
• Property copying (Copy<T>) - deep copy values from one instance into another via serialize + populate
• Options cloning (CopyOptions) - copy all settings between JsonSerializerOptions instances via compiled delegates
• Property name formatting (FormatPropertyName) - transform dot-separated property paths according to the active naming policy

Key Features & STJ Extensions

1. Newtonsoft.Json Compatibility Layer

• ObjectJsonConverter (object as CLR Primitives): Standard STJ deserializes object properties into raw JsonElement structures. This converter maps them directly into native CLR types (string, long, double, bool, Dictionary<string, object>, List<object>), exactly like Json.NET.
• NewtonsoftCompatibleStringConverter: Permissively converts numbers, booleans, and nested tokens into string without throwing STJ schema mismatch exceptions.
• FloatingPointConverterFactory & NumberEnumConverterFactory: Lenient parsing for float, double, decimal, and numeric-backed enum types (supporting both quoted string numbers and numeric literals).
• CustomDateTimeConverter: Multi-format permissive DateTime / DateTimeOffset parsing across diverse legacy date representations.
• ImplicitOperatorConverterFactory: Automatically discovers and invokes custom C# implicit conversion operators during deserialization (ideal for Value Objects and Strongly-Typed IDs).
• ExceptionJsonConverter: Cleanly serializes deep .NET Exception hierarchies and inner exceptions without circular references or max depth exceptions.
• RuntimeTypeJsonConverter: Robust polymorphic type serialization supporting dynamic runtime types.

2. Declarative Attributes & Contract Resolvers

• [JsonIgnoreEmpty] (EmptyCollectionIgnoreResolver): Automatically omits empty collections, lists, arrays, and dictionaries from the serialized JSON output (mirroring Newtonsoft's DefaultValueHandling.Ignore).
• [JsonIgnoreDefault] & [JsonDefaultValue(val)] (DefaultValueAwareResolver): Ignores properties with default values or assigns declared fallback values when deserializing missing properties.
• [JsonNaming(namingPolicy)] & NamingPolicyResolver: Granular per-class or per-property naming policy customization, supporting LowerCaseNamingPolicy, UpperCaseNamingPolicy, CamelCase, and custom policies.

3. Extreme Performance with Zero Overhead

• Expression Tree Delegate Compilation: Fast, compiled Expression Trees are used for CopyOptions and fast property mutation, eliminating runtime reflection overhead and boxing.
• Autonomous & Lightweight: No external reflection libraries or bloated dependencies.

Installation

Install via the .NET CLI:

dotnet add package ActDim.Practix.Json

Or via Package Manager Console:

Install-Package ActDim.Practix.Json

Dependency Injection Setup

Register CoreJsonSerializer as IJsonSerializer, IStringSerializer, IBinarySerializer, and IStreamSerializer:

using ActDim.Practix.Json.Extensions;
using Microsoft.Extensions.DependencyInjection;

public void ConfigureServices(IServiceCollection services)
{
    // Registers IJsonSerializer, IStringSerializer, IBinarySerializer, and IStreamSerializer
    services.AddCoreJsonSerializer();
}

Quick Start Examples

1. Basic Serialization & Deserialization

using ActDim.Practix.Abstractions.Json;
using Microsoft.Extensions.DependencyInjection;

var serializer = serviceProvider.GetRequiredService<IJsonSerializer>();

var user = new UserProfile 
{ 
    Id = 42, 
    Name = "Alice", 
    Email = "alice@example.com" 
};

// Serialize to JSON string
string json = serializer.Serialize(user);

// Deserialize from JSON string
UserProfile restored = serializer.Deserialize<UserProfile>(json);

2. Painless Newtonsoft.Json Migration Patterns

using ActDim.Practix.Json;
using System.Collections.Generic;

public class ApiResponse
{
    // Empty collections are omitted from JSON (like Newtonsoft DefaultValueHandling.Ignore)
    [JsonIgnoreEmpty]
    public List<string> Warnings { get; set; } = new List<string>();

    // Omitted if 0 (default value)
    [JsonIgnoreDefault]
    public int RetryCount { get; set; } = 0;

    // Injects "ACTIVE" if property is missing in input JSON
    [JsonDefaultValue("ACTIVE")]
    public string Status { get; set; }

    // Deserializes into Dictionary/primitives instead of raw JsonElement!
    public object DynamicPayload { get; set; }
}

Testing & Quality

• Test Suite: ActDim.Practix.Json.Tests
• Total Tests: 102 passed (100% success rate, 0 failed, 0 skipped)
• Target Framework: .NET 10.0

dotnet test Tests/Json.Tests/ActDim.Practix.Json.Tests.csproj

AI-Assisted Development

Developed with Along - a provider-agnostic context and memory system for AI coding agents.

License

This project is licensed under the MIT License.