This package provides VS Code's implementation of the WASM component model. It includes an implementation of the canonical ABI and the wit2ts tool, which is used to generate TypeScript bindings from a WIT (WebAssembly Interface Type) file.

Developers can use this to integrate WebAssembly modules into VS Code extensions, allowing for high-performance logic (e.g., written in Rust) to be called via typed TypeScript interfaces.

The @vscode/sync-api-common npm module implements a synchronous communication mechanism between two web workers. This allows a secondary worker to access asynchronous APIs from a main worker (running in Node.js or a Browser) in a synchronous manner.

Requirements and Constraints

• Shared Memory: The implementation relies on SharedArrayBuffers and Atomics.
• Environment Setup:
  • Node.js: Requires a modern version of Node that supports these features.
  • Browser: Requires specific security headers to be enabled (refer to MDN for details on SharedArrayBuffer requirements).
• Data Transfer: The library works most efficiently when using typed arrays (e.g., Uint8Array). When passing JSON structures, the library may perform two calls to the service to receive the data.

Control how memory is allocated and how threading is handled using these flags:

• USE_PTHREADS: Enables support for pthreads (equivalent to the -pthread flag). This requires IMPORTED_MEMORY to be enabled in many configurations.
• IMPORTED_MEMORY: Set to 1 to define the WebAssembly.Memory object in JavaScript outside of the Wasm module. This is required for:
  • USE_PTHREADS
  • RELOCATABLE
  • ASYNCIFY_LAZY_LOAD_CODE
  • WASM2JS (where WASM=0)

To use the sync API, you must define a shared request type that describes the method name, parameters, and the expected result shape using the VariableResult type. This type acts as the contract between the ClientConnection and the ServiceConnection.

import { VariableResult } from '@vscode/sync-api-common';

export type Requests = {
	method: 'getValue';
	params: {
		arg: number;
	};
	result: VariableResult<{ value: string }>;
}

To call the VS Code extension host from a WASM worker, the following lifecycle is currently required:

1. Proxy Installation: Install a function proxy on the WASM side.
2. Serialization: When the proxy is called, serialize arguments and copy data from WASM memory into a SharedArrayBuffer (the only currently viable way to share data with the extension host).
3. Message Passing: Post a message to the extension host thread.
4. Suspension: Suspend the WASM thread (note: this will be mitigated once WASM has native async support).
5. Execution: The extension host thread computes the necessary data.
6. Storage: The result is stored back into the SharedArrayBuffer.
7. Resumption: Resume the WASM worker thread.

Setting MODULARIZE = 1 changes the output from a global Module object to a factory function (default name Module, but configurable via EXPORT_NAME). This factory function returns a Promise that resolves with the module instance.

Usage Patterns:

// Using async/await (Recommended)
const module = await createModule({ option: value });

// Using .then()
let module;
createModule({ option: value }).then(instance => {
  module = instance;
});

Important Notes:

• When using MODULARIZE, default values for the module instance must be passed as an argument to the factory function, as the compiler will not look for a global Module object.
• If WASM_ASYNC_COMPILATION is disabled (synchronous compilation), the factory function returns the Module object directly instead of a Promise.

Emscripten provides a method for 'faux dynamic linking' using SIDE_MODULE and MAIN_MODULE flags. This allows you to compile a side module and link it to a main module for execution in a Node.js or browser environment.

emcc -c func1.c -o out/func1.o
emcc -sSIDE_MODULE out/func1.o -o func1.wasm
emcc -sMAIN_MODULE main.c func1.wasm -o main.js
node main.js

To create a WebAssembly module that uses static linking with the wasi-sdk, you must compile individual C source files into object files and then link them together into a single .wasm file. This process requires the clang tool provided by the wasi-sdk.

Workflow

1. Compile the dependency module (e.g., module1.c) to an object file.
2. Compile the main entry point (e.g., main.c) to an object file.
3. Link the object files into the final main.wasm binary.
4. Run the resulting module using a WASM runtime like wasmtime.

~/bin/wasi-sdk/bin/clang module1.c -c -o out/module1.o
~/bin/wasi-sdk/bin/clang main.c -c -o out/main.o
~/bin/wasi-sdk/bin/clang -o main.wasm out/module1.o out/main.o
wasmtime main.wasm

Expected Output

The result is 3