Golem JS Runtime

Golem JavaScript Runtime (QuickJS)

Both TypeScript and Scala (via Scala.js) Golem agents compile to JavaScript and run inside a QuickJS-based WebAssembly runtime provided by wasm-rquickjs.

Language Support

The runtime supports ES2020 including modules, async/await, async generators, Proxies, BigInt, WeakRef, FinalizationRegistry, and all standard built-ins (Array, Map, Set, Promise, RegExp, Date, JSON, Math, typed arrays, etc.).

Available Web Platform APIs

The following browser/web APIs are available out of the box — no imports needed:

• HTTP: fetch, Headers, Request, Response, FormData
• Files/Blobs: Blob, File
• URLs: URL, URLSearchParams
• Console: console
• Timers: setTimeout/clearTimeout, setInterval/clearInterval, setImmediate
• Abort: AbortController, AbortSignal
• Encoding: TextEncoder, TextDecoder, TextEncoderStream, TextDecoderStream
• Streams: ReadableStream, WritableStream, TransformStream
• Structured clone: structuredClone
• Crypto: crypto.randomUUID, crypto.getRandomValues
• Events: Event, EventTarget, CustomEvent
• Messaging: MessageChannel, MessagePort
• Errors: DOMException
• Internationalization: Intl (DateTimeFormat, NumberFormat, Collator, PluralRules)

Available Node.js Modules

These Node.js-compatible modules can be imported:

Stub Modules (Throw or No-op)

These modules exist for compatibility but will throw or no-op when used:

• node:child_process
• node:cluster
• node:http2
• node:inspector
• node:tls
• node:worker_threads

npm Package Compatibility

Additional npm packages can be installed with npm install (TypeScript) or added as Scala.js-compatible dependencies (Scala). Most packages targeting browsers or using the Node.js APIs listed above will work. Packages that depend on native C/C++ bindings or JVM-specific APIs will not work.

File I/O

Use node:fs or node:fs/promises for filesystem operations. This is the standard way to read/write files in both TypeScript and Scala agents.

TypeScript

import * as fs from 'node:fs';

// Synchronous
const content = fs.readFileSync('/data/config.json', 'utf-8');

// Async
import * as fsp from 'node:fs/promises';
const data = await fsp.readFile('/data/config.json', 'utf-8');

Scala (via Scala.js interop)

import scala.scalajs.js
import scala.scalajs.js.annotation.JSImport

@js.native
@JSImport("node:fs", JSImport.Namespace)
private object Fs extends js.Object {
  def readFileSync(path: String, encoding: String): String = js.native
  def writeFileSync(path: String, data: String): Unit = js.native
  def existsSync(path: String): Boolean = js.native
}

// Usage
val content = Fs.readFileSync("/data/config.json", "utf-8")

Important (Scala.js): WASI modules like node:fs are not available during the build-time pre-initialization (wizer) phase — they are only available at runtime. If you import node:fs at the top level of a Scala.js module, the import executes during pre-initialization and will fail. Use lazy initialization (lazy val) or defer the import to method bodies to ensure the module is loaded at runtime:

// ✅ CORRECT — lazy val defers initialization to first use at runtime
private lazy val fs: Fs.type = Fs

// ❌ WRONG — top-level val triggers import during pre-initialization
private val fs: Fs.type = Fs

Reference

Check the wasm-rquickjs README for the most up-to-date list of available APIs.

Looking up Golem SDK signatures

The full TypeScript type definitions for the Golem SDK live at:

node_modules/@golemcloud/golem-ts-sdk/dist/index.d.mts

Grep there (and in the dist/host/ and dist/lib/ subdirectories under the same package) when you need the exact signature of a helper such as withIdempotenceMode, atomically, withRetryPolicy, Duration, Predicate, Policy, NamedPolicy, etc. The shipped dist/index.mjs is a single-line minified bundle and is not a useful reference; always read the .d.mts instead.