A simple helper function to generate GraphQL queries using plain JavaScript Objects (JSON).
npm install gql-query-builder --save
or yarn add gql-query-builder
import * as gql from 'gql-query-builder'
const query = gql.query(options: object)
const mutation = gql.mutation(options: object)
const subscription = gql.subscription(options: object)
You can also import query
or mutation
or subscription
individually:
import { query, mutation, subscription } from 'gql-query-builder'
query(options: object)
mutation(options: object)
subscription(options: object)
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 }
}
|
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.
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)
Name | Description | Type | Required | Example |
---|---|---|---|---|
operationName | Name of operation to be sent to the server | String | No | getThoughts, createThought |
- Query
- Query (with variables)
- Query (with nested fields selection)
- Query (with required variables)
- Query (with custom argument name)
- Query (with operation name)
- Query (with empty fields)
- Query (with alias)
- Query (with adapter defined)
- Mutation
- Mutation (with required variables)
- Mutation (with custom types)
- Mutation (with adapter defined)
- Mutation (with operation name)
- Subscription
- Subscription (with adapter defined)
- Example with Axios
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
}
}
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 }
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
}
}
}
}
import * as gql from 'gql-query-builder'
const query = gql.query({
operation: 'userLogin',
variables: {
email: { value: 'jon.doe@example.com', 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: "jon.doe@example.com",
password: "123456"
}
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
}
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
}
}
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
}
}
import * as gql from 'gql-query-builder'
const query = gql.query({
operation: {
name: 'thoughts',
alias: 'myThoughts',
},
fields: ['id', 'name', 'thought']
})
console.log(query)
// Output
query {
myThoughts: thoughts {
id,
name,
thought
}
}
import * as gql from 'gql-query-builder'
const query = gql.query({
operation: "thought",
fields: [
"id",
"name",
"thought",
{
operation: "FragmentType",
fields: ["emotion"],
fragment: true,
},
],
});
console.log(query)
// Output
query {
thought {
id,
name,
thought,
... on FragmentType {
emotion
}
}
}
For example, to inject SomethingIDidInMyAdapter
in the operationWrapperTemplate
method.
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.
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."
}
import * as gql from 'gql-query-builder'
const query = gql.mutation({
operation: 'userSignup',
variables: {
name: { value: 'Jon Doe' },
email: { value: 'jon.doe@example.com', 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: "jon.doe@example.com",
password: "123456"
}
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"
}
}
For example, to inject SomethingIDidInMyAdapter
in the operationWrapperTemplate
method.
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.
import * as gql from 'gql-query-builder'
const query = gql.mutation({
operation: 'thoughts',
fields: ['id', 'name', 'thought']
}, undefined, {
operationName: 'someoperation'
})
console.log(query)
// Output
mutation someoperation {
thoughts {
id
name
thought
}
}
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);
}
}
For example, to inject SomethingIDidInMyAdapter
in the operationWrapperTemplate
method.
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.
Example with Axios
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);
}
}
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
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.
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)