quickjs-emscripten

The @jitl/quickjs-ffi-types package provides TypeScript type definitions for the Foreign Function Interface (FFI) used within quickjs-emscripten.

Note: This is an internal package. For general usage and high-level documentation, refer to the main quickjs-emscripten package.

The project is currently pre-1.0.0 and expects occasional breaking API changes. Planned improvements include:

• Module Loading: Creating modules via JavaScript and scanning source text for imports.
• High-level Value Reading: Type guard functions (e.g., context.isArray(handle), context.isPromise(handle)) and iteration utilities (e.g., context.getIterable(handle), context.iterateObjectEntries(handle)).
• High-level Value Creation: Improved environment setup and automatic translation (potentially via quickjs-emscripten-sync).
• SQLite Integration.

Security Note: While the project strives for security, it has not been audited. Use with care in production.

The QuickJSWASMModule class provides a JavaScript interface to the QuickJS interpreter (which supports ES2020). It wraps a WebAssembly module containing the QuickJS library and helper C code. Because WebAssembly modules are isolated by the host runtime, using separate QuickJSWASMModule instances provides the highest level of isolation possible.

To interact with the interpreter, you can use three main approaches:

1. One-off evaluation: Use evalCode() for simple, quick tasks.
2. Context-based control: Use newContext() to create a QuickJSContext (and an associated runtime) for more granular control.
3. Runtime-based control: Use newRuntime() to create a QuickJSRuntime, allowing you to set CPU/memory limits and configure module loading for multiple contexts.

This package is a specialized variant of the quickjs-emscripten library with the following characteristics:

• Library: Uses quickjs-ng (v0.12.1), a fork of QuickJS that includes additional features.
• Release Mode: Optimized for performance; intended for production use.
• Sync Mode: Uses a synchronous build (no extra async magic).
• WASM Delivery: Uses a separate .wasm file rather than embedding it in the JS bundle. This is better for caching and bundle size, but if you encounter loading issues, consider a singlefile variant.
• Compatibility: Supports NodeJS (CommonJS and ESM), Browsers, and Cloudflare Workers (workerd).

The quickjs-emscripten library provides TypeScript bindings for QuickJS (a modern JavaScript interpreter) compiled to WebAssembly. It is designed for:

• Sandboxing: Safely evaluating untrusted JavaScript (supports most of ES2023).
• Runtime Interfacing: Creating and manipulating values inside the QuickJS runtime.
• API Exposure: Exposing host functions to the QuickJS runtime.
• Async Support: Executing synchronous code that uses asynchronous functions via asyncify.
• Cross-Platform Compatibility: Works in browsers, NodeJS, Deno, Bun, Cloudflare Workers, and even QuickJS itself (via quickjs-for-quickjs).

The QuickJSWASMModule class provides a JavaScript interface to the QuickJS interpreter (ES2020 support) by wrapping a WebAssembly module. Each module instance is isolated by the host's WebAssembly runtime, providing the highest level of isolation possible.

For simple tasks, use evalCode() to evaluate JavaScript and receive a native JavaScript value. For more complex environments, use newContext() or newRuntime() to gain control over execution, memory, and resource limits.

A QuickJSAsyncRuntime represents a JavaScript runtime corresponding to a specific object heap.

Key characteristics:

• Isolation: Multiple runtimes can exist simultaneously, but they cannot exchange objects. You should create separate runtime instances to isolate untrusted code from different sources.
• No Multi-threading: Within a single runtime, multi-threading is not supported.
• Analogy: Think of separate runtimes as different browser domains, and the contexts within a runtime as different windows open to the same domain.
• Stronger Isolation: For even stronger isolation (at the cost of higher memory usage), you can create separate WebAssembly modules using newQuickJSWASMModule.

Create a runtime using QuickJSWASMModule.newRuntime.

A WeakLifetime is a specialized version of a Lifetime that does not own its underlying value.

Key characteristics:

• No Disposal: It never calls its disposer function.
• Use Case: It is primarily used for function arguments where the lifetime of the object is managed by an external owner, rather than the lifetime object itself.
• Conversion: While it doesn't own the value, it can be duped to produce regular Lifetime objects that do own the value and call a disposer.

A WeakLifetime is a specialized type of Lifetime that does not own its underlying value. Unlike a standard Lifetime, a WeakLifetime will never call its disposer function.

Key Characteristics:

• Non-owning: It provides access to a value without being responsible for its destruction.
• Use Case: It is primarily used for function arguments where the lifetime of the object is managed by a caller or another owner, rather than the function itself.
• Conversion: You can call .dup() on a WeakLifetime to produce a regular Lifetime that does own the value and will call the disposer.

A Lifetime<T, TCopy, Owner> is an abstraction used to prevent access to a value (typically a C memory pointer) after it has been disposed. It ensures memory safety by tracking whether the underlying value is still valid.

Key Concepts

• Safety: Accessing the .value property after the lifetime has been disposed will throw an error. This prevents use-after-free bugs.
• Disposal: When dispose() is called, the lifetime executes a disposer function provided during construction to perform necessary cleanup (e.g., freeing memory).
• Ownership: The Owner type parameter is optional metadata used to track who created the lifetime, but it is not used for logic by the lifetime itself.

Usage Pattern

Instead of holding onto raw values, you should hold onto the Lifetime object. Use .map() to transform the value or .dup() to create a new handle to the same value.