Candid.JsonPathPlus 1.0.1

Candid.JsonPathPlus

Lightweight JSONPath-like Stream extensions for System.Text.Json.

Extracts JSON subtrees from a Stream by path expression without loading the full document into memory. Internally uses JsonNode.ParseAsync for evaluation; a true token-streaming mode (no full parse) is on the roadmap.

Installation

dotnet add package Candid.JsonPathPlus

Quick start

using Candid.JsonPathPlus;

// First match
JsonNode? node = await stream.ExtractFirstJsonMatchAsync("$.document_data.items[0].seal");

// All matches
await foreach (var item in stream.ExtractAllJsonMatchesAsync("$.items[*].id"))
{
    Console.WriteLine(item);
}

NuGet publishing (GitHub only)

NuGet publishing is automated in GitHub Actions and does not require local package push commands.

Workflows

• Build validation: .github/workflows/build.yml
• NuGet publish: .github/workflows/publish-nuget.yml

Required GitHub secret

Add this repository secret before publishing:

• NUGET_API_KEY: API key from nuget.org with push permission for Candid.JsonPathPlus

Release branch format

Publishing is triggered when you push a branch with this exact pattern:

• release_1.0.0
• release_1.0.1

The version is taken from the branch name after release_. Only semantic versions in major.minor.patch format are accepted.

Publish flow

When a release branch is pushed, .github/workflows/publish-nuget.yml performs:

1. Restore
2. Build (Release) with /p:Version from branch name
3. Test
4. Pack with /p:PackageVersion from branch name
5. Push package to nuget.org with --skip-duplicate

Typical commands

git checkout -b release_1.0.0
git push -u origin release_1.0.0

Notes

• Local nupkg/snupkg outputs are ignored by git.
• If a branch name is invalid (for example release_1.0), the publish workflow fails fast with a validation error.
• If the same package version already exists on nuget.org, publish step is non-failing because --skip-duplicate is enabled.

Supported path syntax

API reference

// Returns the first matching node, or null if not found.
Task<JsonNode?> ExtractFirstJsonMatchAsync(this Stream stream, string? selectToken)

// Returns an async sequence of all matching nodes.
IAsyncEnumerable<JsonNode?> ExtractAllJsonMatchesAsync(this Stream stream, string? selectToken)

Passing null or "$" as selectToken returns the entire document.

Implementation roadmap

The section below details the remaining planned work. All earlier phases (negative/union indexing, filter expressions, computed index expressions) are implemented.

Phase 1 — True streaming (no full-document parse)

Goal: Eliminate the JsonNode.ParseAsync call so large streams are traversed without holding the whole document in RAM.

Implementation sketch:

1. Add a dedicated streaming matcher (for example JsonPathStreamingMatcher) that evaluates parsed JsonPathSegment lists against Utf8JsonReader.
2. Keep JsonPathMatcher as the in-memory strategy and select between strategies in StreamJsonExtractionExtensions.
3. Add compatibility tests to ensure streaming and in-memory strategies return the same results for identical paths.
4. Add benchmark comparing streaming vs full-parse for various document sizes.

JSONPath ↔ XPath quick reference

The table below maps common XPath expressions to their JSONPath equivalents as a reference. Entries marked "not present in the original spec" are extensions defined by the JSONPath-Plus JavaScript library and are not guaranteed to be implemented in this library.

License

MIT