Replace FieldQuery with Selection, and add a GraphQL server example on it

[goccy]

Summary

FieldQuery is replaced by Selection, which selects the fields of a value as a GraphQL selection set does. examples/graphql builds a GraphQL server on it from scratch and compares it with the server which gqlgen generates, to see whether such a server is worth a product of its own.

Fixes #390.

Breaking changes

Removed: FieldQuery, FieldQueryString, BuildFieldQuery, BuildSubFieldQuery, SetFieldQueryToContext, FieldQueryFromContext.

before	after
json.BuildFieldQuery("A", json.BuildSubFieldQuery("B").Fields("C"))	json.Select(json.Field("A"), json.Field("B", json.Field("C"))) or json.ParseSelection("A B { C }")
json.MarshalContext(json.SetFieldQueryToContext(ctx, q), v)	json.MarshalWithOption(v, json.WithSelection(sel)) (or MarshalContext(ctx, v, json.WithSelection(sel)))
json.FieldQueryFromContext(ctx) in MarshalJSON(ctx)	json.SelectionFromContext(ctx)

What a selection does

• The fields are written in the order of the selection, with their aliases (Field("name").As("displayName")).
• The selection of a slice, an array, a map or a pointer is the one of its elements (Support dynamic filter query on slice value and map value #390). The selection of an interface value is the one of the value it holds; before this change the value of an interface was filtered by the whole query instead of the query of its place.
• The fields of a struct embedded as a value are written where they are selected. The fields of a struct embedded by a pointer stay together.
• FieldOf(name, sel) selects a field by an existing selection, and Select() with no field selects nothing ({}).
• MarshalJSON(context.Context) gets the selection of its value (SelectionFromContext) and the selected field (SelectedFieldFromContext), with a value given by SelectionField.With, such as the arguments of a GraphQL field.
• The code compiled for a selection is kept by the selection itself, and is freed with it. The old query cache per type grew without a bound.
• A call without a selection costs only an inlined flag check. MarshalContext now uses the runtime context's table of recently encoded types, which the field query used to turn off.

examples/graphql

A separate module (it needs Go 1.26 for gqlgen, which is not a dependency of go-json). TestSameResponses checks that both servers write the same bytes for queries with aliases, fragments, a union, @skip / @include, __typename, literal / default / variable arguments and merged fields.

Results (Apple M5, arm64, a loaded machine, so the ratios are what to read; the details are in examples/graphql/README.md):

• one request at a time: 4x-26x faster than gqlgen, 15x-6500x fewer allocations;
• requests from all CPUs: 8x-61x faster;
• resolvers with a 1 ms fetch latency: the same time as gqlgen, with 2 fetches instead of 11. The list resolver batches its elements' fetches, because the whole selection is known before writing starts.

Writing the example showed what a product built on this would still need: resolvers write through a nested MarshalContext, whose output is checked again; unions are selected per value in the resolver; resolver errors stop the whole response instead of producing null plus a path; resolvers run serially and must batch their fetches.

Builds on #692

The engine of the example finds a resolved value by the address of its field, which relies on #692 (merged):
a pointer-receiver marshaler of a pointer-sized type is called with the address of the value.

examples/graphql: resolve phase with concurrency and data loaders

The go-json server is now a small engine (examples/graphql/gql) plus the models and resolvers of the schema. A request is served in two phases:

1. Resolve: the fields with resolvers are found from the selection level by level over the whole response and resolved concurrently. A data loader batches a level the same way it does with gqlgen, and a batch resolver resolves the whole level with one call, without the data loader's wait.
2. Write: one MarshalContext with the selection.

TestSameResponses compares five variants (gqlgen with and without dataloadgen, and the engine with batches, with one call per field, and with data loaders), including resolver errors with their paths.

With a 1 ms fetch latency, the engine takes the same time as gqlgen for the same way of fetching (three_levels: 3.9 ms with 3 fetches in batches, vs gqlgen 3.8 ms with 31 fetches or 6.5 ms with data loaders). One request at a time it is 3.9x-17x faster in CPU, with 5x-3600x fewer allocations.

Tests

• go test ./... with Go 1.25.0, 1.26.2 and 1.27.1, and -race for the selection tests and the example
• make lint

🤖 Generated with Claude Code

[codecov-commenter]

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

❌ Patch coverage is 93.75000% with 21 lines in your changes missing coverage. Please review.
✅ Project coverage is 88.36%. Comparing base (aac126f) to head (087a3e9).
❗ Your organization needs to install the Codecov GitHub app to enable full functionality.

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #691      +/-   ##
==========================================
+ Coverage   88.11%   88.36%   +0.25%     
==========================================
  Files          84       84              
  Lines       12945    13125     +180     
==========================================
+ Hits        11406    11598     +192     
+ Misses       1539     1527      -12     

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.