Inspect and iterate handles (#200)

* getOwnPropertyNames flags * getLength * getPropNames, QuicJSIterator * isEqual * wip codegen * DisposableResult * fix new ffi typings * wip * upgrade emcc * iterate on build * regen * new doc * adjust DisposableResult impl and union * fix types more * getPropNames passing * getPropNames -> getOwnPropertyNames * Iterator -> IterableIterator * improve getOwnPropertyNames docs * improve iteration docs and add defaults to getOwnPropertyNames * add callMethod convinience function * add callFunction example * enable debug logging per runtime * regen * docs for debug mode changes * debug log improvement * runtime data func not callable from js * regen * fix build issue * gen doc * doc * for some reason lockfile changed * test: turn on debug mode via env var * fix test leak * changelog, naming adjustments * fix type rename error * fix node test build * tweak to ensure path stuff doesnt affect build * restore previous build tsconfig * disable asyncify-advise, its just really spammy * derp naming * stuff * [[ -> [ for docker build * lint
justjake · Aug 31, 2024 · 7d6814c · 7d6814c
1 parent 87b3e5d
commit 7d6814c
Show file tree

Hide file tree

Showing 188 changed files with 9,392 additions and 2,242 deletions.
diff --git a/.vscode/settings.json b/.vscode/settings.json
@@ -8,6 +8,10 @@
     "lsan_interface.h": "c",
     "math.h": "c",
     "stdbool.h": "c",
-    "emscripten.h": "c"
+    "emscripten.h": "c",
+    "quickjs-atom.h": "c"
+  },
+  "files.exclude": {
+    ".yarn/releases/*": true
   }
 }
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,33 @@
 # Changelog
 
+## v0.30.0
+
+- [#200](https://github.com/justjake/quickjs-emscripten/pull/200) Inspect and iterate handles, equality, changes to result types, changes to debug logging.
+- [#195](https://github.com/justjake/quickjs-emscripten/pull/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.
+
+## v0.29.2
+
+- [#179](https://github.com/justjake/quickjs-emscripten/pull/161) Add a work-around for a bug in Webkit ARM to quickjs build variants. quickjs-ng is still affected by this bug.
+
 ## v0.29.1
 
 - [#161](https://github.com/justjake/quickjs-emscripten/pull/161) Fix a bug where `context.evalCode(..., { type: 'module' })` would return success when some kinds of error occurred when using `quickjs` variants.

diff --git a/README.md b/README.md
@@ -561,8 +561,9 @@ build variant of quickjs-emscripten, and also the [DEBUG_SYNC] build variant.
 The debug sync build variant has extra instrumentation code for detecting memory
 leaks.
 
-The class [TestQuickJSWASMModule] exposes the memory leak detection API, although
-this API is only accurate when using `DEBUG_SYNC` variant.
+The class [TestQuickJSWASMModule] exposes the memory leak detection API,
+although this API is only accurate when using `DEBUG_SYNC` variant. You can also
+enable [debug logging](#debugging) to help diagnose failures.
 
 ```typescript
 // Define your test suite in a function, so that you can test against
@@ -744,40 +745,51 @@ You can use quickjs-emscripten directly from an HTML file in two ways:
 
 ### Debugging
 
-- Switch to a DEBUG build variant of the WebAssembly module to see debug log messages from the C part of this library:
+Debug logging can be enabled globally, or for specific runtimes. You need to use a DEBUG build variant of the WebAssembly module to see debug log messages from the C part of this library.
 
-  ```typescript
-  import { newQuickJSWASMModule, DEBUG_SYNC } from "quickjs-emscripten"
+```typescript
+import { newQuickJSWASMModule, DEBUG_SYNC } from "quickjs-emscripten"
+
+const QuickJS = await newQuickJSWASMModule(DEBUG_SYNC)
+```
+
+With quickjs-emscripten-core:
 
-  const QuickJS = await newQuickJSWASMModule(DEBUG_SYNC)
-  ```
+```typescript
+import { newQuickJSWASMModuleFromVariant } from "quickjs-emscripten-core"
+import DEBUG_SYNC from "@jitl/quickjs-wasmfile-debug-sync"
+
+const QuickJS = await newQuickJSWASMModuleFromVariant(DEBUG_SYNC)
+```
 
-  With quickjs-emscripten-core:
+To enable debug logging globally, call [setDebugMode][setDebugMode]. This affects global Javascript parts of the library, like the module loader and asyncify internals, and is inherited by runtimes created after the call.
 
-  ```typescript
-  import { newQuickJSWASMModuleFromVariant } from "quickjs-emscripten-core"
-  import DEBUG_SYNC from "@jitl/quickjs-wasmfile-debug-sync"
+```typescript
+import { setDebugMode } from "quickjs-emscripten"
 
-  const QuickJS = await newQuickJSWASMModuleFromVariant(DEBUG_SYNC)
-  ```
+setDebugMode(true)
+```
 
-- Enable debug log messages from the Javascript part of this library with [setDebugMode][setDebugMode]:
+With quickjs-emscripten-core:
 
-  ```typescript
-  import { setDebugMode } from "quickjs-emscripten"
+```typescript
+import { setDebugMode } from "quickjs-emscripten-core"
 
-  setDebugMode(true)
-  ```
+setDebugMode(true)
+```
 
-  With quickjs-emscripten-core:
+To enable debug logging for a specific runtime, call [setDebugModeRt][setDebugModeRt]. This affects only the runtime and its associated contexts.
 
-  ```typescript
-  import { setDebugMode } from "quickjs-emscripten-core"
+```typescript
+const runtime = QuickJS.newRuntime()
+runtime.setDebugMode(true)
 
-  setDebugMode(true)
-  ```
+const context = QuickJS.newContext()
+context.runtime.setDebugMode(true)
+```
 
 [setDebugMode]: doc/quickjs-emscripten/exports.md#setdebugmode
+[setDebugModeRt]: https://github.com/justjake/quickjs-emscripten/blob/main/doc/quickjs-emscripten-core/classes/QuickJSRuntime.md#setdebugmode
 
 ### Supported Platforms