PartialObjectExtractor 1.0.0

Partial Object Extractor

A high-performance C# library for extracting partial objects using JSONPath expressions while preserving the original structure. Think GraphQL but with JSONPath syntax.

Overview

This library allows you to query complex object graphs and extract only the data you need, maintaining the hierarchical structure of the original object. Unlike traditional JSONPath implementations that return flat arrays of leaf values, this extractor preserves the object structure, making it ideal for API projections and selective serialization.

Built on Newtonsoft.Json: This library leverages Newtonsoft.Json for serialization and respects all its conventions, attributes, and settings.

High Performance: Uses reflection to traverse objects and extract only requested properties before serialization, avoiding the overhead of serializing entire object graphs. Only the extracted data is converted to JSON, making it significantly faster for large objects when you only need a subset of data.

Installation

using QueryPartialObject;

var extractor = new PartialObjectExtractor();

Basic Usage

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

var result = extractor.ExtractPaths(data, ["$.User.Name", "$.User.Email"]);
Console.WriteLine(expected.ToString(Formatting.Indented));

Prints:

{
  "User": {
    "Name": "John",
    "Email": "email@example.com"
  }
}

Features

1. Property Access

Access nested properties using dot notation:

extractor.ExtractPaths(data, ["$.Parent.Child1"]);

Case Insensitive: Property names are matched case-insensitively.

extractor.ExtractPaths(data, ["$.parent.child1"]);  // Works!

2. Array Operations

Single Index

extractor.ExtractPaths(data, ["$.Items[0]"]);

Multiple Indices

extractor.ExtractPaths(data, ["$.Items[0,2,4]"]);

Negative Indices

extractor.ExtractPaths(data, ["$.Items[-1]"]);  // Last item
extractor.ExtractPaths(data, ["$.Items[-3,-1]"]);  // Multiple negative indices

Array Slicing

extractor.ExtractPaths(data, ["$.Items[1:3]"]);   // Items at index 1 and 2
extractor.ExtractPaths(data, ["$.Items[:]"]);     // All items
extractor.ExtractPaths(data, ["$.Items[:5]"]);    // First 5 items
extractor.ExtractPaths(data, ["$.Items[5:]"]);    // From index 5 to end
extractor.ExtractPaths(data, ["$.Items[-3:]"]);    // Last 3

3. Wildcard Selection

Array Wildcard

extractor.ExtractPaths(data, ["$.Products[*].Name"]);
// Extracts Name from all products

Object Wildcard

extractor.ExtractPaths(data, ["$.Parent[*]"]);
// Extracts all properties of Parent

4. Multi-Field Selection

Select multiple fields at once using bracket notation:

extractor.ExtractPaths(data, ["$.Products[*]['Name', 'Price']"]);
// Extracts only Name and Price from all products

5. Recursive Descent

Search for properties at any depth in the structure:

extractor.ExtractPaths(data, ["$..Value"]);
// Finds all "Value" properties at any nesting level

Combined Recursive Operations

extractor.ExtractPaths(data, ["$..Level1..Value"]);
// Finds Level1 at any depth, then Value at any depth under it

6. Nested Arrays

Handle deeply nested array structures:

extractor.ExtractPaths(data, ["$.NestedArrays[0][0][1]"]);
extractor.ExtractPaths(data, ["$.NestedArrays[*][0][0]"]);

7. Multiple Paths

Extract multiple paths in a single operation:

var result = extractor.ExtractPaths(data, [
    "$.Items[0]",
    "$.Items[1:3]",
    "$.Products[*].Name",
    "$..Child1",
    "$.Parent[*]"
]);

Overlapping paths are automatically merged into a single coherent structure.

8. Custom Serialization Settings

Support for custom JSON serialization settings:

var settings = new JsonSerializerSettings {
    ContractResolver = new CamelCasePropertyNamesContractResolver()
};
var extractor = new PartialObjectExtractor(settings);

Respects [JsonProperty] attributes:

public class MyClass {
    [JsonProperty("display_name")]
    public string DisplayName { get; set; }
}

extractor.ExtractPaths(obj, ["$.CustomData.display_name"]);

More examples with responses in tests

Supported Path Syntax

Edge Cases & Error Handling

• Non-existent properties: Returns empty object
• Array index out of bounds: Gracefully skipped
• Invalid paths: Throws ArgumentException
• Empty collections: Returns appropriate empty structure
• Null source: Returns empty JObject

Performance Considerations

• Reflection-first approach: Uses reflection to traverse the object graph and extract only requested properties
• Lazy serialization: Only extracted values are serialized to JSON, not the entire source object
• Efficient for large objects: When you need a small subset of a large object, this is orders of magnitude faster than serialize-then-query approaches