@bytecodealliance/jco 0.10.3 → 0.11.1

package/README.md

@@ -54,6 +54,7 @@ Options:
 Commands:
   componentize [options] <js-source>    Create a component from a JavaScript module
   transpile [options] <component-path>  Transpile a WebAssembly Component to JS + core Wasm for JavaScript execution
+  run <command> [args...]               Run a WebAssembly Command component
   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]
@@ -98,7 +99,7 @@ Options include:
 * `--js`: Converts core Wasm files to JavaScript for environments that don't even support core Wasm.
 * `--base64-cutoff=<number>`: Sets the maximum number of bytes for inlining Wasm files into the JS using base64 encoding. Set to zero to disable base64 inlining entirely.
 * `--no-wasi-shim`: Disable the WASI shim mapping to `@bytecodealliance/preview2-shim`.
-* `--map`: Provide custom mappings for world imports. Supports both wildcard mappings (`*` similarly as in the package.json "exports" field) as well as `#` mappings for targetting exported interfaces. For example, the WASI mappings are internally defined with mappings like `--map wasi:filesystem/*=@bytecodealliance/preview2-shim/filesystem#*` to map `import as * filesystem from 'wasi:filesystem/filesystem'` to `import { filesystem } from '@bytecodealliance/preview2-shim/filesystem`.
+* `--map`: Provide custom mappings for world imports. Supports both wildcard mappings (`*` similarly as in the package.json "exports" field) as well as `#` mappings for targetting exported interfaces. For example, the WASI mappings are internally defined with mappings like `--map wasi:filesystem/*=@bytecodealliance/preview2-shim/filesystem#*` to map `import as * filesystem from 'wasi:filesystem/types'` to `import { types } from '@bytecodealliance/preview2-shim/filesystem`.
 * `--no-nodejs-compat`: Disables Node.js compat in the output to load core Wasm with FS methods.
 * `--instantiation`: Instead of a direct ES module, export an `instantiate` function which can take the imports as an argument instead of implicit imports.
 * `--valid-lifting-optimization`: Internal validations are removed assuming that core Wasm binaries are valid components, providing a minor output size saving.
@@ -123,6 +124,18 @@ See [ComponentizeJS](https://github.com/bytecodealliance/componentize-js) for mo
 
 > Additional engines may be supported in future via an `--engine` field or otherwise.
 
+### Run
+
+For Wasm components that implement the WASI Command world, a `jco run` utility is provided to run these applications in Node.js:
+
+```
+jco run cowasy.component.wasm hello
+```
+
+Using the preview2-shim WASI implementation, full access to the underlying system primitives is provided, including filesystem and environment variable permissions.
+
+> Since [preview2-shim](packages/preview2-shim) is an experimental work-in-progress implementation, there will likely be bugs.
+
 ## API
 
 #### `transpile(component: Uint8Array, opts?): Promise<{ files: Record<string, Uint8Array> }>`
@@ -178,4 +191,4 @@ See [LICENSE](LICENSE) for more details.
 
 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.
+shall be licensed as above, without any additional terms or conditions.

package/obj/exports/local-wasm-tools-tools.d.ts

@@ -0,0 +1,43 @@
+export namespace LocalWasmToolsTools {
+  export function parse(wat: string): Uint8Array;
+  export function print(binary: Uint8Array | ArrayBuffer): string;
+  export function componentNew(binary: Uint8Array | ArrayBuffer, adapters: [string, Uint8Array | ArrayBuffer][] | null): Uint8Array;
+  export function componentWit(binary: Uint8Array | ArrayBuffer): string;
+  export function componentEmbed(embedOpts: EmbedOpts): Uint8Array;
+  export function metadataShow(binary: Uint8Array | ArrayBuffer): ModuleMetadata[];
+  export function metadataAdd(binary: Uint8Array | ArrayBuffer, metadata: ProducersFields): Uint8Array;
+}
+/**
+ * # Variants
+ * 
+ * ## `"utf8"`
+ * 
+ * ## `"utf16"`
+ * 
+ * ## `"compact-utf16"`
+ */
+export type StringEncoding = 'utf8' | 'utf16' | 'compact-utf16';
+export type ProducersFields = [string, [string, string][]][];
+export interface EmbedOpts {
+  binary?: Uint8Array,
+  witSource?: string,
+  witPath?: string,
+  stringEncoding?: StringEncoding,
+  dummy?: boolean,
+  world?: string,
+  metadata?: ProducersFields,
+}
+export type ModuleMetaType = ModuleMetaTypeModule | ModuleMetaTypeComponent;
+export interface ModuleMetaTypeModule {
+  tag: 'module',
+}
+export interface ModuleMetaTypeComponent {
+  tag: 'component',
+  val: number,
+}
+export interface ModuleMetadata {
+  name?: string,
+  metaType: ModuleMetaType,
+  range: [number, number],
+  producers: ProducersFields,
+}

package/obj/{interfaces/environment.d.ts → exports/wasi-cli-environment.d.ts}

@@ -1,3 +1,3 @@
-export namespace Environment {
+export namespace WasiCliEnvironment {
   export function getEnvironment(): [string, string][];
 }

package/obj/{interfaces/exit.d.ts → exports/wasi-cli-exit.d.ts}

@@ -1,4 +1,4 @@
-export namespace Exit {
+export namespace WasiCliExit {
   export function exit(status: Result<void, void>): void;
 }
 export type Result<T, E> = { tag: 'ok', val: T } | { tag: 'err', val: E };

package/obj/exports/wasi-cli-stderr.d.ts

@@ -0,0 +1,5 @@
+export namespace WasiCliStderr {
+  export function getStderr(): OutputStream;
+}
+import type { OutputStream } from '../exports/wasi-io-streams';
+export { OutputStream };

package/obj/exports/wasi-cli-stdin.d.ts

@@ -0,0 +1,5 @@
+export namespace WasiCliStdin {
+  export function getStdin(): InputStream;
+}
+import type { InputStream } from '../exports/wasi-io-streams';
+export { InputStream };

package/obj/exports/wasi-cli-stdout.d.ts

@@ -0,0 +1,5 @@
+export namespace WasiCliStdout {
+  export function getStdout(): OutputStream;
+}
+import type { OutputStream } from '../exports/wasi-io-streams';
+export { OutputStream };

package/obj/exports/wasi-cli-terminal-input.d.ts

@@ -0,0 +1,4 @@
+export namespace WasiCliTerminalInput {
+  export function dropTerminalInput(this_: TerminalInput): void;
+}
+export type TerminalInput = number;

package/obj/exports/wasi-cli-terminal-output.d.ts

@@ -0,0 +1,4 @@
+export namespace WasiCliTerminalOutput {
+  export function dropTerminalOutput(this_: TerminalOutput): void;
+}
+export type TerminalOutput = number;

package/obj/exports/wasi-cli-terminal-stderr.d.ts

@@ -0,0 +1,5 @@
+export namespace WasiCliTerminalStderr {
+  export function getTerminalStderr(): TerminalOutput | null;
+}
+import type { TerminalOutput } from '../exports/wasi-cli-terminal-output';
+export { TerminalOutput };

package/obj/exports/wasi-cli-terminal-stdin.d.ts

@@ -0,0 +1,5 @@
+export namespace WasiCliTerminalStdin {
+  export function getTerminalStdin(): TerminalInput | null;
+}
+import type { TerminalInput } from '../exports/wasi-cli-terminal-input';
+export { TerminalInput };

package/obj/exports/wasi-cli-terminal-stdout.d.ts

@@ -0,0 +1,5 @@
+export namespace WasiCliTerminalStdout {
+  export function getTerminalStdout(): TerminalOutput | null;
+}
+import type { TerminalOutput } from '../exports/wasi-cli-terminal-output';
+export { TerminalOutput };

package/obj/exports/wasi-filesystem-preopens.d.ts

@@ -0,0 +1,5 @@
+export namespace WasiFilesystemPreopens {
+  export function getDirectories(): [Descriptor, string][];
+}
+import type { Descriptor } from '../exports/wasi-filesystem-types';
+export { Descriptor };

package/obj/{interfaces/filesystem.d.ts → exports/wasi-filesystem-types.d.ts}

@@ -1,16 +1,17 @@
-export namespace Filesystem {
-  export function readViaStream(this: Descriptor, offset: Filesize): InputStream;
-  export function writeViaStream(this: Descriptor, offset: Filesize): OutputStream;
-  export function appendViaStream(this: Descriptor): OutputStream;
-  export function getType(this: Descriptor): DescriptorType;
-  export function stat(this: Descriptor): DescriptorStat;
-  export function openAt(this: Descriptor, pathFlags: PathFlags, path: string, openFlags: OpenFlags, flags: DescriptorFlags, modes: Modes): Descriptor;
-  export function dropDescriptor(this: Descriptor): void;
-  export function dropDirectoryEntryStream(this: DirectoryEntryStream): void;
+export namespace WasiFilesystemTypes {
+  export function readViaStream(this_: Descriptor, offset: Filesize): InputStream;
+  export function writeViaStream(this_: Descriptor, offset: Filesize): OutputStream;
+  export function appendViaStream(this_: Descriptor): OutputStream;
+  export function getType(this_: Descriptor): DescriptorType;
+  export function stat(this_: Descriptor): DescriptorStat;
+  export function openAt(this_: Descriptor, pathFlags: PathFlags, path: string, openFlags: OpenFlags, flags: DescriptorFlags, modes: Modes): Descriptor;
+  export function dropDescriptor(this_: Descriptor): void;
+  export function dropDirectoryEntryStream(this_: DirectoryEntryStream): void;
+  export function metadataHash(this_: Descriptor): MetadataHashValue;
 }
 export type Descriptor = number;
 export type Filesize = bigint;
-import type { InputStream } from '../interfaces/wasi-io-streams';
+import type { InputStream } from '../exports/wasi-io-streams';
 export { InputStream };
 /**
  * # Variants
@@ -90,7 +91,7 @@ export { InputStream };
  * ## `"cross-device"`
  */
 export type ErrorCode = 'access' | 'would-block' | 'already' | 'bad-descriptor' | 'busy' | 'deadlock' | 'quota' | 'exist' | 'file-too-large' | 'illegal-byte-sequence' | 'in-progress' | 'interrupted' | 'invalid' | 'io' | 'is-directory' | 'loop' | 'too-many-links' | 'message-size' | 'name-too-long' | 'no-device' | 'no-entry' | 'no-lock' | 'insufficient-memory' | 'insufficient-space' | 'not-directory' | 'not-empty' | 'not-recoverable' | 'unsupported' | 'no-tty' | 'no-such-device' | 'overflow' | 'not-permitted' | 'pipe' | 'read-only' | 'invalid-seek' | 'text-file-busy' | 'cross-device';
-import type { OutputStream } from '../interfaces/wasi-io-streams';
+import type { OutputStream } from '../exports/wasi-io-streams';
 export { OutputStream };
 /**
  * # Variants
@@ -112,14 +113,10 @@ export { OutputStream };
  * ## `"socket"`
  */
 export type DescriptorType = 'unknown' | 'block-device' | 'character-device' | 'directory' | 'fifo' | 'symbolic-link' | 'regular-file' | 'socket';
-export type Device = bigint;
-export type Inode = bigint;
 export type LinkCount = bigint;
-import type { Datetime } from '../interfaces/wasi-clocks-wall-clock';
+import type { Datetime } from '../exports/wasi-clocks-wall-clock';
 export { Datetime };
 export interface DescriptorStat {
-  device: Device,
-  inode: Inode,
   type: DescriptorType,
   linkCount: LinkCount,
   size: Filesize,
@@ -150,3 +147,7 @@ export interface Modes {
   executable?: boolean,
 }
 export type DirectoryEntryStream = number;
+export interface MetadataHashValue {
+  lower: bigint,
+  upper: bigint,
+}

package/obj/exports/wasi-io-streams.d.ts

@@ -0,0 +1,18 @@
+export namespace WasiIoStreams {
+  export function read(this_: InputStream, len: bigint): [Uint8Array, StreamStatus];
+  export function blockingRead(this_: InputStream, len: bigint): [Uint8Array, StreamStatus];
+  export function dropInputStream(this_: InputStream): void;
+  export function write(this_: OutputStream, buf: Uint8Array | ArrayBuffer): [bigint, StreamStatus];
+  export function blockingWrite(this_: OutputStream, buf: Uint8Array | ArrayBuffer): [bigint, StreamStatus];
+  export function dropOutputStream(this_: OutputStream): void;
+}
+export type InputStream = number;
+/**
+ * # Variants
+ * 
+ * ## `"open"`
+ * 
+ * ## `"ended"`
+ */
+export type StreamStatus = 'open' | 'ended';
+export type OutputStream = number;

package/obj/imports/{wasi-cli-base-environment.d.ts → wasi-cli-environment.d.ts}

@@ -1,3 +1,3 @@
-export namespace WasiCliBaseEnvironment {
+export namespace WasiCliEnvironment {
   export function getEnvironment(): [string, string][];
 }

package/obj/{interfaces/wasi-cli-base-exit.d.ts → imports/wasi-cli-exit.d.ts}

@@ -1,4 +1,4 @@
-export namespace WasiCliBaseExit {
+export namespace WasiCliExit {
   export function exit(status: Result<void, void>): void;
 }
 export type Result<T, E> = { tag: 'ok', val: T } | { tag: 'err', val: E };

package/obj/imports/{wasi-cli-base-stderr.d.ts → wasi-cli-stderr.d.ts}

@@ -1,4 +1,4 @@
-export namespace WasiCliBaseStderr {
+export namespace WasiCliStderr {
   export function getStderr(): OutputStream;
 }
 import type { OutputStream } from '../imports/wasi-io-streams';

package/obj/imports/{wasi-cli-base-stdin.d.ts → wasi-cli-stdin.d.ts}

@@ -1,4 +1,4 @@
-export namespace WasiCliBaseStdin {
+export namespace WasiCliStdin {
   export function getStdin(): InputStream;
 }
 import type { InputStream } from '../imports/wasi-io-streams';

package/obj/imports/{wasi-cli-base-stdout.d.ts → wasi-cli-stdout.d.ts}

@@ -1,4 +1,4 @@
-export namespace WasiCliBaseStdout {
+export namespace WasiCliStdout {
   export function getStdout(): OutputStream;
 }
 import type { OutputStream } from '../imports/wasi-io-streams';

package/obj/imports/wasi-cli-terminal-input.d.ts

@@ -0,0 +1,4 @@
+export namespace WasiCliTerminalInput {
+  export function dropTerminalInput(this_: TerminalInput): void;
+}
+export type TerminalInput = number;

package/obj/imports/wasi-cli-terminal-output.d.ts

@@ -0,0 +1,4 @@
+export namespace WasiCliTerminalOutput {
+  export function dropTerminalOutput(this_: TerminalOutput): void;
+}
+export type TerminalOutput = number;

package/obj/imports/wasi-cli-terminal-stderr.d.ts

@@ -0,0 +1,5 @@
+export namespace WasiCliTerminalStderr {
+  export function getTerminalStderr(): TerminalOutput | null;
+}
+import type { TerminalOutput } from '../imports/wasi-cli-terminal-output';
+export { TerminalOutput };

package/obj/imports/wasi-cli-terminal-stdin.d.ts

@@ -0,0 +1,5 @@
+export namespace WasiCliTerminalStdin {
+  export function getTerminalStdin(): TerminalInput | null;
+}
+import type { TerminalInput } from '../imports/wasi-cli-terminal-input';
+export { TerminalInput };

package/obj/imports/wasi-cli-terminal-stdout.d.ts

@@ -0,0 +1,5 @@
+export namespace WasiCliTerminalStdout {
+  export function getTerminalStdout(): TerminalOutput | null;
+}
+import type { TerminalOutput } from '../imports/wasi-cli-terminal-output';
+export { TerminalOutput };

package/obj/imports/wasi-filesystem-preopens.d.ts

@@ -0,0 +1,5 @@
+export namespace WasiFilesystemPreopens {
+  export function getDirectories(): [Descriptor, string][];
+}
+import type { Descriptor } from '../imports/wasi-filesystem-types';
+export { Descriptor };

package/obj/imports/{wasi-filesystem-filesystem.d.ts → wasi-filesystem-types.d.ts}

@@ -1,12 +1,13 @@
-export namespace WasiFilesystemFilesystem {
-  export function readViaStream(this: Descriptor, offset: Filesize): InputStream;
-  export function writeViaStream(this: Descriptor, offset: Filesize): OutputStream;
-  export function appendViaStream(this: Descriptor): OutputStream;
-  export function getType(this: Descriptor): DescriptorType;
-  export function stat(this: Descriptor): DescriptorStat;
-  export function openAt(this: Descriptor, pathFlags: PathFlags, path: string, openFlags: OpenFlags, flags: DescriptorFlags, modes: Modes): Descriptor;
-  export function dropDescriptor(this: Descriptor): void;
-  export function dropDirectoryEntryStream(this: DirectoryEntryStream): void;
+export namespace WasiFilesystemTypes {
+  export function readViaStream(this_: Descriptor, offset: Filesize): InputStream;
+  export function writeViaStream(this_: Descriptor, offset: Filesize): OutputStream;
+  export function appendViaStream(this_: Descriptor): OutputStream;
+  export function getType(this_: Descriptor): DescriptorType;
+  export function stat(this_: Descriptor): DescriptorStat;
+  export function openAt(this_: Descriptor, pathFlags: PathFlags, path: string, openFlags: OpenFlags, flags: DescriptorFlags, modes: Modes): Descriptor;
+  export function dropDescriptor(this_: Descriptor): void;
+  export function dropDirectoryEntryStream(this_: DirectoryEntryStream): void;
+  export function metadataHash(this_: Descriptor): MetadataHashValue;
 }
 export type Descriptor = number;
 export type Filesize = bigint;
@@ -112,14 +113,10 @@ export { OutputStream };
  * ## `"socket"`
  */
 export type DescriptorType = 'unknown' | 'block-device' | 'character-device' | 'directory' | 'fifo' | 'symbolic-link' | 'regular-file' | 'socket';
-export type Device = bigint;
-export type Inode = bigint;
 export type LinkCount = bigint;
 import type { Datetime } from '../imports/wasi-clocks-wall-clock';
 export { Datetime };
 export interface DescriptorStat {
-  device: Device,
-  inode: Inode,
   type: DescriptorType,
   linkCount: LinkCount,
   size: Filesize,
@@ -150,3 +147,7 @@ export interface Modes {
   executable?: boolean,
 }
 export type DirectoryEntryStream = number;
+export interface MetadataHashValue {
+  lower: bigint,
+  upper: bigint,
+}

package/obj/imports/wasi-io-streams.d.ts

@@ -1,10 +1,10 @@
 export namespace WasiIoStreams {
-  export function read(this: InputStream, len: bigint): [Uint8Array | ArrayBuffer, StreamStatus];
-  export function blockingRead(this: InputStream, len: bigint): [Uint8Array | ArrayBuffer, StreamStatus];
-  export function dropInputStream(this: InputStream): void;
-  export function write(this: OutputStream, buf: Uint8Array): [bigint, StreamStatus];
-  export function blockingWrite(this: OutputStream, buf: Uint8Array): [bigint, StreamStatus];
-  export function dropOutputStream(this: OutputStream): void;
+  export function read(this_: InputStream, len: bigint): [Uint8Array | ArrayBuffer, StreamStatus];
+  export function blockingRead(this_: InputStream, len: bigint): [Uint8Array | ArrayBuffer, StreamStatus];
+  export function dropInputStream(this_: InputStream): void;
+  export function write(this_: OutputStream, buf: Uint8Array): [bigint, StreamStatus];
+  export function blockingWrite(this_: OutputStream, buf: Uint8Array): [bigint, StreamStatus];
+  export function dropOutputStream(this_: OutputStream): void;
 }
 export type InputStream = number;
 /**
@@ -15,7 +15,4 @@ export type InputStream = number;
  * ## `"ended"`
  */
 export type StreamStatus = 'open' | 'ended';
-export interface StreamError {
-  dummy: number,
-}
 export type OutputStream = number;

package/obj/js-component-bindgen-component.d.ts

@@ -44,14 +44,19 @@ export interface Transpiled {
   imports: string[],
   exports: [string, ExportType][],
 }
-import { WasiCliBaseEnvironment } from './imports/wasi-cli-base-environment';
-import { WasiCliBaseExit } from './imports/wasi-cli-base-exit';
-import { WasiCliBasePreopens } from './imports/wasi-cli-base-preopens';
-import { WasiCliBaseStderr } from './imports/wasi-cli-base-stderr';
-import { WasiCliBaseStdin } from './imports/wasi-cli-base-stdin';
-import { WasiCliBaseStdout } from './imports/wasi-cli-base-stdout';
+import { WasiCliEnvironment } from './imports/wasi-cli-environment';
+import { WasiCliExit } from './imports/wasi-cli-exit';
+import { WasiCliStderr } from './imports/wasi-cli-stderr';
+import { WasiCliStdin } from './imports/wasi-cli-stdin';
+import { WasiCliStdout } from './imports/wasi-cli-stdout';
+import { WasiCliTerminalInput } from './imports/wasi-cli-terminal-input';
+import { WasiCliTerminalOutput } from './imports/wasi-cli-terminal-output';
+import { WasiCliTerminalStderr } from './imports/wasi-cli-terminal-stderr';
+import { WasiCliTerminalStdin } from './imports/wasi-cli-terminal-stdin';
+import { WasiCliTerminalStdout } from './imports/wasi-cli-terminal-stdout';
 import { WasiClocksWallClock } from './imports/wasi-clocks-wall-clock';
-import { WasiFilesystemFilesystem } from './imports/wasi-filesystem-filesystem';
+import { WasiFilesystemPreopens } from './imports/wasi-filesystem-preopens';
+import { WasiFilesystemTypes } from './imports/wasi-filesystem-types';
 import { WasiIoStreams } from './imports/wasi-io-streams';
 import { WasiRandomRandom } from './imports/wasi-random-random';
 export function generate(component: Uint8Array | ArrayBuffer, options: GenerateOptions): Transpiled;