@bufferapp/micro-rpc-client

micro-rpc-client

Universal JS RPC Client https://github.com/bufferapp/buffer-rpc/

Quickstart

Create an RPC Client and call an add function

const RPCClient = require('micro-rpc-client');

const client = new RPCClient({
  url: 'https://localhost:3000/rpc',
});

const main = async () => {
  const result = await client.call('add', [1, 2]);
  console.log(result); // 3
};
main();

Usage

A few examples of how to call client methods

const RPCClient = require('micro-rpc-client');

const client = new RPCClient({
  url: 'https://localhost:3000/rpc',
  sendCredentials: 'same-origin', // send cookies on same origin requests
});

const main = async () => {
  const methods = await client.listMethods();
  console.log(method);
  /*
  [
    {
      "docs": "add two numbers"
      "name": "add"
    },
    {
      "docs": "list all available methods",
      "name": "methods"
    }
  ]
  */
  const result = await client.call('add', [1, 2]);
  console.log(result); // 3
};
main();

API

constructor

Create an instance of RPCClient

const client = new RPCClient({
  url,
  sendCredentials,
});

url - string - full url to the RPC Endpoint Server
sendCredentials - string - when to send things like cookies with a request, passes arguments to the credentials init argument in the fetch API https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/fetch#Parameters

Returns an instance of the RPC client

listMethods

List all remote methods on a server

const methods = await client.listMethods()

Returns a promise that resolves with a list of the remote methods

call

const result = await client.call(name, args)

name - string - name of the remote RPC endpoint
args - array or object - arguments to pass to the remote RPC endpoint

Returns a promise that resolves with the result and rejects with an error.

Error Handling

When calling a remote function with call there are different categories of responses:

Success

This is the typical success case

statusCode = 200
result = {} // JSON

Fail (Handled)

An error triggered from createError:

statusCode = 400
result = {
  error: 'string',
  code: 1000, // or some custom code
  handled: true,
}

Fail (Unhandled)

An error triggered from errorMiddleware:

statusCode = 500
result = {
  error: 'string',
  code: 1000, // or some custom code
  handled: true,
}

Fail (Unexpected)

If the errorMiddleware is not hooked up, or something unexpected happened the original error will be thrown.

Changelog

[1.0.0]

Changed

• [Breaking] The RPC client now makes calls to an RPC server in the form of endpoint/:methodName, to allow for clearer debugging and tracing. Ensure you are using >= v. 1.0.0 of buffer-rpc on your server as well.

Added

• Added this CHANGELOG.