tmelliott/rserve-ts

rserve-ts: Typescript wrapper for rserve library

This is a typescript wrapper for the rserve library. The goal is to provide modern async API alternatives with typescript support (via zod).

The package wraps the main connection function and allows users to evaluate arbitrary R code on the server. This will be extended to full OCAP support.

Installation

npm install rserve-ts

Usage

You need to have an Rserve server running for the following to work.

import RserveClient from "rserve-ts";

(async () => {
  const R = await RserveClient.create({
    host: "http://127.0.0.1:8081",
  });

  const rversion = await R.eval("R.version.string", R.character());
  console.log("Connected to ", rversion);
})();

OCAP mode

In OCAP mode, only pre-defined functions can be called. This is useful for restricting the R code that can be executed on the server, or for developing applications.

Zod is used to define function schemas, with additional R types defined.

# ocap.R
library(Rserve)
oc.init <- function() {
  ocap(function() {
    list(
      # Ocaps are functions that javascript can call
      add <- ocap(function(a, b) {
        a + b
      }),
      dist <- ocap(function(which = c('normal', 'uniform')) {
        # Ocaps can return new ocaps, too!
        # This could be useful for progressively revealing functionality, etc.
        switch(which,
          normal = list(sample = ocap(function(n) rnorm(n))),
          uniform = list(sample = ocap(function(n) runif(n)))
        )
      })
    )
  })
}

// ocap.ts
import { function, number, list, ocap } from "rserve-ts/types";

export const appFuns = {
  add: ocap([z.number(), z.number()], number()),
  dist: ocap([z.enum(["normal", "uniform"])], list({
    sample: ocap([z.number()], numeric()),
  })),
};

import { RserveClient } from "rserve-ts";
import { appFuns } from "./ocap";

(async () => {
  const R = await RserveClient.create({
    host: "http://127.0.0.1:8081",
  });

  const app = await R.ocap(appFuns);

  const { data: sum } = await app.add(1, 2);
  console.log("1 + 2 = ", sum);

  const { data: chosenDist } = await app.dist("normal");
  const { data: sample } = await chosenDist.sample(5);
  console.log("Normal sample: ", sample);
})();

rserve-ts's Issues

Export types as a submodule

Make it easier to import just the value types, so scripts can use e.g.,

import { numeric } from "rserve-ts/types";
import type { Character } from "rserve-ts/types";

Refactor types as classes

Rather than using complex generic types, refactor types/index.ts to use classes that can more easily be extended and built up on.

e.g.,

const c = character()
  .length(2);

const f = factor()
  .length(100)
  .levels('one', 'two', 'three');

const l = list({x = c, y = f))
  .class('myobj');