SDK JavaScript: call Touba

Same program, inputs and results as the other SDK. No model, handler or external service is needed.

1. Install the SDK

From an empty application directory:

Terminal

touba sdk install javascript

Node.js 24 and npm are required.

2. Declare the Touba program

This program returns a typed value. It is identical in both SDK tutorials.

program.tb

module sdk.engine
strategy Review
    takes value as Text
    gives Text
    do
        give value

3. Import and run

run.mjs

import assert from "node:assert/strict";
import { ToubaEngine } from "@touba/sdk";

const engine = new ToubaEngine({ projectRoot: "." });
const run = await engine.run({ source: "program.tb", inputs: { value: "Invoice 42" } });
assert.equal(run.status, "success");
assert.equal(run.result, "Invoice 42");
console.log(run.result);

Run node run.mjs; expected result: Invoice 42.

4. Compile and reuse AIR

Use this alternative entry point to compile once and pass the AIR to the same engine:

compiled.mjs

import assert from "node:assert/strict";
import { ToubaEngine } from "@touba/sdk";

const engine = new ToubaEngine({ projectRoot: "." });
const compiled = await engine.compile({ source: "program.tb" });
for (const airJson of [compiled.airJson, compiled.airDocument]) {
  const run = await engine.run({ airJson, inputs: { value: "Invoice 42" } });
  assert.equal(run.status, "success");
  assert.equal(run.result, "Invoice 42");
}
console.log("Invoice 42");

Run node compiled.mjs. Same result; the Core retains all checks.

5. Check results and errors

An incorrect input type must cause refusal, not silent success:

refused.mjs

import assert from "node:assert/strict";
import { ToubaEngine, ToubaEngineError } from "@touba/sdk";

const engine = new ToubaEngine({ projectRoot: "." });
await assert.rejects(
  () => engine.run({ source: "program.tb", inputs: { value: 42 } }),
  (error) => error instanceof ToubaEngineError && error.phase === "run" && error.details.status === "failure",
);
console.log("refused");

Run node refused.mjs. Human waits and explicit stops instead remain controlled outcomes with status and reason; do not treat them as technical errors.

Validate the full example

Terminal

node run.mjs
node compiled.mjs
node refused.mjs

6. Continue with handlers

Continue with the handlers tutorial JavaScript to run host business code. The SDK JavaScript documents options, resumes, testing and limits. Compare the same path with the SDK Python.