componentize-qjs-cli 0.4.3

CLI for converting JavaScript to WebAssembly components using QuickJS
Documentation
# Runtime Intrinsics Reference

This document describes the bridge identifiers and module-state conventions
that componentize-qjs uses to connect WIT with quickjs. These are internal
implementation details; user code should be written as an ES module and should
prefer explicit `import`/`export` syntax plus the public `wit.*` API where
possible.

## Naming Conventions

| Category | Convention | Examples |
|---|---|---|
| Internal namespace | `__cqjs` prefix | `__cqjs.makeStream()` |
| Hidden properties | `__cqjs_` prefix | `__cqjs_handle` |
| Public API | `wit.*` namespace | `wit.Stream`, `wit.Future` |
| JS classes | PascalCase | `StreamReadable`, `FutureWritable` |
| Prototype methods | camelCase | `read`, `cancelRead`, `writeAll` |
| WIT functions → JS | lowerCamelCase | `myFunction` from `my-function` |
| WIT resources → JS | UpperCamelCase class | `InputStream` from `input-stream` |
| Type constants | UPPER_SNAKE_CASE | `wit.Stream.U8`, `wit.Future.RESULT_STRING_U32` |

---

## `globalThis.__cqjs`: Internal Namespace

A frozen object containing all internal bridge functions. Installed during
WIT binding registration and not intended for direct use by application code.

### `__cqjs.makeStream(typeIndex)`

Create a new stream pair. Returns `{ readable, writable }` where `readable`
is a `StreamReadable` instance and `writable` is a `StreamWritable` instance.

- typeIndex (`number`) : Index into the WIT stream type table.
- Returns : `{ readable: StreamReadable, writable: StreamWritable }`

### `__cqjs.makeFuture(typeIndex)`

Create a new future pair. Returns `{ readable, writable }` where `readable`
is a `FutureReadable` instance and `writable` is a `FutureWritable` instance.

- typeIndex (`number`) : Index into the WIT future type table.
- Returns : `{ readable: FutureReadable, writable: FutureWritable }`

### `__cqjs.getMemoryUsage()`

Return quickjs engine memory statistics.

- Returns : Object with the following fields:
  - `mallocSize` : Total bytes allocated via malloc
  - `mallocCount` : Number of active malloc allocations
  - `memoryUsedSize` : Total memory used by the JS engine
  - `objCount` : Number of live JS objects
  - `strCount` : Number of live JS strings
  - `atomCount` : Number of live atoms (interned strings)
  - `atomSize` : Total bytes used by atoms
  - `propCount` : Number of live properties
  - `shapeCount` : Number of live shapes (hidden classes)
  - `arrayCount` : Number of live arrays

### `__cqjs.runGc()`

Trigger a quickjs garbage collection cycle.

- Returns : `undefined`

### `__cqjs.asyncExports`

An object containing wrapper functions for async WIT exports. Each wrapper
calls the user's export function and chains `.then()` to signal `task_return`
back to the component model host.

Structure mirrors the WIT export layout:

```js
__cqjs.asyncExports = {
  myFunc: Function,          // root-scope async export
  myInterface: {             // interface-scoped exports
    anotherFunc: Function,
  },
};
```

---

## `globalThis.wit` : Public Stream/Future API

The user-facing API for creating streams and futures from JavaScript.
Installed by the generated JS shim (see `src/codegen.rs`).

### `wit.Stream(type)`

Create a new stream pair for the given type constant.

```js
const { readable, writable } = wit.Stream(wit.Stream.U8);
```

If only one stream type exists in the WIT world, `type` may be omitted.

### `wit.Stream.from(iterable, type)`

Create a stream backed by a synchronous or asynchronous iterable. Returns
`{ readable, completion }`, where `completion` settles when the iterable has
finished or its producer fails. The `type` may be omitted if only one stream
type exists.

WIT function boundaries use this adapter automatically. When a JavaScript
iterable is passed to or returned from a WIT function, the expected stream type
comes from that function's signature. Iterable adaptation must happen while an
async component call is active.

### `wit.Future(type)`

Create a new future pair for the given type constant.

```js
const { readable, writable } = wit.Future(wit.Future.STRING);
```

If only one future type exists in the WIT world, `type` may be omitted.

### Type Constants

Type constants are generated for each stream/future element type found in
the WIT world. They are available as static properties on `wit.Stream` and
`wit.Future`, and also via the `.types` map for runtime discovery. The numeric
value is an internal index into the runtime WIT stream/future table; user code
should pass the generated constant rather than hard-coding the index.

Named aliases for stream and future types are emitted as additional constants
for the same internal index. For example, `type prompt-stream =
stream<message>` adds `wit.Stream.PROMPT_STREAM`.

| Constant Pattern | Example | WIT Type |
|---|---|---|
| Primitives | `U8`, `STRING`, `BOOL` | `u8`, `string`, `bool` |
| Named types | `MY_TYPE` | `my-type` (user-defined) |
| Options | `OPTION_U32` | `option<u32>` |
| Results | `RESULT_STRING_U32` | `result<string, u32>` |
| Tuples | `TUPLE_U32_STRING` | `tuple<u32, string>` |
| Lists | `LIST_U8` | `list<u8>` |
| Nested streams/futures | `STREAM_U8`, `FUTURE_STRING` | `stream<u8>`, `future<string>` |
| Unit | `UNIT` | (no payload) |

Constants for anonymous composite payloads are named recursively. For example,
`stream<result<string, u32>>` produces `wit.Stream.RESULT_STRING_U32`, and
`stream<stream<u8>>` produces `wit.Stream.STREAM_U8`. True self-recursive WIT
type cycles are rejected by `wit-parser`, so the runtime only needs to support
finite nested type graphs here.

If two payload types would produce the same local constant name, the generated
shim qualifies the duplicate names with their owner. For example, if
`test:dupe/left.point` and `test:dupe/right.point` are both used as stream
payloads, the constants are emitted as `TEST_DUPE_LEFT_POINT` and
`TEST_DUPE_RIGHT_POINT` rather than overwriting `POINT`.

---

## JS Classes

Native quickjs classes registered on `globalThis` via `Class::define`.
These are not user-constructible : instances are created internally by
`__cqjs.makeStream()`, `__cqjs.makeFuture()`, and WIT type lifting.

### `StreamReadable`

Readable endpoint of a component-model stream.

| Method | Description |
|---|---|
| `read(count?)` | Read up to `count` items (default 1). Returns a Promise resolving to an Array (or Uint8Array for `stream<u8>`). |
| `next()` | Read the next async-iterator value. `stream<u8>` yields bounded `Uint8Array` chunks. |
| `return()` | End iteration and release the readable handle. |
| `cancelRead()` | Cancel an in-progress async read. Returns `{ progress, result }` or `undefined` if the cancel itself blocks. |
| `drop()` | Drop the readable end, releasing the underlying handle. |
| `[Symbol.asyncIterator]()` | Return this readable as a one-shot async iterator. |
| `[Symbol.dispose]()` | Alias for `drop()`. |

### `StreamWritable`

Writable endpoint of a component-model stream.

| Method | Description |
|---|---|
| `write(data)` | Write a single item or array of items. Returns a Promise resolving to the number of items written. |
| `writeOne(value)` | Write exactly one item, including list and tuple values represented by JavaScript arrays. |
| `writeAll(buffer)` | Write all items from buffer, calling `write` repeatedly. Returns a Promise resolving to the total count written. |
| `writeIterableItem(value)` | Write one iterable yield. Matching numeric typed arrays are written as batches; all other values are written as one WIT item. Returns a Promise resolving to whether the complete value was written. |
| `cancelWrite()` | Cancel an in-progress async write. Returns `{ progress, result }` or `undefined` if the cancel itself blocks. |
| `drop()` | Drop the writable end, releasing the underlying handle. |
| `[Symbol.dispose]()` | Alias for `drop()`. |

### `FutureReadable`

Readable endpoint of a component-model future.

| Method | Description |
|---|---|
| `read()` | Read the future value. Returns a Promise that resolves with the value or rejects if the writer was dropped/cancelled. |
| `cancelRead()` | Cancel an in-progress async read. Returns the `CopyResult` code or `undefined` if the cancel blocks. |
| `drop()` | Drop the readable end. |
| `[Symbol.dispose]()` | Alias for `drop()`. |

### `FutureWritable`

Writable endpoint of a component-model future.

| Method | Description |
|---|---|
| `write(value)` | Write a value to the future. Returns a Promise resolving to `true` on success, `false` otherwise. |
| `cancelWrite()` | Cancel an in-progress async write. Returns the `CopyResult` code or `undefined` if the cancel blocks. |
| `drop()` | Drop the writable end. |
| `[Symbol.dispose]()` | Alias for `drop()`. |

---

## Hidden Object Properties

### `__cqjs_handle`

A numeric property set on JS objects that wrap imported or exported WIT
resources. Stores the canonical component-model resource handle (`u32`).

- Set on: Resource wrapper objects during `push_borrow`, `push_own`, and
  `exported_resource_to_handle` calls.
- Read by: `imported_resource_to_handle` and `exported_resource_to_handle`
  to retrieve the canonical handle.
- Removed: When an owned resource is lifted back to JS via `push_own`, the
  property is removed since the handle is no longer valid.

## WIT Import/Export Naming

### Import Interfaces

User code imports WIT interfaces as ES modules using their full WIT path:

```js
import random from "wasi:random/random@0.2.6";

export function getRandomU64() {
  return random.getRandomU64();
}
```

The runtime resolves both the versioned specifier and the versionless alias
internally, for example `wasi:random/random@0.2.6` and `wasi:random/random`.
The resolved module is a native runtime module whose exports call the host WIT
imports directly.

### Import Functions

WIT function names are converted from kebab-case to lowerCamelCase:

| WIT Name | JS Name |
|---|---|
| `get-random-bytes` | `getRandomBytes` |
| `my-function` | `myFunction` |

### Import Types

Enums, variants, flags, and records have no standalone runtime object; they are
represented directly by their values. Resources are exposed as classes.

| WIT Category | JS Representation | Example |
|---|---|---|
| Enums | case-name string | `"variant-a"` |
| Variants | `{ tag, val }` (string tag) | `{ tag: "case-a", val }` |
| Flags | `{ name: boolean }` object | `{ flagA: true, flagB: false }` |
| Records | object, camelCase fields | `{ fieldName: value }` |
| Resources | class instance; methods on prototype | `input.blockingRead(n)` |

### Export Functions

Export functions are looked up from the evaluated user ES module namespace
using the same lowerCamelCase convention, optionally nested under the
lowerCamelCase exported interface name.

### Result / Variant / Enum / Flags / Option Protocol

Top-level function returns of WIT `result<T, E>` use JavaScript's exception
convention: return the `ok` payload directly, or throw the `err` payload. When a
WIT import returns `err`, JavaScript receives a thrown object with the payload on
`error.payload`.

Nested WIT `result` values and all `variant` values are represented as plain
objects with a string `tag`:

```js
// nested result<string, u32>
{ tag: "ok", val: "hello" }
{ tag: "err", val: 42 }

// variant (tag is the case name)
{ tag: "circle", val: "payload" }
{ tag: "none" }  // no payload case
```

`enum` values are case-name strings (`"variant-a"`), `flags` are
`{ camelCaseName: boolean }` objects, and `option<T>` is `T | null` — except a
nested `option<option<T>>`, which is wrapped as `{ tag: "some", val } |
{ tag: "none" }` so that `none` and `some(none)` stay distinct.