How Does a GraphQL-ESLint Parser Work?

The graphql-eslint parser is works in the following way:

1. Loads all relevant GraphQL code using ESLint core (either from .graphql files, or using ESLint processor to find in code-files).
2. Is uses graphql-js (and graphql-tools) to parse the found string into a DocumentNode.
3. Extracts all comments (marked as # ...) from the parsed AST, and provides to ESLint as directives hints.
4. If graphql-config is used, or schema field is provided, the schema is being loaded and provided to the rules using parserServices.
5. Converts the DocumentNode to ESTree structure (and enrich the nodes with typeInfo, if schema is loaded).

ESTree Conversion

The GraphQL AST structure is very similar to ESTree structure, but there are a few differences that the parser does.

Here’s a list of changes that the parser performs, in order to make the GraphQL AST compatible with ESTree:

1. ❌ Problem: GraphQL uses kind field to define the kind of the AST node, while ESTree uses type.

   ✅ Solution: The parser adds type field on each node, and just copies the value from kind field.

2. ❌ Problem: Some GraphQL AST nodes are using type field (which conflicts with the ESTree kind).

   ✅ Solution: AST nodes that has type field are being transformed, and the type field changes to gqlType.

3. ❌ Problem: GraphQL AST structure allows circular JSON links (while ESTree might fail on Maximum call stack exceeded).

   ✅ Solution: The parser removes circular JSONs (specifically around GraphQL Location and the Lexer).

4. ❌ Problem: GraphQL uses location field to store the AST locations, while ESTree also uses it in a different structure.

   ✅ Solution: The parser creates a new location field that is compatible with ESTree.

Loading GraphQL Schema

If you are using graphql-config in your project, the parser will automatically use that to load your default GraphQL schema (you can disable this behaviour using skipGraphQLConfig: true in the parserOptions).

If you are not using graphql-config, you can specify parserOptions.schema to load your GraphQL schema. The parser uses graphql-tools and it’s loaders, that means you can either specify a URL, a path to a local .json (introspection) file, or a path to a local .graphql file(s). You can also use Glob expressions to load multiple files.

You can find more detail on the parserOptions config here.

Providing the schema will make sure that rules that needs it will be able to access it, and it enriches every converted AST node with typeInfo.