andela-grpc-caller

grpc-caller

An improved gRPC client.

Features

• Promisifies request / response calls if no callback is supplied
• Promisifies request stream / response calls if no callback is supplied
• Automatically converts plain javascript object to metadata in calls.

Installation

$ npm install grpc-caller

Overview

Improved request / response calls

Works as standard gRPC client:

const caller = require('grpc-caller')
const PROTO_PATH = path.resolve(__dirname, './protos/helloworld.proto')
const client = caller('0.0.0.0:50051', PROTO_PATH, 'Greeter')
client.sayHello({ name: 'Bob' }, (err, res) => {
  console.log(res)
})

For request / response calls, also promisified if callback is not provided:

client.sayHello({ name: 'Bob' })
  .then(res => console.log(res))

Which means means you can use is with async / await

const res = await client.sayHello({ name: 'Bob' })
console.log(res)

Improved request stream / response calls

Lets say we have a remote call writeStuff that accepts a stream of messages and returns some result based on processing of the stream input.

Works as standard gRPC client:

const call = client.writeStuff((err, res) => {
  if (err) console.error(err)
  console.log(res)
})
 
// ... write stuff to call

If no callback is provided we promisify the call such that it returns an object with two properties call and res such that:

• call - the standard stream to write to as returned normally by grpc
• res - a promise that's resolved / rejected when the call is finished, in place of the callback.

Using destructuring we can do something like:

const { call, res } = client.writeStuff()
res
  .then(res => console.log(res))
  .catch(err => console.error(err))
 
// ... write stuff to call

This means we can abstract the whole operation into a nicer promise returning async function to use with async / await

async function writeStuff() {
  const { call, res } = client.writeStuff()
  // ... write stuff to call
  return res
}
 
const res = await writeStuff()
console.log(res)

Automatic Metadata creation

All standard gRPC client calls accept Metadata as first or second parameter (depending on the call type). However one has to manually create the Metadata object. This module uses grpc-create-metadata to automatically create Metadata if plain Javascript object is passed in.

// the 2nd parameter will automatically be converted to gRPC Metadata and
// included in the request
const res = await client.sayHello({ name: 'Bob' }, { requestid: 'my-request-id-123' })
console.log(res)

We can still pass an actual Metadata object and it will be used as is:

const meta = new grpc.Metadata()
meta.add('requestid', 'my-request-id-123')
const res = await client.sayHello({ name: 'Bob' }, meta)
console.log(res)

API Reference

caller(host, proto, name, options) ⇒ Object

Create client isntance.

Kind: global function

Param	Type	Description
host	String	The host to connect to
proto	String | Object	Path to the protocol buffer definition file or Object specifying root directory and file to load or the static client constructor object itself
name	String	In case of proto path the name of the service as defined in the proto definition.
options	Object	Options to be passed to the gRPC client constructor

Example (Create client dynamically)

const PROTO_PATH = path.resolve(__dirname, './protos/helloworld.proto')
const client = caller('localhost:50051', PROTO_PATH, 'Greeter')
 
const root = path.join(__dirname, 'protos');
const file = 'helloworld.proto'
const client = caller('localhost:50051', { root, file }, 'Greeter')

Example (Create a static client)

const services = require('./static/helloworld_grpc_pb')
const client = caller('localhost:50051', services.GreeterClient)

caller.metadata

Utility helper function to create Metadata object from plain Javascript object. See grpc-create-metadata module.

Kind: static property of caller

License

Apache-2.0