jco

WIT result<T, E> types are handled differently depending on whether they are used in function signatures or stored in containers:

1. Function Return Values: Jco uses JavaScript exceptions. A successful return is a direct return value, while an error is handled by throw-ing.
   • If a function returns result<string, string>, throwing an error in JS satisfies the err case.
2. Container Types (Records, Options, etc.): If a result is stored inside another type, it is represented as a variant object: { tag: 'ok', val: T } | { tag: 'err', val: E }.
3. Host Implementation Tip: When a JS host throws an Error object, Jco can extract the error type if the error has a .payload property. This allows you to throw idiomatic JS errors while still satisfying WIT error types.

// Function return (Result as exception)
// WIT: f: func(n: u32) -> result<string, string>;
function f(n: number): string {
    if (n == 42) {
        return 'correct';
    }
    throw 'not correct';
}

// Result in a container (Result as variant)
// WIT: r: func(r: result<string, string>) -> string;
type Result<T,E> = { tag: 'ok', val: T } | { tag: 'err', val: E };

function f(input: Result<string, string>): string {
  switch (input.tag) {
    case 'ok': return `SUCCESS, returned: [${input.val}]`;
    case 'err': return `ERROR, returned: [${input.val}]`;
    default: throw Error("something has gone seriously wrong");
  }
}

// Host implementation using Error.payload
function justThrow() {
    const plainError = new Error('Error for JS users');
    const errorWithPayload = Object.assign(plainError, { payload: 1111 });
    throw errorWithPayload;
}

In optimized bindgen, resource handles are managed via ResourceTable, which is implemented as a JS array of integers. This table maps handles to resource IDs (reps).

Data Structure Details:

• Storage: Uses a JS array of integers. Each entry is a pair of u32 values.
• Bit Layout:
  • The lowest 29 bits are used for the value.
  • The bit 1 << 30 is the flag bit for all data values.
  • The highest bit is unused to avoid SMI deoptimization.
• Free List Entries: The high bit (bit 30) is set to indicate the pair is part of the free list. The first pair (indices 0 and 1) is the head. A value of 0 (after removing the flag) indicates the end of the list.
• Data Entries: The high bit is NOT set. The first value is the scope (ref count or scope ID) and the second is the rep (resource ID). The second value's high bit indicates if it is an 'own' handle.
• Indexing: To access handle n, read the pair at n * 2 and n * 2 + 1.

This project demonstrates how to use the Hono web framework within a WebAssembly component. The architecture relies on the following principles:

1. WASI HTTP Support: Web requests are handled via the wasi:http/incoming-handler interface. When using jco componentize, the StarlingMonkey runtime is used to provide this capability.
2. Standards Compliance: Hono is highly standards-compliant (following WinterCG/WinterTC), allowing it to run on WASI-compatible runtimes like StarlingMonkey without major changes.
3. NodeJS Integration: To run a component in a NodeJS environment, jco transpile is used. This creates a "virtual" WebAssembly + WASI host using @bytecodealliance/preview2-shim to handle incoming HTTP requests.
4. Enhanced Capabilities: By using @bytecodealliance/jco-std, the component can access wasi:cli/environment (for environment variables) and wasi:config/store (for custom configuration) on the WebAssembly platform.

The Jco repository is organized into several specialized subprojects: