@tybys/wasm-util 0.1.0

package/README.md

@@ -0,0 +1,190 @@
+# @tybys/wasm-util
+
+WebAssembly related utils for browser environment
+
+**The output code is ES2019**
+
+## Features
+
+All example code below need to be bundled by ES module bundlers like `webpack` / `rollup`, or specify import map in browser native ES module runtime.
+
+### `load` / `loadSync`
+
+`loadSync` has 4KB wasm size limit in browser.
+
+```js
+// bundler
+import { load, loadSync } from '@tybys/wasm-util'
+
+const imports = { /* ... */ }
+
+// using path
+const { module, instance } = await load('/path/to/file.wasm', imports)
+const { module, instance } = loadSync('/path/to/file.wasm', imports)
+
+// using URL
+const { module, instance } = await load(new URL('./file.wasm', import.meta.url), imports)
+const { module, instance } = loadSync(new URL('./file.wasm', import.meta.url), imports)
+
+// using Uint8Array
+const buffer = new Uint8Array([
+  0x00, 0x61, 0x73, 0x6d,
+  0x01, 0x00, 0x00, 0x00
+])
+const { module, instance } = await load(buffer, imports)
+const { module, instance } = loadSync(buffer, imports)
+
+// auto asyncify
+const {
+  module,
+  instance: asyncifiedInstance
+} = await load(buffer, imports, { /* asyncify options */})
+asyncifiedInstance.exports.fn() // => return Promise
+```
+
+### Extend Memory instance
+
+```js
+import { Memory, extendMemory } from '@tybys/wasm-util'
+
+const memory = new WebAssembly.Memory({ initial: 256 })
+// const memory = instance.exports.memory
+
+extendMemory(memory)
+console.log(memory instanceof Memory)
+console.log(memory instanceof WebAssembly.Memory)
+// expose memory view getters like Emscripten
+const { HEAPU8, HEAPU32, view } = memory
+```
+
+### Asyncify wrap
+
+Build the C code using `clang`, `wasm-ld` and `wasm-opt`
+
+```c
+void async_sleep(int ms);
+
+int main() {
+  async_sleep(200);
+  return 0;
+}
+```
+
+```js
+import { Asyncify } from '@tybys/wasm-util'
+
+const asyncify = new Asyncify()
+
+const imports = {
+  env: {
+    async_sleep: asyncify.wrapImportFunction(function (ms) {
+      return new Promise((resolve) => {
+        setTimeout(resolve, ms)
+      })
+    })
+  }
+}
+
+// async_sleep(200)
+const bytes = await (await fetch('/asyncfied_by_wasm-opt.wasm')).arrayBuffer()
+const { instance } = await WebAssembly.instantiate(bytes, imports)
+const asyncifiedInstance = asyncify.init(instance.exports.memory, instance, {
+  wrapExports: ['_start']
+})
+
+const p = asyncifedInstance._start()
+console.log(typeof p.then === 'function')
+const now = Date.now()
+await p
+console.log(Date.now() - now >= 200)
+```
+
+### WASI polyfill for browser
+
+The API is similar to the `require('wasi').WASI` in Node.js.
+
+You can use `memfs-browser` to provide filesystem capability.
+
+```js
+import { load, WASI } from '@tybys/wasm-util'
+import { Volumn, createFsFromVolume } from 'memfs-browser'
+
+const fs = createFsFromVolume(Volume.from({
+  '/home/wasi': null
+}))
+
+const wasi = new WASI({
+  args: ['chrome', 'file.wasm'],
+  env: {
+    NODE_ENV: 'development',
+    WASI_SDK_PATH: '/opt/wasi-sdk'
+  },
+  preopens: {
+    '/': '/'
+  },
+  filesystem: { type: 'memfs', fs },
+
+  // redirect stdout / stderr
+
+  // print (text) { console.log(text) },
+  // printErr (text) { console.error(text) }
+})
+
+const imports = {
+  wasi_snapshot_preview1: wasi.wasiImport
+}
+
+const { module, instance } = await load('/path/to/file.wasm', imports)
+wasi.start(instance)
+// wasi.initialize(instance)
+```
+
+Implemented syscalls:
+
+#### wasi_snapshot_preview1
+
+- [x] args_get
+- [x] args_sizes_get
+- [x] environ_get
+- [x] environ_sizes_get
+- [x] clock_res_get
+- [x] clock_time_get
+- [ ] ~~fd_advise~~
+- [x] fd_allocate
+- [x] fd_close
+- [x] fd_datasync
+- [x] fd_fdstat_get
+- [ ] ~~fd_fdstat_set_flags~~
+- [x] fd_fdstat_set_rights
+- [x] fd_filestat_get
+- [x] fd_filestat_set_size
+- [x] fd_filestat_set_times
+- [x] fd_pread
+- [x] fd_prestat_get
+- [x] fd_prestat_dir_name
+- [x] fd_pwrite
+- [x] fd_read
+- [x] fd_readdir
+- [x] fd_renumber
+- [x] fd_seek
+- [x] fd_sync
+- [x] fd_tell
+- [x] fd_write
+- [x] path_create_directory
+- [x] path_filestat_get
+- [x] path_filestat_set_times
+- [x] path_link
+- [x] path_open
+- [x] path_readlink
+- [x] path_remove_directory
+- [x] path_rename
+- [x] path_symlink
+- [x] path_unlink_file
+- [ ] ~~poll_oneoff~~
+- [x] proc_exit
+- [ ] ~~proc_raise~~
+- [x] sched_yield
+- [x] random_get
+- [ ] ~~sock_recv~~
+- [ ] ~~sock_send~~
+- [ ] ~~sock_shutdown~~

package/dist/tsdoc-metadata.json

@@ -0,0 +1,11 @@
+// This file is read by tools that parse documentation comments conforming to the TSDoc standard.
+// It should be published with your NPM package.  It should not be tracked by Git.
+{
+  "tsdocVersion": "0.12",
+  "toolPackages": [
+    {
+      "packageName": "@microsoft/api-extractor",
+      "packageVersion": "7.33.4"
+    }
+  ]
+}

package/dist/wasm-util.d.ts

@@ -0,0 +1,113 @@
+/**
+ * @packageDocumentation
+ */
+
+import type { IFs } from 'memfs-browser';
+
+/** @public */
+export declare class Asyncify {
+    private value;
+    private exports;
+    private dataPtr;
+    init<T extends WebAssembly.Exports, U extends Array<Exclude<keyof T, AsyncifyExportName>>>(memory: WebAssembly.Memory, instance: {
+        readonly exports: T;
+    }, options: AsyncifyOptions): {
+        readonly exports: AsyncifyExports<T, U>;
+    };
+    private assertState;
+    wrapImportFunction<T extends Function>(f: T): T;
+    wrapImports<T extends WebAssembly.Imports>(imports: T): T;
+    wrapExportFunction<T extends Function>(f: T): AsyncifyExportFunction<T>;
+    wrapExports<T extends WebAssembly.Exports>(exports: T): AsyncifyExports<T, void>;
+    wrapExports<T extends WebAssembly.Exports, U extends Array<Exclude<keyof T, AsyncifyExportName>>>(exports: T, needWrap: U): AsyncifyExports<T, U>;
+}
+
+/** @public */
+export declare type AsyncifyExportFunction<T> = T extends Callable ? (...args: Parameters<T>) => Promise<ReturnType<T>> : T;
+
+/** @public */
+export declare type AsyncifyExportName = 'asyncify_get_state' | 'asyncify_start_unwind' | 'asyncify_stop_unwind' | 'asyncify_start_rewind' | 'asyncify_stop_rewind';
+
+/** @public */
+export declare type AsyncifyExports<T, U> = T extends Record<string, any> ? {
+    [P in keyof T]: T[P] extends Callable ? U extends Array<Exclude<keyof T, AsyncifyExportName>> ? P extends U[number] ? AsyncifyExportFunction<T[P]> : T[P] : AsyncifyExportFunction<T[P]> : T[P];
+} : T;
+
+/** @public */
+export declare interface AsyncifyOptions {
+    wasm64?: boolean;
+    tryAllocate?: boolean | {
+        size?: number;
+        name?: string;
+    };
+    wrapExports?: string[];
+}
+
+/** @public */
+export declare type Callable = (...args: any[]) => any;
+
+/** @public */
+export declare function extendMemory(memory: WebAssembly.Memory): Memory;
+
+declare const kExitCode: unique symbol;
+
+declare const kInstance: unique symbol;
+
+declare const kSetMemory: unique symbol;
+
+declare const kStarted: unique symbol;
+
+/** @public */
+export declare function load(urlOrBuffer: string | URL | BufferSource, imports?: WebAssembly.Imports, asyncify?: AsyncifyOptions): Promise<WebAssembly.WebAssemblyInstantiatedSource>;
+
+/** @public */
+export declare function loadSync(buffer: BufferSource, imports?: WebAssembly.Imports, asyncify?: AsyncifyOptions): WebAssembly.WebAssemblyInstantiatedSource;
+
+/** @public */
+export declare class Memory extends WebAssembly.Memory {
+    constructor(descriptor: WebAssembly.MemoryDescriptor);
+    get HEAP8(): Int8Array;
+    get HEAPU8(): Uint8Array;
+    get HEAP16(): Int16Array;
+    get HEAPU16(): Uint16Array;
+    get HEAP32(): Int32Array;
+    get HEAPU32(): Uint32Array;
+    get HEAP64(): BigInt64Array;
+    get HEAPU64(): BigUint64Array;
+    get HEAPF32(): Float32Array;
+    get HEAPF64(): Float64Array;
+    get view(): DataView;
+}
+
+/** @public */
+export declare class WASI {
+    private [kSetMemory];
+    private [kStarted];
+    private [kExitCode];
+    private [kInstance];
+    readonly wasiImport: Record<string, any>;
+    constructor(options?: WASIOptions);
+    start(instance: WebAssembly.Instance): number | undefined | Promise<number> | Promise<undefined>;
+    initialize(instance: WebAssembly.Instance): void | Promise<void>;
+}
+
+/** @public */
+export declare interface WASIOptions {
+    args?: string[] | undefined;
+    env?: Record<string, string> | undefined;
+    preopens?: Record<string, string> | undefined;
+    /**
+     * @defaultValue `false`
+     */
+    returnOnExit?: boolean | undefined;
+    print?: (str: string) => void;
+    printErr?: (str: string) => void;
+    filesystem?: {
+        type: 'memfs';
+        fs: IFs;
+    };
+}
+
+export { }
+
+export as namespace wasmUtil;