@tootallnate/quickjs-emscripten 0.23.0

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 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

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:c547eed3b2d585ee5233c06f1f25c5eb76ddc7f88d896349b2d73d8d92c46201","contract":["getQuickJS initializes and resolves a QuickJSWASMModule singleton instance","evalCode evaluates Javascript expressions inside QuickJS WASM module and returns native results","newContext creates an isolated QuickJS context capable of executing code and setting global functions","evalCode interrupts execution and throws InternalError when interrupted by shouldInterruptAfterDeadline","getQuickJSSync returns the initialized QuickJSWASMModule synchronously after getQuickJS resolves"],"goal":"verify pkg:npm/%40tootallnate/quickjs-emscripten@0.23.0","kind":"HOW","packages":["pkg:npm/%40tootallnate/quickjs-emscripten@0.23.0"],"schemaVersion":1},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"npm","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","verifierAdapter":"node-typescript@1"}

import {
  getQuickJS,
  getQuickJSSync,
  shouldInterruptAfterDeadline
} from '@tootallnate/quickjs-emscripten';

/**
 * Initializes and retrieves the shared QuickJS WebAssembly module singleton.
 * @returns {Promise<import('@tootallnate/quickjs-emscripten').QuickJSWASMModule>}
 */
export async function getQuickJSInstance() {
  return await getQuickJS();
}

/**
 * Returns the shared QuickJS WebAssembly module singleton synchronously.
 * Note: Must be called after getQuickJS() has resolved at least once.
 * @returns {import('@tootallnate/quickjs-emscripten').QuickJSWASMModule}
 */
export function getQuickJSSyncInstance() {
  return getQuickJSSync();
}

/**
 * Evaluates JavaScript source code in a one-off QuickJS environment and returns the native result.
 * @param {string} code - JavaScript code to evaluate.
 * @param {import('@tootallnate/quickjs-emscripten').ModuleEvalOptions} [options] - Evaluation options.
 * @returns {Promise<unknown>} The evaluated result converted to native JS value.
 */
export async function evaluateExpression(code, options) {
  const QuickJS = await getQuickJS();
  return QuickJS.evalCode(code, options);
}

/**
 * Creates an isolated QuickJS context for advanced object manipulation and function binding.
 * @returns {Promise<import('@tootallnate/quickjs-emscripten').QuickJSContext>}
 */
export async function createIsolatedContext() {
  const QuickJS = await getQuickJS();
  return QuickJS.newContext();
}

/**
 * Evaluates JavaScript code with a strict execution deadline to prevent infinite loops.
 * @param {string} code - JavaScript code to evaluate.
 * @param {number} timeoutMs - Timeout deadline in milliseconds.
 * @returns {Promise<unknown>}
 */
export async function evaluateWithDeadline(code, timeoutMs = 100) {
  const QuickJS = await getQuickJS();
  const deadline = Date.now() + timeoutMs;
  return QuickJS.evalCode(code, {
    shouldInterrupt: shouldInterruptAfterDeadline(deadline)
  });
}

export { getQuickJS, getQuickJSSync, shouldInterruptAfterDeadline };

{
  "name": "sample-quickjs-emscripten-verify",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-quickjs-emscripten-verify",
      "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-verify",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "dependencies": {
    "@tootallnate/quickjs-emscripten": "0.23.0"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify pkg:npm/%40tootallnate/quickjs-emscripten@0.23.0",
  "kind": "HOW",
  "packages": [
    "pkg:npm/%40tootallnate/quickjs-emscripten@0.23.0"
  ]
}

import assert from 'node:assert/strict';
import {
  getQuickJS,
  getQuickJSSync,
  shouldInterruptAfterDeadline,
  getQuickJSInstance,
  getQuickJSSyncInstance,
  evaluateExpression,
  createIsolatedContext,
  evaluateWithDeadline
} from '../index.mjs';

// 1. getQuickJS initializes and resolves a QuickJSWASMModule singleton instance
const QuickJS = await getQuickJSInstance();
assert.ok(QuickJS, 'QuickJS module should be defined');
assert.equal(typeof QuickJS.evalCode, 'function', 'QuickJS.evalCode should be a function');
assert.equal(typeof QuickJS.newContext, 'function', 'QuickJS.newContext should be a function');
assert.equal(typeof QuickJS.newRuntime, 'function', 'QuickJS.newRuntime should be a function');

// 2. evalCode evaluates Javascript expressions inside QuickJS WASM module and returns native results
const arithmeticResult = await evaluateExpression('10 + 32');
assert.equal(arithmeticResult, 42, 'arithmetic evaluation should equal 42');

const objectResult = await evaluateExpression('({ message: "hello world", count: 3 })');
assert.deepEqual(objectResult, { message: 'hello world', count: 3 }, 'object evaluation should return matching object');

// 3. newContext creates an isolated QuickJS context capable of executing code and setting global functions
const vm = await createIsolatedContext();
try {
  const multiplyFn = vm.newFunction('multiply', (a, b) => {
    const valA = vm.getNumber(a);
    const valB = vm.getNumber(b);
    return vm.newNumber(valA * valB);
  });
  vm.setProp(vm.global, 'multiply', multiplyFn);
  multiplyFn.dispose();

  const evalHandle = vm.unwrapResult(vm.evalCode('multiply(6, 7)'));
  assert.equal(vm.getNumber(evalHandle), 42, 'custom guest function invocation should return 42');
  evalHandle.dispose();

  // Test error throwing inside VM
  const errResult = vm.evalCode('throw new TypeError("custom failure");');
  assert.ok('error' in errResult, 'evalCode should return an error result when guest throws');
  const dumpedError = vm.dump(errResult.error);
  assert.equal(dumpedError.name, 'TypeError');
  assert.equal(dumpedError.message, 'custom failure');
  errResult.error.dispose();
} finally {
  vm.dispose();
}

// 4. evalCode interrupts execution and throws InternalError when interrupted by shouldInterruptAfterDeadline
let interrupted = false;
try {
  await evaluateWithDeadline('while (true) {}', 50);
} catch (err) {
  interrupted = true;
  assert.equal(err.name, 'InternalError', 'Interrupted execution should throw InternalError');
  assert.equal(err.message, 'interrupted', 'Interrupted error message should be "interrupted"');
}
assert.ok(interrupted, 'Infinite loop execution should be interrupted by deadline');

// 5. getQuickJSSync returns the initialized QuickJSWASMModule synchronously after getQuickJS resolves
const syncModule = getQuickJSSyncInstance();
assert.equal(syncModule, QuickJS, 'getQuickJSSync should return the same singleton as getQuickJS');
const syncEval = syncModule.evalCode('["a", "b"].join("-")');
assert.equal(syncEval, 'a-b', 'syncModule.evalCode should evaluate synchronous expressions');