LinKit.Json.Runtime 1.0.0

LinKit.Json.Runtime

A powerful, flexible, and high-performance .NET toolkit for working with JSON. LinKit.Json.Runtime provides intelligent serialization/deserialization capabilities through JConvert and efficient JSON path querying through JPath.

Overview

LinKit.Json.Runtime is a comprehensive JSON handling library built on top of System.Text.Json, Newtonsoft.Json, and SpanJson. It offers:

• Unified JSON Conversion: Seamless serialization and deserialization with intelligent format handling
• Path-Based JSON Querying: Query JSON structures using intuitive path expressions
• Multiple Naming Conventions: Support for PascalCase, camelCase, snake_case, kebab-case, and more
• Advanced Enum Handling: Serialize enums as numbers or strings with flexible configuration
• Reference Loop Handling: Multiple strategies to handle circular references
• Multi-Framework Support: Built for .NET 8.0, .NET 9.0, and .NET 10.0

Features

🔄 JConvert - Smart JSON Serialization

JConvert provides a fluent, easy-to-use API for serializing and deserializing JSON with powerful options:

// Basic serialization
var json = myObject.ToJson();

// With formatting options
var prettyJson = myObject.ToJson(options =>
{
    options.WriteIndented = true;
    options.NamingConvention = NamingConvention.CamelCase;
    options.EnumSerialization = EnumSerializationMode.AsString;
});

// Deserialization
var obj = json.FromJson<MyClass>();

Key Features:

• Support for both System.Text.Json and Newtonsoft.Json objects
• Caching of serialization options for optimal performance
• Custom context support via JsonSerializerContext
• Automatic null handling
• Intelligent type inference

🗂️ JPath - JSON Path Navigation

JPath provides a powerful query syntax to navigate JSON structures:

using System.Text.Json.Nodes;

var json = JsonNode.Parse(jsonString);

// Simple property access
var userName = json.SelectNode("data.user.name");

// Array indexing
var firstItem = json.SelectNode("data.items[0]");

// Type-safe value retrieval
if (json.TryGetValueByPath<string>("data.user.email", out var email))
{
    Console.WriteLine(email);
}

// Direct access with exceptions
var age = json.GetValueByPath<int>("data.user.age");

Supported Syntax:

• Property access: property, nested.property
• Array indexing: array[0], array[5]
• Complex paths: data.users[0].name, items[2].details.id

📝 Naming Conventions

Configure how property names are transformed during serialization:

var options = new JConvertOptions
{
    NamingConvention = NamingConvention.CamelCase
};

// Available conventions:
// - Unchanged: Keep original names (default)
// - PascalCase: MyPropertyName
// - CamelCase: myPropertyName
// - SnakeCaseLower: my_property_name
// - KebabCaseLower: my-property-name

🔢 Enum Serialization

Choose how enums are represented in JSON:

var options = new JConvertOptions
{
    EnumSerialization = EnumSerializationMode.AsString
};

// AsNumber (default): enum values as integers (0, 1, 2, ...)
// AsString: enum values as strings ("Active", "Inactive", ...)

🔁 Reference Loop Handling

Control how circular references are managed:

var options = new JConvertOptions
{
    LoopHandling = ReferenceLoopHandling.Ignore
};

// Available strategies:
// - Throw: Throw exception (default)
// - Ignore: Skip circular references
// - Serialize: Include circular references (if supported)

🎨 Advanced Customization

Access the underlying System.Text.Json options for fine-grained control:

var options = new JConvertOptions();

// Add custom converters
options.SystemTextJsonOptions.Converters.Add(new CustomConverter());

// Configure other System.Text.Json settings
options.SystemTextJsonOptions.PropertyNameCaseInsensitive = true;

var json = myObject.ToJson(opt =>
{
    opt.SystemTextJsonOptions.Converters.Add(new MyCustomConverter());
});

Installation

Package

dotnet add package LinKit.Json.Runtime

From Source

Clone and build from the repository:

dotnet build LinKit.Json.Runtime.sln

Core Components

Public API

• JConvert.cs - Main serialization/deserialization class
• JConvertOptions.cs - Configuration options for conversion
• JPath.cs - JSON path querying utilities

Enumerations

• EnumSerializationMode.cs - Enum serialization strategies
• NamingConvention.cs - Property naming convention options

Serialization Infrastructure

Converters

• CanonicalDoubleConverter / CanonicalFloatConverter - High-precision float handling
• FlexibleEnumConverterFactory - Flexible enum conversion supporting multiple formats
• ObjectToInferredTypesConverter - Intelligent type inference for untyped objects
• RecursiveJsonNodeConverter / RecursiveJTokenConverter - Support for recursive JSON structures
• RecursiveSpanJsonDynamicObjectConverter - SpanJson dynamic object support
• LinKitJsonConverter - Base converter class for custom implementations

Naming Policies

• KebabCaseLowerNamingPolicy - kebab-case-lower transformation
• PascalCaseNamingPolicy - PascalCase transformation

Reference Handling

• ReferenceLoopHandling.cs - Circular reference strategies

Canonical Configuration

• CanonicalJsonConfiguration.cs - RFC-compliant JSON formatting

SpanJson Integration

• JConvert.SpanJson.cs - SpanJson-specific serialization methods
• SpanJsonResolver.cs - Type resolution for SpanJson

Usage Examples

Basic Serialization

using LinKit.Json.Runtime;

public class User
{
    public string Name { get; set; }
    public int Age { get; set; }
    public string Email { get; set; }
}

var user = new User { Name = "John Doe", Age = 30, Email = "john@example.com" };

// Simple JSON
string json = user.ToJson();
// Output: {"Name":"John Doe","Age":30,"Email":"john@example.com"}

// Pretty JSON with camelCase
string prettyJson = user.ToJson(options =>
{
    options.WriteIndented = true;
    options.NamingConvention = NamingConvention.CamelCase;
});
/* Output:
{
  "name": "John Doe",
  "age": 30,
  "email": "john@example.com"
}
*/

Deserialization

var json = """{"name":"Jane Doe","age":28,"email":"jane@example.com"}""";

// Simple deserialization
var user = json.FromJson<User>();

// With custom options
var options = new JsonSerializerOptions { PropertyNameCaseInsensitive = true };
var user2 = json.FromJson<User>(opts =>
{
    opts.SystemTextJsonOptions = options;
});

JSON Path Navigation

using System.Text.Json.Nodes;

var jsonString = """
{
  "data": {
    "users": [
      { "id": 1, "name": "Alice", "role": "admin" },
      { "id": 2, "name": "Bob", "role": "user" }
    ]
  }
}
""";

var root = JsonNode.Parse(jsonString);

// Get first user's name
var firstName = root.SelectNode("data.users[0].name")?.GetValue<string>();
// Output: "Alice"

// Get second user's role
if (root.TryGetValueByPath<string>("data.users[1].role", out var role))
{
    Console.WriteLine(role); // Output: "user"
}

Handling Different Enum Formats

public enum Status { Inactive, Active, Pending }

public class Order
{
    public int OrderId { get; set; }
    public Status Status { get; set; }
}

var order = new Order { OrderId = 1, Status = Status.Active };

// As number (default)
var json1 = order.ToJson();
// {"OrderId":1,"Status":1}

// As string
var json2 = order.ToJson(options =>
{
    options.EnumSerialization = EnumSerializationMode.AsString;
});
// {"OrderId":1,"Status":"Active"}

Handling Reference Loops

public class TreeNode
{
    public string Name { get; set; }
    public TreeNode? Left { get; set; }
    public TreeNode? Right { get; set; }
}

var node = new TreeNode { Name = "Root" };
node.Left = new TreeNode { Name = "LeftChild" };
node.Right = node; // Circular reference!

// Throw on circular reference (default)
try
{
    node.ToJson(); // Throws exception
}
catch (JsonException ex)
{
    Console.WriteLine("Circular reference detected");
}

// Ignore circular references
var json = node.ToJson(options =>
{
    options.LoopHandling = ReferenceLoopHandling.Ignore;
});

Performance Considerations

• Caching: Serialization options are cached for repeated use patterns
• Span-based Parsing: Efficient path navigation using Span<T>
• Multi-library Support: Choose between System.Text.Json (lightweight), Newtonsoft.Json (flexible), or SpanJson (high-performance)
• Zero Allocations: Where possible, the library minimizes allocations in the hot path

Supported .NET Versions

• .NET 8.0
• .NET 9.0
• .NET 10.0

Dependencies

• System.Text.Json - Built-in JSON serialization (via .NET runtime)
• Newtonsoft.Json (13.0.3+) - Flexible JSON handling
• SpanJson (4.2.1+) - High-performance JSON processing

Author

Created by Linh Nguyen

License

This project is provided as-is. Refer to the repository for license details.

Contributing

Contributions are welcome! Feel free to submit issues and pull requests to help improve this library.

Happy JSON handling! 🚀