@andreiltd/componentize-qjs-binding-win32-arm64-msvc 0.4.4 → 0.5.0

package/README.md

@@ -24,11 +24,13 @@ Under the hood it:
 3. Snapshots the initialized JS state with
    [Wizer](https://github.com/bytecodealliance/wizer) so startup cost is paid at
    build time, not at runtime.
+4. Prunes explicitly marked one-time setup code with Walrus and strips
+   debug/build metadata from the snapshotted component.
 
 ## Prerequisites
 
-Rust **1.94** or later is required (the `wasm32-wasip2` target needs a recent
-toolchain for PIC support in wasi-libc).
+Rust **1.97** or later is required by Wasmtime (the `wasm32-wasip2` target also
+needs a recent toolchain for PIC support in wasi-libc).
 
 ## Installation
 
@@ -186,7 +188,7 @@ a project root that contains shared files or `node_modules`.
 | `bool` | `boolean` | |
 | `u8`, `u16`, `u32` | `number` | |
 | `s8`, `s16`, `s32` | `number` | |
-| `u64`, `s64` | `number` | Precision limited to 2⁵³ (Number.MAX_SAFE_INTEGER) |
+| `u64`, `s64` | `BigInt` | |
 | `f32`, `f64` | `number` | |
 | `char` | `string` | Must be exactly one Unicode scalar value |
 | `string` | `string` | |
@@ -227,6 +229,43 @@ output.blockingWriteAndFlush(chunk);
 `[static]` methods are exposed on the resource class and `[constructor]` makes
 the class callable with `new`.
 
+Owned imported resources support `[Symbol.dispose]()` for deterministic
+cleanup. Passing one to a WIT `own<T>` parameter transfers ownership and
+invalidates the original wrapper. Borrowed wrappers expire when their component
+call completes and cannot be transferred or disposed as owners. Resources lent
+to an in-flight import remain alive and cannot be disposed or transferred until
+that import completes. Ownership is restored for unconsumed stream/future writes
+and for imported calls cancelled before they start. Await imports using an
+incoming borrowed resource before returning from its export.
+
+### Cancelling Async Imports
+
+A pending async import exposes a `cancel()` method on its Promise. Calling it
+requests cancellation of that import. If cancellation succeeds, the original
+Promise rejects with `async import cancelled`; a call that finishes first may
+still resolve normally. The enclosing export remains active, so its catch/finally
+blocks can await further host operations.
+Await the original Promise before releasing resources it borrowed.
+Call `cancel()` from the same async export invocation that started the import;
+it has no effect from another export invocation.
+
+Calls that complete immediately may have no `cancel` method; use optional
+chaining when completion timing is unknown. Repeated cancellation is harmless,
+and a saved cancellation function cannot affect a later call that reuses the
+same runtime handle.
+
+```js
+const pending = service.compute(input);
+const abort = () => pending.cancel?.();
+signal.addEventListener("abort", abort);
+try {
+    return await pending;
+} finally {
+    signal.removeEventListener("abort", abort);
+    await service.release();
+}
+```
+
 ### Async Exports
 
 Async exports are declared with the `async` keyword in WIT and implemented
@@ -405,7 +444,7 @@ world async-value {
 ```
 
 ```js
-async function compute() {
+export async function compute() {
     const { readable, writable } = wit.Future();
 
     // Write the value (fire-and-forget; completes when reader reads)
@@ -418,6 +457,16 @@ async function compute() {
 **Future type constants** follow the same pattern: `wit.Future.U32`,
 `wit.Future.STRING`, etc.
 
+Future handles are deliberately not thenable: use `await readable.read()` to
+obtain the payload. This keeps `return readable` in an async export from
+implicitly consuming the future, and preserves nested future handles.
+Repeated `read()` calls share the same Promise; a cancelled read rejects that
+Promise and allows a subsequent read to retry.
+
+`wit.Future.from(value, type)` adapts a value or Promise and returns
+`{ readable, completion }`. Return its `readable` from an async export rather
+than returning the payload Promise directly, which JavaScript would await.
+
 **FutureReadable methods:**
 
 | Method | Returns | Description |
@@ -436,19 +485,33 @@ async function compute() {
 
 ### Resource Cleanup
 
-Stream and future handles support
+Owned imported resources, stream endpoints, and future endpoints support
 [Explicit Resource Management](https://github.com/tc39/proposal-explicit-resource-management)
 via `Symbol.dispose`. In environments that support `using`:
 
 ```js
 {
-    using stream = wit.Stream();
-    // stream.writable and stream.readable are auto-dropped when leaving scope
+    const stream = wit.Stream();
+    using writable = stream.writable;
+    using readable = stream.readable;
+    // Each endpoint is disposed when leaving scope.
 }
 ```
 
+The factory's `{ readable, writable }` pair is not itself disposable.
+Complete an endpoint's pending operation (or cancel it and await its
+settlement) before leaving its `using` scope or calling `.drop()`.
+Host-requested task cancellation retains pending ABI buffers until the host
+acknowledges each operation's completion or cancellation.
+
 Otherwise, call `.drop()` explicitly to release handles.
 
+## Snapshot Initialization
+
+Snapshot creation uses a 1 GiB host-call copy budget to accommodate large module
+graphs. This allowance belongs to the build-time initializer; execution hosts
+continue to choose their own budgets for instantiated components.
+
 ## Node.js API
 
 The npm package exposes both a CLI and a programmatic API.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andreiltd/componentize-qjs-binding-win32-arm64-msvc",
-  "version": "0.4.4",
+  "version": "0.5.0",
   "cpu": [
     "arm64"
   ],
@@ -28,4 +28,4 @@
   "os": [
     "win32"
   ]
-}
+}