Nominating Presidential Muppets
    Have ideas to improve npm?Join in the discussion! »

    gql-query-builder
    TypeScript icon, indicating that this package has built-in type declarations

    3.5.5 • Public • Published

    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: "user@example.com", 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: '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"
    }

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

    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)

    Install

    npm i gql-query-builder

    DownloadsWeekly Downloads

    5,345

    Version

    3.5.5

    License

    MIT

    Unpacked Size

    118 kB

    Total Files

    54

    Last publish

    Collaborators

    • avatar