Integration with Rserve, a TCP/IP server for R framework


RIO, R Input Output, connects an app to Rserve, a TCP/IP server which allows other programs to use facilities of R.

It supports double, double array, integer, integer array, string, string array, boolean, boolean array objects and raw vector (images or files).

It supports also the plain text authentication, if Rserve is configured for that capability.

The main goal is to pass a string containing a script call using a JSON object as parameter. Then, inside the script, using RJSONIO or jsonlite package, deserializing the JSON object, calling a method, serializing the response and returning to Node.js.


var rio = require("rio");

rio.e({command: "pi / 2 * 2"});
rio.e({command: "c(1, 2)"});
rio.e({command: "as.character('Hello World')"});
rio.e({command: "c('a', 'b')"});
rio.e({command: "Sys.sleep(5); 11"})

See examples directory.

  • ex1: Getting started with evaluate api.
  • ex2: How to evaluate a filename and entrypoint.
  • ex3: How to evaluate a filename and host.
  • ex4: An example with utf-8 chars.
  • ex5: How to retrieve a plot.
  • ex6: How to call functions already loaded in R session.
  • ex7: An example with large data packet.


To install with npm:

npm install rio

Tested with Node.js 5.x and Rserve 1.7.3 (on Windows 10 64) with R 3.2.2.

Don't forget to start Rserve. For instance, from R console, after installing the package Rserve:


To shutdown the server from R console:

c <- RSconnect()


Evaluate a command, connecting to Rserve, executing the command and then disconnecting. The result is passed to the callback.

The defaults for the options parameter:

config = {
    command: "",
    filename: "",

    entrypoint: "",
    data: {},

    callback: function (err, res) {
        if (!err) {
        } else {
            console.log("Rserve call failed. " + err);

    host = "",
    port = "6311",
    path = undefined,

    user = "anon",
    password = "anon"
  • command OR filename OR entrypoint need to be filled. Otherwise it is missing the evaluation object.

  • if command AND filename AND entrypoint are empty then error. As above, said in different way.

  • command AND filename are exclusive: if both are not empty then error. Otherwise what does rio evaluate, command or filename?

  • if command AND filename are empty then entrypoint is mandatory. This is the case when rio evaluates a function defined on R side.

  • host AND path are exclusive. rio needs to choose beetween net socket or unix socket transport.

When filename is filled, rio loads the content of a R file, calling finally an entrypoint, passing data.

config = {
    filename: "foo.R",
    entrypoint: "main", // entrypoint is called
    data: { foo: "bar" } // data is stringified and passed to entrypoint

When entrypoint is filled, finally passing data, it is used when we need to call a function defined in Rserve instance.

config = {
    entrypoint: "echo",
    data: ["test", "data"],
    callback: printEcho

Sends the CMD_shutdown command to the Rserve server. Options are the same as for evaluate.

It enables debugging mode, printing the packet and logging messages on client side.

You may start also a Rserve instance in debugging mode with following commands (on Windows box with Git Bash Shell):

export R_PATH=/c/My/Programs/R
export PATH=$PATH:$R_PATH/bin/x64
$R_PATH/library/Rserve/libs/x64/Rserve_d.exe --

Set your paths accordingly.

It enables record mode, dumping the incoming data to a file specified in the options.

options = {
    fileName: "node-rio-dump.bin"

It is useful to record a Rserve session to replay it in an environment without Rserve (for example Travis CI). For instance,

> var rio=require("./index.js")
> rio.enableRecordMode(true, {fileName: "test/dump/integer-test.bin"});
> rio.evaluate({command: "as.integer(3)"})
> 3
(^C again to quit)

Then, you need to export the variable CI to emulate CI environment: export CI=true

Eventually npm test.

It enables playback mode, reading a dump file instead connecting to the server.

options = {
    fileName: "node-rio-dump.bin"


You can manually promisifying rio.evaluate with your preferred promise library:

var rio = require("rio");
rio.evaluateAsync = function(params) {
    return new Promise(function (resolve, reject) {
        var opts = params || {};
        opts.callback = function(err, result) {
            if (err) {
                return reject(err);
            return resolve(result);
        return rio.evaluate(params);

Then, for instance, in express, you can use it in a route:

return rio.evaluateAsync(
    .then(function (data) {
        return res.send(data.toString()); // or whatever
    }, function (e) {
        return res.sendStatus(500);

Thanks to @tamaracha to provide the snippet.


project  : node-rio
 repo age : 4 years, 4 months
 active   : 101 days
 commits  : 226
 files    : 49
 authors  :
   197  icebox                  87.2%
     8  Alberto Santini         3.5%
     7  Manuel Santillan        3.1%
     6  albertosantini          2.7%
     3  Karthik Madathil        1.3%
     2  Anand Patil             0.9%
     1  Alex Proca              0.4%
     1  Farrin Reid             0.4%
     1  Koichiro Sobue          0.4%