@ricsam/quickjs-runtime 0.2.20 → 0.2.21

package/README.md

@@ -1,49 +1,291 @@
 # @ricsam/quickjs-runtime
 
-Umbrella package that combines all APIs.
+The recommended way to create QuickJS sandboxed runtimes with web-standard APIs.
+
+## Installation
+
+```bash
+bun add @ricsam/quickjs-runtime quickjs-emscripten
+```
+
+## Quick Start
+
+```typescript
+import { createRuntime } from "@ricsam/quickjs-runtime";
+
+const runtime = await createRuntime({
+  console: {
+    onEntry: (entry) => {
+      if (entry.type === "output") {
+        console.log(`[sandbox:${entry.level}]`, ...entry.args);
+      }
+    },
+  },
+  fetch: async (request) => fetch(request),
+});
+
+await runtime.eval(`
+  const response = await fetch("https://api.example.com/data");
+  const data = await response.json();
+  console.log("Fetched:", data);
+`);
+
+await runtime.dispose();
+```
+
+## API
+
+### createRuntime(options?)
+
+Creates a fully configured QuickJS runtime with all WHATWG APIs.
 
 ```typescript
-import { setupRuntime } from "@ricsam/quickjs-runtime";
+const runtime = await createRuntime({
+  // Memory limit in bytes
+  memoryLimit: 1024 * 1024 * 10, // 10MB
 
-const handle = setupRuntime(context, {
-  // Fetch API - pass true for defaults or options object
-  fetch: {
-    onFetch: async (req) => fetch(req),
+  // Console output handler
+  console: {
+    onEntry: (entry) => { /* handle console output */ },
   },
-  // File System API
+
+  // Fetch handler for outbound requests
+  fetch: async (request) => fetch(request),
+
+  // File system access
   fs: {
     getDirectory: async (path) => createNodeDirectoryHandle(`./sandbox${path}`),
   },
-  // Console API - pass true for defaults or options with handlers
-  console: {
-    handlers: {
-      onLog: (level, args) => console.log(`[${level}]`, ...args),
+
+  // ES module loader
+  moduleLoader: async (moduleName) => {
+    if (moduleName === "@/utils") {
+      return `export const add = (a, b) => a + b;`;
+    }
+    throw new Error(`Unknown module: ${moduleName}`);
+  },
+
+  // Custom host functions
+  customFunctions: {
+    hashPassword: {
+      fn: async (password) => Bun.password.hash(password),
+      async: true,
+    },
+    getConfig: {
+      fn: () => ({ environment: "production" }),
+      async: false,
     },
   },
-  // Crypto API - pass true to enable
-  crypto: true,
-  // Encoding API (atob/btoa) - pass true to enable
-  encoding: true,
+
+  // Enable test environment (describe, it, expect)
+  testEnvironment: {
+    onEvent: (event) => { /* handle test events */ },
+  },
+
+  // Playwright browser automation
+  playwright: {
+    page: playwrightPage,
+    baseUrl: "https://example.com",
+  },
 });
+```
+
+### RuntimeHandle
+
+The returned handle provides:
+
+```typescript
+interface RuntimeHandle {
+  // Unique runtime identifier
+  readonly id: string;
+
+  // Execute code as ES module (supports top-level await)
+  eval(code: string, filename?: string): Promise<void>;
 
-// Access individual handles
-handle.core;     // CoreHandle (always present)
-handle.fetch;    // FetchHandle (if enabled)
-handle.fs;       // FsHandle (if enabled)
-handle.console;  // ConsoleHandle (if enabled)
-handle.crypto;   // CryptoHandle (if enabled)
-handle.encoding; // EncodingHandle (if enabled)
+  // Dispose all resources
+  dispose(): Promise<void>;
 
-handle.dispose(); // Cleanup all
+  // Sub-handles for specific features
+  readonly fetch: RuntimeFetchHandle;
+  readonly timers: RuntimeTimersHandle;
+  readonly console: RuntimeConsoleHandle;
+  readonly testEnvironment: RuntimeTestEnvironmentHandle;
+  readonly playwright: RuntimePlaywrightHandle;
+}
 ```
 
-**Quick enable with defaults:**
+## Examples
+
+### HTTP Server
 
 ```typescript
-const handle = setupRuntime(context, {
-  fetch: true,     // Enable fetch with default options
-  console: true,   // Enable console with no handlers (silent)
-  crypto: true,    // Enable Web Crypto API
-  encoding: true,  // Enable atob/btoa
+const runtime = await createRuntime({
+  console: { onEntry: (e) => e.type === "output" && console.log(...e.args) },
 });
-```
+
+await runtime.eval(`
+  serve({
+    fetch(request) {
+      const url = new URL(request.url);
+      return Response.json({ path: url.pathname });
+    },
+  });
+`);
+
+// Dispatch requests to the sandboxed server
+const response = await runtime.fetch.dispatchRequest(
+  new Request("http://localhost/api/users")
+);
+console.log(await response.json()); // { path: "/api/users" }
+
+await runtime.dispose();
+```
+
+### Running Tests
+
+```typescript
+const runtime = await createRuntime({
+  testEnvironment: {
+    onEvent: (event) => {
+      if (event.type === "testEnd") {
+        const icon = event.test.status === "pass" ? "✓" : "✗";
+        console.log(`${icon} ${event.test.fullName}`);
+      }
+    },
+  },
+});
+
+await runtime.eval(`
+  describe("Math", () => {
+    it("adds numbers", () => {
+      expect(1 + 1).toBe(2);
+    });
+  });
+`);
+
+const results = await runtime.testEnvironment.runTests();
+console.log(`${results.passed}/${results.total} passed`);
+
+await runtime.dispose();
+```
+
+### Browser Automation with Playwright
+
+```typescript
+import { chromium } from "playwright";
+
+const browser = await chromium.launch();
+const page = await browser.newPage();
+
+const runtime = await createRuntime({
+  testEnvironment: true,
+  playwright: {
+    page,
+    baseUrl: "https://example.com",
+  },
+});
+
+await runtime.eval(`
+  describe("Homepage", () => {
+    it("displays welcome message", async () => {
+      await page.goto("/");
+      await expect(page.getByRole("heading")).toContainText("Welcome");
+    });
+  });
+`);
+
+await runtime.testEnvironment.runTests();
+await runtime.dispose();
+await browser.close();
+```
+
+### Custom Functions
+
+```typescript
+const runtime = await createRuntime({
+  customFunctions: {
+    // Async function
+    hashPassword: {
+      fn: async (password) => Bun.password.hash(password),
+      async: true,
+    },
+    // Sync function
+    generateId: {
+      fn: () => crypto.randomUUID(),
+      async: false,
+    },
+  },
+});
+
+await runtime.eval(`
+  const hash = await hashPassword("secret123");
+  const id = generateId();
+  console.log({ hash, id });
+`);
+```
+
+### ES Modules
+
+```typescript
+const runtime = await createRuntime({
+  moduleLoader: async (moduleName) => {
+    const modules = {
+      "@/utils": `export const double = (n) => n * 2;`,
+      "@/config": `export default { apiUrl: "https://api.example.com" };`,
+    };
+    if (moduleName in modules) {
+      return modules[moduleName];
+    }
+    throw new Error(`Module not found: ${moduleName}`);
+  },
+});
+
+await runtime.eval(`
+  import { double } from "@/utils";
+  import config from "@/config";
+
+  console.log(double(21)); // 42
+  console.log(config.apiUrl);
+`);
+```
+
+## Included APIs
+
+When you use `createRuntime()`, the following globals are automatically available in the sandbox:
+
+- **Console**: `console.log`, `console.warn`, `console.error`, etc.
+- **Fetch**: `fetch`, `Request`, `Response`, `Headers`, `FormData`, `AbortController`
+- **Server**: `serve()` with WebSocket support
+- **Crypto**: `crypto.getRandomValues()`, `crypto.randomUUID()`, `crypto.subtle`
+- **Encoding**: `atob()`, `btoa()`
+- **Timers**: `setTimeout`, `setInterval`, `clearTimeout`, `clearInterval`
+- **Streams**: `ReadableStream`, `WritableStream`, `TransformStream`
+- **Blob/File**: `Blob`, `File`
+- **Path**: `path.join()`, `path.resolve()`, etc.
+
+Optional (when configured):
+- **File System**: `fs.getDirectory()` (requires `fs` option)
+- **Test Environment**: `describe`, `it`, `expect` (requires `testEnvironment` option)
+- **Playwright**: `page` object (requires `playwright` option)
+
+## Security
+
+- **No automatic network access** - `fetch` option must be explicitly provided
+- **File system isolation** - `fs.getDirectory` controls all path access
+- **Memory limits** - Use `memoryLimit` option to prevent resource exhaustion
+- **No access to host** - Code runs in isolated QuickJS VM
+
+## Advanced: Low-level API
+
+For advanced use cases requiring direct context manipulation, you can use the low-level `setupRuntime()` function or individual package setup functions. See the individual package READMEs for details:
+
+- [@ricsam/quickjs-core](../core)
+- [@ricsam/quickjs-console](../console)
+- [@ricsam/quickjs-fetch](../fetch)
+- [@ricsam/quickjs-fs](../fs)
+- [@ricsam/quickjs-crypto](../crypto)
+- [@ricsam/quickjs-encoding](../encoding)
+- [@ricsam/quickjs-timers](../timers)
+- [@ricsam/quickjs-path](../path)
+- [@ricsam/quickjs-test-environment](../test-environment)
+- [@ricsam/quickjs-playwright](../playwright)

package/dist/cjs/create-runtime.cjs

@@ -0,0 +1,329 @@
+// @bun @bun-cjs
+(function(exports, require, module, __filename, __dirname) {var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __moduleCache = /* @__PURE__ */ new WeakMap;
+var __toCommonJS = (from) => {
+  var entry = __moduleCache.get(from), desc;
+  if (entry)
+    return entry;
+  entry = __defProp({}, "__esModule", { value: true });
+  if (from && typeof from === "object" || typeof from === "function")
+    __getOwnPropNames(from).map((key) => !__hasOwnProp.call(entry, key) && __defProp(entry, key, {
+      get: () => from[key],
+      enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+    }));
+  __moduleCache.set(from, entry);
+  return entry;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: (newValue) => all[name] = () => newValue
+    });
+};
+
+// packages/runtime/src/create-runtime.ts
+var exports_create_runtime = {};
+__export(exports_create_runtime, {
+  createRuntime: () => createRuntime
+});
+module.exports = __toCommonJS(exports_create_runtime);
+var import_quickjs_emscripten = require("quickjs-emscripten");
+var import_quickjs_core = require("@ricsam/quickjs-core");
+var import_quickjs_fetch = require("@ricsam/quickjs-fetch");
+var import_quickjs_fs = require("@ricsam/quickjs-fs");
+var import_quickjs_console = require("@ricsam/quickjs-console");
+var import_quickjs_encoding = require("@ricsam/quickjs-encoding");
+var import_quickjs_timers = require("@ricsam/quickjs-timers");
+var import_quickjs_crypto = require("@ricsam/quickjs-crypto");
+var import_quickjs_test_environment = require("@ricsam/quickjs-test-environment");
+var import_quickjs_playwright = require("@ricsam/quickjs-playwright");
+async function createRuntime(options) {
+  const opts = options ?? {};
+  const id = crypto.randomUUID();
+  const needsAsync = opts.moduleLoader !== undefined;
+  let context;
+  let runtime;
+  let isAsyncContext = false;
+  if (needsAsync) {
+    const asyncContext = await import_quickjs_emscripten.newAsyncContext();
+    context = asyncContext;
+    runtime = asyncContext.runtime;
+    isAsyncContext = true;
+    if (opts.moduleLoader) {
+      const moduleLoader = opts.moduleLoader;
+      runtime.setModuleLoader(async (moduleName) => {
+        try {
+          const code = await moduleLoader(moduleName);
+          return code;
+        } catch (error) {
+          return { error };
+        }
+      });
+    }
+  } else {
+    const QuickJS = await import_quickjs_emscripten.getQuickJS();
+    runtime = QuickJS.newRuntime();
+    context = runtime.newContext();
+  }
+  if (opts.memoryLimit) {
+    runtime.setMemoryLimit(opts.memoryLimit);
+  }
+  const stateMap = import_quickjs_core.createStateMap();
+  const coreHandle = import_quickjs_core.setupCore(context, { stateMap });
+  const consoleHandle = import_quickjs_console.setupConsole(context, {
+    ...opts.console,
+    stateMap,
+    coreHandle
+  });
+  const encodingHandle = import_quickjs_encoding.setupEncoding(context, { stateMap, coreHandle });
+  const timersHandle = import_quickjs_timers.setupTimers(context, { stateMap, coreHandle });
+  const cryptoHandle = import_quickjs_crypto.setupCrypto(context, { stateMap, coreHandle });
+  let fetchHandle;
+  if (opts.fetch) {
+    const fetchCallback = opts.fetch;
+    fetchHandle = import_quickjs_fetch.setupFetch(context, {
+      stateMap,
+      coreHandle,
+      onFetch: async (request) => {
+        return Promise.resolve(fetchCallback(request));
+      }
+    });
+  } else {
+    fetchHandle = import_quickjs_fetch.setupFetch(context, { stateMap, coreHandle });
+  }
+  let fsHandle;
+  if (opts.fs) {
+    fsHandle = import_quickjs_fs.setupFs(context, {
+      ...opts.fs,
+      stateMap,
+      coreHandle
+    });
+  }
+  if (opts.customFunctions) {
+    for (const [name, def] of Object.entries(opts.customFunctions)) {
+      if (def.async) {
+        const fn = import_quickjs_core.defineAsyncFunction(context, name, async (...args) => {
+          return def.fn(...args);
+        });
+        context.setProp(context.global, name, fn);
+        fn.dispose();
+      } else {
+        const fn = import_quickjs_core.defineFunction(context, name, (...args) => {
+          return def.fn(...args);
+        });
+        context.setProp(context.global, name, fn);
+        fn.dispose();
+      }
+    }
+  }
+  let testEnvHandle;
+  if (opts.testEnvironment) {
+    const testEnvOpts = typeof opts.testEnvironment === "object" ? opts.testEnvironment : {};
+    testEnvHandle = import_quickjs_test_environment.setupTestEnvironment(context, {
+      stateMap,
+      coreHandle,
+      onEvent: testEnvOpts.onEvent
+    });
+  }
+  let playwrightHandle;
+  if (opts.playwright) {
+    playwrightHandle = import_quickjs_playwright.setupPlaywright(context, {
+      ...opts.playwright,
+      stateMap,
+      coreHandle,
+      consoleCallbacks: opts.playwright.console ? opts.console : undefined
+    });
+  }
+  const runtimeFetchHandle = {
+    async dispatchRequest(request, _options) {
+      if (!fetchHandle) {
+        throw new Error("Fetch not configured");
+      }
+      return fetchHandle.dispatchRequest(request);
+    },
+    hasServeHandler() {
+      return fetchHandle?.hasServeHandler() ?? false;
+    },
+    hasActiveConnections() {
+      return fetchHandle?.hasActiveConnections() ?? false;
+    }
+  };
+  const runtimeTimersHandle = {
+    clearAll() {
+      timersHandle.clearAll();
+    }
+  };
+  const runtimeConsoleHandle = {
+    reset() {
+      consoleHandle.reset();
+    },
+    getTimers() {
+      return consoleHandle.getTimers();
+    },
+    getCounters() {
+      return consoleHandle.getCounters();
+    },
+    getGroupDepth() {
+      return consoleHandle.getGroupDepth();
+    }
+  };
+  const runtimeTestEnvironmentHandle = {
+    async runTests(_timeout) {
+      if (!testEnvHandle) {
+        throw new Error("Test environment not enabled. Set testEnvironment: true in createRuntime options.");
+      }
+      return testEnvHandle.run();
+    },
+    hasTests() {
+      return testEnvHandle?.hasTests() ?? false;
+    },
+    getTestCount() {
+      return testEnvHandle?.getTestCount() ?? 0;
+    },
+    reset() {
+      testEnvHandle?.reset();
+    }
+  };
+  const runtimePlaywrightHandle = {
+    getCollectedData() {
+      if (!playwrightHandle) {
+        return { browserConsoleLogs: [], networkRequests: [], networkResponses: [] };
+      }
+      return {
+        browserConsoleLogs: playwrightHandle.getBrowserConsoleLogs(),
+        networkRequests: playwrightHandle.getNetworkRequests(),
+        networkResponses: playwrightHandle.getNetworkResponses()
+      };
+    },
+    clearCollectedData() {
+      playwrightHandle?.clearCollected();
+    }
+  };
+  return {
+    id,
+    fetch: runtimeFetchHandle,
+    timers: runtimeTimersHandle,
+    console: runtimeConsoleHandle,
+    testEnvironment: runtimeTestEnvironmentHandle,
+    playwright: runtimePlaywrightHandle,
+    async eval(code, filename) {
+      if (isAsyncContext) {
+        const asyncContext = context;
+        const result = await asyncContext.evalCodeAsync(code, filename ?? "<eval>", {
+          type: "module"
+        });
+        if (result.error) {
+          const err = context.dump(result.error);
+          result.error.dispose();
+          throw new Error(`Eval failed: ${typeof err === "string" ? err : JSON.stringify(err)}`);
+        }
+        const promiseState = context.getPromiseState(result.value);
+        if (promiseState.type === "pending") {
+          const resolved = await context.resolvePromise(result.value);
+          result.value.dispose();
+          if (resolved.error) {
+            const err = context.dump(resolved.error);
+            resolved.error.dispose();
+            throw new Error(`Promise rejected: ${typeof err === "string" ? err : JSON.stringify(err)}`);
+          }
+          resolved.value.dispose();
+        } else {
+          result.value.dispose();
+        }
+        runtime.executePendingJobs();
+      } else {
+        const result = context.evalCode(code, filename ?? "<eval>", {
+          type: "module"
+        });
+        if (result.error) {
+          const err = context.dump(result.error);
+          result.error.dispose();
+          throw new Error(`Eval failed: ${typeof err === "string" ? err : JSON.stringify(err)}`);
+        }
+        const promiseState = context.getPromiseState(result.value);
+        if (promiseState.type === "pending") {
+          const resolved = await context.resolvePromise(result.value);
+          result.value.dispose();
+          runtime.executePendingJobs();
+          if (resolved.error) {
+            const err = context.dump(resolved.error);
+            resolved.error.dispose();
+            throw new Error(`Promise rejected: ${typeof err === "string" ? err : JSON.stringify(err)}`);
+          }
+          resolved.value.dispose();
+        } else {
+          result.value.dispose();
+        }
+        runtime.executePendingJobs();
+      }
+    },
+    async dispose() {
+      for (let i = 0;i < 1000; i++) {
+        if (!runtime.hasPendingJob())
+          break;
+        const result = runtime.executePendingJobs();
+        if (result.error)
+          result.error.dispose();
+      }
+      playwrightHandle?.dispose();
+      testEnvHandle?.dispose();
+      cryptoHandle.dispose();
+      timersHandle.dispose();
+      encodingHandle.dispose();
+      consoleHandle.dispose();
+      fsHandle?.dispose();
+      fetchHandle?.dispose();
+      for (let i = 0;i < 1000; i++) {
+        if (!runtime.hasPendingJob())
+          break;
+        const result = runtime.executePendingJobs();
+        if (result.error)
+          result.error.dispose();
+      }
+      import_quickjs_core.cleanupUnmarshaledHandles(context);
+      import_quickjs_core.clearAllInstanceState();
+      try {
+        const clearGlobals = context.evalCode(`
+          (function() {
+            const keysToDelete = Object.keys(globalThis).filter(k =>
+              k !== 'globalThis' && k !== 'undefined' && k !== 'NaN' && k !== 'Infinity'
+            );
+            for (const key of keysToDelete) {
+              try { globalThis[key] = undefined; } catch (e) {}
+            }
+            for (const key of keysToDelete) {
+              try { delete globalThis[key]; } catch (e) {}
+            }
+            return keysToDelete.length;
+          })()
+        `);
+        if (clearGlobals.error) {
+          clearGlobals.error.dispose();
+        } else {
+          clearGlobals.value.dispose();
+        }
+      } catch {}
+      for (let i = 0;i < 100; i++) {
+        if (!runtime.hasPendingJob())
+          break;
+        const result = runtime.executePendingJobs();
+        if (result.error)
+          result.error.dispose();
+      }
+      coreHandle.dispose();
+      context.dispose();
+      if (!isAsyncContext) {
+        runtime.dispose();
+      }
+    }
+  };
+}
+})
+
+//# debugId=0041C068E93313DA64756E2164756E21