Write GraphQL queries as objects instead of strings
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.
$ npm install gotql
Or
$ yarn install gotql
const gotQl = require('gotql')
const query = {
operation: {
name: 'users',
fields: ['name', 'age', 'id']
}
}
const options = {
headers: {
"Authorization": "Bearer <token>"
},
debug: false,
useHttp2: false
}
gotQL.query('mygraphqlendpoint.com.br/api', query, options)
.then(response => console.log(response.data))
.catch(console.error)
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.
See more on: https://hasura.io/blog/fluent-graphql-clients-how-to-write-queries-like-a-boss/
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: literal`status_change`, // 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.
gotQl.query(graphQLEndpoint, query, [options])
GraphQLEndpoint
string
query
object
options
See option object for more information.
gotQl.mutation(graphQLEndpoint, query, [options])
GraphQLEndpoint
string
query
object
options
See option object for more information.
gotQl.parser(query, type)
query
object
type
string
'query'
or 'mutation'
Both gotql.query
and gotql.mutation
accept an optional user option object with the following API:
object
number
object
, in the form of [headerName: string]: headerValue: string
got
. Internally this will be called as got.post(prependHttp(endPoint), gotPayload)
false
(see release 11 of got)
boolean
Note: GotQL uses
debug
internally as default debugger, so you can set debug levels by setting theDEBUG
environment variable. These are the current levels:
gotql:info
gotql:info:parser
gotql:info:runner
gotql:errors
All methods return a string
like this:
const response = 'query { test { name args } }'
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]: [{
args?: { [argName: string]: any } | {
[argName: string]: {
value: string,
escape: boolean
}
},
fields?: (string | { [fieldName: string]: [any] })[]
}]
})[]
},
variables?: {
[varName: string]: {
type: string,
value: string
}
}
}
object
string
object
with signature like [varName: string]: { type: string, value: string }
string
string!
)
string
any
object
string
string
[argName: string]: any
or a detailed arg object
object
where the key is the argument name and its value. Accepts variables in the format of argName: '$value'
args { name: 'myName' }
tagged template
args: { status: literal`an_enum` }
should output operation (status: an_enum)...
array
of object
(to use nested fields) or string
, or both.object
where the field name is the key[argName: string]: any
or a detailed arg object
object
where the key is the argument name and its value. Accepts variables in the format of argName: '$value'
args { name: 'myName' }
tagged template
args: { status: literal`an_enum` }
should output operation (status: an_enum)...
const query = {
operation: {
name: 'users',
fields: ['name', 'age']
}
}
Outputs:
query { users { name age } }
const query = {
name: 'myQuery',
operation: {
name: 'users',
fields: ['name', 'age']
}
}
Outputs:
query myQuery { users { name age } }
const query = {
operation: {
name: 'users',
args: {
name: 'Joe'
},
fields: ['name', 'age']
}
}
Outputs:
query { users(name: "Joe") { name age } }
const query = {
variables: {
name: {
type: 'string!',
value: 'Joe'
}
},
operation: {
name: 'users',
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" }
}
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 or literal values should not be escaped, to do that, GotQL has a helper called literal
which can be used to tell the query that value will not be escaped:
const { literal } = require('gotql')
const query = {
operation: {
name: 'users',
args: {
type: literal`internal`
},
fields: ['name', 'age']
}
}
The code above outputs:
query { users(type: internal) { name age } }
The literal
helper is just a shorthand to the old-style {value: string, escape: boolean}
object like below:
const query = {
operation: {
name: 'users',
args: {
type: {
value: 'internal',
escape: false
}
},
fields: ['name', 'age']
}
}
If literal
is omitted, or 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).
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 😄
This project exists thanks to all the people who contribute. [Contribute].
Become a financial contributor and help us sustain our community. [Contribute]
Support this project with your organization. Your logo will show up here with a link to your website. [Contribute]