@tybys/wasm-util 0.7.0 → 0.8.0

package/README.md

@@ -1,193 +1,193 @@
-# @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.
-
-### 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.
-
-- Example: [https://github.com/toyobayashi/wasi-wabt](https://github.com/toyobayashi/wasi-wabt)
-- Demo: [https://toyobayashi.github.io/wasi-wabt/](https://toyobayashi.github.io/wasi-wabt/)
-
-```js
-import { load, WASI } from '@tybys/wasm-util'
-import { Volumn, createFsFromVolume } from 'memfs-browser'
-
-const fs = createFsFromVolume(Volume.from({
-  '/home/wasi': null
-}))
-
-const wasi = WASI.createSync({
-  args: ['chrome', 'file.wasm'],
-  env: {
-    NODE_ENV: 'development',
-    WASI_SDK_PATH: '/opt/wasi-sdk'
-  },
-  preopens: {
-    '/': '/'
-  },
-  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](#wasi_snapshot_preview1)
-
-### `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_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
-- [x] poll_oneoff (timer only)
-- [x] proc_exit
-- [ ] ~~proc_raise~~
-- [x] sched_yield
-- [x] random_get
-- [ ] ~~sock_recv~~
-- [ ] ~~sock_send~~
-- [ ] ~~sock_shutdown~~
+# @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.
+
+### 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.
+
+- Example: [https://github.com/toyobayashi/wasi-wabt](https://github.com/toyobayashi/wasi-wabt)
+- Demo: [https://toyobayashi.github.io/wasi-wabt/](https://toyobayashi.github.io/wasi-wabt/)
+
+```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: {
+    '/': '/'
+  },
+  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](#wasi_snapshot_preview1)
+
+### `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_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
+- [x] poll_oneoff (timer only)
+- [x] proc_exit
+- [ ] ~~proc_raise~~
+- [x] sched_yield
+- [x] random_get
+- [ ] ~~sock_recv~~
+- [ ] ~~sock_send~~
+- [ ] ~~sock_shutdown~~

package/dist/tsdoc-metadata.json

@@ -5,7 +5,7 @@
   "toolPackages": [
     {
       "packageName": "@microsoft/api-extractor",
-      "packageVersion": "7.34.4"
+      "packageVersion": "7.33.4"
     }
   ]
 }

package/dist/wasm-util.d.ts

@@ -32,10 +32,10 @@ export declare type AsyncifyExports<T, U> = T extends Record<string, any> ? {
 } : T;
 
 /** @public */
-export declare function asyncifyLoad(asyncify: AsyncifyOptions, urlOrBuffer: string | URL | BufferSource, imports?: WebAssembly.Imports): Promise<WebAssembly.WebAssemblyInstantiatedSource>;
+export declare function asyncifyLoad(asyncify: AsyncifyOptions, urlOrBuffer: string | URL | BufferSource | WebAssembly.Module, imports?: WebAssembly.Imports): Promise<WebAssembly.WebAssemblyInstantiatedSource>;
 
 /** @public */
-export declare function asyncifyLoadSync(asyncify: AsyncifyOptions, buffer: BufferSource, imports?: WebAssembly.Imports): WebAssembly.WebAssemblyInstantiatedSource;
+export declare function asyncifyLoadSync(asyncify: AsyncifyOptions, buffer: BufferSource | WebAssembly.Module, imports?: WebAssembly.Imports): WebAssembly.WebAssemblyInstantiatedSource;
 
 /** @public */
 export declare interface AsyncifyOptions {
@@ -76,6 +76,9 @@ export declare type BufferEncodingOption = 'buffer' | {
 /** @public */
 export declare type Callable = (...args: any[]) => any;
 
+/** @public */
+export declare function createAsyncWASI(options?: AsyncWASIOptions): Promise<WASI>;
+
 /** @public */
 export declare function extendMemory(memory: WebAssembly.Memory): Memory;
 
@@ -254,6 +257,8 @@ export declare interface IFsPromises {
     symlink(target: PathLike, path: PathLike, type?: 'dir' | 'file' | 'junction'): Promise<void>;
 }
 
+declare const kBindingName: unique symbol;
+
 declare const kExitCode: unique symbol;
 
 declare const kInstance: unique symbol;
@@ -263,10 +268,10 @@ declare const kSetMemory: unique symbol;
 declare const kStarted: unique symbol;
 
 /** @public */
-export declare function load(urlOrBuffer: string | URL | BufferSource, imports?: WebAssembly.Imports): Promise<WebAssembly.WebAssemblyInstantiatedSource>;
+export declare function load(wasmInput: string | URL | BufferSource | WebAssembly.Module, imports?: WebAssembly.Imports): Promise<WebAssembly.WebAssemblyInstantiatedSource>;
 
 /** @public */
-export declare function loadSync(buffer: BufferSource, imports?: WebAssembly.Imports): WebAssembly.WebAssemblyInstantiatedSource;
+export declare function loadSync(wasmInput: BufferSource | WebAssembly.Module, imports?: WebAssembly.Imports): WebAssembly.WebAssemblyInstantiatedSource;
 
 /** @public */
 export declare interface MakeDirectoryOptions {
@@ -367,16 +372,17 @@ export declare class WASI {
     private [kStarted];
     private [kExitCode];
     private [kInstance];
+    private [kBindingName];
     readonly wasiImport: Record<string, any>;
-    static createSync(options?: SyncWASIOptions): WASI;
-    static createAsync(options?: AsyncWASIOptions): Promise<WASI>;
     constructor(options?: SyncWASIOptions);
     start(instance: WebAssembly.Instance): number | undefined | Promise<number> | Promise<undefined>;
     initialize(instance: WebAssembly.Instance): void | Promise<void>;
+    getImportObject(): Record<string, Record<string, any>>;
 }
 
 /** @public */
 export declare interface WASIOptions {
+    version?: 'unstable' | 'preview1';
     args?: string[] | undefined;
     env?: Record<string, string> | undefined;
     preopens?: Record<string, string> | undefined;