libgraphql-parser 0.0.5

Features

• Error-resilient parsing — documents produce a partial AST alongside a list of errors, even when the input is malformed. Never panics.
• Rust-inspired error output — error messages with source snippets, span highlighting, contextual notes, and fix suggestions.
• Blazing fast - Perf metrics exceeding apollo_parser (v0.8.4) and matching or exceeding graphql_parser (v0.4.1) on all fixtures.
• Zero-copy lexing — uses Cow<'src, str> to avoid allocations for tokens that match the source verbatim.
• Parse schema, executable, and mixed documents — parses type definitions, operations/fragments, or documents containing both interleaved together.
• September 2025 GraphQL specification compliance.
• Dual column tracking — reports both UTF-8 character positions (for display) and UTF-16 code unit positions (for LSP integration).
• Comment/trivia preservation — captures comments and other trivia as "preceding trivia" attached to tokens.
• Generic over token sources — the parser works with any GraphQLTokenSource (string input, Rust proc-macro token stream input, etc.).
• Configurable AST access — valid() API for strict consumers that require error-free input, ast() for best-effort tooling that needs error-recovery (IDEs, linters, formatters, etc).
• Fuzz-tested at scale — 70M+ libfuzzer executions across 4 fuzz targets, zero crashes.
• Lossless syntax tree — every AST node carries byte-offset spans; combined with the SourceMap, the original source text can be reconstructed losslessly via AstNode::append_source().
• graphql-parser v0.4 compatibility — bidirectional conversion between libgraphql-parser's AST and the graphql_parser v0.4 AST via the compat module.

Coming soon:

• Drop-in compat with apollo-parser — translation utils to make it easy to integrate with tools that already depend on the apollo_parser::cst AST structure.

Getting Started

cargo add libgraphql-parser

Or add this to your Cargo.toml:

[dependencies]
libgraphql-parser = "0.0.4"

Usage

Parse a GraphQL schema document:

use libgraphql_parser::GraphQLParser;

let result = GraphQLParser::new("type Query { hello: String }")
    .parse_schema_document();

assert!(!result.has_errors());
let (doc, _) = result.valid().unwrap();

Parse an executable document (queries, mutations, subscriptions):

use libgraphql_parser::GraphQLParser;

let result = GraphQLParser::new("{ user { name email } }")
    .parse_executable_document();

assert!(!result.has_errors());

Get the line and column of a node:

use libgraphql_parser::GraphQLParser;

let result = GraphQLParser::new("type Query { hello: String }")
    .parse_schema_document();
let (doc, source_map) = result.valid().unwrap();

let query_def_node = &doc.definitions[0];
let source_span = query_def_node.source_span(&source_map).unwrap();
// line_col() returns 0-based (line, column) pairs where columns
// are measured in UTF-8 characters (not bytes or UTF-16 units).
let ((start_line, start_col), (end_line, end_col)) = source_span.line_col();

Error Recovery

Unlike many GraphQL parsers that stop at the first error, libgraphql-parser collects multiple errors and still produces a best-effort AST. This is essential for IDE integration, linters, and formatters:

use libgraphql_parser::GraphQLParser;

// This schema has errors: missing `:` on field type, unclosed brace
let source = "type Query { hello String";
let result = GraphQLParser::new(source).parse_schema_document();

// Errors are collected — inspect them all at once
assert!(result.has_errors());
for error in result.errors() {
    eprintln!("{}", error.format_detailed(Some(source)));
}

// A partial AST is always available for best-effort tooling
let doc = result.ast();
// IDE completions, formatting, linting can still work
// on the partially-parsed document
println!("Parsed {} definitions", doc.definitions.len());

Diagnostic Output

Error messages include source spans, contextual notes, and fix suggestions — inspired by the Rust compiler's diagnostic style:

error: unknown directive location `FIELD_DEFINTION`
  --> <input>:1:42
   |
 1 | directive @deprecated(reason: String) on FIELD_DEFINTION | ENUM_VALUE
   |                                          ^^^^^^^^^^^^^^^
   = help: did you mean `FIELD_DEFINITION`?

Unclosed delimiters point back to the opening location:

error: unclosed `{`
  --> <input>:9:2
   |
 9 | }
   |  ^
   = note: opening `{` in selection set here
      1 | query {
        |       -

Strict vs. Best-Effort AST Access

ParseResult offers two modes for accessing the AST:

use libgraphql_parser::GraphQLParser;

let source = "type Query { hello: String }";
let result = GraphQLParser::new(source).parse_schema_document();

// Strict mode: returns AST only if there were zero errors.
// Use this when compiling schemas or executing queries.
if let Some((doc, _source_map)) = result.valid() {
    // Guaranteed: no parse errors
}

// Best-effort mode: AST is always available, even with errors.
// Use this for IDE features, formatters, and linters.
let doc = result.ast();
// May be a partial/recovered AST — check result.has_errors()

Design Goals

• Performance — zero-copy lexing via Cow<'src, str>, minimal allocations (e.g., SmallVec for trivia), and hand-written recursive descent parsing.
• Error resilience — always produce as much AST as possible, collecting all errors in a single pass rather than stopping at the first failure.
• Spec correctness — targets the September 2025 GraphQL specification.
• Extensible architecture — the parser is generic over GraphQLTokenSource, enabling the same parsing logic to work across string input, proc-macro token streams, and other token sources.
• Tooling-ready — designed for IDE integration, linters, formatters, and compiler frontends with dual UTF-8/UTF-16 position tracking and configurable AST access.

Comparison to Alternatives

Performance

Performance is a first-class design goal. The lexer avoids allocations via Cow<'src, str> (borrowing directly from the source string for tokens that don't need transformation) and uses SmallVec for trivia storage and token-buffering. The parser itself is a hand-written recursive descent parser, avoiding the overhead of parser generator runtimes and allowing for more helpful and structured error information, notes, and possible-fix suggestions.

Benchmarks run via Criterion on synthetic schemas (small ~1.5KB, medium ~106KB, large ~500KB), vendored real-world schemas (Star Wars ~4KB, GitHub ~1.2MB), and a locally-fetched real-world schema (Shopify Admin ~3.1MB), plus executable documents.

You can run these benchmarks yourself with cargo bench --package libgraphql-parser, or use the high-confidence script which will also aggregate results in a table like below: ./crates/libgraphql-parser/scripts/run-benchmarks.sh.

Measured: 2026-03-19 on Apple M2 Max (arm64), 64 GB RAM, macOS, rustc 1.90.0-nightly (0d9592026 2025-07-19), --release profile. Comparison parsers: graphql-parser 0.4.1, apollo-parser 0.8.4. All values are Criterion point estimates at a 99% confidence level.

Schema Parsing

Executable Document Parsing

Lexer Throughput

Core Types

Part of the libgraphql Ecosystem

libgraphql-parser is the parsing foundation of the libgraphql project — a comprehensive GraphQL engine library for building tools, clients, and servers in Rust. It is used by libgraphql-core for schema building, operation validation, and type system logic.

Running Tests

cargo test --package libgraphql-parser

Fuzz Testing

The crate includes a cargo-fuzz setup under fuzz/ with four targets:

Prerequisites

rustup toolchain install nightly
cargo install cargo-fuzz

Running Fuzz Tests

Quick smoke test (1 minute per target, parallel):

./crates/libgraphql-parser/scripts/run-fuzz-tests.sh

Sustained run (15 minutes per target, parallel):

./crates/libgraphql-parser/scripts/run-fuzz-tests.sh 15

Single target:

./crates/libgraphql-parser/scripts/run-fuzz-tests.sh 5 fuzz_lexer

Raw cargo fuzz (from the fuzz directory):

cd crates/libgraphql-parser/fuzz
cargo +nightly fuzz run fuzz_lexer -- -max_total_time=60

Latest Fuzz Testing Results

Date: 2026-02-10 Duration: 60 minutes per target (4 targets in parallel) Platform: macOS (aarch64), nightly Rust

Total: 70,644,979 executions across all targets, zero crashes.

License

Licensed under the MIT license.