Need help with gql-query-builder?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

atulmy
193 Stars 30 Forks MIT License 103 Commits 15 Opened issues

Description

🔧 Simple GraphQL Query Builder

Services available

!
?

Need anything else?

Contributors list

# 5,492
JavaScr...
Express
fullsta...
Redux
77 commits
# 30,303
HTML
nuxtjs
Bootstr...
IPFS
3 commits
# 7,117
JavaScr...
React
ecmascr...
uglify
2 commits
# 54,193
Node.js
travis-...
graphql...
Crystal
1 commit
# 327,798
CSS
React
Shell
rust-la...
1 commit
# 192,528
C#
Node.js
GraphQL
query-b...
1 commit
# 235,276
Node.js
Redis
memcach...
sequeli...
1 commit
# 369,238
Kotlin
Node.js
query-b...
C++
1 commit

GraphQL Query Builder

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

Usage

Install

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

Getting Started

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)

API

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)

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 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 } }

config

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

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.

Examples

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

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.

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" } }

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); } }

Mutation (with adapter defined):

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.

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

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.

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

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
  • [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 http://github.com/atulmy

The MIT License (http://www.opensource.org/licenses/mit-license.php)

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.