Hyperbee.Json 1.2.1-develop.240621185513

Hyperbee.Json

Hyperbee.Json is a high-performance JSONPath parser for .NET, that supports both JsonElement and JsonNode.
The library is designed to be quick and extensible, allowing support for other JSON document types.

Features

• High Performance: Optimized for performance and efficiency.
• Supports: JsonElement and JsonNode.
• Extensible: Easily extended to support additional JSON document types.
• IEnumerable Results: Deferred execution queries with IEnumerable.
• Comformant: Adheres to the JSONPath Specification RFC 9535.

JSONPath Consensus

Hyperbee.Json aims to follow the emerging JSONPath consensus standard where possible.
This standardization effort is critical for ensuring consistent behavior across different implementations of JSONPath.
However, where the consensus is ambiguous or not aligned with our performance and usability goals, we may deviate. Our
goal is always to provide a robust and performant library while keeping an eye on standardization progress.

Installation

Install via NuGet:

dotnet add package Hyperbee.Json

Usage

Basic Examples

Selecting a Single Element

using Hyperbee.JsonPath;
using System.Text.Json;

var json = """
{ 
  "store": { 
    "book": [ 
      { "category": "fiction" }, 
      { "category": "science" } 
    ] 
  } 
}
""";

var root = JsonDocument.Parse(json);
var result = JsonPath.Select(root, "$.store.book[0].category");

Console.WriteLine(result.First()); // Output: "fiction"

Selecting Multiple Elements

using Hyperbee.JsonPath;
using System.Text.Json;

var json = """
{ 
  "store": { 
    "book": [
      { "category": "fiction" }, 
      { "category": "science" } 
    ] 
  } 
}
""";

var root = JsonDocument.Parse(json);
var result = JsonPath.Select(root, "$.store.book[*].category");

foreach (var item in result)
{
    Console.WriteLine(item); // Output: "fiction" and "science"
}

Advanced Examples

Filtering

using Hyperbee.JsonPath;
using System.Text.Json;

var json = """
{ 
  "store": { 
    "book": [
      { 
        "category": "fiction",
        "price": 10  
      }, 
      { 
        "category": "science",
        "price": 15  
      } 
    ] 
  } 
}
""";

var root = JsonDocument.Parse(json);
var result = JsonPath.Select(root, "$.store.book[?(@.price > 10)]");

foreach (var item in result)
{
    Console.WriteLine(item); // Output: { "category": "science", "price": 15 }
}

Working with JsonNode

using Hyperbee.JsonPath;
using System.Text.Json.Nodes;

var json = """
{ 
  "store": { 
    "book": [
      { "category": "fiction" }, 
      { "category": "science" } 
    ] 
  } 
}
""";

var root = JsonNode.Parse(json);
var result = JsonPath.Select(root, "$.store.book[0].category");

Console.WriteLine(result.First()); // Output: "fiction"

JSONPath Syntax Reference

Here's a quick reference for JSONPath syntax supported by Hyperbee.Json:

JSONPath expressions refer to a JSON structure in the same way as XPath expressions are used in combination with an XML document. JSONPath assumes the name $ is assigned to the root level object.

JSONPath expressions can use dot-notation:

$.store.book[0].title

or bracket-notation:

$['store']['book'][0]['title']

JSONPath allows the wildcard symbol * for member names and array indices. It borrows the descendant operator .. from [E4X][e4x], and the array slice syntax proposal [start:end:step] from ECMASCRIPT 4.

Expressions can be used as an alternative to explicit names or indices, as in:

$.store.book[(@.length-1)].title

using the symbol @ for the current object. Filter expressions are supported via the syntax ?(<boolean expr>), as in:

$.store.book[?(@.price < 10)].title

Supported JSONPath Methods

JsonPath expressions support basic methods calls. By default, Hyperbee supports the methods defined in the RFC. You can extend the supported funtion set by creating your own functions.

Additional Documentation

Additional documentation can be found in the project's /docs folder.

Benchmarks

Here is a performance comparison of various queries on the standard book store document.

{
  "store": {
    "book": [
      {
        "category": "reference",
        "author": "Nigel Rees",
        "title": "Sayings of the Century",
        "price": 8.95
      },
      {
        "category": "fiction",
        "author": "Evelyn Waugh",
        "title": "Sword of Honour",
        "price": 12.99
      },
      {
        "category": "fiction",
        "author": "Herman Melville",
        "title": "Moby Dick",
        "isbn": "0-553-21311-3",
        "price": 8.99
      },
      {
        "category": "fiction",
        "author": "J. R. R. Tolkien",
        "title": "The Lord of the Rings",
        "isbn": "0-395-19395-8",
        "price": 22.99
      }
    ],
    "bicycle": {
      "color": "red",
      "price": 19.95
    }
  }
}

Comparison with Other Libraries

There are excellent options available for RFC-9535 .NET JsonPath.

JsonPath.Net Json-Everything

• Pros:

  • Extensive JSON ecosystem.
  • Comprehensive feature set.
  • Deferred execution queries with IEnumerable.
  • Strong community support.

• Cons:

  • No support for JsonElement.
  • Slower performance and higher memory allocation than other System.Text.Json implementations.

JsonCons.NET

• Pros:

  • High performance.
  • Enhanced JsonPath syntax.

• Cons:

  • No support for JsonNode.
  • Does not return an IEnumerable result (no defered query execution). making it less efficient, and more memory intensive, for certain operations,

Json.NET Newtonsoft

• Pros:

  • Comprehensive feature set.
  • Documentation and examples.
  • Level 2 .NET Foundation Project.

• Cons:

  • No support for JsonElement, or JsonNode.
  • Slower performance and higher memory allocation than System.Text.Json.

Why Choose Hyperbee.Json ?

• High Performance.
• Focus on consensus implementation.
• Supports both JsonElement, and JsonNode.
• Deferred execution queries with IEnumerable.
• Extendable to support additional JSON document types and functions.

Credits

Hyperbee.Json is built upon the great work of several open-source projects. Special thanks to:

• Stefan Goessner for the original JSONPath implementation.
• System.Text.Json team for their work on the System.Text.Json library.
• Atif Aziz's C# port of Goessner's JSONPath library .NET JSONPath.
• Christoph Burgmer JSONPath consensus effort.

Contributing

We welcome contributions! Please see our Contributing Guide for more details.