graphql-sort-ast

Normalize GraphQL queries into a canonical, sorted form for stable cache keys and signatures.

sort_ast reorders the order-insensitive sibling lists of an executable GraphQL document into a fixed order. Two queries that differ only in the order of fields, arguments, definitions, or variable definitions normalize to the same document. They print to the same string and hash to the same signature. A cache can then treat semantically identical queries as one, and a client that emits query text in nondeterministic order still produces a stable key.

The transform preserves meaning. It reorders only siblings whose order carries no meaning. List and object literal values keep their authored order.

Installation

[dependencies]
graphql-sort-ast = "0.1"

Usage

use graphql_sort_ast::{parse_document, print_document, sort_ast};

let doc = parse_document("query Foo { c b a }").unwrap();
let sorted = sort_ast(doc);
assert_eq!(print_document(&sorted), "query Foo {\n  a\n  b\n  c\n}\n");

What gets sorted

Node	List	Sort key
Document	definitions	kind, then name
Operation	variable definitions	variable name
Selection set	selections	kind, then name
Field	arguments	argument name
Fragment definition	variable definitions	variable name
Directive	arguments	argument name

Definitions sort fragments before operations. Selections sort fields first, then fragment spreads, then inline fragments. Names compare by UTF-16 code unit, case-sensitive, with no locale collation. A missing name sorts after every present name. Equal keys keep their source order because the sort is stable.

Directive lists keep their source order in every context, because directive order can carry meaning. Each directive's own arguments still sort.

What does not get sorted

• Elements inside a list literal.
• Fields inside an object literal.
• The order of values anywhere.

Scope

The parser and AST cover executable documents: operations, fragments, selection sets, fields, spreads, inline fragments, arguments, directives, variable definitions, and values. Type-system (schema) definitions are rejected.

License

Licensed under the MIT license.