gql-generator-node

Generate queries based on GraphQL schema.

1npm install gql-generator-node --save-dev 

ToC

• Functionality
• Features
• Usage
• Advanced usage
  • Generate single query
  • Limit query fields
  • Custom dedupe
• Example use case
• Notes
• Credits
• Contribution

Functionality

Given any schema:

1type Query {
2  user(id: Int!): User!
3}
4
5type User {
6  id: Int!
7  username: String!
8  email: String!
9  createdAt: String!
10}

this library automatically creates queries like:

1query user($id: Int!) {
2  user(id: $id){
3    id
4    username
5    email
6    createdAt
7  }
8}

Features

It supports all query types:

• Query
• Mutation
• Subscription

as well as all fields descriptors, including unions, interfaces and fragments.

Last but not least it addresses corner cases - like circular reference.

Usage

The most basic usage is to generate all queries at once by passing schema to generateAll function:

1import {generateAll} from 'gql-generator-node';
2const {queries, mutations, subscriptions} = generateAll(schema);
3
4console.log(mutations.signup);
5/*
6mutation signup($username: String!, email: String!, password: String!){
7  signup(username: $username, email: $email, password: $password){
8    token
9    user {
10      id
11      username
12      email
13      createdAt
14    }
15  }
16}
17*/

Advanced usage

Generate single query

1import {generateQuery} from "gql-generator-node";
2
3const query = generateQuery({
4    field: schema
5        .getQueryType()
6        .getFields().user
7})
8
9console.log(query);
10/*
11	Query user($user_context_user_details_region_language: String, $user_details_region_language: String, $id: Int!){
12	    user(id: $id){
13	        id
14	        username
15	        email
16	        createdAt
17	        context{
18	            user{
19	                id
20	                username
21	                email
22	                createdAt
23	                details{
24	                    ... on Guest {
25	                        region(language: $user_context_user_details_region_language)
26	                    }
27	                    ... on Member {
28	                        address
29	                    }
30	                }
31	            }
32	            domain
33	        }
34	        details{
35	            ... on Guest {
36	                region(language: $user_details_region_language)
37	            }
38	            ... on Member {
39	                address
40	            }
41	        }
42	    }
43	}
44*/

Limit query fields

By default query is generated with all nested fields (skipping only circular references), however this behavior can be customised by passing skeleton of object we are interested in. For instance:

1const query = generateQuery({
2    field: schema
3        .getQueryType()
4        .getFields().user,
5    skeleton: {
6        'email':
7            true
8    }
9})
10
11console.log(query);
12/*
13	Query user($id: Int!){
14	    user(id: $id){
15	        email
16	    }
17	}
18*/

Custom dedupe

As default top variables names correspond to schema while nested ones can be addressed by the path - so all of them can be addressed independently in a declarative way. Ex:

1mutation signup($signup_user_context_user_details_region_language: String, $signup_user_details_region_language: String, $email: String!, $username: String!, $password: String!){
2    signup(email: $email, username: $username, password: $password){
3        token
4        user{
5            id
6            username
7            email
8            createdAt
9            context{
10                user{
11                    id
12                    username
13                    email
14                    createdAt
15                    details{
16                        ... on Guest {
17                            region(language: $signup_user_context_user_details_region_language)
18                        }
19                        ... on Member {
20                            address
21                        }
22                    }
23                }
24                domain
25            }
26            details{
27                ... on Guest {
28                    region(language: $signup_user_details_region_language)
29                }
30                ... on Member {
31                    address
32                }
33            }
34        }
35    }
36}

Yet some applications might take advantage of custom dedupe functions to for instance to send same argument to all sub fields using same name:

1gqlGenerator(schema,depth,({args})=>{
2        const o = {};
3        (args || []).forEach(arg=>{
4            o[arg.name] = arg;
5        });
6        return o;
7    })

=>

1mutation signup($language: String, $email: String!, $username: String!, $password: String!){
2    signup(email: $email, username: $username, password: $password){
3        token
4        user{
5            id
6            username
7            email
8            createdAt
9            context{
10                user{
11                    id
12                    username
13                    email
14                    createdAt
15                    details{
16                        ... on Guest {
17                            region(language: $language)
18                        }
19                        ... on Member {
20                            address
21                        }
22                    }
23                }
24                domain
25            }
26            details{
27                ... on Guest {
28                    region(language: $language)
29                }
30                ... on Member {
31                    address
32                }
33            }
34        }
35    }
36}

Example use case

I personally use it to write graphql endpoints tests.

Assuming GraphQL schema:

1type Mutation {
2  signup(
3    email: String!
4    username: String!
5    password: String!
6  ): UserToken!
7}
8
9type UserToken {
10  token: String!
11  user: User!
12}
13
14type User {
15  id: Int!
16  username: String!
17  email: String!
18  createdAt: String!
19}

Before this tool, one needed to write GraphQL API test like this:

1test('signup', async () => {
2  const query = `mutation signup($username: String!, email: String!, password: String!){
3    signup(username: $username, email: $email, password: $password){
4      token
5      user {
6        id
7        username
8        email
9        createdAt
10      }
11    }
12  }`;
13
14  return graphql(query);
15});

As gqlGenerator can generate queries, above test becomes:

1const {queries} = generateAll(schema.getMutationType().signup);
2
3const variables = { username: "I", email: "best_developer@testing.org", password: '1234' };
4
5test.each(Object.entries(queries))('%s', async ([name,query]) => 
6  graphql(query,{variables})
7);

It not only greatly simplifies testing which might be now automated and batched but also ensures that you would never miss the field to test. Last but not least there is no code duplication between schema and test so most schema updates does not force tests update.

Notes

• Variable names are derived from argument names, so variables generated from multiple occurrences of the same argument name must be deduped. By default, subtree arguments are given path prefix (ex. can be found in dedupe description).

Credits

Code has has its origins at modelo/gql-generator, however it greatly diverged from this implementation.

Contribution

Please feel free open the issues! Although the current stage satisfies my application usage, I would be happy to provide help and improvements if there will be a need for it. Also you can gratify it with star, if you find it useful.