GraphQL query utility for serverside apps
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
.github
media
src ♻️ Add error handling for missing type Mar 17, 2018
tests
.gitignore 🔥 Removes postinstall Apr 12, 2018
.travis.yml 🔥 Remove awesome bot from travis May 9, 2018
LICENSE Initial commit Nov 28, 2017
README.md
code-of-conduct.md
index.js
package-lock.json
package.json
yarn.lock

README.md


GotQL


Write GraphQL queries as objects instead of strings


Codacy Badge Build Status Codecov Status JavaScript Style Guide

Downloads NPM Node Version

This is a better implementation of the GraphQL query API via NodeJS, created as a wrapper of Got. It works like a transpiler, with a built in HTTPRequest Client (Got), allowing you to write your GraphQL queries as Javascript Objects instead of strings.

Built because manipulating strings is a real pain.

Table of Contents

Install

$ npm install gotql

Or

$ yarn install gotql

Basic Usage

const gotQl = require('gotql')

const query = {
  operation: {
    name: 'users',
    fields: ['name', 'age', 'id']
  }
}

const options = {
  headers: {
    "Authorization": "Bearer <token>"
  },
  debug: false
}

gotQL.query('mygraphqlendpoint.com.br/api', query, options)
  .then(response => console.log(response.data))
  .catch(console.error)

What is it?

GotQL is a better interface for GraphQL queries. It provides a way for developers to run queries using JSON instead of strings. Which is a way more usable data format than the string itself.

Motivation

Manipulating strings is very smelly, even on dynamically typed languages. So, in order to avoid things such as this:

Which can be translated to something waay more readable in a JSON format like this:

const mutation = {
  operation {
    name: 'addLog',
    args: {
      logType: { value: 'status_change', escape: false}, // Enum Value
      fromState: variables.fromState,
      toState: variables.toState,
      idUser: variables.idUser,
      idCampaign: variables.idCampaign,
      owner: {
        ownerType: variables.ownerType,
        username: variables.username,
        picture: variables.picture,
        name: variables.name,
        id: variables.id
      }
    },
    fields: [ 'uuid' ]
  }
}

This is why GotQL was created.

API

gotQl.query(graphQLEndpoint, query, [options])
  • Description: Performs a graphQL query

GraphQLEndpoint

  • Type: string
  • Description: The GraphQL endpoint to query on

query

options

  • Type: object
  • Description: The option object with the following properties.
    • debug: Activates debug logging
      • Type: boolean
    • errorStatusCode: Default HTTP status code to be returned on error
      • Type: number
    • headers: Additional headers to be sent
      • Type: object, in the form of [headerName: string]: headerValue: string

gotQl.mutation(graphQLEndpoint, query, [options])
  • Description: Performs a graphQL mutation

GraphQLEndpoint

  • Type: string
  • Description: The GraphQL endpoint to query on

query

options

  • Type: object
  • Description: The option object with the following properties.
    • debug: Activates debug logging
      • Type: boolean
    • errorStatusCode: Default HTTP status code to be returned on error
      • Type: number
    • headers: Additional headers to be sent
      • Type: object, in the form of [headerName: string]: headerValue: string

gotQl.parser(query, type)
  • Description: Parses a JSON-Like query and returns the query's string

query

type

  • Type: string
  • Description: Must be either 'query' or 'mutation'

Returns

All methods return a string like this:

const response = 'query { test { name args } }'

The JSON query format

The JSON format gotQL uses is a simple and intuitive description based on the anatomy of a GraphQL query blog post.

This is a generic model of a JSONLike query:

const query = {
    name?: string;
    operation: {
        name: string;
        alias?: string;
        args?: {
            [argName: string]: any;
        } | {
          [argName: string]: {
              value: string;
              escape: boolean;
          };
        };
        fields: (string | {
            [fieldName: string]: [{
                fields?: (string | {
                    [fieldName: string]: [any];
                })[];
            }];
        })[];
    };
    variables?: {
        [varName: string]: {
            type: string;
            value: string;
        };
    };
}

Description

  • Query:
    • Type: object
    • Description: The full query object
    • Properties:
      • name: [optional]: Query name
        • Type: string
      • variables: [optional] Query variable declaration
        • Type: object with signature like [varName: string]: { type: string, value: string }
        • Properties:
          • varName: Variable name
            • Type: string
          • type: Variable type. Can be a GraphQL definition of type (i.e: string!)
            • Type: string
          • value: Variable value
            • Type: any
      • operation: The query operation (action that will be executed)
        • Type: object
        • Properties:
          • name: The operation name
            • Type: string
          • alias: [optional] An alias to give the operation
            • Type: string
          • args: [optional] The operation args
            • Type: [argName: string]: any or a detailed arg object
              • Simple args: An object where the key is the argument name and its value. Accepts variables in the format of argName: '$value'
                • Example: args { name: 'myName' }
              • Detailed args: An object with two properties. This will give more control over escaping (mostly to use enums). Argument name should be the key
                • Type: object
                • Properties:
                  • value: The argument value
                    • Type: any
                  • escape: Whether the argument should be escaped or not (escaped means surrounded with double quotes "argValue")
                    • Type: boolean
                • Examples: args: { status: { value: 'an_enum', escape: false } } should output operation (status: an_enum)...
          • fields: The field list to get back from the operation
            • Type: An array of object (to use nested fields) or string, or both.
            • Properties (for nested fields):
              • Type: object where the field name is the key
              • fields: Recursive definition, accepts another array just like the fields above.

Examples

Simple query

const query = {
  operation: {
    name: 'users',
    fields: ['name', 'age']
  }
}

Outputs:

query { users { name age } }

Named query

const query = {
  name: 'myQuery',
  operation: {
    name: 'users',
    fields: ['name', 'age']
  }
}

Outputs:

query myQuery { users { name age } }

Query with simple args

const query = {
  operation: {
    name: 'user',
    args: {
      name: 'Joe'
    }
    fields: ['name', 'age']
  }
}

Outputs:

query { user(name: "Joe") { name age } }

Query with variables

const query = {
  variables: {
    name: {
      type: 'string!',
      value: 'Joe'
    }
  },
  operation: {
    name: 'user',
    args: {
      name: '$name'
    }
    fields: ['name', 'age']
  }
}

Outputs:

query ($name: string!) { users(name: $name) { name age } }

Variables are sent on a separate object to graphQL.

{
  "variables": { "name": "Joe" }
}

Nested fields

const query = {
  operation: {
    name: 'users',
    fields: ['name', 'age', { friends: { fields: ['name', 'age'] }
    }]
  }
}

Outputs:

query { users { name age friends { name age } } }

Recursive fields can go forever.

Enum args

const query = {
  operation: {
    name: 'user',
    args: {
      type: {
        value: 'internal',
        escape: false
      }
    }
    fields: ['name', 'age']
  }
}

Outputs:

query { users(type: internal) { name age } }

If escape is set to true, the output would be:

query { users(type: "internal") { name age } }

Note: Variables such as described here will not be recognized. If the arg object is not an [argName]: value, variables will not pass through the definition check (GotQL warns if a variable is not declared but used on operation).

Contributing to this project

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

Hey! If you want to contribute, please read the contributing guidelines 😄