GraphQL Query Builder

Generate GraphQL queries using plain JavaScript Objects (JSON)

GraphQLJSON
atulmy/gql-query-buildergql-query-builder

README

GraphQL Query Builder


A simple helper function to generate GraphQL queries using plain JavaScript Objects (JSON).

downloads

demo

Install


npm install gql-query-builder --save or yarn add gql-query-builder

Usage


  1. ```typescript
  2. import * as gql from 'gql-query-builder'

  4. const query = gql.query(options: object)
  5. const mutation = gql.mutation(options: object)
  6. const subscription = gql.subscription(options: object)
  7. ```

You can also import query or mutation or subscription individually:

  1. ```typescript
  2. import  { query, mutation, subscription } from 'gql-query-builder'

  4. query(options: object)
  5. mutation(options: object)
  6. subscription(options: object)
  7. ```

Options


options is { operation, fields, variables } or an array of options

Name Description Type Required Example
operation Name of operation to be executed on server String | Object Yes getThoughts, createThought

{ name: 'getUser', alias: 'getAdminUser' }
fields Selection of fields Array No ['id', 'name', 'thought']

['id', 'name', 'thought', { user: ['id', 'email'] }]
variables Variables sent to the operation Object No { key: value } eg: { id: 1 }

{ key: { value: value, required: true, type: GQL type, list: true, name: argument name } eg:

{

email: { value: "user@example.com", required: true },

password: { value: "123456", required: true },

secondaryEmails: { value: [], required: false, type: 'String', list: true, name: secondaryEmail }

}

Adapter


An optional second argument adapter is a typescript/javascript class that implements src/adapters/IQueryAdapter or src/adapters/IMutationAdapter.

If adapter is undefined then src/adapters/DefaultQueryAdapter or src/adapters/DefaultMutationAdapter is used.

  1. ```
  2. import * as gql from 'gql-query-builder'

  4. const query = gql.query(options: object, adapter?: MyCustomQueryAdapter,config?: object)
  5. const mutation = gql.mutation(options: object, adapter?: MyCustomQueryAdapter)
  6. const subscription = gql.subscription(options: object, adapter?: MyCustomSubscriptionAdapter)
  7. ```

Config



Name Description Type Required Example
operationName Name of operation to be sent to the server String No getThoughts, createThought

Examples


1. Query2. Query (with variables)3. Query (with nested fields selection)4. Query (with required variables)5. Query (with custom argument name)6. Query (with operation name)7. Query (with empty fields)8. Query (with alias)9. Query (with adapter defined)10. Mutation11. Mutation (with required variables)12. Mutation (with custom types)13. Mutation (with adapter defined)14. Mutation (with operation name)15. Subscription16. Subscription (with adapter defined)17. Example with Axios

Query:


  1. ```javascript
  2. import * as gql from 'gql-query-builder'

  4. const query = gql.query({
  5.   operation: 'thoughts',
  6.   fields: ['id', 'name', 'thought']
  7. })

  9. console.log(query)

  11. // Output
  12. query {
  13.   thoughts {
  14.     id,
  15.     name,
  16.     thought
  17.   }
  18. }
  19. ```

↑ all examples

Query (with variables):


  1. ```javascript
  2. import * as gql from 'gql-query-builder'

  4. const query = gql.query({
  5.   operation: 'thought',
  6.   variables: { id: 1 },
  7.   fields: ['id', 'name', 'thought']
  8. })

  10. console.log(query)

  12. // Output
  13. query ($id: Int) {
  14.   thought (id: $id) {
  15.     id, name, thought
  16.   }
  17. }

  19. // Variables
  20. { "id": 1 }
  21. ```

↑ all examples

Query (with nested fields selection):


  1. ```javascript
  2. import * as gql from 'gql-query-builder'

  4. const query = gql({
  5.   operation: 'orders',
  6.   fields: [
  7.     'id',
  8.     'amount',
  9.     {
  10.      user: [
  11.         'id',
  12.         'name',
  13.         'email',
  14.         {
  15.           address: [
  16.             'city',
  17.             'country'
  18.           ]
  19.         }
  20.       ]
  21.     }
  22.   ]
  23. })

  25. console.log(query)

  27. // Output
  28. query {
  29.   orders  {
  30.     id,
  31.     amount,
  32.     user {
  33.       id,
  34.       name,
  35.       email,
  36.       address {
  37.         city,
  38.         country
  39.       }
  40.     }
  41.   }
  42. }
  43. ```

↑ all examples

Query (with required variables):


  1. ```javascript
  2. import * as gql from 'gql-query-builder'

  4. const query = gql.query({
  5.   operation: 'userLogin',
  6.   variables: {
  7.     email: { value: 'jon.doe@example.com', required: true },
  8.     password: { value: '123456', required: true }
  9.   },
  10.   fields: ['userId', 'token']
  11. })

  13. console.log(query)

  15. // Output
  16. query ($email: String!, $password: String!) {
  17.   userLogin (email: $email, password: $password) {
  18.     userId, token
  19.   }
  20. }

  22. // Variables
  23. {
  24.   email: "jon.doe@example.com",
  25.   password: "123456"
  26. }
  27. ```

↑ all examples

Query (with custom argument name):


  1. ```javascript
  2. import * as gql from 'gql-query-builder'

  4. const query = gql.query([{
  5.   operation: "someoperation",
  6.   fields: [{
  7.     operation: "nestedoperation",
  8.     fields: ["field1"],
  9.     variables: {
  10.       id2: {
  11.         name: "id",
  12.         type: "ID",
  13.         value: 123,
  14.       },
  15.     },
  16.   }, ],
  17.   variables: {
  18.     id1: {
  19.       name: "id",
  20.       type: "ID",
  21.       value: 456,
  22.     },
  23.   },
  24. }, ]);

  26. console.log(query)

  28. // Output
  29. query($id2: ID, $id1: ID) {
  30.   someoperation(id: $id1) {
  31.     nestedoperation(id: $id2) {
  32.       field1
  33.     }
  34.   }
  35. }

  37. // Variables
  38. {
  39.   "id1": 1,
  40.   "id2": 1
  41. }
  42. ```

↑ all examples

Query (with operation name):


  1. ```javascript
  2. import * as gql from 'gql-query-builder'

  4. const query = gql.query({
  5.   operation: 'userLogin',
  6.   fields: ['userId', 'token']
  7. }, null, {
  8.   operationName: 'someoperation'
  9. })

  11. console.log(query)

  13. // Output
  14. query someoperation {
  15.   userLogin {
  16.     userId
  17.     token
  18.   }
  19. }
  20. ```

↑ all examples

Query (with empty fields):


  1. ```javascript
  2. import * as gql from 'gql-query-builder'

  4. const query = gql.query([{
  5.   operation: "getFilteredUsersCount",
  6. },
  7.   {
  8.     operation: "getAllUsersCount",
  9.     fields: []
  10.   },
  11.   operation: "getFilteredUsers",
  12.   fields: [{
  13.   count: [],
  14. }, ],
  15. ]);

  17. console.log(query)

  19. // Output
  20. query {
  21.   getFilteredUsersCount
  22.   getAllUsersCount
  23.   getFilteredUsers {
  24.     count
  25.   }
  26. }
  27. ```

↑ all examples

Query (with alias):


  1. ```javascript
  2. import * as gql from 'gql-query-builder'

  4. const query = gql.query({
  5.   operation: {
  6.     name: 'thoughts',
  7.     alias: 'myThoughts',
  8.   },
  9.   fields: ['id', 'name', 'thought']
  10. })

  12. console.log(query)

  14. // Output
  15. query {
  16.   myThoughts: thoughts {
  17.     id,
  18.     name,
  19.     thought
  20.   }
  21. }
  22. ```

↑ all examples

Query (with inline fragment):


  1. ```javascript
  2. import * as gql from 'gql-query-builder'

  4. const query = gql.query({
  5.     operation: "thought",
  6.     fields: [
  7.         "id",
  8.         "name",
  9.         "thought",
  10.         {
  11.             operation: "FragmentType",
  12.             fields: ["emotion"],
  13.             fragment: true,
  14.         },
  15.     ],
  16. });

  18. console.log(query)

  20. // Output
  21. query {
  22.     thought {
  23.         id,
  24.         name,
  25.         thought,
  26.         ... on FragmentType {
  27.             emotion
  28.         }
  29.     }
  30. }
  31. ```

↑ all examples

Query (with adapter defined):


For example, to inject SomethingIDidInMyAdapter in the operationWrapperTemplate method.

  1. ```javascript
  2. import * as gql from 'gql-query-builder'
  3. import MyQueryAdapter from 'where/adapters/live/MyQueryAdapter'

  5. const query = gql.query({
  6.   operation: 'thoughts',
  7.   fields: ['id', 'name', 'thought']
  8. }, MyQueryAdapter)

  10. console.log(query)

  12. // Output
  13. query SomethingIDidInMyAdapter {
  14.   thoughts {
  15.     id,
  16.     name,
  17.     thought
  18.   }
  19. }
  20. ```

Take a peek at DefaultQueryAdapter to get an understanding of how to make a new adapter.

↑ all examples

Mutation:


  1. ```javascript
  2. import * as gql from 'gql-query-builder'

  4. const query = gql.mutation({
  5.   operation: 'thoughtCreate',
  6.   variables: {
  7.     name: 'Tyrion Lannister',
  8.     thought: 'I drink and I know things.'
  9.   },
  10.   fields: ['id']
  11. })

  13. console.log(query)

  15. // Output
  16. mutation ($name: String, $thought: String) {
  17.   thoughtCreate (name: $name, thought: $thought) {
  18.     id
  19.   }
  20. }

  22. // Variables
  23. {
  24.   "name": "Tyrion Lannister",
  25.   "thought": "I drink and I know things."
  26. }
  27. ```

↑ all examples

Mutation (with required variables):


  1. ```javascript
  2. import * as gql from 'gql-query-builder'

  4. const query = gql.mutation({
  5.   operation: 'userSignup',
  6.   variables: {
  7.     name: { value: 'Jon Doe' },
  8.     email: { value: 'jon.doe@example.com', required: true },
  9.     password: { value: '123456', required: true }
  10.   },
  11.   fields: ['userId']
  12. })

  14. console.log(query)

  16. // Output
  17. mutation ($name: String, $email: String!, $password: String!) {
  18.   userSignup (name: $name, email: $email, password: $password) {
  19.     userId
  20.   }
  21. }

  23. // Variables
  24. {
  25.   name: "Jon Doe",
  26.   email: "jon.doe@example.com",
  27.   password: "123456"
  28. }
  29. ```

↑ all examples

Mutation (with custom types):


  1. ```javascript
  2. import * as gql from 'gql-query-builder'

  4. const query = gql.mutation({
  5.   operation: "userPhoneNumber",
  6.   variables: {
  7.     phone: {
  8.       value: { prefix: "+91", number: "9876543210" },
  9.       type: "PhoneNumber",
  10.       required: true
  11.     }
  12.   },
  13.   fields: ["id"]
  14. })

  16. console.log(query)

  18. // Output
  19. mutation ($phone: PhoneNumber!) {
  20.   userPhoneNumber (phone: $phone) {
  21.     id
  22.   }
  23. }

  25. // Variables
  26. {
  27.   phone: {
  28.     prefix: "+91", number: "9876543210"
  29.   }
  30. }
  31. ```

↑ all examples

Mutation (with adapter defined):


For example, to inject SomethingIDidInMyAdapter in the operationWrapperTemplate method.

  1. ```javascript
  2. import * as gql from 'gql-query-builder'
  3. import MyMutationAdapter from 'where/adapters/live/MyQueryAdapter'

  5. const query = gql.mutation({
  6.   operation: 'thoughts',
  7.   fields: ['id', 'name', 'thought']
  8. }, MyMutationAdapter)

  10. console.log(query)

  12. // Output
  13. mutation SomethingIDidInMyAdapter {
  14.   thoughts {
  15.     id,
  16.     name,
  17.     thought
  18.   }
  19. }
  20. ```

↑ all examples

Take a peek at DefaultMutationAdapter to get an understanding of how to make a new adapter.

Mutation (with operation name):


  1. ```javascript
  2. import * as gql from 'gql-query-builder'

  4. const query = gql.mutation({
  5.   operation: 'thoughts',
  6.   fields: ['id', 'name', 'thought']
  7. }, undefined, {
  8.   operationName: 'someoperation'
  9. })

  11. console.log(query)

  13. // Output
  14. mutation someoperation {
  15.   thoughts {
  16.     id
  17.     name
  18.     thought
  19.   }
  20. }
  21. ```

↑ all examples

Subscription:


  1. ```javascript
  2. import axios from "axios";
  3. import { subscription } from "gql-query-builder";

  5. async function saveThought() {
  6.   try {
  7.     const response = await axios.post(
  8.       "http://api.example.com/graphql",
  9.       subscription({
  10.         operation: "thoughtCreate",
  11.         variables: {
  12.           name: "Tyrion Lannister",
  13.           thought: "I drink and I know things.",
  14.         },
  15.         fields: ["id"],
  16.       })
  17.     );

  19.     console.log(response);
  20.   } catch (error) {
  21.     console.log(error);
  22.   }
  23. }
  24. ```

↑ all examples

Subscription (with adapter defined):


For example, to inject SomethingIDidInMyAdapter in the operationWrapperTemplate method.

  1. ```javascript
  2. import * as gql from 'gql-query-builder'
  3. import MySubscriptionAdapter from 'where/adapters/live/MyQueryAdapter'

  5. const query = gql.subscription({
  6.   operation: 'thoughts',
  7.   fields: ['id', 'name', 'thought']
  8. }, MySubscriptionAdapter)

  10. console.log(query)

  12. // Output
  13. subscription SomethingIDidInMyAdapter {
  14.   thoughts {
  15.     id,
  16.     name,
  17.     thought
  18.   }
  19. }
  20. ```

Take a peek at DefaultSubscriptionAdapter to get an understanding of how to make a new adapter.

↑ all examples

Example with Axios


Query:

  1. ```javascript
  2. import axios from "axios";
  3. import { query } from "gql-query-builder";

  5. async function getThoughts() {
  6.   try {
  7.     const response = await axios.post(
  8.       "http://api.example.com/graphql",
  9.       query({
  10.         operation: "thoughts",
  11.         fields: ["id", "name", "thought"],
  12.       })
  13.     );

  15.     console.log(response);
  16.   } catch (error) {
  17.     console.log(error);
  18.   }
  19. }
  20. ```

↑ all examples

Mutation:

  1. ```javascript
  2. import axios from "axios";
  3. import { mutation } from "gql-query-builder";

  5. async function saveThought() {
  6.   try {
  7.     const response = await axios.post(
  8.       "http://api.example.com/graphql",
  9.       mutation({
  10.         operation: "thoughtCreate",
  11.         variables: {
  12.           name: "Tyrion Lannister",
  13.           thought: "I drink and I know things.",
  14.         },
  15.         fields: ["id"],
  16.       })
  17.     );

  19.     console.log(response);
  20.   } catch (error) {
  21.     console.log(error);
  22.   }
  23. }
  24. ```

↑ all examples

Showcase


Following projects are using gql-query-builder

- Crate - Get monthly subscription of trendy clothes and accessories - GitHub
- Fullstack GraphQL Application - GitHub
- Would really appreciate if you add your project to this list by sending a PR

Author


- Atul Yadav - GitHub · Twitter

Contributors


**If you are interested in actively maintaining / enhancing this project, get in touch.**

- Juho Vepsäläinen - GitHub · Twitter
- Daniel Hreben - GitHub · Twitter
- Todd Baur - GitHub · Twitter
- Alireza Hariri - GitHub
- Cédric - GitHub
- Clayton Collie - GitHub
- Devon Reid - GitHub
- Harry Brundage - GitHub · Twitter
- Clément Berard - GitHub · Twitter
- Lee Rose - GitHub
- Christian Westgaard - GitHub
- [YOUR NAME HERE] - Feel free to contribute to the codebase by resolving any open issues, refactoring, adding new features, writing test cases or any other way to make the project better and helpful to the community. Feel free to fork and send pull requests.

Donate


If you liked this project, you can donate to support it ❤️

Donate via PayPal

License


Copyright (c) 2018 Atul Yadav

The MIT License ()