Best Javascript GraphQL Client for the Browser and Node.js

Just provide the url of any GraphQL endpoint to generate the information the client needs and be ready to write queries like this:

bgc.get('posts', {where: {title: "Your title"}}, ["author", {comments: ["user"]}])

If you care about overfetching and don't need all the fields, just use GraphQL-syntax as you already now it:

bgc.get('posts', {where: {title: "Your title"}}, 'text author{ name } comments{ text user{ id name } }');

Or put in a whole GraphQL-query. It's up to you:

bgc.get('query { posts { text author{ name } comments{ text user{ id name } } } }');

By the way: The client supports subscriptions out of the box:

bgc.subscribe(function(data) { console.log(data); }, 'notification', {where: {user: {id: 1}}});

This client is the best for you, if you like it short and elegant. It uses the ApolloClient in the background.

Installation

Add this repo to your package.json:

dependencies:

• "best-graphql-client": "git+https://github.com/mantir/best-graphl-client.git"

Add this script to your package.json:

scripts:

• "generate": "FOLDER=`pwd` npm run --prefix node_modules/best-graphql-client generate"

npm install

Generate definitions for endpoint:

ENDPOINT=https://url-to-endpoint npm run generate
ENDPOINT=https://url-to-endpoint NAME=definitions-filename npm run generate

This will create definitions.js which must be included when initializing the client.

const endpoint = 'http://url-to-endpoint'; //Url to endpoint
const definitions = require('./definitions');
var bgc = require('best-graphql-client/browser')(endpoint, definitions);
/* OR */
var bgc = require('best-graphql-client/nodejs')(endpoint, definitions);

Functions

The following functions can be used to query a GraphlQL endpoint.

get(string name [, object parameters [, array includes] [, string fields] [, object options]])

Graphql-Query: query do(parameters) { name(parameters) { fields + includes } }

If 3 parameters are given: If the 3rd is a string, it is used as the fields. If fields are empty, all fields are returned. includes can also be ['*'], then all connected objects are returned. (See Example-Usage)

mutate(string name [, object parameters [, array includes] [, string fields] [, object options]])

Graphql-Mutation: (Same as get, just as mutation)

subscribe(function callback, string name [, object parameters [, array includes] [, string fields] [, object options]])

Graphql-Mutation: (Same as get, just as subscription)

• options?: Object : optional, object to modify default ApolloClient behavior
  • timeout?: number : how long the client should wait in ms for a keep-alive message from the server (default 30000 ms), this parameter is ignored if the server does not send keep-alive messages. This will also be used to calculate the max connection time per connect/reconnect
  • lazy?: boolean : use to set lazy mode - connects only when first subscription created, and delay the socket initialization
  • connectionParams?: Object | Function | Promise<Object> : object that will be available as first argument of onConnect (in server side), if passed a function - it will call it and send the return value, if function returns as promise - it will wait until it resolves and send the resolved value.
  • reconnect?: boolean : automatic reconnect in case of connection error
  • reconnectionAttempts?: number : how much reconnect attempts
  • connectionCallback?: (error) => {} : optional, callback that called after the first init message, with the error (if there is one)
  • inactivityTimeout?: number : how long the client should wait in ms, when there are no active subscriptions, before disconnecting from the server. Set to 0 to disable this behavior. (default 0)

fragment(string name, array includes, string query)

Fragment for Graphql-Query

getMulti(array queries, object options = { int chunkSize = 100, function onError(object result, int errorCount), function progressCallback(float percent between 0 and 1) })

Executes multiple queries at once. The queries array contains arrays of the parameters for the get function. E.g.: queries = [['elements', { where: { date: '01.01.2022' } }, ['includes'], 'field1 field2'], ['elements', { where: { date: '02.01.2022' } }, ...], ...]. chunkSize indicates how many queries are submitted per request. onError is a custom function executed if a request fails. The can return 'REPEAT', then the request will be tried again. The max number of repetitions is 10. progressCallback is a custom function which receives the ratio of requests sent and total requests to be sent.

mutateMulti(array queries, object options = { int chunkSize = 100, function onError(object result, int errorCount), function progressCallback(float percent between 0 and 1) })

Same as getMulti, just for the mutate function.

Includes

To pass parameters to includes, e.g. to get the comments of only one user:

{ comments: { $: {user_id: 1} }}

parameters can be passed with $ as key.

If an include should have another name in the result it can be passed as $name, e.g.

{ comments: { $name: "userComments", $: {user_id: 1} }}

Example-Usage

const endpoint = 'http://url-to-endpoint.com'; //Url to endpoint
const definitions = require('./definitions');
/* For usage in browser environment */
var bgc = require('best-graphql-client/browser')(endpoint, definitions);
/* For usage in nodejs environment */
var bgc = require('best-graphql-client/nodejs')(endpoint, definitions);

/* All tags with all fields but without connected objects */
var stations = await bgc.get('tags');

/* All tags with parameters, all fields but without connected objects */
var tags = await bgc.get('tags', {orderBy: 'name_ASC'});

/* All tags with only field 'name' and connected object 'tagCategory' */
var tags = await bgc.get('tags', {orderBy: 'name_ASC'}, ['tagCategory'], 'name');
/* Same as */
var tags = await bgc.get('tags', {orderBy: 'name_ASC'}, 'name tagCategory { allFields }');

/* All tags with the field 'name' but without connected objects */
var tags = await bgc.get('tags', {}, 'name');

/* All tags with all fields and all connected objects with all their fields */
var tags = await bgc.get('tags', {orderBy: 'name_ASC'}, ['*'])

/* All tags with all fields and all connected objects (except movies) with all their fields */
var tags = await bgc.get('tags', {orderBy: 'name_ASC'}, ['*', '!movies'])

/* posts: includes the fields of all connected objects and for the comments it includes also all the fields of the user */
var posts = await bgc.get('posts', {where: {title: "Your title"}}, ["*", {comments: ["user"]}])

/* posts: includes the fields of all connected objects and for the comments, which contain "hello", it includes also all the fields of the user */
var posts = await bgc.get('posts', {where: {title: "Your title"}}, ["*", {comments: {$: {where: {content_contains: "hello"} }, user: true}])

/* The same but as fragments */
var posts = await bgc.get('posts', {where: {title: "Your title"}}, ["*|fragment", {"comments|fragment": ["user"]}])

/* Create tag */
var res = await bgc.mutate('createTag', {data: { name: "TESTING" }})