Skip to content

Commit cc9b624

Browse files
justjakejustjake
committed
rebuild docs
1 parent 31732b3 commit cc9b624

File tree

15 files changed

+173
-108
lines changed

15 files changed

+173
-108
lines changed

‎README.md‎

Lines changed: 8 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -360,21 +360,19 @@ without introducing asynchronous host code, described by the type [JSPromiseStat
360360

361361
```typescript
362362
type JSPromiseState =
363-
| { type: 'pending', error: Error }
364-
| { type: 'fulfilled', value: QuickJSHandle, notAPromise?: boolean }
365-
| { type: 'rejected', error: QuickJSHandle }
363+
| { type: "pending"; error: Error }
364+
| { type: "fulfilled"; value: QuickJSHandle; notAPromise?: boolean }
365+
| { type: "rejected"; error: QuickJSHandle }
366366
```
367367
368368
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.
369369
370370
```typescript
371-
const promiseHandle = context.evalCode(`Promise.resolve(42)`);
372-
const resultHandle = context.unwrapResult(
373-
context.getPromiseState(promiseHandle)
374-
);
375-
context.getNumber(resultHandle) === 42; // true
376-
resultHandle.dispose();
377-
promiseHandle.dispose();
371+
const promiseHandle = context.evalCode(`Promise.resolve(42)`)
372+
const resultHandle = context.unwrapResult(context.getPromiseState(promiseHandle))
373+
context.getNumber(resultHandle) === 42 // true
374+
resultHandle.dispose()
375+
promiseHandle.dispose()
378376
```
379377

380378
[JSPromiseState]: https://github.com/justjake/quickjs-emscripten/blob/main/doc/quickjs-emscripten/exports.md#jspromisestate

‎doc/README.md‎

Lines changed: 32 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -60,6 +60,8 @@ main()
6060
- [`Lifetime.consume(fn)`](#lifetimeconsumefn)
6161
- [Exposing APIs](#exposing-apis)
6262
- [Promises](#promises)
63+
- [context.getPromiseState(handle)](#contextgetpromisestatehandle)
64+
- [context.resolvePromise(handle)](#contextresolvepromisehandle)
6365
- [Asyncify](#asyncify)
6466
- [Async module loader](#async-module-loader)
6567
- [Async on host, sync in QuickJS](#async-on-host-sync-in-quickjs)
@@ -352,8 +354,36 @@ execute immediately. Your code needs to explicitly call
352354
gives your code maximum control to _schedule_ when QuickJS will block the host's
353355
event loop by resuming execution.
354356

355-
To work with QuickJS handles that contain a promise inside the environment, you
356-
can convert the QuickJSHandle into a native promise using
357+
To work with QuickJS handles that contain a promise inside the environment,
358+
there are two options:
359+
360+
##### context.getPromiseState(handle)
361+
362+
You can synchronously peek into a QuickJS promise handle and get its state
363+
without introducing asynchronous host code, described by the type [JSPromiseState][]:
364+
365+
```typescript
366+
type JSPromiseState =
367+
| { type: "pending"; error: Error }
368+
| { type: "fulfilled"; value: QuickJSHandle; notAPromise?: boolean }
369+
| { type: "rejected"; error: QuickJSHandle }
370+
```
371+
372+
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.
373+
374+
```typescript
375+
const promiseHandle = context.evalCode(`Promise.resolve(42)`)
376+
const resultHandle = context.unwrapResult(context.getPromiseState(promiseHandle))
377+
context.getNumber(resultHandle) === 42 // true
378+
resultHandle.dispose()
379+
promiseHandle.dispose()
380+
```
381+
382+
[JSPromiseState]: https://github.com/justjake/quickjs-emscripten/blob/main/doc/quickjs-emscripten/exports.md#jspromisestate
383+
384+
##### context.resolvePromise(handle)
385+
386+
You can convert the QuickJSHandle into a native promise using
357387
`context.resolvePromise()`. Take care with this API to avoid 'deadlocks' where
358388
the host awaits a guest promise, but the guest cannot make progress until the
359389
host calls `runtime.executePendingJobs()`. The simplest way to avoid this kind

‎doc/quickjs-emscripten-core/classes/QuickJSAsyncContext.md‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -309,7 +309,7 @@ socket.on("data", chunk => {
309309

310310
#### Source
311311

312-
[packages/quickjs-emscripten-core/src/context.ts:1145](https://github.com/justjake/quickjs-emscripten/blob/main/packages/quickjs-emscripten-core/src/context.ts#L1145)
312+
[packages/quickjs-emscripten-core/src/context.ts:1160](https://github.com/justjake/quickjs-emscripten/blob/main/packages/quickjs-emscripten-core/src/context.ts#L1160)
313313

314314
***
315315

@@ -374,6 +374,7 @@ will result in an error.
374374
> **dump**(`handle`): `any`
375375
376376
Dump a JSValue to Javascript in a best-effort fashion.
377+
If the value is a promise, dumps the promise's state.
377378
Returns `handle.toString()` if it cannot be serialized to JSON.
378379

379380
#### Parameters
@@ -390,7 +391,7 @@ Returns `handle.toString()` if it cannot be serialized to JSON.
390391

391392
#### Source
392393

393-
[packages/quickjs-emscripten-core/src/context.ts:971](https://github.com/justjake/quickjs-emscripten/blob/main/packages/quickjs-emscripten-core/src/context.ts#L971)
394+
[packages/quickjs-emscripten-core/src/context.ts:972](https://github.com/justjake/quickjs-emscripten/blob/main/packages/quickjs-emscripten-core/src/context.ts#L972)
394395

395396
***
396397

@@ -424,7 +425,7 @@ socket.write(dataLifetime?.value)
424425

425426
#### Source
426427

427-
[packages/quickjs-emscripten-core/src/context.ts:1128](https://github.com/justjake/quickjs-emscripten/blob/main/packages/quickjs-emscripten-core/src/context.ts#L1128)
428+
[packages/quickjs-emscripten-core/src/context.ts:1143](https://github.com/justjake/quickjs-emscripten/blob/main/packages/quickjs-emscripten-core/src/context.ts#L1143)
428429

429430
***
430431

@@ -1335,7 +1336,7 @@ If the result is an error, converts the error to a native object and throws the
13351336

13361337
#### Source
13371338

1338-
[packages/quickjs-emscripten-core/src/context.ts:1000](https://github.com/justjake/quickjs-emscripten/blob/main/packages/quickjs-emscripten-core/src/context.ts#L1000)
1339+
[packages/quickjs-emscripten-core/src/context.ts:1015](https://github.com/justjake/quickjs-emscripten/blob/main/packages/quickjs-emscripten-core/src/context.ts#L1015)
13391340

13401341
***
13411342

‎doc/quickjs-emscripten-core/classes/QuickJSContext.md‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -333,7 +333,7 @@ socket.on("data", chunk => {
333333

334334
#### Source
335335

336-
[packages/quickjs-emscripten-core/src/context.ts:1145](https://github.com/justjake/quickjs-emscripten/blob/main/packages/quickjs-emscripten-core/src/context.ts#L1145)
336+
[packages/quickjs-emscripten-core/src/context.ts:1160](https://github.com/justjake/quickjs-emscripten/blob/main/packages/quickjs-emscripten-core/src/context.ts#L1160)
337337

338338
***
339339

@@ -402,6 +402,7 @@ will result in an error.
402402
> **dump**(`handle`): `any`
403403
404404
Dump a JSValue to Javascript in a best-effort fashion.
405+
If the value is a promise, dumps the promise's state.
405406
Returns `handle.toString()` if it cannot be serialized to JSON.
406407

407408
#### Parameters
@@ -414,7 +415,7 @@ Returns `handle.toString()` if it cannot be serialized to JSON.
414415

415416
#### Source
416417

417-
[packages/quickjs-emscripten-core/src/context.ts:971](https://github.com/justjake/quickjs-emscripten/blob/main/packages/quickjs-emscripten-core/src/context.ts#L971)
418+
[packages/quickjs-emscripten-core/src/context.ts:972](https://github.com/justjake/quickjs-emscripten/blob/main/packages/quickjs-emscripten-core/src/context.ts#L972)
418419

419420
***
420421

@@ -444,7 +445,7 @@ socket.write(dataLifetime?.value)
444445

445446
#### Source
446447

447-
[packages/quickjs-emscripten-core/src/context.ts:1128](https://github.com/justjake/quickjs-emscripten/blob/main/packages/quickjs-emscripten-core/src/context.ts#L1128)
448+
[packages/quickjs-emscripten-core/src/context.ts:1143](https://github.com/justjake/quickjs-emscripten/blob/main/packages/quickjs-emscripten-core/src/context.ts#L1143)
448449

449450
***
450451

@@ -1225,7 +1226,7 @@ If the result is an error, converts the error to a native object and throws the
12251226

12261227
#### Source
12271228

1228-
[packages/quickjs-emscripten-core/src/context.ts:1000](https://github.com/justjake/quickjs-emscripten/blob/main/packages/quickjs-emscripten-core/src/context.ts#L1000)
1229+
[packages/quickjs-emscripten-core/src/context.ts:1015](https://github.com/justjake/quickjs-emscripten/blob/main/packages/quickjs-emscripten-core/src/context.ts#L1015)
12291230

12301231
***
12311232

‎doc/quickjs-emscripten/README.md‎

Lines changed: 35 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -53,12 +53,15 @@ main()
5353
- [Safely evaluate Javascript code](#safely-evaluate-javascript-code)
5454
- [Interfacing with the interpreter](#interfacing-with-the-interpreter)
5555
- [Runtime](#runtime)
56+
- [EcmaScript Module Exports](#ecmascript-module-exports)
5657
- [Memory Management](#memory-management)
5758
- [`using` statement](#using-statement)
5859
- [Scope](#scope)
5960
- [`Lifetime.consume(fn)`](#lifetimeconsumefn)
6061
- [Exposing APIs](#exposing-apis)
6162
- [Promises](#promises)
63+
- [context.getPromiseState(handle)](#contextgetpromisestatehandle)
64+
- [context.resolvePromise(handle)](#contextresolvepromisehandle)
6265
- [Asyncify](#asyncify)
6366
- [Async module loader](#async-module-loader)
6467
- [Async on host, sync in QuickJS](#async-on-host-sync-in-quickjs)
@@ -371,8 +374,38 @@ execute immediately. Your code needs to explicitly call
371374
gives your code maximum control to _schedule_ when QuickJS will block the host's
372375
event loop by resuming execution.
373376

374-
To work with QuickJS handles that contain a promise inside the environment, you
375-
can convert the QuickJSHandle into a native promise using
377+
To work with QuickJS handles that contain a promise inside the environment,
378+
there are two options:
379+
380+
##### context.getPromiseState(handle)
381+
382+
You can synchronously peek into a QuickJS promise handle and get its state
383+
without introducing asynchronous host code, described by the type [JSPromiseState][]:
384+
385+
```typescript
386+
type JSPromiseState =
387+
| { type: 'pending', error: Error }
388+
| { type: 'fulfilled', value: QuickJSHandle, notAPromise?: boolean }
389+
| { type: 'rejected', error: QuickJSHandle }
390+
```
391+
392+
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.
393+
394+
```typescript
395+
const promiseHandle = context.evalCode(`Promise.resolve(42)`);
396+
const resultHandle = context.unwrapResult(
397+
context.getPromiseState(promiseHandle)
398+
);
399+
context.getNumber(resultHandle) === 42; // true
400+
resultHandle.dispose();
401+
promiseHandle.dispose();
402+
```
403+
404+
[JSPromiseState]: https://github.com/justjake/quickjs-emscripten/blob/main/doc/quickjs-emscripten/exports.md#jspromisestate
405+
406+
##### context.resolvePromise(handle)
407+
408+
You can convert the QuickJSHandle into a native promise using
376409
`context.resolvePromise()`. Take care with this API to avoid 'deadlocks' where
377410
the host awaits a guest promise, but the guest cannot make progress until the
378411
host calls `runtime.executePendingJobs()`. The simplest way to avoid this kind

‎doc/quickjs-emscripten/classes/QuickJSAsyncContext.md‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -309,7 +309,7 @@ socket.on("data", chunk => {
309309

310310
#### Source
311311

312-
packages/quickjs-emscripten-core/dist/index.d.ts:1274
312+
packages/quickjs-emscripten-core/dist/index.d.ts:1275
313313

314314
***
315315

@@ -374,6 +374,7 @@ packages/quickjs-emscripten-core/dist/index.d.ts:890
374374
> **dump**(`handle`): `any`
375375
376376
Dump a JSValue to Javascript in a best-effort fashion.
377+
If the value is a promise, dumps the promise's state.
377378
Returns `handle.toString()` if it cannot be serialized to JSON.
378379

379380
#### Parameters
@@ -390,7 +391,7 @@ Returns `handle.toString()` if it cannot be serialized to JSON.
390391

391392
#### Source
392393

393-
packages/quickjs-emscripten-core/dist/index.d.ts:1227
394+
packages/quickjs-emscripten-core/dist/index.d.ts:1228
394395

395396
***
396397

@@ -424,7 +425,7 @@ socket.write(dataLifetime?.value)
424425

425426
#### Source
426427

427-
packages/quickjs-emscripten-core/dist/index.d.ts:1261
428+
packages/quickjs-emscripten-core/dist/index.d.ts:1262
428429

429430
***
430431

@@ -1335,7 +1336,7 @@ If the result is an error, converts the error to a native object and throws the
13351336

13361337
#### Source
13371338

1338-
packages/quickjs-emscripten-core/dist/index.d.ts:1234
1339+
packages/quickjs-emscripten-core/dist/index.d.ts:1235
13391340

13401341
***
13411342

‎doc/quickjs-emscripten/classes/QuickJSAsyncWASMModule.md‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -50,7 +50,7 @@ Synchronous evalCode is not supported.
5050

5151
#### Source
5252

53-
packages/quickjs-emscripten-core/dist/index.d.ts:1457
53+
packages/quickjs-emscripten-core/dist/index.d.ts:1458
5454

5555
***
5656

@@ -80,7 +80,7 @@ See the documentation for [QuickJSWASMModule#evalCode](QuickJSWASMModule.md#eval
8080

8181
#### Source
8282

83-
packages/quickjs-emscripten-core/dist/index.d.ts:1469
83+
packages/quickjs-emscripten-core/dist/index.d.ts:1470
8484

8585
***
8686

@@ -104,7 +104,7 @@ and provide the [CustomizeVariantOptions#wasmMemory](../interfaces/CustomizeVari
104104

105105
#### Source
106106

107-
packages/quickjs-emscripten-core/dist/index.d.ts:1413
107+
packages/quickjs-emscripten-core/dist/index.d.ts:1414
108108

109109
***
110110

@@ -130,7 +130,7 @@ be disposed when the context is disposed.
130130

131131
#### Source
132132

133-
packages/quickjs-emscripten-core/dist/index.d.ts:1455
133+
packages/quickjs-emscripten-core/dist/index.d.ts:1456
134134

135135
***
136136

@@ -156,7 +156,7 @@ concurrent async actions, create multiple WebAssembly modules.
156156

157157
#### Source
158158

159-
packages/quickjs-emscripten-core/dist/index.d.ts:1449
159+
packages/quickjs-emscripten-core/dist/index.d.ts:1450
160160

161161
***
162162

‎doc/quickjs-emscripten/classes/QuickJSContext.md‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -333,7 +333,7 @@ socket.on("data", chunk => {
333333

334334
#### Source
335335

336-
packages/quickjs-emscripten-core/dist/index.d.ts:1274
336+
packages/quickjs-emscripten-core/dist/index.d.ts:1275
337337

338338
***
339339

@@ -402,6 +402,7 @@ packages/quickjs-emscripten-core/dist/index.d.ts:890
402402
> **dump**(`handle`): `any`
403403
404404
Dump a JSValue to Javascript in a best-effort fashion.
405+
If the value is a promise, dumps the promise's state.
405406
Returns `handle.toString()` if it cannot be serialized to JSON.
406407

407408
#### Parameters
@@ -414,7 +415,7 @@ Returns `handle.toString()` if it cannot be serialized to JSON.
414415

415416
#### Source
416417

417-
packages/quickjs-emscripten-core/dist/index.d.ts:1227
418+
packages/quickjs-emscripten-core/dist/index.d.ts:1228
418419

419420
***
420421

@@ -444,7 +445,7 @@ socket.write(dataLifetime?.value)
444445

445446
#### Source
446447

447-
packages/quickjs-emscripten-core/dist/index.d.ts:1261
448+
packages/quickjs-emscripten-core/dist/index.d.ts:1262
448449

449450
***
450451

@@ -1225,7 +1226,7 @@ If the result is an error, converts the error to a native object and throws the
12251226

12261227
#### Source
12271228

1228-
packages/quickjs-emscripten-core/dist/index.d.ts:1234
1229+
packages/quickjs-emscripten-core/dist/index.d.ts:1235
12291230

12301231
***
12311232

‎doc/quickjs-emscripten/classes/QuickJSWASMModule.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -81,7 +81,7 @@ with name `"InternalError"` and message `"interrupted"`.
8181

8282
#### Source
8383

84-
packages/quickjs-emscripten-core/dist/index.d.ts:1403
84+
packages/quickjs-emscripten-core/dist/index.d.ts:1404
8585

8686
***
8787

@@ -101,7 +101,7 @@ and provide the [CustomizeVariantOptions#wasmMemory](../interfaces/CustomizeVari
101101

102102
#### Source
103103

104-
packages/quickjs-emscripten-core/dist/index.d.ts:1413
104+
packages/quickjs-emscripten-core/dist/index.d.ts:1414
105105

106106
***
107107

@@ -123,7 +123,7 @@ be disposed when the context is disposed.
123123

124124
#### Source
125125

126-
packages/quickjs-emscripten-core/dist/index.d.ts:1377
126+
packages/quickjs-emscripten-core/dist/index.d.ts:1378
127127

128128
***
129129

@@ -145,7 +145,7 @@ loading for one or more [QuickJSContext](QuickJSContext.md)s inside the runtime.
145145

146146
#### Source
147147

148-
packages/quickjs-emscripten-core/dist/index.d.ts:1371
148+
packages/quickjs-emscripten-core/dist/index.d.ts:1372
149149

150150
***
151151

0 commit comments

Comments
 (0)