@bytecodealliance/jco 0.8.0 → 0.9.0

package/src/cmd/wasm-tools.js

@@ -0,0 +1,114 @@
+import { writeFile } from "node:fs/promises";
+import { readFile } from '../common.js';
+import { $init, print as printFn, parse as parseFn, componentWit as componentWitFn, componentNew as componentNewFn, componentEmbed as componentEmbedFn, metadataAdd as metadataAddFn, metadataShow as metadataShowFn } from "../../obj/wasm-tools.js";
+import { resolve, basename, extname } from 'node:path';
+import c from 'chalk-template';
+
+export async function parse(file, opts) {
+  await $init;
+  const source = (await readFile(file)).toString();
+  const output = parseFn(source);
+  await writeFile(opts.output, output);
+}
+
+export async function print(file, opts) {
+  await $init;
+  const source = await readFile(file);
+  const output = printFn(source);
+  if (opts.output) {
+    await writeFile(opts.output, output);
+  } else {
+    console.log(output);
+  }
+}
+
+export async function componentWit(file, opts) {
+  await $init;
+  const source = await readFile(file);
+  const output = componentWitFn(source, opts.document);
+  if (opts.output) {
+    await writeFile(opts.output, output);
+  } else {
+    console.log(output);
+  }
+}
+
+export async function componentNew(file, opts) {
+  await $init;
+  const source = file ? await readFile(file) : null;
+  let adapters = null;
+  if (opts.adapt)
+    adapters = await Promise.all(opts.adapt.map(async adapt => {
+      let adapter;
+      if (adapt.includes('='))
+        adapter = adapt.split('=');
+      else 
+        adapter = [basename(adapt).slice(0, -extname(adapt).length), adapt];
+      adapter[1] = await readFile(adapter[1]);
+      return adapter;
+    }));
+  const output = componentNewFn(source, adapters);
+  await writeFile(opts.output, output);
+}
+
+export async function componentEmbed(file, opts) {
+  await $init;
+  if (opts.metadata)
+    opts.metadata = opts.metadata.map(meta => {
+      const [field, data = ''] = meta.split('=');
+      const [name, version = ''] = data.split('@');
+      return [field, [[name, version]]];
+    });
+  const source = file ? await readFile(file) : null;
+  opts.binary = source;
+  opts.witPath = resolve(opts.wit);
+  const output = componentEmbedFn(opts);
+  await writeFile(opts.output, output);
+}
+
+export async function metadataAdd(file, opts) {
+  await $init;
+  const metadata = opts.metadata.map(meta => {
+    const [field, data = ''] = meta.split('=');
+    const [name, version = ''] = data.split('@');
+    return [field, [[name, version]]];
+  });
+  const source = await readFile(file);
+  const output = metadataAddFn(source, metadata);
+  await writeFile(opts.output, output);
+}
+
+export async function metadataShow(file, opts) {
+  await $init;
+  const source = await readFile(file);
+  let output = '', stack = [1];
+  const meta = metadataShowFn(source);
+  if (opts.json) {
+    console.log(JSON.stringify(meta, null, 2));
+  }
+  else {
+    for (const { name, metaType, producers } of meta) {
+      output += '  '.repeat(stack.length - 1);
+      const indent = '  '.repeat(stack.length);
+      if (metaType.tag === 'component') {
+        output += c`{bold [component${name ? ' ' + name : ''}]}\n`;
+        if (metaType.val > 0)
+          stack.push(metaType.val);
+      } else {
+        output += c`{bold [module${name ? ' ' + name : ''}]}\n`;
+      }
+      if (producers.length === 0)
+        output += `${indent}(no metadata)\n`;
+      for (const [field, items] of producers) {
+        for (const [name, version] of items) {
+          output += `${indent}${(field + ':').padEnd(13, ' ')} ${name}${version ? c`{cyan  ${version}}` : ''}\n`;
+        }
+      }
+      output += '\n';
+      if (stack[stack.length - 1] === 0)
+        stack.pop();
+      stack[stack.length - 1]--;
+    }
+    process.stdout.write(output);
+  }
+}

package/src/common.js

@@ -0,0 +1,104 @@
+import crypto from 'node:crypto';
+import { resolve } from 'node:path';
+import { tmpdir } from 'node:os';
+import { readFile, writeFile, unlink } from 'node:fs/promises';
+import { spawn } from 'node:child_process';
+import { argv0 } from 'node:process';
+import c from 'chalk-template';
+
+let _showSpinner = false;
+export function setShowSpinner (val) {
+  _showSpinner = val;
+}
+export function getShowSpinner () {
+  const showSpinner = _showSpinner;
+  _showSpinner = false;
+  return showSpinner;
+}
+
+export function sizeStr (num) {
+  num /= 1024;
+  if (num < 1000)
+    return `${fixedDigitDisplay(num, 4)} KiB`;
+  num /= 1024;
+  if (num < 1000)
+    return `${fixedDigitDisplay(num, 4)} MiB`;
+}
+
+export function fixedDigitDisplay (num, maxChars) {
+  const significantDigits = String(num).split('.')[0].length;
+  let str;
+  if (significantDigits >= maxChars - 1) {
+    str = String(Math.round(num));
+  } else {
+    const decimalPlaces = maxChars - significantDigits - 1;
+    const rounding = 10 ** decimalPlaces;
+    str = String(Math.round(num * rounding) / rounding);
+  }
+  if (maxChars - str.length < 0)
+    return str;
+  return ' '.repeat(maxChars - str.length) + str;
+}
+
+export function table (data, align = []) {
+  if (data.length === 0) return '';
+  const colLens = data.reduce((maxLens, cur) => maxLens.map((len, i) => Math.max(len, cur[i].length)), data[0].map(cell => cell.length));
+  let outTable = '';
+  for (const row of data) {
+    for (const [i, cell] of row.entries()) {
+      if (align[i] === 'right')
+        outTable += ' '.repeat(colLens[i] - cell.length) + cell;
+      else
+        outTable += cell + ' '.repeat(colLens[i] - cell.length);
+    }
+    outTable += '\n';
+  }
+  return outTable;
+}
+
+export function getTmpFile (source, ext) {
+  return resolve(tmpdir(), crypto.createHash('sha256').update(source).update(Math.random().toString()).digest('hex') + ext);
+}
+
+async function readFileCli (file, encoding) {
+  try {
+    return await readFile(file, encoding)
+  }
+  catch (e) {
+    throw c`Unable to read file {bold ${file}}`;
+  }
+}
+export { readFileCli as readFile }
+
+export async function spawnIOTmp (cmd, input, args) {
+  const inFile = getTmpFile(input, '.wasm');
+  let outFile = getTmpFile(inFile, '.wasm');
+
+  await writeFile(inFile, input);
+
+  const cp = spawn(argv0, [cmd, inFile, ...args, outFile], { stdio: 'pipe' });
+
+  let stderr = '';
+  const p = new Promise((resolve, reject) => {
+    cp.stderr.on('data', data => stderr += data.toString());
+    cp.on('error', e => {
+      reject(e);
+    });
+    cp.on('exit', code => {
+      if (code === 0)
+        resolve();
+      else
+        reject(stderr);
+    });
+  });
+
+  try {
+    await p;
+    var output = await readFile(outFile);
+    await Promise.all([unlink(inFile), unlink(outFile)]); 
+    return output;
+  } catch (e) {
+    await unlink(inFile);
+    throw e;
+  }
+}

package/src/jco.js

@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+import { program } from 'commander';
+import { opt } from './cmd/opt.js';
+import { transpile } from './cmd/transpile.js';
+import { parse, print, componentNew, componentEmbed, metadataAdd, metadataShow, componentWit } from './cmd/wasm-tools.js';
+import { componentize } from './cmd/componentize.js';
+import c from 'chalk-template';
+
+program
+  .name('jco')
+  .description(c`{bold jco - WebAssembly JS Component Tools}\n      JS Component Transpilation Bindgen & Wasm Tools for JS`)
+  .usage('<command> [options]')
+  .version('0.8.0');
+
+function myParseInt(value) {
+  return parseInt(value, 10);
+}
+
+program.command('componentize')
+  .description('Create a component from a JavaScript module')
+  .usage('<js-source> -o <component-path>')
+  .argument('<js-source>', 'JS source file to build')
+  .requiredOption('-w, --wit <path>', 'WIT path to build with')
+  .option('-n, --world-name <name>', 'WIT world to build')
+  .requiredOption('-o, --out <out>', 'output component file')
+  .action(asyncAction(componentize));
+
+program.command('transpile')
+  .description('Transpile a WebAssembly Component to JS + core Wasm for JavaScript execution')
+  .usage('<component-path> -o <out-dir>')
+  .argument('<component-path>', 'Wasm component binary filepath')
+  .option('--name <name>', 'custom output name')
+  .requiredOption('-o, --out-dir <out-dir>', 'output directory')
+  .option('-m, --minify', 'minify the JS output (--optimize / opt cmd still required)')
+  .option('-O, --optimize', 'optimize the component first')
+  .option('--no-typescript', 'do not output TypeScript .d.ts types')
+  .option('--valid-lifting-optimization', 'optimize component binary validations assuming all lifted values are valid')
+  .option('-b, --base64-cutoff <bytes>', 'set the byte size under which core Wasm binaries will be inlined as base64', myParseInt)
+  .option('--tla-compat', 'enables compatibility for JS environments without top-level await support via an async $init promise export')
+  .option('--no-nodejs-compat', 'disables compatibility in Node.js without a fetch global')
+  .option('-M, --map <mappings...>', 'specifier=./output custom mappings for the component imports')
+  .option('--no-wasi-shim', 'disable automatic rewriting of WASI imports to use @bytecodealliance/preview2-shim')
+  .option('--js', 'output JS instead of core WebAssembly')
+  .option('-I, --instantiation', 'output for custom module instantiation')
+  .option('-q, --quiet', 'disable logging')
+  .option('--', 'for --optimize, custom wasm-opt arguments (defaults to best size optimization)')
+  .action(asyncAction(transpile));
+
+program.command('opt')
+  .description('optimizes a Wasm component, including running wasm-opt Binaryen optimizations')
+  .usage('<component-file> -o <output-file>')
+  .argument('<component-file>', 'Wasm component binary filepath')
+  .requiredOption('-o, --output <output-file>', 'optimized component output filepath')
+  .option('-q, --quiet')
+  .option('--', 'custom wasm-opt arguments (defaults to best size optimization)')
+  .action(asyncAction(opt));
+
+program.command('wit')
+  .description('extract the WIT from a WebAssembly Component [wasm-tools component wit]')
+  .argument('<component-path>', 'Wasm component binary filepath')
+  .option('-d, --document <name>', 'WIT document of a package to print')
+  .option('-o, --output <output-file>', 'WIT output file path')
+  .action(asyncAction(componentWit));
+
+program.command('print')
+  .description('print the WebAssembly WAT text for a binary file [wasm-tools print]')
+  .argument('<input>', 'input file to process')
+  .option('-o, --output <output-file>', 'output file path')
+  .action(asyncAction(print));
+
+program.command('metadata-show')
+  .description('extract the producer metadata for a Wasm binary [wasm-tools metadata show]')
+  .argument('[module]', 'Wasm component or core module filepath')
+  .option('--json', 'output component metadata as JSON')
+  .action(asyncAction(metadataShow));
+
+program.command('metadata-add')
+  .description('add producer metadata for a Wasm binary [wasm-tools metadata add]')
+  .argument('[module]', 'Wasm component or core module filepath')
+  .requiredOption('-m, --metadata <metadata...>', 'field=name[@version] producer metadata to add with the embedding')
+  .requiredOption('-o, --output <output-file>', 'output binary path')
+  .action(asyncAction(metadataAdd));
+
+program.command('parse')
+  .description('parses the Wasm text format into a binary file [wasm-tools parse]')
+  .argument('<input>', 'input file to process')
+  .requiredOption('-o, --output <output-file>', 'output binary file path')
+  .action(asyncAction(parse));
+
+program.command('new')
+  .description('create a WebAssembly component adapted from a component core Wasm [wasm-tools component new]')
+  .argument('<core-module>', 'Wasm core module filepath')
+  .requiredOption('-o, --output <output-file>', 'Wasm component output filepath')
+  .option('--name <name>', 'custom output name')
+  .option('--adapt <[NAME=]adapter...>', 'component adapters to apply')
+  .action(asyncAction(componentNew));
+
+program.command('embed')
+  .description('embed the component typing section into a core Wasm module [wasm-tools component embed]')
+  .argument('[core-module]', 'Wasm core module filepath')
+  .requiredOption('-o, --output <output-file>', 'Wasm component output filepath')
+  .requiredOption('--wit <wit-world>', 'WIT world path')
+  .option('--dummy', 'generate a dummy component')
+  .option('--string-encoding <utf8|utf16|compact-utf16>', 'set the component string encoding')
+  .option('--world <world-name>', 'positional world path to embed')
+  .option('-m, --metadata <metadata...>', 'field=name[@version] producer metadata to add with the embedding')
+  .action(asyncAction(componentEmbed));
+
+program.parse();
+
+function asyncAction (cmd) {
+  return function () {
+    const args = [...arguments];
+    (async () => {
+      try {
+        await cmd.apply(null, args);
+      }
+      catch (e) {
+        process.stdout.write(`(jco ${cmd.name}) `);
+        if (typeof e === 'string') {
+          console.error(c`{red.bold Error}: ${e}\n`);
+        } else {
+          console.error(e);
+        }
+        process.exit(1);
+      }
+    })();
+  };
+}

package/api.d.ts

@@ -1,109 +0,0 @@
-/**
- * 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[],
-  /// rewrites WASI imports to the @bytecodealliance/preview2-shim
-  /// defaults to true
-  wasiShim?: boolean
-}
-
-export interface EmbedOpts {
-  /// Component binary to embed
-  binary?: Uint8Array,
-  /// Pass an inline WIT source
-  witSource?: string,
-  /// Pass the file system path to WIT file
-  /// Either a path or a source must be passed not both
-  witPath?: string,
-  /// String encoding for the component functions
-  stringEncoding?: 'utf8' | 'utf16',
-  /// Generate a dummy component
-  dummy: option<bool>,
-  /// World name to embed
-  world?: string,
-  /// Metadata to embed
-  metadata?: Metadata
-}
-
-/**
- * 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(opts: EmbedOpts): 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>;