Files
58c2c80401 Migrate from Yarn to pnpm (#246)
* Migrate from Yarn to pnpm

- Replace Yarn 4.0.2 with pnpm 10.29.3 as the package manager
- Add pnpm-workspace.yaml and .npmrc configuration
- Update all scripts to use pnpm commands
- Rename getYarnWorkspaces() to getWorkspaces() in scripts/helpers.ts
- Update CI workflow to use pnpm/action-setup@v4 with Node 22
- Add @jitl/tsconfig as root devDependency for proper resolution
- Add variant packages as devDependencies for test resolution
- Fix TypeScript 5.9 compatibility in memory.ts (Int32Array<ArrayBuffer>)
- Upgrade typedoc to 0.28.17 for TypeScript 5.9 support
- Upgrade typedoc-plugin-markdown to 4.10.0
- Regenerate documentation with new typedoc version

* Clarify git commit --amend rule in CLAUDE.md

* CI: Add --ignore-scripts to pnpm install

Equivalent to yarn's YARN_ENABLE_SCRIPTS=0 - prevents prepare scripts
from running during install, which would fail on a fresh checkout.

* Fix pnpm tarball naming in smoketest scripts

pnpm pack generates tarball names like jitl-quickjs-ffi-types-0.32.0.tgz
(without @ prefix, with version) instead of @jitl-quickjs-ffi-types.tgz

* Update examples to TypeScript 5.9 for compatibility

The library now requires TypeScript 5.9+ due to stricter typed array
generics (Int32Array<ArrayBuffer>). Update all TypeScript-using examples.

* Use --legacy-peer-deps for create-react-app smoketest

react-scripts@5 only supports TypeScript 3.x/4.x, but our library now
requires TypeScript 5.9+ for typed array generics. Use --legacy-peer-deps
to work around the peer dependency conflict.

* Fix formatting issues

* Fix remaining formatting issues

* Add reminder to run prettier and lint before pushing

* Document CI workflow in CLAUDE.md

* Add typedoc.json and remark plugins for in-page table of contents

- Add typedoc-plugin-remark, remark-toc, and remark-insert-headings
- Configure remark plugins to generate "Contents" section for Class,
  Interface, Enum, TypeAlias, and Function pages
- This restores the in-page TOC that lists methods/properties that was
  removed in typedoc-plugin-markdown 4.3.0

* Use custom remark plugin for headless TOC in docs

Replace remark-insert-headings + remark-toc with a custom plugin that
inserts the table of contents directly after the class description,
without a separate "Contents" heading.

* Revert to standard remark plugins for TOC with Contents heading

Use remark-insert-headings + remark-toc instead of custom plugin.
Remove mdast-util-toc dependency and custom remark-toc-headless.mjs.

* Fix lockfile - remove mdast-util-toc

* Ignore pnpm-lock.yaml in prettier, update .yarn to .pnpm

---------

Co-authored-by: Hanzo Dev <[email protected]>
2026-02-16 20:35:52 +00:00

6.3 KiB

quickjs-emscripten

Package Manager

Use corepack pnpm to run pnpm commands, e.g.:

  • corepack pnpm install
  • corepack pnpm build
  • corepack pnpm build:ts

Building Variants

Variants are WASM/JS builds of QuickJS with different configurations. They are generated by scripts/prepareVariants.ts.

To build a variant:

cd packages/variant-quickjs-<name>
make           # builds the C code with emscripten
corepack pnpm build:ts  # builds the TypeScript wrapper

Emscripten

  • Most variants use the default emscripten version (defined in scripts/prepareVariants.ts as DEFAULT_EMSCRIPTEN_VERSION)
  • The asmjs variant uses an older emscripten version (ASMJS_EMSCRIPTEN_VERSION) to avoid newer browser APIs
  • Emscripten runs via Docker when the local version doesn't match; see scripts/emcc.sh

Testing

Run all tests:

corepack pnpm test

Run tests for a specific variant (e.g., quickjs-ng only):

cd packages/quickjs-emscripten
npx vitest run -t "quickjs-ng"

Other test filters:

  • -t "RELEASE_SYNC" - only release sync variants
  • -t "DEBUG" - only debug variants
  • -t "QuickJSContext" - only sync context tests

Git

  • Never use git commit --amend - always create new commits. It's better to have a history of what was actually done since branches get rebased/squashed anyway when merged.
  • Before pushing, run pnpm run prettier and pnpm run lint to fix formatting and lint issues. No need to check after every commit - just before pushing.

CI Workflow

After pushing a PR, monitor CI using the gh CLI:

# Check CI status for a PR
gh pr checks <PR_NUMBER>

# View a specific job's progress
gh run view --job=<JOB_ID>

# Get logs for failed steps
gh run view <RUN_ID> --log-failed

When CI fails:

  1. Get the failed logs with gh run view <RUN_ID> --log-failed | tail -100
  2. Fix the issue locally
  3. Commit the fix (new commit, don't amend)
  4. Push and repeat until CI passes

The full CI build takes ~20 minutes due to emscripten compilation.

Key Files

  • scripts/prepareVariants.ts - Generates all variant packages from templates
  • scripts/generate.ts - Generates FFI bindings and symbols
  • templates/Variant.mk - Makefile template for variants
  • c/interface.c - C interface to QuickJS exposed to JavaScript

QuickJS C API Tips

Value Ownership

QuickJS has strict ownership semantics. Functions either "consume" (take ownership of) or "borrow" values:

Functions that CONSUME values (caller must NOT free afterward):

  • JS_DefinePropertyValue - consumes val
  • JS_DefinePropertyValueStr - consumes val
  • JS_DefinePropertyValueUint32 - consumes val
  • JS_SetPropertyValue - consumes val
  • JS_SetPropertyStr - consumes val
  • JS_Throw - consumes the error value

Functions that DUP values internally (caller SHOULD free afterward):

  • JS_NewCFunctionData - calls JS_DupValue on data values, so free your reference after
  • JS_SetProperty - dups the value

Common double-free bug pattern:

// WRONG - double free!
JSValue val = JS_NewString(ctx, "hello");
JS_DefinePropertyValueStr(ctx, obj, "name", val, JS_PROP_CONFIGURABLE);
JS_FreeValue(ctx, val);  // BUG: val was already consumed!

// CORRECT
JSValue val = JS_NewString(ctx, "hello");
JS_DefinePropertyValueStr(ctx, obj, "name", val, JS_PROP_CONFIGURABLE);
// No JS_FreeValue needed - value is consumed

quickjs vs quickjs-ng Differences

Some functions have different signatures between bellard/quickjs and quickjs-ng:

// bellard/quickjs - class ID is global
JS_NewClassID(&class_id);

// quickjs-ng - class ID is per-runtime
JS_NewClassID(rt, &class_id);

Use #ifdef QTS_USE_QUICKJS_NG for compatibility:

#ifdef QTS_USE_QUICKJS_NG
  JS_NewClassID(rt, &class_id);
#else
  JS_NewClassID(&class_id);
#endif

Class Registration

  • JS_NewClassID allocates a new class ID (only call once globally or per-runtime for ng)
  • JS_NewClass registers the class definition with a runtime
  • JS_IsRegisteredClass checks if a class is already registered with a runtime
  • Class prototypes default to JS_NULL for new classes - set with JS_SetClassProto if needed

Disposal Order

When disposing resources, order matters for finalizers:

// CORRECT: Free runtime first so GC finalizers can call back to JS
const rt = new Lifetime(ffi.QTS_NewRuntime(), undefined, (rt_ptr) => {
  ffi.QTS_FreeRuntime(rt_ptr);        // 1. Free runtime - runs GC finalizers
  callbacks.deleteRuntime(rt_ptr);     // 2. Then delete callbacks
});

GC and Prevent Corruption Assertions

If you see assertions like:

  • Assertion failed: i != 0, at: quickjs.c, JS_FreeAtomStruct - atom hash corruption (often double-free)
  • Assertion failed: list_empty(&rt->gc_obj_list) - objects leaked
  • Assertion failed: p->gc_obj_type == JS_GC_OBJ_TYPE_JS_OBJECT - memory corruption

These usually indicate memory management bugs: double-frees, use-after-free, or missing frees.

C Code Style in interface.c

Naming Conventions

  • QTS_ prefix for exported FFI functions (defined in interface.h, called from JavaScript)
  • qts_ prefix for internal C helper functions
  • static keyword for file-local functions and variables
  • Use bool from <stdbool.h> for boolean values (already included)

Code Organization

  • Section comments with // ---- separators for logical grouping
  • Forward declarations at the top of sections when needed
  • Constants defined near related functions

Error Handling Patterns

  • Check JS_IsException(value) for error conditions
  • Use JS_GetException(ctx) to retrieve the exception value
  • Clean up resources in reverse order of allocation
  • Return JS_EXCEPTION or NULL to signal errors to callers

Example

// ----------------------------------------------------------------------------
// Section Name

// Forward declaration
static JSValue qts_helper_function(JSContext *ctx, JSValueConst obj);

// Internal helper - not exported
static bool qts_check_something(JSContext *ctx, JSValueConst obj) {
  if (!JS_IsObject(obj)) return false;
  // ... implementation
  return true;
}

// Exported FFI function
JSValue *QTS_DoSomething(JSContext *ctx, JSValueConst *obj) {
  JSValue result = qts_helper_function(ctx, *obj);
  if (JS_IsException(result)) {
    return jsvalue_to_heap(JS_EXCEPTION);
  }
  return jsvalue_to_heap(result);
}