@andreiltd/componentize-qjs-binding-linux-x64-musl 0.2.2 → 0.4.0

package/README.md

@@ -104,8 +104,9 @@ wasmtime run --wasm component-model-async=y --invoke 'greet("World")' hello.wasm
 ```
 
 The built-in runtime published with componentize-qjs includes component-model
-async support. A custom runtime built without that Cargo feature can be passed
-with `--runtime` for sync-only components.
+async support. Pass `--sync` to embed the built-in non-async runtime instead,
+producing components that run on hosts without component-model async support. A
+custom runtime can also be supplied with `--runtime`.
 
 ## CLI Reference
 
@@ -118,16 +119,19 @@ componentize-qjs [OPTIONS] --wit <WIT> --js <JS>
 | `--wit <PATH>` | `-w` | Path to the WIT file or directory |
 | `--js <PATH>` | `-j` | Path to the JavaScript source file |
 | `--output <PATH>` | `-o` | Output path (default: `output.wasm`) |
+| `--module-root <PATH>` | | Root directory exposed read-only during Wizer for resolving JavaScript imports |
 | `--world <NAME>` | `-n` | World name when the WIT defines multiple worlds |
 | `--stub-wasi` | | Replace all WASI imports with trap stubs |
 | `--minify` | `-m` | Minify JS source before embedding |
 | `--opt-size` | | Use the built-in QuickJS runtime optimized for size |
+| `--sync` | | Use the built-in non-async runtime (combine with `--opt-size` for the non-async opt-size runtime) |
 | `--runtime <PATH>` | | Custom QuickJS runtime Wasm module to embed |
 
 ### Cargo features
 
 | Feature | Effect |
 |---|---|
+| `component-model-async` | (default) Embed the component-model async runtime as the default built-in. The non-async runtime is always embedded and selectable via `--sync`. Disable to build a smaller binary with only the non-async runtime |
 | `opt-size` | Selects the bundled opt-size runtime when no runtime option is provided by the CLI or npm API |
 
 Build with features:
@@ -166,6 +170,13 @@ export function doubleAdd(a, b) {
 }
 ```
 
+JavaScript modules imported by the entry file are resolved during Wizer
+initialization. Relative imports are resolved from the entry file path passed to
+`--js`; bare package imports are resolved under the read-only module root. By
+default the CLI uses the current directory when the entry file is under it, or
+the entry file's parent directory otherwise. Use `--module-root <PATH>` to expose
+a project root that contains shared files or `node_modules`.
+
 ## WIT Type Mappings
 
 ### Primitive Types
@@ -187,13 +198,33 @@ export function doubleAdd(a, b) {
 | `list<T>` | `Array` | `[1, 2, 3]` |
 | `list<u8>` | `Uint8Array` or `Array` | `new Uint8Array([1, 2, 3])` |
 | `tuple<T, U, ...>` | `Array` | `[42, "hello"]` |
-| `option<T>` | `T \| null \| undefined` | `null` for none |
-| `result<T, E>` | `{ tag: "ok"\|"err", val?: T\|E }` | `{ tag: "ok", val: 42 }` |
+| `option<T>` | `T \| null` (nested: `{ tag: "some"\|"none", val }`) | `null` for none; `option<option<T>>` is wrapped |
+| `result<T, E>` | top-level function result: return `T` or throw `E`; nested result: `{ tag: "ok"\|"err", val?: T\|E }` | `return 42` / `throw "error"` |
 | `record { ... }` | `object` (camelCase keys) | `{ myField: 1 }` |
-| `variant` | `{ tag: number, val?: T }` | `{ tag: 0, val: "hi" }` |
-| `enum` | `number` | Lookup tables provided on the interface |
-| `flags` | `number` (bitmask) | Bit constants provided on the interface |
-| `own<R>`, `borrow<R>` | `number` (handle) | Opaque resource handle |
+| `variant` | `{ tag: string, val?: T }` | `{ tag: "circle", val: 2.5 }` |
+| `enum` | `string` (case name) | `"red"` |
+| `flags` | `object` (camelCase booleans) | `{ read: true, write: false }` |
+| `own<R>`, `borrow<R>` | resource object (methods on its prototype) | `input.blockingRead(n)` |
+
+### Imported Resources
+
+Imported resources are exposed as JavaScript classes. Resource methods are
+called on the handle:
+
+```js
+import stdin from "wasi:cli/stdin@0.2.10";
+import stdout from "wasi:cli/stdout@0.2.10";
+
+const input = stdin.getStdin();     // an InputStream
+const output = stdout.getStdout();  // an OutputStream
+
+// Methods whose WIT return type is result<...> return the ok payload or throw.
+const chunk = input.blockingRead(4096);   // method on the resource (len is a number)
+output.blockingWriteAndFlush(chunk);
+```
+
+`[static]` methods are exposed on the resource class and `[constructor]` makes
+the class callable with `new`.
 
 ### Async Exports
 
@@ -383,7 +414,10 @@ const { component } = await componentize({
 // component is a Buffer containing the WebAssembly component bytes
 ```
 
-Runtime selection is available through `optSize`, `runtime`, or `runtimeBytes`; provide only one of those options. The `runtime` option is a path to a custom QuickJS runtime Wasm module.
+Runtime selection is available through `optSize`, `sync`, `runtime`, or
+`runtimeBytes`. `optSize` and `sync` may be combined to select the non-async
+opt-size runtime, but neither can be combined with a custom `runtime`/`runtimeBytes`.
+The `runtime` option is a path to a custom QuickJS runtime Wasm module.
 
 ## Acknowledgments
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andreiltd/componentize-qjs-binding-linux-x64-musl",
-  "version": "0.2.2",
+  "version": "0.4.0",
   "cpu": [
     "x64"
   ],