unwasm 0.2.0 → 0.3.0

package/README.md

@@ -17,53 +17,42 @@ The development will be split into multiple stages.
 > [!IMPORTANT]
 > This Project is under development! See the linked discussions to be involved!
 
-- [ ] Universal builder plugins built with [unjs/unplugin](https://github.com/unjs/unplugin) ([unjs/unwasm#2](https://github.com/unjs/unwasm/issues/2))
+- [ ] Builder plugin powered by [unjs/unplugin](https://github.com/unjs/unplugin) ([unjs/unwasm#2](https://github.com/unjs/unwasm/issues/2))
   - [x] Rollup
-- [ ] Tools to operate and inspect `.wasm` files ([unjs/unwasm#3](https://github.com/unjs/unwasm/issues/3))
-- [ ] Runtime utils ([unjs/unwasm#4](https://github.com/unjs/unwasm/issues/4))
-- [ ] ESM loader for Node.js and other JavaScript runtimes ([unjs/unwasm#5](https://github.com/unjs/unwasm/issues/5))
+- [ ] Build Tools ([unjs/unwasm#3](https://github.com/unjs/unwasm/issues/3))
+  - [x] `parseWasm`
+- [ ] Runtime Utils ([unjs/unwasm#4](https://github.com/unjs/unwasm/issues/4))
+- [ ] ESM Loader ([unjs/unwasm#5](https://github.com/unjs/unwasm/issues/5))
 - [ ] Integration with [Wasmer](https://github.com/wasmerio) ([unjs/unwasm#6](https://github.com/unjs/unwasm/issues/6))
-- [ ] Convention and tools for library authors exporting wasm modules ([unjs/unwasm#7](https://github.com/unjs/unwasm/issues/7))
+- [ ] Convention for library authors exporting wasm modules ([unjs/unwasm#7](https://github.com/unjs/unwasm/issues/7))
 
 ## Bindings API
 
-When importing a `.wasm` module using unwasm, it will take steps to transform the binary and finally resolve to an ESM module that allows you to interact with the WASM module. The returned result is a [Proxy](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy) object. This proxy allows to use of an elegant API while also having both backward and forward compatibility with WASM modules as the ecosystem evolves.
+When importing a `.wasm` module, unwasm resolves, reads, and then parses the module during build process to get the information about imports and exports and generate appropriate code bindings.
 
-WebAssembly modules that don't require any imports, can be imported simply like you import any other ESM module.
+If the target environment supports [top level `await`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/await#top_level_await) and also the wasm module requires no imports object (auto-detected after parsing), unwasm generates bindings to allow importing wasm module like any other ESM import.
 
-**Using static import:**
+If the target environment lacks support for top level `await` or the wasm module requires imports object or `lazy` plugin option is set to `true`, unwasm will export a wrapped [Proxy](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy) object which can be called as a function to lazily evaluate the module with custom imports object. This way we still have a simple syntax as close as possible to ESM modules and also we can lazily initialize modules.
+
+**Example:** Using static import
 
 ```js
 import { sum } from "unwasm/examples/sum.wasm";
 ```
 
-**Using dynamic import:**
+**Example:** Using dynamic import
 
 ```js
-const { sum } = await import("unwasm/examples/sum.wasm").then(
-  (mod) => mod.default,
-);
+const { sum } = await import("unwasm/examples/sum.wasm");
 ```
 
-In case your WebAssembly module requires an import object (which is likely!), the usage syntax would be slightly different as we need to initate the module with an import object first.
-
-**Using static import with imports object:**
-
-```js
-import { rand, $init } from "unwasm/examples/rand.wasm";
-
-await $init({
-  env: {
-    seed: () => () => Math.random() * Date.now(),
-  },
-});
-```
+If your WebAssembly module requires an import object (which is likely!), the usage syntax would be slightly different as we need to initiate the module with an import object first.
 
-**Using dynamic import with imports object:**
+**Example:** Using dynamic import with imports object
 
 ```js
-const { rand } = await import("unwasm/examples/rand.wasm").then((mod) =>
-  mod.$init({
+const { rand } = await import("unwasm/examples/rand.wasm").then((r) =>
+  r.default({
     env: {
       seed: () => () => Math.random() * Date.now(),
     },
@@ -71,19 +60,28 @@ const { rand } = await import("unwasm/examples/rand.wasm").then((mod) =>
 );
 ```
 
-> [!NOTE]
-> When using **static import syntax**, and before calling `$init`, the named exports will be wrapped into a function by proxy that waits for the module initialization and before that, if called, will immediately try to call `$init()` and return a Promise that calls a function after init.
+**Example:** Using static import with imports object
+
+```js
+import initRand, { rand } from "unwasm/examples/rand.wasm";
+
+await initRand({
+  env: {
+    seed: () => () => Math.random() * Date.now(),
+  },
+});
+```
 
 > [!NOTE]
-> Named exports with the `$` prefix are reserved for unwasm. In case your module uses them, you can access them from the `$exports` property.
+> When using **static import syntax**, and before initializing the module, the named exports will be wrapped into a function by proxy that waits for the module initialization and if called before init, will immediately try to call init without imports and return a Promise that calls a function after init.
 
-## Usage
+## Integration
 
-Unwasm needs to transform the `.wasm` imports to the compatible bindings. Currently only method is using a rollup plugin. In the future, more usage methods will be introduced.
+Unwasm needs to transform the `.wasm` imports to the compatible bindings. Currently, the only method is using a rollup plugin. In the future, more usage methods will be introduced.
 
 ### Install
 
-First, install the [`unwasm` npm package](https://www.npmjs.com/package/unwasm):
+First, install the [`unwasm`](https://www.npmjs.com/package/unwasm) npm package.
 
 ```sh
 # npm
@@ -105,11 +103,11 @@ bun i -D unwasm
 
 ```js
 // rollup.config.js
-import unwasmPlugin from "unwasm/plugin";
+import { rollup as unwasm } from "unwasm/plugin";
 
 export default {
   plugins: [
-    unwasmPlugin.rollup({
+    unwasm({
       /* options */
     }),
   ],
@@ -118,8 +116,58 @@ export default {
 
 ### Plugin Options
 
-- `esmImport`: Direct import the wasm file instead of bundling, required in Cloudflare Workers (default is `false`)
-- `lazy`: Import `.wasm` files using a lazily evaluated promise for compatibility with runtimes without top-level await support (default is `false`)
+- `esmImport`: Direct import the wasm file instead of bundling, required in Cloudflare Workers and works with environments that allow natively importing a `.wasm` module (default is `false`)
+- `lazy`: Import `.wasm` files using a lazily evaluated proxy for compatibility with runtimes without top-level await support (default is `false`)
+
+## Tools
+
+unwasm provides useful build tools to operate on `.wasm` modules directly.
+
+**Note:** `unwasm/tools` subpath export is **not** meant or optimized for production runtime. Only rely on it for development and build time.
+
+### `parseWasm`
+
+Parses `wasm` binary format with useful information using [webassemblyjs/wasm-parser](https://github.com/xtuc/webassemblyjs/tree/master/packages/wasm-parser).
+
+```js
+import { readFile } from "node:fs/promises";
+import { parseWasm } from "unwasm/tools";
+
+const source = await readFile(new URL("./examples/sum.wasm", import.meta.url));
+const parsed = parseWasm(source);
+console.log(JSON.stringify(parsed, undefined, 2));
+```
+
+Example parsed result:
+
+```json
+{
+  "modules": [
+    {
+      "exports": [
+        {
+          "id": 5,
+          "name": "rand",
+          "type": "Func"
+        },
+        {
+          "id": 0,
+          "name": "memory",
+          "type": "Memory"
+        }
+      ],
+      "imports": [
+        {
+          "module": "env",
+          "name": "seed",
+          "params": [],
+          "returnType": "f64"
+        }
+      ]
+    }
+  ]
+}
+```
 
 ## Development
 

package/dist/plugin.d.mts

@@ -0,0 +1,25 @@
+import { Plugin } from 'rollup';
+
+interface UnwasmPluginOptions {
+    /**
+     * Directly import the `.wasm` files instead of bundling as base64 string.
+     *
+     * @default false
+     */
+    esmImport?: boolean;
+    /**
+     * Avoid using top level await and always use a proxy.
+     *
+     * Useful for compatibility with environments that don't support top level await.
+     *
+     * @default false
+     */
+    lazy?: boolean;
+}
+
+declare const rollup: (opts: UnwasmPluginOptions) => Plugin;
+declare const _default: {
+    rollup: (opts: UnwasmPluginOptions) => Plugin<any>;
+};
+
+export { _default as default, rollup };

package/dist/plugin.d.ts

@@ -0,0 +1,25 @@
+import { Plugin } from 'rollup';
+
+interface UnwasmPluginOptions {
+    /**
+     * Directly import the `.wasm` files instead of bundling as base64 string.
+     *
+     * @default false
+     */
+    esmImport?: boolean;
+    /**
+     * Avoid using top level await and always use a proxy.
+     *
+     * Useful for compatibility with environments that don't support top level await.
+     *
+     * @default false
+     */
+    lazy?: boolean;
+}
+
+declare const rollup: (opts: UnwasmPluginOptions) => Plugin;
+declare const _default: {
+    rollup: (opts: UnwasmPluginOptions) => Plugin<any>;
+};
+
+export { _default as default, rollup };

package/dist/{plugin/index.mjs → plugin.mjs}

@@ -3,6 +3,8 @@ import { basename } from 'pathe';
 import MagicString from 'magic-string';
 import { createUnplugin } from 'unplugin';
 import { createHash } from 'node:crypto';
+import { parseWasm } from './tools.mjs';
+import '@webassemblyjs/wasm-parser';
 
 const UNWASM_EXTERNAL_PREFIX = "\0unwasm:external:";
 const UMWASM_HELPERS_ID = "\0unwasm:helpers";
@@ -25,24 +27,42 @@ function _instantiate(imports) {
   return WebAssembly.instantiate(_data, imports)
 }
   `;
-  return js`
-import { createUnwasmModule } from "${UMWASM_HELPERS_ID}";
+  const canTopAwait = opts.lazy !== true && Object.keys(asset.imports).length === 0;
+  if (canTopAwait) {
+    return js`
+import { getExports } from "${UMWASM_HELPERS_ID}";
+${envCode}
+
+const $exports = getExports(await _instantiate());
+
+${asset.exports.map((name) => `export const ${name} = $exports.${name};`).join("\n")}
+
+export const $init = () => $exports;
+
+export default $exports;
+    `;
+  } else {
+    return js`
+import { createLazyWasmModule } from "${UMWASM_HELPERS_ID}";
 ${envCode}
-const _mod = createUnwasmModule(_instantiate);
+
+const _mod = createLazyWasmModule(_instantiate);
+
+${asset.exports.map((name) => `export const ${name} = _mod.${name};`).join("\n")}
 
 export const $init = _mod.$init.bind(_mod);
-export const exports = _mod;
 
 export default _mod;
-`;
+    `;
+  }
 }
 function getPluginUtils() {
   return js`
 export function debug(...args) {
-  console.log('[wasm]', ...args);
+  console.log('[wasm] [debug]', ...args);
 }
 
-function getExports(input) {
+export function getExports(input) {
   return input?.instance?.exports || input?.exports || input;
 }
 
@@ -56,14 +76,14 @@ export function base64ToUint8Array(str) {
   return bytes;
 }
 
-export function createUnwasmModule(_instantiator) {
+export function createLazyWasmModule(_instantiator) {
   const _exports = Object.create(null);
   let _loaded;
   let _promise;
 
-  const $init = (imports) => {
+  const init = (imports) => {
     if (_loaded) {
-      return Promise.resolve(_proxy);
+      return Promise.resolve(exportsProxy);
     }
     if (_promise) {
       return _promise;
@@ -73,16 +93,16 @@ export function createUnwasmModule(_instantiator) {
         Object.assign(_exports, getExports(r));
         _loaded = true;
         _promise = undefined;
-        return _proxy;
+        return exportsProxy;
       })
       .catch(error => {
         _promise = undefined;
-        console.error('[wasm]', error);
+        console.error('[wasm] [error]', error);
         throw error;
       });
   }
 
-  const $exports = new Proxy(_exports, {
+  const exportsProxy = new Proxy(_exports, {
     get(_, prop) {
       if (_loaded) {
         return _exports[prop];
@@ -90,33 +110,51 @@ export function createUnwasmModule(_instantiator) {
       return (...args) => {
         return _loaded
           ? _exports[prop]?.(...args)
-          : $init().then(() => $exports[prop]?.(...args));
+          : init().then(() => _exports[prop]?.(...args));
       };
     },
   });
 
-  const _instance = {
-    $init,
-    $exports,
-  };
 
-  const _proxy = new Proxy(_instance, {
+  const lazyProxy = new Proxy(() => {}, {
     get(_, prop) {
-      // Reserve all to avoid future breaking changes
-      if (prop.startsWith('$')) {
-        return _instance[prop];
-      }
-      return $exports[prop];
-    }
+      return exportsProxy[prop];
+    },
+    apply(_, __, args) {
+      return init(args[0])
+    },
   });
 
-  return _proxy;
+  return lazyProxy;
 }
   `;
 }
 
 const unplugin = createUnplugin((opts) => {
   const assets = /* @__PURE__ */ Object.create(null);
+  const _parseCache = /* @__PURE__ */ Object.create(null);
+  function parse(name, source) {
+    if (_parseCache[name]) {
+      return _parseCache[name];
+    }
+    const parsed = parseWasm(source);
+    const imports = /* @__PURE__ */ Object.create(null);
+    const exports = [];
+    for (const mod of parsed.modules) {
+      exports.push(...mod.exports.map((e) => e.name));
+      for (const imp of mod.imports) {
+        if (!imports[imp.module]) {
+          imports[imp.module] = [];
+        }
+        imports[imp.module].push(imp.name);
+      }
+    }
+    _parseCache[name] = {
+      imports,
+      exports
+    };
+    return _parseCache[name];
+  }
   return {
     name: "unwasm",
     rollup: {
@@ -136,8 +174,7 @@ const unplugin = createUnplugin((opts) => {
             return {
               id: r.id.startsWith("file://") ? r.id.slice(7) : r.id,
               external: false,
-              moduleSideEffects: false,
-              syntheticNamedExports: true
+              moduleSideEffects: false
             };
           }
         }
@@ -163,7 +200,14 @@ const unplugin = createUnplugin((opts) => {
       }
       const source = await promises.readFile(id);
       const name = `wasm/${basename(id, ".wasm")}-${sha1(source)}.wasm`;
-      assets[id] = { name, id, source };
+      const parsed = parse(name, source);
+      assets[id] = {
+        name,
+        id,
+        source,
+        imports: parsed.imports,
+        exports: parsed.exports
+      };
       return `export default "UNWASM DUMMY EXPORT";`;
     },
     transform(_code, id) {
@@ -176,8 +220,7 @@ const unplugin = createUnplugin((opts) => {
       }
       return {
         code: getWasmBinding(asset, opts),
-        map: { mappings: "" },
-        syntheticNamedExports: true
+        map: { mappings: "" }
       };
     },
     renderChunk(code, chunk) {
@@ -230,4 +273,4 @@ const index = {
   rollup
 };
 
-export { index as default };
+export { index as default, rollup };

package/dist/tools.d.mts

@@ -0,0 +1,25 @@
+type ParsedWasmModule = {
+    id?: string;
+    imports: ModuleImport[];
+    exports: ModuleExport[];
+};
+type ModuleImport = {
+    module: string;
+    name: string;
+    returnType?: string;
+    params?: {
+        id?: string;
+        type: string;
+    }[];
+};
+type ModuleExport = {
+    name: string;
+    id: string | number;
+    type: "Func" | "Memory";
+};
+type ParseResult = {
+    modules: ParsedWasmModule[];
+};
+declare function parseWasm(source: Buffer | ArrayBuffer): ParseResult;
+
+export { type ModuleExport, type ModuleImport, type ParseResult, type ParsedWasmModule, parseWasm };

package/dist/tools.d.ts

@@ -0,0 +1,25 @@
+type ParsedWasmModule = {
+    id?: string;
+    imports: ModuleImport[];
+    exports: ModuleExport[];
+};
+type ModuleImport = {
+    module: string;
+    name: string;
+    returnType?: string;
+    params?: {
+        id?: string;
+        type: string;
+    }[];
+};
+type ModuleExport = {
+    name: string;
+    id: string | number;
+    type: "Func" | "Memory";
+};
+type ParseResult = {
+    modules: ParsedWasmModule[];
+};
+declare function parseWasm(source: Buffer | ArrayBuffer): ParseResult;
+
+export { type ModuleExport, type ModuleImport, type ParseResult, type ParsedWasmModule, parseWasm };

package/dist/tools.mjs

@@ -0,0 +1,41 @@
+import { decode } from '@webassemblyjs/wasm-parser';
+
+function parseWasm(source) {
+  const ast = decode(source);
+  const modules = [];
+  for (const body of ast.body) {
+    if (body.type === "Module") {
+      const module = {
+        imports: [],
+        exports: []
+      };
+      modules.push(module);
+      for (const field of body.fields) {
+        if (field.type === "ModuleImport") {
+          module.imports.push({
+            module: field.module,
+            name: field.name,
+            returnType: field.descr?.signature?.results?.[0],
+            params: field.descr.signature.params?.map(
+              (p) => ({
+                id: p.id,
+                type: p.valtype
+              })
+            )
+          });
+        } else if (field.type === "ModuleExport") {
+          module.exports.push({
+            name: field.name,
+            id: field.descr.id.value,
+            type: field.descr.exportType
+          });
+        }
+      }
+    }
+  }
+  return {
+    modules
+  };
+}
+
+export { parseWasm };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unwasm",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "WebAssembly tools for JavaScript",
   "repository": "unjs/unwasm",
   "license": "MIT",
@@ -9,8 +9,12 @@
   "exports": {
     "./examples/*": "./examples/*",
     "./plugin": {
-      "types": "./dist/plugin/index.d.mts",
-      "import": "./dist/plugin/index.mjs"
+      "types": "./dist/plugin.d.mts",
+      "import": "./dist/plugin.mjs"
+    },
+    "./tools": {
+      "types": "./dist/tools.d.mts",
+      "import": "./dist/tools.mjs"
     }
   },
   "files": [
@@ -30,6 +34,7 @@
     "test:types": "tsc --noEmit --skipLibCheck"
   },
   "dependencies": {
+    "@webassemblyjs/wasm-parser": "^1.11.6",
     "magic-string": "^0.30.5",
     "mlly": "^1.4.2",
     "pathe": "^1.1.1",

package/plugin.d.ts

@@ -1 +1,3 @@
 export * from "./dist/plugin";
+
+export { default } from "./dist/plugin";

package/dist/plugin/index.d.mts

@@ -1,22 +0,0 @@
-import { Plugin } from 'rollup';
-
-interface UnwasmPluginOptions {
-    /**
-     * Direct import the wasm file instead of bundling, required in Cloudflare Workers
-     *
-     * @default false
-     */
-    esmImport?: boolean;
-    /**
-     * Import `.wasm` files using a lazily evaluated promise for compatibility with runtimes without top-level await support
-     *
-     * @default false
-     */
-    lazy?: boolean;
-}
-
-declare const _default: {
-    rollup: (opts: UnwasmPluginOptions) => Plugin<any>;
-};
-
-export { _default as default };

package/dist/plugin/index.d.ts

@@ -1,22 +0,0 @@
-import { Plugin } from 'rollup';
-
-interface UnwasmPluginOptions {
-    /**
-     * Direct import the wasm file instead of bundling, required in Cloudflare Workers
-     *
-     * @default false
-     */
-    esmImport?: boolean;
-    /**
-     * Import `.wasm` files using a lazily evaluated promise for compatibility with runtimes without top-level await support
-     *
-     * @default false
-     */
-    lazy?: boolean;
-}
-
-declare const _default: {
-    rollup: (opts: UnwasmPluginOptions) => Plugin<any>;
-};
-
-export { _default as default };