@jitl/quickjs-wasmfile-debug-asyncify

@jitl/quickjs-wasmfile-debug-asyncify

Variant with separate .WASM file. Supports browser ESM, NodeJS ESM, and NodeJS CommonJS.

This generated package is part of quickjs-emscripten. It contains a variant of the quickjs WASM library, and can be used with quickjs-emscripten-core.

import variant from "@jitl/quickjs-wasmfile-debug-asyncify"
import { newQuickJSAsyncWASMModuleFromVariant } from "quickjs-emscripten-core"
const QuickJS = await newQuickJSAsyncWASMModuleFromVariant(variant)

This variant was built with the following settings:

Library: quickjs

The original bellard/quickjs library.

Version 2024-02-14+36911f0d vendored to quickjs-emscripten on 2024-06-15.

Release mode: debug

Enables assertions and memory sanitizers. Try to run your tests against debug variants, in addition to your preferred production variant, to catch more bugs.

Exports: require import browser workerd

Exports the following in package.json for the package entrypoint:

• Exports a NodeJS-compatible CommonJS module, which is faster to load and run compared to an ESModule.
• Exports a NodeJS-compatible ESModule. Cannot be imported synchronously from a NodeJS CommonJS module.
• Exports a browser-compatible ESModule, designed to work in browsers and browser-like environments.
• Targets Cloudflare Workers.

Extra async magic? Yes

Build run through the ASYNCIFY WebAssembly transform. This imposes substantial size (2x the size of sync) and speed penalties (40% the speed of sync). In return, allows synchronous calls from the QuickJS WASM runtime to async functions on the host. The extra magic makes this variant slower than sync variants. Note that both variants support regular async functions. Only adopt ASYNCIFY if you need to! The QuickJSAsyncRuntime and QuickJSAsyncContext classes expose the ASYNCIFY-specific APIs.

Single-file, or separate .wasm file? wasm

Has a separate .wasm file. May offer better caching in your browser, and reduces the size of your JS bundle. If you have issues, try a 'singlefile' variant.

More details

Full variant JSON description:

{
  "library": "quickjs",
  "releaseMode": "debug",
  "syncMode": "asyncify",
  "description": "Variant with separate .WASM file. Supports browser ESM, NodeJS ESM, and NodeJS CommonJS.",
  "emscriptenInclusion": "wasm",
  "exports": {
    "require": {
      "emscriptenEnvironment": ["node"]
    },
    "import": {
      "emscriptenEnvironment": ["node"]
    },
    "browser": {
      "emscriptenEnvironment": ["web", "worker"]
    },
    "workerd": {
      "emscriptenEnvironment": ["web"]
    }
  }
}

Variant-specific Emscripten build flags:

[
  "-s ASYNCIFY=1",
  "-DQTS_ASYNCIFY=1",
  "-DQTS_ASYNCIFY_DEFAULT_STACK_SIZE=81920",
  "-s ASYNCIFY_STACK_SIZE=81920",
  "-s ASYNCIFY_REMOVE=@$(BUILD_WRAPPER)/asyncify-remove.json",
  "-s ASYNCIFY_IMPORTS=@$(BUILD_WRAPPER)/asyncify-imports.json",
  "-lasync.js",
  "-O0",
  "-DQTS_DEBUG_MODE",
  "-DDUMP_LEAKS=1",
  "-gsource-map",
  "-s ASSERTIONS=1",
  "--pre-js $(TEMPLATES)/pre-extension.js",
  "--pre-js $(TEMPLATES)/pre-sourceMapJson.js",
  "--pre-js $(TEMPLATES)/pre-wasmOffsetConverter.js",
  "--pre-js $(TEMPLATES)/pre-wasmMemory.js",
  "-O3"
]

Changelog

v0.30.0

• #200 Inspect and iterate handles, equality, changes to result types, changes to debug logging.
• #195 Export setDebugMode

Collection & Iteration

• For objects and arrays: add context.getOwnPropertyNames(handle, options) to iterate the key or array index handles.
• For arrays: add context.getLength(handle) which reads handle.length and returns it as a number or undefined to make writing for (i=0;i<length;i++) loops easier.
• For iterable collections like Map, Set, Array: add context.getIterator(handle) calls handle[Symbol.iterator]() and then exposes the result as an IterableIterator to host javascript.

Usability improvements

• The SuccessOrFail<T, QuickJSHandle> return type is largely replaced with a new return type DisposableSuccess<T> | DisposableFail<QuickJSHandle>. The new type implements result.unwrap() as a replacement for context.unwrapResult(result). It also implements dispose() directly, so you no longer need to distinguish between success and failure to clean up.
• add context.callMethod(handle, 'methodName'), this makes it easier to call methods like context.callMethod(handle, 'keys') or context.callMethod('values') which can be used with the new iterator.

Equality

• Added context.eq(a, b), context.sameValue(a, b), context.sameValueZero(a, b)

Debug logging changes

Debug logging is now disabled by default, even when using a DEBUG variant. It can be enabled on a runtime-by-runtime basis with runtime.setDebugMode(boolean) or context.runtime.setDebugMode(boolean), or globally using setDebugMode(boolean). As with before, you should use a DEBUG variant to see logs from the WebAssembly C code.