senegraph

0.0.19 • Public • Published

Senegraph

HapiJS and Express plugin connecting SenecaJS and GraphQL:

Do you like Microservices? Do you like GraphQL?

Me too! Let me then propose this simple plugin for HapiJS and Express Middleware to you. It's fairly simple and flexible tool for creating API endpoints.

Installation:

npm install --save senegraph

Usage:

HAPI JS :

Here is a simple setup for HapiJS:

import * as hapi from 'hapi';
import { senegraphHapi, hapiql } from 'senegraph';
 
// setup Hapi server
const server = new hapi.Server();
server.connection({ port: 3000 });
 
// register the plugins
server.register([{
    register: senegraphHapi,
    options: senegraphOptions,
}, {
    register: hapiql,
    options: {
        path: '/graphiql' // Optional default '/graphiql'
        hapiqlOptions: {
            endpointURL: '/graphql', // required - pointing to the graphQL route
        },
    },
}], (err) => {
    if(err) {
        throw err;
    }
    server.start((error) => {
        if (error) {
          throw error;
        }
        server.log('info', `Server running at: ${server.info.uri}`);
    });
});

Now the senegraphOptions variable can look like this:

const senegraphOptions = {
    // Setting up the seneca microservices
    setupSeneca: (seneca) => {
        // we can return a promise if we need it
        // to wait for some async operation
        seneca.add({ role: 'greeter', cmd: 'sayHello' }, (message, done) => {
            if(message.user) {
                done(null, { message: 'Hello ' + message.user });
            } else {
                done(new Error('You forgot to tell me who you are'));
            }
        });
    },
    // Setting up the schema (for this example it's pretty simple
    // but you can for example split it into multiple modules
    schema: `
        type Query {
            hello(name: String!): String
        }
    `,
    resolvers: {
        Query: {
            // third argument is context, which contains
            // the seneca that we can use for our purpose
            hello: (root, { name }, { seneca }) => {
                // we need to use promise
                // but we could use bluebird's Promisify
                // on seneca, check the links below
                return new Promise((resolve, reject) => {
                    seneca.act({
                        role: 'greeter',
                        cmd: 'sayHello',
                        user: name,
                    }, (err, greetings) => {
                        if(err) {
                            reject(err);
                        } else {
                            resolve(greetings.message);
                        }
                    });
                });
            }
        }
    }
}

To split the schema and/or resolvers into multiple modules take a look at this: http://dev.apollodata.com/tools/graphql-tools/generate-schema.html#modularizing

To modularize SenecaJS into multiple files take a look at this: http://jakepruitt.com/2015/02/09/beginners-guide-to-seneca-js.html

To promisify seneca take a look at this: http://senecajs.org/docs/tutorials/seneca-with-promises.html


What if you need to make action for every request called upon your graphql endpoint? What if you need to provide some additional context and/or root value for your resolvers?

Here's how you do that:

  const senegraphOptions = {
    schema: mySchema,
    resolvers: {
      Query: {
        hello: ({ myRootData }, args, { seneca, myContextData }) => {
          // use myRootData = 'random data2' and myContextData = 'random data1'
          return 'world';
        }
      }
    },
    // This function is called before every request
    // on your graphql endpoint:
    perRequest: (seneca) => {
      // It can either return a value or a Promise
      return new Promise((resolve) => {
        setTimeout(() => {
          resolve({
            // returns context and rootValue used in the next graphql call
            context: { myContextData: 'random data1' },
            rootValue: { myRootData: 'random data2' },
          });
        }, 200);
      });
    }
  }

cool isn't it? You can do for example authentication on every single request.

API

SenegraphHapi options:

option type description required
schema String! true
resolvers Object! or Array Containing the resolvers of your graphql schema. true
path String The url for the endpoint route. false Default: '/graphql'
methods String Array The methods supported for graphql endpoint
setupSeneca Function (seneca) => {} Is being called at the beginning. This option is optional. false
perRequest Promise OR Function OR Function<Promise> Is being called on every request. Can be Promise or function returning object or function returning Promise. This option is optional false
senecaOptions Object The seneca instantiating options e.g. { log: 'silent' } false Default: {}

HapiQL takes this options:

option type description required
path String The path on which the server should serve for graphiql false Default: '/graphiql'
hapiqlOptions Object The options for the hapiql contains endpoint and many more described below true At least endpoint should be provided

hapiqlOptions take these values:

option type description required
endpointURL String the graphql endpoint by default on address '/graphql' true
subscriptionsEndpoint String Endpoint for subscriptions false
query String The default query false
variables Object The default variables false
operationName String The default operation name false
result Object The default results false

Check out this video: https://youtu.be/VWPVrJU2upw

EXPRESS :
import * as Express from 'express'
import { senegraphExpress, expressiql }
 
const app = Express();
 
app.use('/graphql', senegraphExpress(senegraphOptions));
app.use('/graphiql', expressiql({ endpointURL: '/graphql' }));
 
app.listen(3000)

Now the senegraphOptions could look the same as in Hapi example...

API

SenegraphExpress Options:

option type description required
schema String! true
resolvers Object! or Array Containing the resolvers of your graphql schema. true
setupSeneca Function (seneca) => {} Is being called at the beginning. This option is optional. false
perRequest Promise OR Function OR Function<Promise> Is being called on every request. Can be Promise or function returning object or function returning Promise. This option is optional false
senecaOptions Object The seneca instantiating options e.g. { log: 'silent' } false Default: {}

The expressiql options should be in this manner:

option type description required
endpointURL String the graphql endpoint by default on address '/graphql' true
subscriptionsEndpoint String Endpoint for subscriptions false
query String The default query false
variables Object The default variables false
operationName String The default operation name false
result Object The default results false

Check out the video on how to use Senegraph with Express: https://youtu.be/-XHN1T6r_R4

CONNECT :

With connect framework it's very similar to Express.

We simply instantiate our server and use the senegraph middleware.

import * as Connect from 'connect'
import * as http from 'http'
import { senegraphConnect, connectiql }
 
const app = Express();
 
app.use('/graphql', senegraphConnect(senegraphOptions));
app.use('/graphiql', connectiql({ endpointURL: '/graphql' }));
 
http.createServer(app).listen(3000);

API

The API is the same as in Senegraph Express implementation.

On both server frameworks you can run seneca.actWithPromise which is the act returning a promise.

Package Sidebar

Install

npm i senegraph

Weekly Downloads

2

Version

0.0.19

License

ISC

Last publish

Collaborators

  • durisvk