@bytecodealliance/jco 0.4.0

package/README.md

@@ -0,0 +1,136 @@
+<div align="center">
+  <h1><code>jco</code></h1>
+
+  <p>
+    <strong>JavaScript component toolchain for working with <a href="https://github.com/WebAssembly/component-model">WebAssembly Components</a></strong>
+  </p>
+
+  <strong>A <a href="https://bytecodealliance.org/">Bytecode Alliance</a> project</strong>
+
+  <p>
+    <a href="https://github.com/bytecodealliance/jco/actions?query=workflow%3ACI"><img src="https://github.com/bytecodealliance/jco/workflows/CI/badge.svg" alt="build status" /></a>
+  </p>
+</div>
+
+## Overview
+
+`jco` is a fully native JS tool for working with the emerging [WebAssembly Components](https://github.com/WebAssembly/component-model) specification in JavaScript.
+
+Features include:
+
+* "Transpiling" Wasm Component binaries into ES modules that can run in any JS environment.
+* Optimization helpers for Components via Binaryen
+* Component builds of [Wasm Tools](https://github.com/bytecodealliance/wasm-tools) helpers, available for use as a library or CLI commands for use in native JS environments.
+
+For creating components, see the [Cargo Component](https://github.com/bytecodealliance/cargo-Component) project for Rust and [Wit Bindgen](https://github.com/bytecodealliance/wit-bindgen) for various guest bindgen helpers.
+
+> **Note**: This is an experimental project, no guarantees are provided for stability or support and breaking changes may be made in future.
+
+## Installation
+
+```shell
+npm install @bytecodealliance/jco
+```
+
+jco can be used as either a library or as a CLI via the `jco` CLI command.
+
+## Example
+
+See the [example workflow](EXAMPLE.md) page for a full usage example.
+
+## API
+
+The below is an outline of the available API functions, see [api.d.ts](api.d.ts) file for the exact options.
+
+#### `transpile(component: Uint8Array, opts?): Promise<{ files: Record<string, Uint8Array> }>`
+
+Transpile a Component to JS.
+
+**Transpilation options:**
+
+* `name?: string` - name for the generated JS file.
+* `instantiation?: bool` - instead of a direct ES module, output the raw instantiation function for custom virtualization.
+* `map?: Record<string, string>` - remap component imports
+* `validLiftingOptimization?: bool` - optimization to reduce code size
+* `noNodejsCompat?: bool` - disables Node.js compatible output
+* `tlaCompat?: bool` - enable compat in JS runtimes without TLA support
+* `base64Cutoff?: number` - size in bytes, under which Wasm modules get inlined as base64.
+* `js?: bool` - convert Wasm into JS instead for execution compatibility in JS environments without Wasm support.
+* `minify?: bool` - minify the output JS.
+* `optimize?: bool` - optimize the component with Binaryen wasm-opt first.
+* `optArgs?: string[]` - if using optimize, custom optimization options (defaults to best optimization, but this is very slow)
+
+#### `opt(component: Uint8Array, opts?): Promise<{ component: Uint8Array }>`
+
+Optimize a Component with the [Binaryen Wasm-opt](https://www.npmjs.com/package/binaryen) project.
+
+#### `componentWit(component: Uint8Array, document?: string): string`
+
+Extract the WIT world from a component binary.
+
+#### `print(component: Uint8Array): string`
+
+Print the WAT for a Component binary.
+
+#### `metadataShow(wasm: Uint8Array): Metadata`
+
+Extract the producer toolchain metadata for a component and its nested modules.
+
+#### `parse(wat: string): Uint8Array`
+
+Parse a compoment WAT to output a Component binary.
+
+#### `componentNew(coreWasm: Uint8Array | null, adapters?: [String, Uint8Array][]): Uint8Array`
+
+"WIT Component" Component creation tool, optionally providing a set of named adapter binaries.
+
+#### `componentEmbed(coreWasm: Uint8Array | null, wit: String, opts?: { stringEncoding?, dummy?, world?, metadata? }): Uint8Array`
+
+"WIT Component" Component embedding tool, for embedding component types into core binaries, as an advanced use case of component generation.
+
+#### `metadataAdd(wasm: Uint8Array, metadata): Uint8Array`
+
+Add new producer metadata to a component or core Wasm binary.
+
+## CLI
+
+```shell
+Usage: jco <command> [options]
+
+jco - WebAssembly JS Component Tools
+      JS Component Bindgen & Wasm Tools for JS
+
+Options:
+  -V, --version                         output the version number
+  -h, --help                            display help for command
+
+Commands:
+  transpile [options] <component-path>  Transpile a WebAssembly Component to JS + core Wasm for JavaScript execution
+  opt [options] <component-file>        optimizes a Wasm component, including running wasm-opt Binaryen optimizations
+  wit [options] <component-path>        extract the WIT from a WebAssembly Component [wasm-tools component wit]
+  print [options] <input>               print the WebAssembly WAT text for a binary file [wasm-tools print]
+  metadata [options] [module]           extract the producer metadata for a Wasm binary [wasm-tools metadata show]
+  parse [options] <input>               parses the Wasm text format into a binary file [wasm-tools parse]
+  new [options] <core-module>           create a WebAssembly component adapted from a component core Wasm [wasm-tools component new]
+  embed [options] [core-module]         embed the component typing section into a core Wasm module [wasm-tools component embed]
+  help [command]                        display help for command
+```
+
+## Contributing
+
+Development is based on a standard `npm install && npm run build && npm run test` workflow.
+
+Tests can be run without bundling via `npm run build:dev && npm run test:dev`.
+
+Specific tests can be run adding the mocha `--grep` flag, for example: `npm run test:dev -- --grep exports_only`.
+
+# License
+
+This project is licensed under the Apache 2.0 license with the LLVM exception.
+See [LICENSE](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.

package/api.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Optimize a Component with Binaryen wasm-opt optimizations
+ */
+export function opt(componentBytes: Uint8Array, opts?: { quiet: boolean; optArgs?: string[] }): Promise<{
+  component: Uint8Array,
+  compressionInfo: { beforeBytes: number, afterBytes: number }[]
+}>;
+
+export interface TranspileOpts {
+  /// name for the generated JS file.
+  name?: string,
+  /// instead of a direct ES module, output the raw 
+  /// instantiation function for custom virtualization.
+  instantiation?: boolean,
+  /// remap Component imports
+  map?: Record<string, string>,
+  /// optimization to reduce code size
+  validLiftingOptimization?: boolean,
+  /// disables Node.js compatible output
+  noNodejsCompat?: boolean,
+  /// enable compat in JS runtimes without TLA support
+  tlaCompat?: boolean,
+  /// size in bytes, under which Wasm modules get inlined as base64.
+  base64Cutoff?: number,
+  /// use asm.js instead of core WebAssembly for execution.
+  asm?: boolean,
+  /// minify the output JS.
+  minify?: boolean,
+  /// optimize the Component with Binaryen wasm-opt first.
+  optimize?: boolean,
+  /// if using optimize, custom optimization options
+  /// (defaults to best optimization, but this is very slow)
+  optArgs?: string[],
+}
+
+/**
+ * Transpile a Component into a JS-executable package
+ */
+export function transpile(component: Uint8Array, opts?: TranspileOpts): Promise<{
+  files: Record<string, Uint8Array>,
+  imports: string[],
+  exports: [string, 'function' | 'instance'][]
+}>;
+
+/**
+ * Parse a WAT string into a Wasm binary
+ */
+export function parse(wat: string): Uint8Array;
+
+/**
+ * Print a Wasm binary as a WAT string
+ */
+export function print(binary: Uint8Array | ArrayBuffer): string;
+
+/**
+ * WIT Component - create a Component from a Wasm core binary
+ */
+export function componentNew(binary: Uint8Array | ArrayBuffer, adapters?: [string, Uint8Array][] | null): Uint8Array;
+
+type Metadata = [string, [string, string][]][];
+
+/**
+ * Embed a world into a Wasm core binary
+ */
+export function componentEmbed(binary: Uint8Array | ArrayBuffer | null, wit: string, opts: {
+  stringEncoding?: 'utf8' | 'utf16' | 'compact-utf16',
+  dummy?: boolean,
+  world?: string,
+  metadata?: Metadata
+}): Uint8Array;
+
+/**
+ * Extract the producer metadata for a Wasm component or core module
+ */
+export function metadataShow(binary: Uint8Array | ArrayBuffer): {
+  name?: string,
+  metaType: { tag: 'module' } | { tag: 'component', val: number },
+  metadata: Metadata
+}[];
+
+/**
+ * Extract the producer metadata for a Wasm component or core module
+ */
+export function metadataAdd(binary: Uint8Array | ArrayBuffer, metadata: Metadata): Uint8Array;
+
+/**
+ * Extract the WIT world from a Wasm Component
+ */
+export function componentWit(binary: Uint8Array | ArrayBuffer, document?: string | null): string;
+
+export type StringEncoding = 'utf8' | 'utf16' | 'compact-utf16';
+
+export const $init: Promise<void>;