rebuild docs

justjake · Mar 10, 2024 · cc9b624 · cc9b624
1 parent 31732b3
commit cc9b624
Show file tree

Hide file tree

Showing 15 changed files with 173 additions and 108 deletions.
diff --git a/README.md b/README.md
@@ -360,21 +360,19 @@ without introducing asynchronous host code, described by the type [JSPromiseStat
 
 ```typescript
 type JSPromiseState =
-  | { type: 'pending', error: Error }
-  | { type: 'fulfilled', value: QuickJSHandle, notAPromise?: boolean }
-  | { type: 'rejected', error: QuickJSHandle }
+  | { type: "pending"; error: Error }
+  | { type: "fulfilled"; value: QuickJSHandle; notAPromise?: boolean }
+  | { type: "rejected"; error: QuickJSHandle }
 ```
 
 The result conforms to the `SuccessOrFail` type returned by `context.evalCode`, so you can use `context.unwrapResult(context.getPromiseState(promiseHandle))` to assert a promise is settled successfully and retrieve its value. Calling `context.unwrapResult` on a pending or rejected promise will throw an error.
 
 ```typescript
-const promiseHandle = context.evalCode(`Promise.resolve(42)`);
-const resultHandle = context.unwrapResult(
-  context.getPromiseState(promiseHandle)
-);
-context.getNumber(resultHandle) === 42; // true
-resultHandle.dispose();
-promiseHandle.dispose();
+const promiseHandle = context.evalCode(`Promise.resolve(42)`)
+const resultHandle = context.unwrapResult(context.getPromiseState(promiseHandle))
+context.getNumber(resultHandle) === 42 // true
+resultHandle.dispose()
+promiseHandle.dispose()
 ```
 
 [JSPromiseState]: https://github.com/justjake/quickjs-emscripten/blob/main/doc/quickjs-emscripten/exports.md#jspromisestate

diff --git a/doc/README.md b/doc/README.md
@@ -60,6 +60,8 @@ main()
       - [`Lifetime.consume(fn)`](#lifetimeconsumefn)
     - [Exposing APIs](#exposing-apis)
       - [Promises](#promises)
+        - [context.getPromiseState(handle)](#contextgetpromisestatehandle)
+        - [context.resolvePromise(handle)](#contextresolvepromisehandle)
       - [Asyncify](#asyncify)
         - [Async module loader](#async-module-loader)
         - [Async on host, sync in QuickJS](#async-on-host-sync-in-quickjs)
@@ -352,8 +354,36 @@ execute immediately. Your code needs to explicitly call
 gives your code maximum control to _schedule_ when QuickJS will block the host's
 event loop by resuming execution.
 
-To work with QuickJS handles that contain a promise inside the environment, you
-can convert the QuickJSHandle into a native promise using
+To work with QuickJS handles that contain a promise inside the environment,
+there are two options:
+
+##### context.getPromiseState(handle)
+
+You can synchronously peek into a QuickJS promise handle and get its state
+without introducing asynchronous host code, described by the type [JSPromiseState][]:
+
+```typescript
+type JSPromiseState =
+  | { type: "pending"; error: Error }
+  | { type: "fulfilled"; value: QuickJSHandle; notAPromise?: boolean }
+  | { type: "rejected"; error: QuickJSHandle }
+```
+
+The result conforms to the `SuccessOrFail` type returned by `context.evalCode`, so you can use `context.unwrapResult(context.getPromiseState(promiseHandle))` to assert a promise is settled successfully and retrieve its value. Calling `context.unwrapResult` on a pending or rejected promise will throw an error.
+
+```typescript
+const promiseHandle = context.evalCode(`Promise.resolve(42)`)
+const resultHandle = context.unwrapResult(context.getPromiseState(promiseHandle))
+context.getNumber(resultHandle) === 42 // true
+resultHandle.dispose()
+promiseHandle.dispose()
+```
+
+[JSPromiseState]: https://github.com/justjake/quickjs-emscripten/blob/main/doc/quickjs-emscripten/exports.md#jspromisestate
+
+##### context.resolvePromise(handle)
+
+You can convert the QuickJSHandle into a native promise using
 `context.resolvePromise()`. Take care with this API to avoid 'deadlocks' where
 the host awaits a guest promise, but the guest cannot make progress until the
 host calls `runtime.executePendingJobs()`. The simplest way to avoid this kind

diff --git a/doc/quickjs-emscripten-core/classes/QuickJSAsyncContext.md b/doc/quickjs-emscripten-core/classes/QuickJSAsyncContext.md
@@ -309,7 +309,7 @@ socket.on("data", chunk => {
 
 #### Source
 
-[packages/quickjs-emscripten-core/src/context.ts:1145](https://github.com/justjake/quickjs-emscripten/blob/main/packages/quickjs-emscripten-core/src/context.ts#L1145)
+[packages/quickjs-emscripten-core/src/context.ts:1160](https://github.com/justjake/quickjs-emscripten/blob/main/packages/quickjs-emscripten-core/src/context.ts#L1160)
 
 ***
 
@@ -374,6 +374,7 @@ will result in an error.
 > **dump**(`handle`): `any`
 
 Dump a JSValue to Javascript in a best-effort fashion.
+If the value is a promise, dumps the promise's state.
 Returns `handle.toString()` if it cannot be serialized to JSON.
 
 #### Parameters
@@ -390,7 +391,7 @@ Returns `handle.toString()` if it cannot be serialized to JSON.
 
 #### Source
 
-[packages/quickjs-emscripten-core/src/context.ts:971](https://github.com/justjake/quickjs-emscripten/blob/main/packages/quickjs-emscripten-core/src/context.ts#L971)
+[packages/quickjs-emscripten-core/src/context.ts:972](https://github.com/justjake/quickjs-emscripten/blob/main/packages/quickjs-emscripten-core/src/context.ts#L972)
 
 ***
 
@@ -424,7 +425,7 @@ socket.write(dataLifetime?.value)
 
 #### Source
 
-[packages/quickjs-emscripten-core/src/context.ts:1128](https://github.com/justjake/quickjs-emscripten/blob/main/packages/quickjs-emscripten-core/src/context.ts#L1128)
+[packages/quickjs-emscripten-core/src/context.ts:1143](https://github.com/justjake/quickjs-emscripten/blob/main/packages/quickjs-emscripten-core/src/context.ts#L1143)
 
 ***
 
@@ -1335,7 +1336,7 @@ If the result is an error, converts the error to a native object and throws the
 
 #### Source
 
-[packages/quickjs-emscripten-core/src/context.ts:1000](https://github.com/justjake/quickjs-emscripten/blob/main/packages/quickjs-emscripten-core/src/context.ts#L1000)
+[packages/quickjs-emscripten-core/src/context.ts:1015](https://github.com/justjake/quickjs-emscripten/blob/main/packages/quickjs-emscripten-core/src/context.ts#L1015)
 
 ***
 

diff --git a/doc/quickjs-emscripten-core/classes/QuickJSContext.md b/doc/quickjs-emscripten-core/classes/QuickJSContext.md
@@ -333,7 +333,7 @@ socket.on("data", chunk => {
 
 #### Source
 
-[packages/quickjs-emscripten-core/src/context.ts:1145](https://github.com/justjake/quickjs-emscripten/blob/main/packages/quickjs-emscripten-core/src/context.ts#L1145)
+[packages/quickjs-emscripten-core/src/context.ts:1160](https://github.com/justjake/quickjs-emscripten/blob/main/packages/quickjs-emscripten-core/src/context.ts#L1160)
 
 ***
 
@@ -402,6 +402,7 @@ will result in an error.
 > **dump**(`handle`): `any`
 
 Dump a JSValue to Javascript in a best-effort fashion.
+If the value is a promise, dumps the promise's state.
 Returns `handle.toString()` if it cannot be serialized to JSON.
 
 #### Parameters
@@ -414,7 +415,7 @@ Returns `handle.toString()` if it cannot be serialized to JSON.
 
 #### Source
 
-[packages/quickjs-emscripten-core/src/context.ts:971](https://github.com/justjake/quickjs-emscripten/blob/main/packages/quickjs-emscripten-core/src/context.ts#L971)
+[packages/quickjs-emscripten-core/src/context.ts:972](https://github.com/justjake/quickjs-emscripten/blob/main/packages/quickjs-emscripten-core/src/context.ts#L972)
 
 ***
 
@@ -444,7 +445,7 @@ socket.write(dataLifetime?.value)
 
 #### Source
 
-[packages/quickjs-emscripten-core/src/context.ts:1128](https://github.com/justjake/quickjs-emscripten/blob/main/packages/quickjs-emscripten-core/src/context.ts#L1128)
+[packages/quickjs-emscripten-core/src/context.ts:1143](https://github.com/justjake/quickjs-emscripten/blob/main/packages/quickjs-emscripten-core/src/context.ts#L1143)
 
 ***
 
@@ -1225,7 +1226,7 @@ If the result is an error, converts the error to a native object and throws the
 
 #### Source
 
-[packages/quickjs-emscripten-core/src/context.ts:1000](https://github.com/justjake/quickjs-emscripten/blob/main/packages/quickjs-emscripten-core/src/context.ts#L1000)
+[packages/quickjs-emscripten-core/src/context.ts:1015](https://github.com/justjake/quickjs-emscripten/blob/main/packages/quickjs-emscripten-core/src/context.ts#L1015)
 
 ***
 

diff --git a/doc/quickjs-emscripten/README.md b/doc/quickjs-emscripten/README.md
@@ -53,12 +53,15 @@ main()
     - [Safely evaluate Javascript code](#safely-evaluate-javascript-code)
     - [Interfacing with the interpreter](#interfacing-with-the-interpreter)
       - [Runtime](#runtime)
+      - [EcmaScript Module Exports](#ecmascript-module-exports)
     - [Memory Management](#memory-management)
       - [`using` statement](#using-statement)
       - [Scope](#scope)
       - [`Lifetime.consume(fn)`](#lifetimeconsumefn)
     - [Exposing APIs](#exposing-apis)
       - [Promises](#promises)
+        - [context.getPromiseState(handle)](#contextgetpromisestatehandle)
+        - [context.resolvePromise(handle)](#contextresolvepromisehandle)
       - [Asyncify](#asyncify)
         - [Async module loader](#async-module-loader)
         - [Async on host, sync in QuickJS](#async-on-host-sync-in-quickjs)
@@ -371,8 +374,38 @@ execute immediately. Your code needs to explicitly call
 gives your code maximum control to _schedule_ when QuickJS will block the host's
 event loop by resuming execution.
 
-To work with QuickJS handles that contain a promise inside the environment, you
-can convert the QuickJSHandle into a native promise using
+To work with QuickJS handles that contain a promise inside the environment,
+there are two options:
+
+##### context.getPromiseState(handle)
+
+You can synchronously peek into a QuickJS promise handle and get its state
+without introducing asynchronous host code, described by the type [JSPromiseState][]:
+
+```typescript
+type JSPromiseState =
+  | { type: 'pending', error: Error }
+  | { type: 'fulfilled', value: QuickJSHandle, notAPromise?: boolean }
+  | { type: 'rejected', error: QuickJSHandle }
+```
+
+The result conforms to the `SuccessOrFail` type returned by `context.evalCode`, so you can use `context.unwrapResult(context.getPromiseState(promiseHandle))` to assert a promise is settled successfully and retrieve its value. Calling `context.unwrapResult` on a pending or rejected promise will throw an error.
+
+```typescript
+const promiseHandle = context.evalCode(`Promise.resolve(42)`);
+const resultHandle = context.unwrapResult(
+  context.getPromiseState(promiseHandle)
+);
+context.getNumber(resultHandle) === 42; // true
+resultHandle.dispose();
+promiseHandle.dispose();
+```
+
+[JSPromiseState]: https://github.com/justjake/quickjs-emscripten/blob/main/doc/quickjs-emscripten/exports.md#jspromisestate
+
+##### context.resolvePromise(handle)
+
+You can convert the QuickJSHandle into a native promise using
 `context.resolvePromise()`. Take care with this API to avoid 'deadlocks' where
 the host awaits a guest promise, but the guest cannot make progress until the
 host calls `runtime.executePendingJobs()`. The simplest way to avoid this kind

diff --git a/doc/quickjs-emscripten/classes/QuickJSAsyncContext.md b/doc/quickjs-emscripten/classes/QuickJSAsyncContext.md
@@ -309,7 +309,7 @@ socket.on("data", chunk => {
 
 #### Source
 
-packages/quickjs-emscripten-core/dist/index.d.ts:1274
+packages/quickjs-emscripten-core/dist/index.d.ts:1275
 
 ***
 
@@ -374,6 +374,7 @@ packages/quickjs-emscripten-core/dist/index.d.ts:890
 > **dump**(`handle`): `any`
 
 Dump a JSValue to Javascript in a best-effort fashion.
+If the value is a promise, dumps the promise's state.
 Returns `handle.toString()` if it cannot be serialized to JSON.
 
 #### Parameters
@@ -390,7 +391,7 @@ Returns `handle.toString()` if it cannot be serialized to JSON.
 
 #### Source
 
-packages/quickjs-emscripten-core/dist/index.d.ts:1227
+packages/quickjs-emscripten-core/dist/index.d.ts:1228
 
 ***
 
@@ -424,7 +425,7 @@ socket.write(dataLifetime?.value)
 
 #### Source
 
-packages/quickjs-emscripten-core/dist/index.d.ts:1261
+packages/quickjs-emscripten-core/dist/index.d.ts:1262
 
 ***
 
@@ -1335,7 +1336,7 @@ If the result is an error, converts the error to a native object and throws the
 
 #### Source
 
-packages/quickjs-emscripten-core/dist/index.d.ts:1234
+packages/quickjs-emscripten-core/dist/index.d.ts:1235
 
 ***
 

diff --git a/doc/quickjs-emscripten/classes/QuickJSAsyncWASMModule.md b/doc/quickjs-emscripten/classes/QuickJSAsyncWASMModule.md
@@ -50,7 +50,7 @@ Synchronous evalCode is not supported.
 
 #### Source
 
-packages/quickjs-emscripten-core/dist/index.d.ts:1457
+packages/quickjs-emscripten-core/dist/index.d.ts:1458
 
 ***
 
@@ -80,7 +80,7 @@ See the documentation for [QuickJSWASMModule#evalCode](QuickJSWASMModule.md#eval
 
 #### Source
 
-packages/quickjs-emscripten-core/dist/index.d.ts:1469
+packages/quickjs-emscripten-core/dist/index.d.ts:1470
 
 ***
 
@@ -104,7 +104,7 @@ and provide the [CustomizeVariantOptions#wasmMemory](../interfaces/CustomizeVari
 
 #### Source
 
-packages/quickjs-emscripten-core/dist/index.d.ts:1413
+packages/quickjs-emscripten-core/dist/index.d.ts:1414
 
 ***
 
@@ -130,7 +130,7 @@ be disposed when the context is disposed.
 
 #### Source
 
-packages/quickjs-emscripten-core/dist/index.d.ts:1455
+packages/quickjs-emscripten-core/dist/index.d.ts:1456
 
 ***
 
@@ -156,7 +156,7 @@ concurrent async actions, create multiple WebAssembly modules.
 
 #### Source
 
-packages/quickjs-emscripten-core/dist/index.d.ts:1449
+packages/quickjs-emscripten-core/dist/index.d.ts:1450
 
 ***
 

diff --git a/doc/quickjs-emscripten/classes/QuickJSContext.md b/doc/quickjs-emscripten/classes/QuickJSContext.md
@@ -333,7 +333,7 @@ socket.on("data", chunk => {
 
 #### Source
 
-packages/quickjs-emscripten-core/dist/index.d.ts:1274
+packages/quickjs-emscripten-core/dist/index.d.ts:1275
 
 ***
 
@@ -402,6 +402,7 @@ packages/quickjs-emscripten-core/dist/index.d.ts:890
 > **dump**(`handle`): `any`
 
 Dump a JSValue to Javascript in a best-effort fashion.
+If the value is a promise, dumps the promise's state.
 Returns `handle.toString()` if it cannot be serialized to JSON.
 
 #### Parameters
@@ -414,7 +415,7 @@ Returns `handle.toString()` if it cannot be serialized to JSON.
 
 #### Source
 
-packages/quickjs-emscripten-core/dist/index.d.ts:1227
+packages/quickjs-emscripten-core/dist/index.d.ts:1228
 
 ***
 
@@ -444,7 +445,7 @@ socket.write(dataLifetime?.value)
 
 #### Source
 
-packages/quickjs-emscripten-core/dist/index.d.ts:1261
+packages/quickjs-emscripten-core/dist/index.d.ts:1262
 
 ***
 
@@ -1225,7 +1226,7 @@ If the result is an error, converts the error to a native object and throws the
 
 #### Source
 
-packages/quickjs-emscripten-core/dist/index.d.ts:1234
+packages/quickjs-emscripten-core/dist/index.d.ts:1235
 
 ***
 

diff --git a/doc/quickjs-emscripten/classes/QuickJSWASMModule.md b/doc/quickjs-emscripten/classes/QuickJSWASMModule.md
@@ -81,7 +81,7 @@ with name `"InternalError"` and  message `"interrupted"`.
 
 #### Source
 
-packages/quickjs-emscripten-core/dist/index.d.ts:1403
+packages/quickjs-emscripten-core/dist/index.d.ts:1404
 
 ***
 
@@ -101,7 +101,7 @@ and provide the [CustomizeVariantOptions#wasmMemory](../interfaces/CustomizeVari
 
 #### Source
 
-packages/quickjs-emscripten-core/dist/index.d.ts:1413
+packages/quickjs-emscripten-core/dist/index.d.ts:1414
 
 ***
 
@@ -123,7 +123,7 @@ be disposed when the context is disposed.
 
 #### Source
 
-packages/quickjs-emscripten-core/dist/index.d.ts:1377
+packages/quickjs-emscripten-core/dist/index.d.ts:1378
 
 ***
 
@@ -145,7 +145,7 @@ loading for one or more [QuickJSContext](QuickJSContext.md)s inside the runtime.
 
 #### Source
 
-packages/quickjs-emscripten-core/dist/index.d.ts:1371
+packages/quickjs-emscripten-core/dist/index.d.ts:1372
 
 ***