@robinbraemer/llrt

TypeScript-friendly Node bindings for AWS LLRT.

This package exposes LLRT as an embedded runtime through a napi-rs native addon. The public API is intentionally small while the proof of concept hardens.

npm install @robinbraemer/llrt

Usage

LlrtRuntime.callJson() runs an async JavaScript function in a fresh LLRT VM and returns a typed result envelope instead of throwing for guest failures:

import { LlrtRuntime } from "@robinbraemer/llrt";

const runtime = new LlrtRuntime({ memoryMB: 64, wallTimeMs: 1000 });

const result = await runtime.callJson<{ name: string }, { greeting: string }>(
  `async ({ input }) => ({ greeting: "Hello " + input.name })`,
  { name: "Ada" },
);

The boundary is JSON-safe:

• the input value must serialize to JSON;
• the guest return value is serialized back through JSON;
• Host functions are explicit async functions passed per call through functions;
• each call creates a fresh LLRT VM, so guest globals do not persist across calls.

Resource controls can be set on the runtime or per call:

const runtime = new LlrtRuntime({
  memoryMB: 64,
  wallTimeMs: 1000,
  maxStackBytes: 512 * 1024,
});

const result = await runtime.callJson(
  `async ({ input, host }) => host.echo(input)`,
  { ok: true },
  {
    memoryMB: 32,
    wallTimeMs: 500,
    functions: {
      echo: async (value) => value,
    },
  },
);

The package reports TIMEOUT, MEMORY_LIMIT, SERIALIZATION_ERROR, EVALUATION_ERROR, NATIVE_LOAD_ERROR, RUNTIME_DISPOSED, and UNSUPPORTED as typed error codes.

Runtime Support

Supported Node version:

• Node.js 24

Supported native targets:

• aarch64-apple-darwin
• x86_64-apple-darwin
• x86_64-unknown-linux-gnu
• aarch64-unknown-linux-gnu

Unsupported runtimes:

• Bun
• Cloudflare Workers
• browser environments

This package is a Node native addon and does not guarantee support in non-Node JavaScript runtimes.

Safety Boundaries

Guest code does not receive Node.js compatibility APIs by default. The runtime does not expose filesystem, process, require, or fetch unless a caller deliberately provides equivalent behavior through Host functions.

The isolation model is intentionally simple: every callJson() invocation uses a fresh LLRT VM with its own memory and wall-time limits. This is slower than a reused VM could be, but it avoids cross-call global state leaks and keeps resource limits scoped to one execution.

Native Packages

The main package ships JavaScript and TypeScript declarations. Platform-specific native binaries are published as optional packages generated by napi-rs:

• @robinbraemer/llrt-darwin-arm64
• @robinbraemer/llrt-darwin-x64
• @robinbraemer/llrt-linux-x64-gnu
• @robinbraemer/llrt-linux-arm64-gnu

For local development, build the native addon with:

pnpm --filter @robinbraemer/llrt run dev:native

Release preparation uses the napi-rs package layout:

pnpm --filter @robinbraemer/llrt run create:native-packages
pnpm --filter @robinbraemer/llrt run prepare:llrt-source
LLRT_TARGET=aarch64-apple-darwin pnpm --filter @robinbraemer/llrt run build:native:target
pnpm --filter @robinbraemer/llrt run collect:native-artifacts
pnpm --filter @robinbraemer/llrt run smoke:packed-install
pnpm --filter @robinbraemer/llrt run prepublish:native-packages:dry-run
pnpm --filter @robinbraemer/llrt run prepare:native-publish