readme.hbs

# grpc-caller

An improved [gRPC](http://www.grpc.io) client.

[![npm version](https://img.shields.io/npm/v/grpc-caller.svg?style=flat-square)](https://www.npmjs.com/package/grpc-caller)
[![build status](https://img.shields.io/travis/bojand/grpc-caller/master.svg?style=flat-square)](https://travis-ci.org/bojand/grpc-caller)
[![JavaScript Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg?style=flat-square)](https://standardjs.com)
[![License](https://img.shields.io/github/license/bojand/grpc-caller.svg?style=flat-square)](https://raw.githubusercontent.com/bojand/grpc-caller/master/LICENSE)

#### Features

* Promisifies request / response (Unary) 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.
* Adds optional retry functionality to request / response (Unary) calls.
* Exposes expanded `Request` API for collecting metadata and status.

## Installation

```
$ npm install grpc-caller
```

## Overview

#### Improved unary calls

Works as standard gRPC client:

```js
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 unary calls, also promisified if callback is not provided:

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

Which means means you can use is with `async / await`

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

For Unary calls we expose `retry` option identical to [async.retry](http://caolan.github.io/async/docs.html#retry).

```
const res = await client.sayHello({ name: 'Bob' }, {}, { retry: 3 })
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:

```js
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:

```js
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`

```js
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`](http://www.grpc.io/grpc/node/module-src_metadata-Metadata.html)
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](https://www.github.com/bojand/grpc-create-metadata)
to automatically create Metadata if plain Javascript object is passed in.

```js
// 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:

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

## Request API

In addition to simple API above, the library provides a more detailed `"Request"` API that can 
be used to control the call details. The API can only be used for Unary and 
request streaming calls.

#### Unary calls

```js
const req = new client
  .Request('sayHello', { name: 'Bob' }) // call method name and argument
  .withMetadata({ requestId: 'bar-123' }) // call request metadata
  .withResponseMetadata(true) // we want to collect response metadata
  .withResponseStatus(true) // we want to collect the response status
  .withRetry(5) // retry options

const res = await req.exec()  
// res is an instance of our `Response`
// we can also call exec() using a callback

console.log(res.response) // the actual response data { message: 'Hello Bob!' }
console.log(res.metadata) // the response metadata
console.log(res.status)   // the response status
console.log(res.call)     // the internal gRPC call
```

#### Request streaming calls

In case of request streaming calls if `exec()` is called with a callback the gRPC `call` stream is returned.
If no callback is provided an object is returned with `call` property being the call stream and `res`
property being a Promise fulfilled when the call is completed. There is no `retry` option for 
request streaming calls.

```js

const req = new client.Request('writeStuff') // the call method name
    .withMetadata({ requestId: 'bar-123' })  // the call request metadata
    .withResponseMetadata(true) // we want to collect response metadata
    .withResponseStatus(true)   // we want to collect the response status

const { call, res: resPromise } = req.exec()

// ... write data to call

const res = await resPromise // res is our `Response`

console.log(res.response) // the actual response data
console.log(res.metadata) // the response metadata
console.log(res.status)   // the response status
console.log(res.call)     // the internal gRPC call
```

## API Reference

{{>all-docs~}}


## License

  Apache-2.0