@bytecodealliance/jco-std

This @bytecodealliance/jco sub-project contains shared functionality and reusable libraries that can be used for building WebAssembly Components in Javascript.

WebAssembly Components are a WebAssembly binaries that use the Component Model, an evolving architecture for interoperable WebAssembly libraries, applications and environments.

WebAssembly components can be used from server side applications and in the browser, and @bytecodealliance/jco-std contains shared functionality and helpers for both environments.

@bytecodealliance/preview2-shim is an optional peer dependency used by the opt-in Node implementation of wasi:tls. Applications using this provider must share the same shim instance with their WASI sockets and streams: separate instances have different resource classes and IO workers. Use a shim version that satisfies the installed jco-std release's peer requirement. Other consumers do not need the shim.

Adapters

Below is a list of adapters provided by @bytecodealliance/jco-std:

HTTP

NodeJS API (experimental)

jco-std also makes available an experimental NodeJS API that is used by tools like jco to build NodeJS programs as components.

Quickstart

@bytecodealliance/jco-std can be used in varied ways via it's exports, this section contains some examples of how to get started quickly.

Http (via the Hono Adapter)

To use @bytecodealliance/jco-std to make building Hono applications easier with WebAssembly, use the @bytecodealliance/jco-std/http/adapters/hono export:

import { Hono } from "hono";

import { fire } from "@bytecodealliance/jco-std/wasi/0.2.x/http/adapters/hono/server";

const app = new Hono();
app.get("/", () => "Hello World!");

fire(app);

// Although we've called `fire()` with wasi HTTP configured for use above,
// we still need to actually export the `wasi:http/incoming-handler` interface object,
// as componentize-js will be looking for the ES module export.
export { incomingHandler } from "@bytecodealliance/jco-std/wasi/0.2.x/http/adapters/hono/server";

[!NOTE] We use @bytecodealliance/jco-std/wasi/0.2.x, but if you'd like to use a specific version, you can use an explicitly versioned export like @bytecodealliance/jco-std/wasi/0.2.12.

The 0.2.x path selects the newest WASI 0.2 adapter verified with the ComponentizeJS version used by Jco. It may change in any jco-std release. Use an explicitly versioned path when your component must retain an older WIT world.

Node.js compatibility APIs

[!WARNING] Jco's Node.js built-in compatibility for components is experimental and subject to change. APIs, behavior, and generated component interfaces may change incompatibly without a semver-major release.

The table above lists the available adapters. Application code should normally keep its node: imports and let jco componentize select the implementation. See the Node.js built-in compatibility guide for setup, versioning, capabilities, and compatibility boundaries.

node:path

import path, { matchesGlob } from "node:path";
import { join as winJoin } from "node:path/win32";

export function outputPath(name) {
  if (!matchesGlob(name, "**/*.js")) throw new TypeError("expected JavaScript");
  return `${path.resolve("dist", name)}|${winJoin("C:\\dist", name)}`;
}

See node:path.

node:string_decoder

import { Buffer } from "node:buffer";
import { StringDecoder } from "node:string_decoder";

const decoder = new StringDecoder("utf8");
decoder.write(Buffer.from([0xf0, 0x9f]));
decoder.end(Buffer.from([0x8c, 0x8d])); // "🌍"

See node:string_decoder.

node:repl

import repl from "node:repl";

export function attach(input, output) {
  const server = repl.start({ prompt: "app> ", input, output, useGlobal: true });
  server.context.app = { version: "1.0.0" };
  return server;
}

See node:repl.

node:tty

import { ReadStream, WriteStream, isatty } from "node:tty";

export function terminal() {
  if (!isatty(0) || !isatty(1)) throw new Error("a terminal is required");
  return { input: new ReadStream(0), output: new WriteStream(1) };
}

See node:tty.

node:wasi

import { WASI } from "node:wasi";

export function createWasi() {
  return new WASI({ version: "preview1" });
}

See node:wasi.

Node.js error globals

export function describeFailure() {
  const cause = new TypeError("invalid input");
  return new Error("operation failed", { cause }).cause.message;
}

See Node.js error globals.

node:child_process

import { execFileSync } from "node:child_process";

export function nodeVersion() {
  return execFileSync("node", ["--version"], { encoding: "utf8" }).trim();
}

See node:child_process.

node:fs

import { readFileSync } from "node:fs";
import { writeFile } from "node:fs/promises";

export async function replace(path, contents) {
  await writeFile(path, contents);
  return readFileSync(path, "utf8");
}

See node:fs.

node:os

import os from "node:os";

export function hostSummary() {
  return `${os.platform()} ${os.arch()} (${os.availableParallelism()} CPUs)`;
}

See node:os.

node:dns

import dns from "node:dns";
import dnsPromises from "node:dns/promises";

export function configuredServers() {
  return [...dns.getServers(), ...dnsPromises.getServers()];
}

See node:dns.

node:net

import { connect, createServer } from "node:net";

createServer((socket) => socket.end("hello")).listen(8080, "127.0.0.1");
connect(8080, "127.0.0.1").setEncoding("utf8").on("data", console.log);

See node:net.

node:http and node:https

import { createServer } from "node:http";
import { get } from "node:https";

createServer((request, response) => {
  response.end(`received ${request.method} ${request.url}`);
}).listen(8080, "127.0.0.1");

get("https://example.com/", (response) => response.resume());

See node:http and node:https.

node:http2

import { connect } from "node:http2";

const session = connect("https://example.com");
const stream = session.request({ ":path": "/status" });
stream.on("end", () => session.close());
stream.end();

See node:http2.

node:timers

import { setTimeout as delay, scheduler } from "node:timers/promises";

await delay(10, "ready");
await scheduler.yield();

See node:timers.

License

This project is licensed under the Apache 2.0 license with the LLVM exception. See LICENSE for more details.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this project by you, as defined in the Apache-2.0 license, shall be licensed as above, without any additional terms or conditions.