TypeScript SDK Reference

The TypeScript SDK is a thin N-API wrapper around the Rust SDK. TypeScript code gets an idiomatic async API with camelCase fields while rototo keeps workspace loading, linting, refresh, and resolution behavior in the Rust core.

Install

rototo is currently published as an alpha package for Node.js 20 and newer:

npm install rototo@alpha

The package includes native modules for Linux, macOS, and Windows on the supported x64 and arm64 targets. The rototo release version stays SemVer, for example 0.1.0-alpha.4.

Load A Workspace

import { Workspace } from "rototo";

const workspace = await Workspace.load("examples/basic");

Workspace.load accepts the same source strings as the CLI. It lints the workspace and rejects lint failures before returning.

Resolve A Variable

const resolution = await workspace.resolveVariable(
  "premium-message",
  { user: { tier: "premium" } },
);

console.log(resolution.valueKey);
console.log(resolution.value);

VariableResolution has:

Resolve A Qualifier

const resolution = await workspace.resolveQualifier(
  "premium-users",
  { user: { tier: "premium" } },
);

console.log(resolution.value);

QualifierResolution has id and value.

Context Validation

Resolution validates context against schemas/context.schema.json by default. Skip validation for one call when a tool needs to evaluate partial context:

const resolution = await workspace.resolveVariable(
  "premium-message",
  context,
  { validateContext: false },
);

The context still must be a JSON object.

Inspect And Lint

const workspace = await Workspace.inspect("examples/basic");
const lint = await workspace.lint();

Inspection is for tools. A workspace loaded through inspect cannot resolve variables or qualifiers because it does not compile the runtime model.

Refreshing Workspace

import { RefreshingWorkspace } from "rototo";

const workspace = await RefreshingWorkspace.load(source, {
  periodSeconds: 30,
});

const resolution = await workspace.resolveVariable("premium-message", context);
const status = await workspace.status();
await workspace.shutdown();

RefreshingWorkspace keeps serving the last successfully loaded workspace when refresh fails. status returns a RefreshStatus object with fingerprint, success, attempt, failure, error, refreshing, and immutable fields.

Errors

Rust RototoError values become RototoError in TypeScript:

import { RototoError } from "rototo";

try {
  await workspace.resolveVariable("missing", {});
} catch (error) {
  if (error instanceof RototoError) {
    console.log(error.message);
  }
}

Public Types