Introducing the API

The JavaScript client library is a light-weight fluent API used to communcate with DeployR from both the browser and Node.js environments. It is crafted for flexibility, readability, and a low learning curve.

For additional information review the User guide. It provides an introduction and comprehensive overview for the main areas of the API. It also introduces features and walks you through what you'll need to know in order to obtain the most out of the DeployR JavaScript client library.

Global Object `deployr`

The deployr global namespace object. This is the public interface for all DeployR Request instances. All things start here.

auth (username, password) static

Convenience function to sign the user in by authenticating the credentials with the DeployR server.

Example:

deployr.auth('testuser', 'secret');

This call is equivalent to:

deployr.io('/r/user/login')
  .data({ username: 'testuser', password: 'secret' })
  .end();

Parameters:

username String Specifies the username
password String Specifies the password

Returns: DeployR

A new /r/user/login request transaction.

configure (config) chainable static

Represents a static method for configuring all DeployR requests. Settings made here are applied globally across every request.

Parameters:

[config] Object The object literal configuration hash. The complete list of supported configuration properties accepted:
- host String The location of the DeployR server including the port. This is required for Node.js environments and is (optional) for the Browser which will fallback to the domain that served up the page. Example: { host: 'http://dhost:8000' }.
- cors Boolean optional If true Cross-origin resource sharing (CORS) withCredentials will be enabled. See the CORS section for instruction on how to enable for the DeployR server.
- logging Boolean optional Turn logging on or off. true for on, false for off.
- [events] Object optional The object literal hash defining global events from request lifecycle moments to specific errors. See the events section for a complete list of supported events.
Example:
```
deployr.configure( {
   host: 'http://dhost:8000',
   cors: true,
   logging: true,
   events: {
      error: function(code, res, api) {
         // Generic errors
      }, 

      409: function(res, api) {
         // 409 errors
      }
   }
});
```

Returns: this

The refrence to deployr on which the method is being called.

io (api) static

Factory for creating new IO requests to DeployR.

Example:

var request = deployr.io('/r/user/about');

Parameters:

api String One of the supported DeployR APIs:

Returns: DeployR

A new DeployR request transaction.

pipeline (tasks) static

Run an series of chained DeployR requests in sequence and without overlap.

Example:

function firstTask() {
    return deployr.io('/r/user/login')
             .delay()
             .data({ username: 'testuser', password: 'secret' })    
             .end()             
             .io('/r/project/create')
             .end();
}

function secondTask() {
    return deployr.io('/r/user/about')
             .delay()
             .end()
             .io('/r/user/logout')
             .end();
}

deployr.pipeline([ firstTask(), secondTask() ]);

Parameters:

tasks Array Specifies the list of Function tasks.

Returns: Promise

A promise wrapping the resolution of either "resolve" or "reject" callback.

RInput - property static

Defines the factory for creating a DeployR-specific encoded R object to be sent as input parameters to an R script.

Example:

var rinput = deployr.RInput.logical('logical_name', true);

var rinput = deployr.RInput.numeric('numeric_name', 10.5);

var rinput = deployr.RInput.integer('integer_name', 5);

var rinput = deployr.RInput.character('character_name', 'Hello');

// ect...

script (...) static

Script execution convenience function for:

/r/repository/script/execute

From:

 deployr.io('/r/repository/script/execute')
   .data({ filename: 'script.R', author: 'testuser', directory: 'root' })
   .end();

To:

 deployr.script('/testuser/root/script.R').end();

/r/project/execute/script

From:

 var project = 'PROJECT-5ac47aff-8f8c-4ac2-8a8f-6e31468e6a19';

 deployr.io('/r/project/execute/script')
   .data({ 
    filename: 'script.R', 
    author: 'testuser', 
    directory: 'root',
    project: project
   })
   .end();

To:

 var project = 'PROJECT-5ac47aff-8f8c-4ac2-8a8f-6e31468e6a19';

 deployr.script('/testuser/root/script.R', project).end();

Parameters:

... Arguments to define the fully qualified script for execution. Possible signatures:

The fully qualified script: /author/directory/filename and (optional) project for executing external scripts on the R session:
```
deployr.script('/testuser/root/script.R', project).end();
```
The fully qualified script: filename, directory, author and (optional) project for executing external scripts on the R session:
```
deployr.script('script.R', 'testuser', 'root', project).end();
```

The fully qualified script as an object hash:

deployr.script({ 
  filename: 'script.R', 
  author: 'testuser', 
  directory: 'root', 
  project: 'project' // (optional) for executing external scripts on the R session
}).end();

Returns: DeployR

A new /r/repository/script/execute or /r/project/execute/script request transaction.

Request

The Request class is a utility that brokers HTTP requests through a simplified fluid interface to DeployR.

abort () chainable

Aborts the specific transaction.

Returns: DeployR

The refrence to this request on which the method is being called.

attach (file, filename) chainable

Attaches a file to be uploaded.

Example:

Parameters:

file {File|Blob|path} The file to be attached for an upload. For Browser environments the HTML5 File|Blob is used. For the Node.js environment, a file path is accepted.
filename String optional The name of the file to be uploaded. This name does not have to match the actual source filename.

Returns: DeployR

The refrence to this request on which the method is being called.

data (params) chainable

Defines the request data being sent to a DeployR API. The supported parameters depend on the API being called:

For example, using the /r/user/login API we can identify the supported parameters and construct a call as such:

deployr.io('/r/user/login')
  .data( { username: 'testuser', password: 'secret' })
  .end();

Important

The DeployR parameters: format, inputs, outputs are reserved paramters. As a result they should never be included as one of the .data() parameters.

Parameters:

params Object The object literal hash of data to be sent.

Returns: DeployR

The refrence to this request on which the method is being called.

[object Object] () undefined

Nulls internal references and removes any event listeners.

end (λ) chainable

Indicates that the request is ready to be sent to DeployR. It is important to note that if the .end() method is never called the request will not be sent.

Example:

deployr.io('/r/user/about')
  .end(function(res, chain) {
     console.log(res.get('user'));
  });

Parameters:

λ Function optional The callback function. Supplies two arguments:
- res Object The DeployR JSON response.
- chain Array The response chain of all the previous successful responses. This value can be null if there were no previous requests.

Returns: DeployR

The refrence to this request on which the method is being called.

ensure (λ) chainable

Acts as a finally statement allowing you to execute "cleanup" type tasks in a request chain. It arranges for cleanup to be called, with no arguments, when the DeployR request chain is either completely fulfilled or rejected.

Example:

deployr.io('/r/user/login')
  .data({ username: 'testuser' , password: 'secret' }) 
  .end()
  .ensure(function() {
    console.log('cleanup...'); 
  });

Parameters:

λ Function The callback function.

Returns: Promise

A promise wrapping the resolution of either "resolve" or "reject" callback.

error (λ) chainable

The general failure callback. If called, all DeployR errors for this transaction will be returned here when raised.

Parameters:

λ Function The error callback function. Supplies one argument:
- err Object The DeployR JSON error reponse.

Returns: DeployR

The refrence to this request on which the method is being called.

io (api) chainable

Add an additional IO request to the exsisting sequential request chain.

Example:

deployr.io('/r/user/about')
   .end()
   .io('/r/user/logout')
   .end();

Parameters:

api String One of the supported DeployR APIs:

Returns: DeployR

The refrence to this request on which the method is being called.

log () chainable

Turn logging on for the specific transaction.

Returns: DeployR

The refrence to this request on which the method is being called.

on (event, λ) chainable

Adds a listener for the specified event on this request.

Parameters:

event String The event name.
λ FunctionThe callback function.

Returns: DeployR

The refrence to this request on which the method is being called.

pipe (stream) chainable Node.js

Stream the DeployR response into the pipe. It is important to note that if the .pipe() method is never called the request will not be sent.

The .pipe() method should be be used as an alternative to .end() and never along side of it. .pipe() and .end() are an either-or.

Note This is a chainable method for piping streams and can not be used as a chain with .io() requests.

Parameters:

stream: A destination Stream.

Returns:

Stream: The passed in destination stream to be used for additional piping.

release (projects) static

Release any residual project resources associated with the application instance whenever a client application terminates. This includes closing any supplied projects down and logging out.

Example:

var ruser = deployr.auth('testuser', 'secret');

// ...

var projects = [ 'PROJECT-5ac47aff-8f8c', 'PROJECT-1zkl466qii-1z4w' ];

// ...

ruser.release(projects);

Parameters:

projects String|Array optional
The project or list of projects to close.

Returns: Promise

A promise wrapping the resolution of either "resolve" or "reject" callback.

rinput (rinput) chainable

Used to pass a single input from JavaScript to an R script using one of the defined RInput factories.

Example:

var RIn    = deployr.RInput; // alias
var rinput = RIn.character('reduce', 'left');

deployr.io('/r/repository/script/execute')   
   .data({ filename: 'accumulate.R', author: 'testuser' })
   .rinput(rinput)
   .end(function(res) {
      // handle successful response
   });

Parameters:

rinput RInput The DeployR-specific encoded R object data for use on an API call.

Returns: DeployR

The refrence to this request on which the method is being called.

rinputs (rinputs) chainable

Used to pass multiple inputs at once from JavaScript to an R script using one of the defined RInput factories.

Example:

var RIn     = deployr.RInput; // alias
var rinputs = [];

rinputs.push( RIn.character('reduce', 'left') );
rinputs.push( RIn.character('fold', 'left') );
rinputs.push( RIn.character('scan', 'left') );

deployr.io('/r/repository/script/execute')   
   .data({ filename: 'accumulate.R', author: 'testuser' })
   .rinputs(rinputs)
   .end(function(res) {
      // handle successful response
   });

Parameters:

rinputs Array The RInput list of DeployR-specific encoded R object data for use on an API call.

Returns: DeployR

The refrence to this request on which the method is being called.

routput (robject) chainable

Defines the name of the R object that will be returned as a DeployR-encoded R object on the response markup.

Parameters:

robject String The name of the R object that will be returned.

JavaScript:

 deployr.script('/testuser/root/script.R')
   .routput('max')
   .end(function(res) {
      console.log(res.workspace('max').value); // prints 500
   });

#######################
# File: script.R
#######################

max<-500

Returns: DeployR

The refrence to this request on which the method is being called.

routputs (robjects) chainable

A convenience alternative to multiple .rinput() calls. Defines a name list of R objects that will be returned as DeployR-encoded R objects on the response markup.

Calling this method .routputs([ ... ]) is equivalent to invoking multiple .routput(...) calls.

JavaScript:

 deployr.script('/testuser/root/script.R')
   .routputs([ 'min', 'max', 'mean' ])
   .end(function(res) {
      console.log(res.workspace('min').value);  // prints 400
      console.log(res.workspace('max').value);  // prints 500
      console.log(res.workspace('mean').value); // prints 600
   });

#######################
# File: script.R
#######################

min<-400
max<-500
mean<-600

Parameters:

robject Array A name list of R objects that will be returned.

Returns: DeployR

The refrence to this request on which the method is being called.

script (...) chainable

Convenience function for adding an additional script execution to the exsisting sequential request chain.

See deployr.script(...)

Example:

 deployr.script('/testuser/root/left.R')
   .end()
   .script('/testuser/root/right.R')
   .end()
   .script('/testuser/root/scan.R')
   .end();

Parameters:

... Arguments to define the fully qualified script for execution. See deployr.script

Returns: DeployR

The refrence to this request on which the method is being called.

stream (options) chainable Node.js

Supported only in Node.js, this method works in conjunction with the attach method to indicate that the file should be read in as a readable stream during a file upload.

Parameters:

options: Object optional The Readable Stream options:

{ flags: 'r',
  encoding: null,
  fd: null,
  mode: 0666,
  autoClose: true
}

Returns: DeployR

The refrence to this request on which the method is being called.

timeout (ms) chainable

This value, defined in milliseconds, is a time threshold for the transaction. When this limit is reached, and the transaction has not yet completed, the transaction will be aborted.

Parameters:

ms: Number The threshold duration in milliseconds.

Returns: DeployR

The refrence to this request on which the method is being called.

R Data Types

DeployR-specific encodings are used to encode R object data for use on the API. Encoded object data can be sent to the server as parameter values on the following calls:

To pass values from JavaScript as input to an R script you use one of the defined factory methods in the first column:

deployr.RInput	JavaScript	R Object	R Class
.logical()	Boolean	primitive	logical
.numeric()	Number	primitive	integer
.integer()	Number	primative	numeric
.character()	String	primitive	character
.date()	Date	date	Date
.posix()	Date	date	POSIXct
.list()	Array [RInput]	list	list
.dataframe()	Array [RInput]	dataframe	data.frame
.factor()	Array	factor	factor
.ordered()	Array	factor	ordered factor
.logicalVector()	Array [Boolean]	primative(s)	vector
.numericVector()	Array [Number]	primitive(s)	vector
.integerVector()	Array [Number]	primitive(s)	vector
.characterVector()	Array [String]	primative(s)	vector
.dateVector()	Array [Date]	date(s)	vector
.posixVector()	Array [Date]	date(s)	vector
.numericMatrix	Array [[Numeric]]	primative(s)	matrix
.integerMatrix()	Array [[Numeric]]	primative(s)	matrix
.logicalMatrix()	Array [[Boolean]]	primative(s)	matrix
.characterMatrix()	Array [[String]]	primative(s)	matrix

There are two ways to build an input to a R Script depending on need:

Using deployr.RInput factory.

var rinputs = [];

rinputs.push(deployr.RInput.logical('logical_name', true));
rinputs.push(deployr.RInput.numeric('numeric_name', 10.5));
rinputs.push(deployr.RInput.integer('integer_name', 5));
rinputs.push(deployr.RInput.character('character_name', 'Hello'));

// ect...

deployr.io('/r/repository/script/execute')
   .data({ filename: 'script.R', author: 'testuser' })
   .rinputs(rinputs)
   .end();

Inlined through the individual DeployR request transaction.

deployr.io('/r/repository/script/execute')
  .data({ filename: 'script.R', author: 'testuser' })
  .logical('logical_name', true)
  .numeric('numeric_name', 10.5)
  .integer('integer_name', 5)
  .character('character_name', 'Hello')
  .end();

character (name, value) chainable

The DeployR-specific encoding for a R character value.

Parameters:

name String The name of the encoded object.
value String The data encapsulated by the encoded object.

Returns: DeployR

The refrence to this request on which the method is being called.

characterMatrix (name, value) chainable

The DeployR-specific encoding for a R character matrix value.

Example:

var RIn    = deployr.RInput; // alias
var matrix = [ [ RIn.character('cname', 'Hello') ] ];

.characterMatrix('name', matrix)

Parameters:

name String The name of the encoded object.
value Array The data encapsulated by the encoded object.

Returns: DeployR

The refrence to this request on which the method is being called.

characterVector (name, value) chainable

The DeployR-specific encoding for a R character vector value.

Example:

var RIn    = deployr.RInput; // alias
var vector = [ RIn.character('cname', 'Hello') ];

.characterVector('name', vector)

Parameters:

name String The name of the encoded object.
value Array The data encapsulated by the encoded object.

Returns: DeployR

The refrence to this request on which the method is being called.

dataframe (name, value) chainable

The DeployR-specific encoding for a R data.frame value.

Example:

var RIn   = deployr.RInput; // alias
var rnval = [ RInput.numeric('nname', 1.0) ];
var df    = [ RInput.numericVector('nvname', rnvval) ];

.dataframe('name', df)

Parameters:

name String The name of the encoded object.
value Array The data encapsulated by the encoded object.

Returns: DeployR

The refrence to this request on which the method is being called.

date (name, value) chainable

The DeployR-specific encoding for a R date value.

Example:

.date('name', new Date())

Parameters:

name String The name of the encoded object.
value Date The data encapsulated by the encoded object.

Returns: DeployR

The refrence to this request on which the method is being called.

dateVector (name, value) chainable

The DeployR-specific encoding for a R date vector value.

Example:

var RIn    = deployr.RInput; // alias
var vector = [ RIn.date('dname', new Date()) ];

.dateVector('name', vector)

Parameters:

name String The name of the encoded object.
value Array The data encapsulated by the encoded object.

Returns: DeployR

The refrence to this request on which the method is being called.

factor (name, value, levels, labels) chainable

The DeployR-specific encoding for a R factor value.

Example:

var value   = [ 1, 2, 3 ];
var levels  = [ 1, 2, 3 ];
var labels  = [ 'red', 'blue', 'green' ];

.factor('name', value, levels, labels);

Parameters:

name String The name of the encoded object.
value Array The data encapsulated by the encoded object.
levels Array The value levels.
labels Array The value labels.

Returns: DeployR

The refrence to this request on which the method is being called.

integer (name, value) chainable

The DeployR-specific encoding for a R integer value.

Parameters:

name String The name of the encoded object.
value Number The data encapsulated by the encoded object.

Returns: DeployR

The refrence to this request on which the method is being called.

integerMatrix (name, value) chainable

The DeployR-specific encoding for a R integer matrix value.

Example:

var RIn    = deployr.RInput; // alias
var matrix = [ [ RIn.integer('iname', 5) ] ];

.integerMatrix('name', matrix)

Parameters:

name String The name of the encoded object.
value Array The data encapsulated by the encoded object.

Returns: DeployR

The refrence to this request on which the method is being called.

integerVector (name, value) chainable

The DeployR-specific encoding for a R integer vector value.

Example:

var RIn    = deployr.RInput; // alias
var vector = [ RIn.integer('iname', 5) ];

.integerVector('name', vector)

Parameters:

name String The name of the encoded object.
value Array The data encapsulated by the encoded object.

Returns: DeployR

The refrence to this request on which the method is being called.

list (name, value) chainable

The DeployR-specific encoding for a R list value.

Example:

var RIn   = deployr.RInput; // alias
var list  = [ RInput.character('cname', 'Hello'), RInput.numeric('iname', 1.0) ];

.list('name', list)

Parameters:

name String The name of the encoded object.
value Array The data encapsulated by the encoded object.

Returns: DeployR

The refrence to this request on which the method is being called.

logical (name, value) chainable

The DeployR-specific encoding for a R logical value.

Parameters:

name String The name of the encoded object.
value Boolean The data encapsulated by the encoded object.

Returns: DeployR

The refrence to this request on which the method is being called.

logicalMatrix (name, value) chainable

The DeployR-specific encoding for a R logical matrix value.

Example:

var RIn    = deployr.RInput; // alias
var matrix = [ [ RIn.logical('lname', true) ] ];

.logicalMatrix('name', matrix)

Parameters:

name String The name of the encoded object.
value Array The data encapsulated by the encoded object.

Returns: DeployR

The refrence to this request on which the method is being called.

logicalVector (name, value) chainable

The DeployR-specific encoding for a R logical vector value.

Example:

var RIn    = deployr.RInput; // alias
var vector = [ RIn.logical('lname', true) ];

.logicalVector('name', vector)

Parameters:

name String The name of the encoded object.
value Array The data encapsulated by the encoded object.

Returns: DeployR

The refrence to this request on which the method is being called.

numeric (name, value) chainable

The DeployR-specific encoding for a R numeric value.

Parameters:

name String The name of the encoded object.
value Number The data encapsulated by the encoded object.

Returns: DeployR

The refrence to this request on which the method is being called.

numericMatrix (name, value) chainable

The DeployR-specific encoding for a R numeric matrix value.

Example:

var RIn    = deployr.RInput; // alias
var matrix = [ [ RIn.numeric('nname', 3.14) ] ];

.numericMatrix('name', matrix)

Parameters:

name String The name of the encoded object.
value Array The data encapsulated by the encoded object.

Returns: DeployR

The refrence to this request on which the method is being called.

numericVector (name, value) chainable

The DeployR-specific encoding for a R numeric vector value.

Example:

var RIn    = deployr.RInput; // alias
var vector = [ RIn.numeric('nname', 3.14) ];

.numericVector('name', vector)

Parameters:

name String The name of the encoded object.
value Array The data encapsulated by the encoded object.

Returns: DeployR

The refrence to this request on which the method is being called.

ordered (name, value, levels, labels) chainable

The DeployR-specific encoding for a R ordered factor value.

Example:

var value   = [ 1, 2, 3 ];
var levels  = [ 1, 2, 3 ];
var labels  = [ 'red', 'blue', 'green' ];

.ordered('name', value, levels, labels);

Parameters:

name String The name of the encoded object.
value Array The data encapsulated by the encoded object.
levels Array The value levels.
labels Array The value labels.

Returns: DeployR

The refrence to this request on which the method is being called.

posix (name, value) chainable

The DeployR-specific encoding for a R POSIXct value.

Example:

.posix('name', new Date())

Parameters:

name String The name of the encoded object.
value Date The data encapsulated by the encoded object.

Returns: DeployR

The refrence to this request on which the method is being called.

posixVector (name, value) chainable

The DeployR-specific encoding for a R POSIXct vector value.

Example:

var RIn    = deployr.RInput; // alias
var vector = [ RIn.posix('pxname', new Date()) ];

.posixVector('name', vector)

Parameters:

name String The name of the encoded object.
value Array The data encapsulated by the encoded object.

Returns: DeployR

The refrence to this request on which the method is being called.

JavaScript API

Introducing the API

Global Object deployr

Request

R Data Types

Global Object `deployr`