@tootallnate/quickjs-emscripten 0.23.0: getQuickJS

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify @tootallnate/quickjs-emscripten.getQuickJS in pkg:npm/%40tootallnate/quickjs-emscripten@0.23.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/%40tootallnate/quickjs-emscripten@0.23.0
Demonstrate these symbols/APIs:
  - @tootallnate/quickjs-emscripten.getQuickJS
Constraints:
  - executionContext: node
Required runtime conditions:
  - ecosystem: npm
  - language: javascript
  - moduleSystem: cjs
  - packageManager: npm@10.9.8
  - runtime: node@22.23.2

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:c2c88e135bf7a3946d85c8deaf658cfde01d1c1823d4e3fef286f1dbe0d65c1f","constraints":{"executionContext":"node"},"contract":["getQuickJS returns a Promise that resolves to a QuickJSWASMModule instance","QuickJSWASMModule.evalCode evaluates JavaScript expressions and returns serialized primitive results","QuickJSWASMModule.newContext creates an isolated execution context capable of evaluating code","QuickJSContext.newFunction exposes host functions callable from within the guest VM","QuickJSContext.evalCode captures syntax and runtime exceptions in guest execution","QuickJSContext and value handles manage WebAssembly memory with explicit dispose","getQuickJS resolves to the same singleton instance on repeated calls"],"goal":"verify @tootallnate/quickjs-emscripten.getQuickJS in pkg:npm/%40tootallnate/quickjs-emscripten@0.23.0","kind":"HOW","packages":["pkg:npm/%40tootallnate/quickjs-emscripten@0.23.0"],"schemaVersion":1,"symbols":["@tootallnate/quickjs-emscripten.getQuickJS"]},"contractCommand":["node","test/contract.cjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","executionContext":"node","language":"javascript","libc":"glibc","libcVersion":"2.39","moduleSystem":"cjs","os":"linux","osVersionBucket":"24","packageManager":"npm","packageManagerVersion":"10.9.8","runtime":"node","runtimeVersion":"22.23.2","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/%40tootallnate/quickjs-emscripten@0.23.0"],"schemaVersion":1,"subject":"pkg:npm/%40tootallnate/quickjs-emscripten@0.23.0","symbols":["@tootallnate/quickjs-emscripten.getQuickJS"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-quickjs-emscripten-getquickjs",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-quickjs-emscripten-getquickjs",
      "version": "1.0.0",
      "dependencies": {
        "@tootallnate/quickjs-emscripten": "0.23.0"
      }
    },
    "node_modules/@tootallnate/quickjs-emscripten": {
      "version": "0.23.0",
      "resolved": "https://registry.npmjs.org/@tootallnate/quickjs-emscripten/-/quickjs-emscripten-0.23.0.tgz",
      "integrity": "sha512-C5Mc6rdnsaJDjO3UpGW/CQTHtCKaYlScZTly4JIu97Jxo/odCiH0ITnDXSJPTOrEKk/ycSZ0AOgTmkDtkOsvIA==",
      "license": "MIT"
    }
  }
}

{
  "name": "sample-quickjs-emscripten-getquickjs",
  "version": "1.0.0",
  "private": true,
  "dependencies": {
    "@tootallnate/quickjs-emscripten": "0.23.0"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify @tootallnate/quickjs-emscripten.getQuickJS in pkg:npm/%40tootallnate/quickjs-emscripten@0.23.0",
  "kind": "HOW",
  "packages": [
    "pkg:npm/%40tootallnate/quickjs-emscripten@0.23.0"
  ],
  "symbols": [
    "@tootallnate/quickjs-emscripten.getQuickJS"
  ],
  "constraints": {
    "executionContext": "node"
  },
  "runtimeConditions": {
    "ecosystem": "npm",
    "language": "javascript",
    "moduleSystem": "cjs",
    "packageManager": "npm@10.9.8",
    "runtime": "node@22.23.2"
  }
}

const assert = require('node:assert/strict');
const { getQuickJS, getQuickJSSync } = require('@tootallnate/quickjs-emscripten');

async function main() {
  // 1. getQuickJS returns a Promise that resolves to a QuickJSWASMModule instance
  const quickjs = await getQuickJS();
  assert.ok(quickjs);
  assert.equal(typeof quickjs.evalCode, 'function');
  assert.equal(typeof quickjs.newContext, 'function');
  assert.equal(typeof quickjs.newRuntime, 'function');

  // 2. QuickJSWASMModule.evalCode evaluates JavaScript expressions and returns serialized primitive results
  {
    const result = quickjs.evalCode('40 + 2');
    assert.equal(result, 42);

    const stringResult = quickjs.evalCode('`hello ${"world"}`');
    assert.equal(stringResult, 'hello world');

    const objResult = quickjs.evalCode('({ a: 1, b: [2, 3] })');
    assert.deepEqual(objResult, { a: 1, b: [2, 3] });
  }

  // 3. QuickJSWASMModule.newContext creates an isolated execution context capable of evaluating code
  {
    const vm = quickjs.newContext();
    const resultHandle = vm.evalCode('const x = 10; const y = 20; x * y;');
    assert.ok('value' in resultHandle);
    const value = vm.dump(resultHandle.value);
    assert.equal(value, 200);

    resultHandle.value.dispose();
    vm.dispose();
  }

  // 4. QuickJSContext.newFunction exposes host functions callable from within the guest VM
  {
    const vm = quickjs.newContext();
    let hostCalledWith = null;

    const fnHandle = vm.newFunction('sendToHost', (argHandle) => {
      hostCalledWith = vm.dump(argHandle);
      return vm.newNumber(hostCalledWith.length);
    });

    vm.setProp(vm.global, 'sendToHost', fnHandle);
    fnHandle.dispose();

    const callResult = vm.evalCode('sendToHost("codesamplex")');
    assert.ok('value' in callResult);
    const dumpedLen = vm.dump(callResult.value);
    assert.equal(dumpedLen, 11);
    assert.equal(hostCalledWith, 'codesamplex');

    callResult.value.dispose();
    vm.dispose();
  }

  // 5. QuickJSContext.evalCode captures syntax and runtime exceptions in guest execution
  {
    const vm = quickjs.newContext();

    const errResult = vm.evalCode('throw new TypeError("custom error message");');
    assert.ok('error' in errResult);
    const dumpedErr = vm.dump(errResult.error);
    assert.equal(typeof dumpedErr, 'object');
    assert.equal(dumpedErr.name, 'TypeError');
    assert.equal(dumpedErr.message, 'custom error message');

    errResult.error.dispose();
    vm.dispose();
  }

  // 6. QuickJSContext and value handles manage WebAssembly memory with explicit dispose
  {
    const vm = quickjs.newContext();
    const strHandle = vm.newString('disposable string');
    assert.equal(strHandle.alive, true);
    assert.equal(vm.alive, true);

    strHandle.dispose();
    assert.equal(strHandle.alive, false);

    vm.dispose();
    assert.equal(vm.alive, false);
  }

  // 7. getQuickJS resolves to the same singleton instance on repeated calls
  {
    const secondCall = await getQuickJS();
    assert.strictEqual(quickjs, secondCall);

    const syncInstance = getQuickJSSync();
    assert.strictEqual(quickjs, syncInstance);
  }
}

main().catch((err) => {
  console.error(err);
  process.exit(1);
});