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

Author: justjake

.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
   }
 }

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.

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