Support using statement for Disposable (#134)

* add Symbol.dispose methods * doc; remove polyfill * document using statement; test example * fix vite tests * smoketest node minimal when running yarn check * smoketest changes
justjake · Dec 29, 2023 · 1758926 · 1758926
1 parent 0c30c6f
commit 1758926
Show file tree

Hide file tree

Showing 44 changed files with 1,389 additions and 466 deletions.
diff --git a/README.md b/README.md
@@ -50,6 +50,7 @@ main()
     - [Interfacing with the interpreter](#interfacing-with-the-interpreter)
       - [Runtime](#runtime)
     - [Memory Management](#memory-management)
+      - [`using` statement](#using-statement)
       - [Scope](#scope)
       - [`Lifetime.consume(fn)`](#lifetimeconsumefn)
     - [Exposing APIs](#exposing-apis)
@@ -192,6 +193,33 @@ vm.dispose()
 Here are some strategies to reduce the toil of calling `.dispose()` on each
 handle you create:
 
+#### `using` statement
+
+The `using` statement is a Stage 3 (as of 2023-12-29) proposal for Javascript that declares a constant variable and automatically calls the `[Symbol.dispose]()` method of an object when it goes out of scope. Read more [in this Typescript release announcement][using]. Here's the "Interfacing with the interpreter" example re-written using `using`:
+
+```typescript
+using vm = QuickJS.newContext()
+let state = 0
+
+// The block here isn't needed for correctness, but it shows
+// how to get a tighter bound on the lifetime of `fnHandle`.
+{
+  using fnHandle = vm.newFunction("nextId", () => {
+    return vm.newNumber(++state)
+  })
+
+  vm.setProp(vm.global, "nextId", fnHandle)
+  // fnHandle.dispose() is called automatically when the block exits
+}
+
+using nextId = vm.unwrapResult(vm.evalCode(`nextId(); nextId(); nextId()`))
+console.log("vm result:", vm.getNumber(nextId), "native state:", state)
+// nextId.dispose() is called automatically when the block exits
+// vm.dispose() is called automatically when the block exits
+```
+
+[using]: https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-2.html#using-declarations-and-explicit-resource-management
+
 #### Scope
 
 A

diff --git a/doc/README.md b/doc/README.md
@@ -54,6 +54,7 @@ main()
     - [Interfacing with the interpreter](#interfacing-with-the-interpreter)
       - [Runtime](#runtime)
     - [Memory Management](#memory-management)
+      - [`using` statement](#using-statement)
       - [Scope](#scope)
       - [`Lifetime.consume(fn)`](#lifetimeconsumefn)
     - [Exposing APIs](#exposing-apis)
@@ -196,6 +197,33 @@ vm.dispose()
 Here are some strategies to reduce the toil of calling `.dispose()` on each
 handle you create:
 
+#### `using` statement
+
+The `using` statement is a Stage 3 (as of 2023-12-29) proposal for Javascript that declares a constant variable and automatically calls the `[Symbol.dispose]()` method of an object when it goes out of scope. Read more [in this Typescript release announcement][using]. Here's the "Interfacing with the interpreter" example re-written using `using`:
+
+```typescript
+using vm = QuickJS.newContext()
+let state = 0
+
+// The block here isn't needed for correctness, but it shows
+// how to get a tighter bound on the lifetime of `fnHandle`.
+{
+  using fnHandle = vm.newFunction("nextId", () => {
+    return vm.newNumber(++state)
+  })
+
+  vm.setProp(vm.global, "nextId", fnHandle)
+  // fnHandle.dispose() is called automatically when the block exits
+}
+
+using nextId = vm.unwrapResult(vm.evalCode(`nextId(); nextId(); nextId()`))
+console.log("vm result:", vm.getNumber(nextId), "native state:", state)
+// nextId.dispose() is called automatically when the block exits
+// vm.dispose() is called automatically when the block exits
+```
+
+[using]: https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-2.html#using-declarations-and-explicit-resource-management
+
 #### Scope
 
 A

diff --git a/doc/quickjs-emscripten-core/classes/Lifetime.md b/doc/quickjs-emscripten-core/classes/Lifetime.md
@@ -7,13 +7,13 @@
 # Class: Lifetime\<T, TCopy, Owner\>
 
 A lifetime prevents access to a value after the lifetime has been
-[dispose](Lifetime.md#dispose)ed.
+[dispose](Lifetime.md#dispose-1)ed.
 
 Typically, quickjs-emscripten uses Lifetimes to protect C memory pointers.
 
 ## Contents
 
-- [Extended By](Lifetime.md#extended-by)
+- [Extends](Lifetime.md#extends)
 - [Type parameters](Lifetime.md#type-parameters)
 - [Implements](Lifetime.md#implements)
 - [Constructors](Lifetime.md#constructors)
@@ -31,14 +31,14 @@ Typically, quickjs-emscripten uses Lifetimes to protect C memory pointers.
   - [owner](Lifetime.md#owner)
   - [value](Lifetime.md#value)
 - [Methods](Lifetime.md#methods)
+  - [`[dispose]`()](Lifetime.md#dispose)
   - [consume()](Lifetime.md#consume)
   - [dispose()](Lifetime.md#dispose)
   - [dup()](Lifetime.md#dup)
 
-## Extended By
+## Extends
 
-- [`StaticLifetime`](StaticLifetime.md)
-- [`WeakLifetime`](WeakLifetime.md)
+- [`UsingDisposable`](UsingDisposable.md)
 
 ## Type parameters
 
@@ -79,9 +79,13 @@ the creator.
 
 [`Lifetime`](Lifetime.md)\<`T`, `TCopy`, `Owner`\>
 
+#### Overrides
+
+[`quickjs-emscripten-core.UsingDisposable.constructor`](UsingDisposable.md#constructors)
+
 #### Source
 
-[packages/quickjs-emscripten-core/src/lifetime.ts:43](https://github.com/justjake/quickjs-emscripten/blob/main/packages/quickjs-emscripten-core/src/lifetime.ts#L43)
+[packages/quickjs-emscripten-core/src/lifetime.ts:75](https://github.com/justjake/quickjs-emscripten/blob/main/packages/quickjs-emscripten-core/src/lifetime.ts#L75)
 
 ## Properties
 
@@ -91,7 +95,7 @@ the creator.
 
 #### Source
 
-[packages/quickjs-emscripten-core/src/lifetime.ts:32](https://github.com/justjake/quickjs-emscripten/blob/main/packages/quickjs-emscripten-core/src/lifetime.ts#L32)
+[packages/quickjs-emscripten-core/src/lifetime.ts:64](https://github.com/justjake/quickjs-emscripten/blob/main/packages/quickjs-emscripten-core/src/lifetime.ts#L64)
 
 ***
 
@@ -101,7 +105,7 @@ the creator.
 
 #### Source
 
-[packages/quickjs-emscripten-core/src/lifetime.ts:33](https://github.com/justjake/quickjs-emscripten/blob/main/packages/quickjs-emscripten-core/src/lifetime.ts#L33)
+[packages/quickjs-emscripten-core/src/lifetime.ts:65](https://github.com/justjake/quickjs-emscripten/blob/main/packages/quickjs-emscripten-core/src/lifetime.ts#L65)
 
 ***
 
@@ -111,7 +115,7 @@ the creator.
 
 #### Source
 
-[packages/quickjs-emscripten-core/src/lifetime.ts:47](https://github.com/justjake/quickjs-emscripten/blob/main/packages/quickjs-emscripten-core/src/lifetime.ts#L47)
+[packages/quickjs-emscripten-core/src/lifetime.ts:79](https://github.com/justjake/quickjs-emscripten/blob/main/packages/quickjs-emscripten-core/src/lifetime.ts#L79)
 
 ***
 
@@ -121,7 +125,7 @@ the creator.
 
 #### Source
 
-[packages/quickjs-emscripten-core/src/lifetime.ts:44](https://github.com/justjake/quickjs-emscripten/blob/main/packages/quickjs-emscripten-core/src/lifetime.ts#L44)
+[packages/quickjs-emscripten-core/src/lifetime.ts:76](https://github.com/justjake/quickjs-emscripten/blob/main/packages/quickjs-emscripten-core/src/lifetime.ts#L76)
 
 ***
 
@@ -139,7 +143,7 @@ the creator.
 
 #### Source
 
-[packages/quickjs-emscripten-core/src/lifetime.ts:45](https://github.com/justjake/quickjs-emscripten/blob/main/packages/quickjs-emscripten-core/src/lifetime.ts#L45)
+[packages/quickjs-emscripten-core/src/lifetime.ts:77](https://github.com/justjake/quickjs-emscripten/blob/main/packages/quickjs-emscripten-core/src/lifetime.ts#L77)
 
 ***
 
@@ -157,7 +161,7 @@ the creator.
 
 #### Source
 
-[packages/quickjs-emscripten-core/src/lifetime.ts:46](https://github.com/justjake/quickjs-emscripten/blob/main/packages/quickjs-emscripten-core/src/lifetime.ts#L46)
+[packages/quickjs-emscripten-core/src/lifetime.ts:78](https://github.com/justjake/quickjs-emscripten/blob/main/packages/quickjs-emscripten-core/src/lifetime.ts#L78)
 
 ## Accessors
 
@@ -171,11 +175,11 @@ the creator.
 
 true if the object is alive
 
-false after the object has been [dispose](Lifetime.md#dispose)d
+false after the object has been [dispose](Lifetime.md#dispose-1)d
 
 #### Source
 
-[packages/quickjs-emscripten-core/src/lifetime.ts:50](https://github.com/justjake/quickjs-emscripten/blob/main/packages/quickjs-emscripten-core/src/lifetime.ts#L50)
+[packages/quickjs-emscripten-core/src/lifetime.ts:84](https://github.com/justjake/quickjs-emscripten/blob/main/packages/quickjs-emscripten-core/src/lifetime.ts#L84)
 
 ***
 
@@ -189,7 +193,7 @@ false after the object has been [dispose](Lifetime.md#dispose)d
 
 #### Source
 
-[packages/quickjs-emscripten-core/src/lifetime.ts:69](https://github.com/justjake/quickjs-emscripten/blob/main/packages/quickjs-emscripten-core/src/lifetime.ts#L69)
+[packages/quickjs-emscripten-core/src/lifetime.ts:103](https://github.com/justjake/quickjs-emscripten/blob/main/packages/quickjs-emscripten-core/src/lifetime.ts#L103)
 
 ***
 
@@ -203,7 +207,7 @@ false after the object has been [dispose](Lifetime.md#dispose)d
 
 #### Source
 
-[packages/quickjs-emscripten-core/src/lifetime.ts:65](https://github.com/justjake/quickjs-emscripten/blob/main/packages/quickjs-emscripten-core/src/lifetime.ts#L65)
+[packages/quickjs-emscripten-core/src/lifetime.ts:99](https://github.com/justjake/quickjs-emscripten/blob/main/packages/quickjs-emscripten-core/src/lifetime.ts#L99)
 
 ***
 
@@ -216,18 +220,42 @@ may become invalid, leading to memory errors.
 
 #### Throws
 
-If the lifetime has been [dispose](Lifetime.md#dispose)d already.
+If the lifetime has been [dispose](Lifetime.md#dispose-1)d already.
 
 #### Returns
 
 `T`
 
 #### Source
 
-[packages/quickjs-emscripten-core/src/lifetime.ts:60](https://github.com/justjake/quickjs-emscripten/blob/main/packages/quickjs-emscripten-core/src/lifetime.ts#L60)
+[packages/quickjs-emscripten-core/src/lifetime.ts:94](https://github.com/justjake/quickjs-emscripten/blob/main/packages/quickjs-emscripten-core/src/lifetime.ts#L94)
 
 ## Methods
 
+### `[dispose]`()
+
+> **[dispose]**(): `void`
+
+Just calls the standard .dispose() method of this class.
+
+#### Returns
+
+`void`
+
+#### Implementation of
+
+[`quickjs-emscripten-core.Disposable.[dispose]`](../interfaces/Disposable.md#dispose)
+
+#### Inherited from
+
+[`quickjs-emscripten-core.UsingDisposable.[dispose]`](UsingDisposable.md#dispose)
+
+#### Source
+
+[packages/quickjs-emscripten-core/src/lifetime.ts:49](https://github.com/justjake/quickjs-emscripten/blob/main/packages/quickjs-emscripten-core/src/lifetime.ts#L49)
+
+***
+
 ### consume()
 
 #### consume(map)
@@ -252,7 +280,7 @@ the result of `map(this)`.
 
 ##### Source
 
-[packages/quickjs-emscripten-core/src/lifetime.ts:93](https://github.com/justjake/quickjs-emscripten/blob/main/packages/quickjs-emscripten-core/src/lifetime.ts#L93)
+[packages/quickjs-emscripten-core/src/lifetime.ts:127](https://github.com/justjake/quickjs-emscripten/blob/main/packages/quickjs-emscripten-core/src/lifetime.ts#L127)
 
 #### consume(map)
 
@@ -272,7 +300,7 @@ the result of `map(this)`.
 
 ##### Source
 
-[packages/quickjs-emscripten-core/src/lifetime.ts:96](https://github.com/justjake/quickjs-emscripten/blob/main/packages/quickjs-emscripten-core/src/lifetime.ts#L96)
+[packages/quickjs-emscripten-core/src/lifetime.ts:130](https://github.com/justjake/quickjs-emscripten/blob/main/packages/quickjs-emscripten-core/src/lifetime.ts#L130)
 
 ***
 
@@ -288,11 +316,15 @@ Dispose of [value](Lifetime.md#value-1) and perform cleanup.
 
 #### Implementation of
 
-[`quickjs-emscripten-core.Disposable.dispose`](../interfaces/Disposable.md#dispose)
+[`quickjs-emscripten-core.Disposable.dispose`](../interfaces/Disposable.md#dispose-1)
+
+#### Overrides
+
+[`quickjs-emscripten-core.UsingDisposable.dispose`](UsingDisposable.md#abstract-dispose)
 
 #### Source
 
-[packages/quickjs-emscripten-core/src/lifetime.ts:107](https://github.com/justjake/quickjs-emscripten/blob/main/packages/quickjs-emscripten-core/src/lifetime.ts#L107)
+[packages/quickjs-emscripten-core/src/lifetime.ts:141](https://github.com/justjake/quickjs-emscripten/blob/main/packages/quickjs-emscripten-core/src/lifetime.ts#L141)
 
 ***
 
@@ -308,7 +340,7 @@ Create a new handle pointing to the same [value](Lifetime.md#value-1).
 
 #### Source
 
-[packages/quickjs-emscripten-core/src/lifetime.ts:76](https://github.com/justjake/quickjs-emscripten/blob/main/packages/quickjs-emscripten-core/src/lifetime.ts#L76)
+[packages/quickjs-emscripten-core/src/lifetime.ts:110](https://github.com/justjake/quickjs-emscripten/blob/main/packages/quickjs-emscripten-core/src/lifetime.ts#L110)
 
 ***