🔧 Simple GraphQL Query Builder
A simple helper function to generate GraphQL queries using plain JavaScript Objects (JSON).
npm install gql-query-builder --saveor
yarn add gql-query-builder
You can also import
queryor
mutationor
subscriptionindividually:
import { query, mutation, subscription } from 'gql-query-builder'query(options: object) mutation(options: object) subscription(options: object)
import * as gql from 'gql-query-builder'const query = gql.query(options: object, adapter?: MyCustomQueryAdapter,config?: object) const mutation = gql.mutation(options: object, adapter?: MyCustomQueryAdapter) const subscription = gql.subscription(options: object, adapter?: MyCustomSubscriptionAdapter)
optionsis
{ operation, fields, variables }or an array of
options
Name | Description | Type | Required | Example |
---|---|---|---|---|
operation | Name of operation to be executed on server | String | Yes | getThoughts, createThought |
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: "[email protected]", required: true },
password: { value: "123456", required: true },
secondaryEmails: { value: [], required: false, type: 'String', list: true,name: secondaryEmail }
}
|
Name | Description | Type | Required | Example |
---|---|---|---|---|
operationName | Name of operation to be sent to the server | String | No | getThoughts, createThought |
An optional second argument
adapteris a typescript/javascript class that implements
src/adapters/IQueryAdapteror
src/adapters/IMutationAdapter.
If adapter is undefined then
src/adapters/DefaultQueryAdapteror
src/adapters/DefaultMutationAdapteris used.
Query:
import * as gql from 'gql-query-builder'const query = gql.query({ operation: 'thoughts', fields: ['id', 'name', 'thought'] })
console.log(query)
// Output query { thoughts { id, name, thought } }
Query (with variables):
import * as gql from 'gql-query-builder'const query = gql.query({ operation: 'thought', variables: { id: 1 }, fields: ['id', 'name', 'thought'] })
console.log(query)
// Output query ($id: Int) { thought (id: $id) { id, name, thought } }
// Variables { "id": 1 }
Query (with nested fields selection)
import * as gql from 'gql-query-builder'const query = gql({ operation: 'orders', fields: [ 'id', 'amount', { user: [ 'id', 'name', 'email', { address: [ 'city', 'country' ] } ] } ] })
console.log(query)
// Output query { orders { id, amount, user { id, name, email, address { city, country } } } }
Query (with required variables):
import * as gql from 'gql-query-builder'const query = gql.query({ operation: 'userLogin', variables: { email: { value: '[email protected]', required: true }, password: { value: '123456', required: true } }, fields: ['userId', 'token'] })
console.log(query)
// Output query ($email: String!, $password: String!) { userLogin (email: $email, password: $password) { userId, token } }
// Variables { email: "[email protected]", password: "123456" }
Query (with custom argument name):
import * as gql from 'gql-query-builder'const query = gql.query([{ operation: "someoperation", fields: [{ operation: "nestedoperation", fields: ["field1"], variables: { id2: { name: "id", type: "ID", value: 123, }, }, }, ], variables: { id1: { name: "id", type: "ID", value: 456, }, }, }, ]);
console.log(query)
// Output query($id2: ID, $id1: ID) { someoperation(id: $id1) { nestedoperation(id: $id2) { field1 } } }
// Variables { "id1": 1, "id2": 1 }
Query (with operation name):
import * as gql from 'gql-query-builder'const query = gql.query({ operation: 'userLogin', fields: ['userId', 'token'] }, null, { operationName: 'someoperation' })
console.log(query)
// Output query someoperation { userLogin { userId token } }
Query (with empty fields):
import * as gql from 'gql-query-builder'const query = gql.query([{ operation: "getFilteredUsersCount", }, { operation: "getAllUsersCount", fields: [] }, operation: "getFilteredUsers", fields: [{ count: [], }, ], ]);
console.log(query)
// Output query { getFilteredUsersCount getAllUsersCount getFilteredUsers { count } }
Query (with adapter defined):
For example, to inject
SomethingIDidInMyAdapterin the
operationWrapperTemplatemethod.
import * as gql from 'gql-query-builder' import MyQueryAdapter from 'where/adapters/live/MyQueryAdapter'const query = gql.query({ operation: 'thoughts', fields: ['id', 'name', 'thought'] }, MyQueryAdapter)
console.log(query)
// Output query SomethingIDidInMyAdapter { thoughts { id, name, thought } }
Take a peek at DefaultQueryAdapter to get an understanding of how to make a new adapter.
Mutation:
import * as gql from 'gql-query-builder'const query = gql.mutation({ operation: 'thoughtCreate', variables: { name: 'Tyrion Lannister', thought: 'I drink and I know things.' }, fields: ['id'] })
console.log(query)
// Output mutation ($name: String, $thought: String) { thoughtCreate (name: $name, thought: $thought) { id } }
// Variables { "name": "Tyrion Lannister", "thought": "I drink and I know things." }
Mutation (with required variables):
import * as gql from 'gql-query-builder'const query = gql.mutation({ operation: 'userSignup', variables: { name: { value: 'Jon Doe' }, email: { value: '[email protected]', required: true }, password: { value: '123456', required: true } }, fields: ['userId'] })
console.log(query)
// Output mutation ($name: String, $email: String!, $password: String!) { userSignup (name: $name, email: $email, password: $password) { userId } }
// Variables { name: "Jon Doe", email: "[email protected]", password: "123456" }
Mutation (with custom types):
import * as gql from 'gql-query-builder'const query = gql.mutation({ operation: "userPhoneNumber", variables: { phone: { value: { prefix: "+91", number: "9876543210" }, type: "PhoneNumber", required: true } }, fields: ["id"] })
console.log(query)
// Output mutation ($phone: PhoneNumber!) { userPhoneNumber (phone: $phone) { id } }
// Variables { phone: { prefix: "+91", number: "9876543210" } }
Query:
import axios from "axios"; import { query } from "gql-query-builder";async function getThoughts() { try { const response = await axios.post( "http://api.example.com/graphql", query({ operation: "thoughts", fields: ["id", "name", "thought"], }) );
console.log(response);
} catch (error) { console.log(error); } }
Mutation:
import axios from "axios"; import { mutation } from "gql-query-builder";async function saveThought() { try { const response = await axios.post( "http://api.example.com/graphql", mutation({ operation: "thoughtCreate", variables: { name: "Tyrion Lannister", thought: "I drink and I know things.", }, fields: ["id"], }) );
console.log(response);
} catch (error) { console.log(error); } }
Mutation (with adapter defined):
For example, to inject
SomethingIDidInMyAdapterin the
operationWrapperTemplatemethod.
import * as gql from 'gql-query-builder' import MyMutationAdapter from 'where/adapters/live/MyQueryAdapter'const query = gql.mutation({ operation: 'thoughts', fields: ['id', 'name', 'thought'] }, MyMutationAdapter)
console.log(query)
// Output mutation SomethingIDidInMyAdapter { thoughts { id, name, thought } }
Take a peek at DefaultMutationAdapter to get an understanding of how to make a new adapter.
Subscription:
import axios from "axios"; import { subscription } from "gql-query-builder";async function saveThought() { try { const response = await axios.post( "http://api.example.com/graphql", subscription({ operation: "thoughtCreate", variables: { name: "Tyrion Lannister", thought: "I drink and I know things.", }, fields: ["id"], }) );
console.log(response);
} catch (error) { console.log(error); } }
Subscription (with adapter defined):
For example, to inject
SomethingIDidInMyAdapterin the
operationWrapperTemplatemethod.
import * as gql from 'gql-query-builder' import MySubscriptionAdapter from 'where/adapters/live/MyQueryAdapter'const query = gql.subscription({ operation: 'thoughts', fields: ['id', 'name', 'thought'] }, MySubscriptionAdapter)
console.log(query)
// Output subscription SomethingIDidInMyAdapter { thoughts { id, name, thought } }
Take a peek at DefaultSubscriptionAdapter to get an understanding of how to make a new adapter.
Following projects are using gql-query-builder
If you are interested in actively maintaining / enhancing this project, get in touch.
If you liked this project, you can donate to support it ❤️
Copyright (c) 2018 Atul Yadav http://github.com/atulmy
The MIT License (http://www.opensource.org/licenses/mit-license.php)