unwasm 0.3.1 → 0.3.3

package/README.md

@@ -25,14 +25,15 @@ The development will be split into multiple stages.
 - [ ] 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 for library authors exporting wasm modules ([unjs/unwasm#7](https://github.com/unjs/unwasm/issues/7))
+  - [x] Auto resolve imports from the imports map
 
 ## Bindings API
 
-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.
+When importing a `.wasm` module, unwasm resolves, reads, and then parses the module during the build process to get the information about imports and exports and even tries to [automatically resolve imports](#auto-imports) and generate appropriate code bindings for the bundler.
 
-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.
+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 (or they are auto resolvable), unwasm generates bindings to allow importing wasm module like any other ESM 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.
+If the target environment lacks support for top-level `await` or the wasm module requires an 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 evaluate the module with custom imports object lazily. 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
 
@@ -46,7 +47,7 @@ import { sum } from "unwasm/examples/sum.wasm";
 const { sum } = await import("unwasm/examples/sum.wasm");
 ```
 
-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.
+If your WebAssembly module requires an import object (unwasm can [automatically infer them](#auto-imports)), the usage syntax would be slightly different as we need to initiate the module with an import object first.
 
 **Example:** Using dynamic import with imports object
 
@@ -169,6 +170,27 @@ Example parsed result:
 }
 ```
 
+## Auto Imports
+
+unwasm can automatically infer the imports object and bundle them using imports maps (read more: [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script/type/importmap), [Node.js](https://nodejs.org/api/packages.html#imports) and [WICG](https://github.com/WICG/import-maps)).
+
+To hint to the bundler how to resolve imports needed by the `.wasm` file, you need to define them in a parent `package.json` file.
+
+**Example:**
+
+```js
+{
+  "exports": {
+    "./rand.wasm": "./rand.wasm"
+  },
+  "imports": {
+    "env": "./env.mjs"
+  }
+}
+```
+
+**Note:** The imports can also be prefixed with `#` like `#env` if you like to respect Node.js conventions.
+
 ## Development
 
 - Clone this repository

package/dist/plugin.cjs

@@ -7,6 +7,7 @@ const pathe = require('pathe');
 const MagicString = require('magic-string');
 const unplugin$1 = require('unplugin');
 const node_crypto = require('node:crypto');
+const pkgTypes = require('pkg-types');
 const tools = require('./tools.cjs');
 require('@webassemblyjs/wasm-parser');
 
@@ -21,21 +22,25 @@ function sha1(source) {
 }
 
 const js = String.raw;
-function getWasmBinding(asset, opts) {
+async function getWasmBinding(asset, opts) {
+  const autoImports = await getWasmImports(asset);
   const envCode = opts.esmImport ? js`
-async function _instantiate(imports) {
-  const _mod = await import("${UNWASM_EXTERNAL_PREFIX}${asset.id}").then(r => r.default || r);
+${autoImports.code};
+
+async function _instantiate(imports = _imports) {
+  const _mod = await import("${UNWASM_EXTERNAL_PREFIX}${asset.name}").then(r => r.default || r);
   return WebAssembly.instantiate(_mod, imports)
 }
   ` : js`
 import { base64ToUint8Array } from "${UMWASM_HELPERS_ID}";
+${autoImports.code};
 
-function _instantiate(imports) {
+function _instantiate(imports = _imports) {
   const _data = base64ToUint8Array("${asset.source.toString("base64")}")
   return WebAssembly.instantiate(_data, imports)
 }
   `;
-  const canTopAwait = opts.lazy !== true && Object.keys(asset.imports).length === 0;
+  const canTopAwait = opts.lazy !== true && autoImports.resolved;
   if (canTopAwait) {
     return js`
 import { getExports } from "${UMWASM_HELPERS_ID}";
@@ -133,6 +138,43 @@ export function createLazyWasmModule(_instantiator) {
 }
   `;
 }
+async function getWasmImports(asset, opts) {
+  const importNames = Object.keys(asset.imports || {});
+  if (importNames.length === 0) {
+    return {
+      code: "const _imports = { /* no imports */ }",
+      resolved: true
+    };
+  }
+  const pkgJSON = await pkgTypes.readPackageJSON(asset.id);
+  let code = "const _imports = {";
+  let resolved = true;
+  for (const moduleName of importNames) {
+    const importNames2 = asset.imports[moduleName];
+    const pkgImport = pkgJSON.imports?.[moduleName] || pkgJSON.imports?.[`#${moduleName}`];
+    if (pkgImport) {
+      code = `import * as _imports_${moduleName} from "${pkgImport}";
+${code}`;
+    } else {
+      resolved = false;
+    }
+    code += `
+  ${moduleName}: {`;
+    for (const name of importNames2) {
+      code += pkgImport ? `
+    ${name}: _imports_${moduleName}.${name},
+` : `
+    ${name}: () => { throw new Error("\`${moduleName}.${name}\` is not provided!")},
+`;
+    }
+    code += "  },\n";
+  }
+  code += "};\n";
+  return {
+    code,
+    resolved
+  };
+}
 
 const unplugin = unplugin$1.createUnplugin((opts) => {
   const assets = /* @__PURE__ */ Object.create(null);
@@ -202,28 +244,26 @@ const unplugin = unplugin$1.createUnplugin((opts) => {
       if (!id.endsWith(".wasm") || !node_fs.existsSync(id)) {
         return;
       }
-      const source = await node_fs.promises.readFile(id);
-      const name = `wasm/${pathe.basename(id, ".wasm")}-${sha1(source)}.wasm`;
-      const parsed = parse(name, source);
-      assets[id] = {
+      this.addWatchFile(id);
+      const buff = await node_fs.promises.readFile(id);
+      return buff.toString("binary");
+    },
+    async transform(code, id) {
+      if (!id.endsWith(".wasm")) {
+        return;
+      }
+      const buff = Buffer.from(code, "binary");
+      const name = `wasm/${pathe.basename(id, ".wasm")}-${sha1(buff)}.wasm`;
+      const parsed = parse(name, buff);
+      const asset = assets[name] = {
         name,
         id,
-        source,
+        source: buff,
         imports: parsed.imports,
         exports: parsed.exports
       };
-      return `export default "UNWASM DUMMY EXPORT";`;
-    },
-    transform(_code, id) {
-      if (!id.endsWith(".wasm")) {
-        return;
-      }
-      const asset = assets[id];
-      if (!asset) {
-        return;
-      }
       return {
-        code: getWasmBinding(asset, opts),
+        code: await getWasmBinding(asset, opts),
         map: { mappings: "" }
       };
     },

package/dist/plugin.mjs

@@ -3,6 +3,7 @@ import { basename } from 'pathe';
 import MagicString from 'magic-string';
 import { createUnplugin } from 'unplugin';
 import { createHash } from 'node:crypto';
+import { readPackageJSON } from 'pkg-types';
 import { parseWasm } from './tools.mjs';
 import '@webassemblyjs/wasm-parser';
 
@@ -13,21 +14,25 @@ function sha1(source) {
 }
 
 const js = String.raw;
-function getWasmBinding(asset, opts) {
+async function getWasmBinding(asset, opts) {
+  const autoImports = await getWasmImports(asset);
   const envCode = opts.esmImport ? js`
-async function _instantiate(imports) {
-  const _mod = await import("${UNWASM_EXTERNAL_PREFIX}${asset.id}").then(r => r.default || r);
+${autoImports.code};
+
+async function _instantiate(imports = _imports) {
+  const _mod = await import("${UNWASM_EXTERNAL_PREFIX}${asset.name}").then(r => r.default || r);
   return WebAssembly.instantiate(_mod, imports)
 }
   ` : js`
 import { base64ToUint8Array } from "${UMWASM_HELPERS_ID}";
+${autoImports.code};
 
-function _instantiate(imports) {
+function _instantiate(imports = _imports) {
   const _data = base64ToUint8Array("${asset.source.toString("base64")}")
   return WebAssembly.instantiate(_data, imports)
 }
   `;
-  const canTopAwait = opts.lazy !== true && Object.keys(asset.imports).length === 0;
+  const canTopAwait = opts.lazy !== true && autoImports.resolved;
   if (canTopAwait) {
     return js`
 import { getExports } from "${UMWASM_HELPERS_ID}";
@@ -125,6 +130,43 @@ export function createLazyWasmModule(_instantiator) {
 }
   `;
 }
+async function getWasmImports(asset, opts) {
+  const importNames = Object.keys(asset.imports || {});
+  if (importNames.length === 0) {
+    return {
+      code: "const _imports = { /* no imports */ }",
+      resolved: true
+    };
+  }
+  const pkgJSON = await readPackageJSON(asset.id);
+  let code = "const _imports = {";
+  let resolved = true;
+  for (const moduleName of importNames) {
+    const importNames2 = asset.imports[moduleName];
+    const pkgImport = pkgJSON.imports?.[moduleName] || pkgJSON.imports?.[`#${moduleName}`];
+    if (pkgImport) {
+      code = `import * as _imports_${moduleName} from "${pkgImport}";
+${code}`;
+    } else {
+      resolved = false;
+    }
+    code += `
+  ${moduleName}: {`;
+    for (const name of importNames2) {
+      code += pkgImport ? `
+    ${name}: _imports_${moduleName}.${name},
+` : `
+    ${name}: () => { throw new Error("\`${moduleName}.${name}\` is not provided!")},
+`;
+    }
+    code += "  },\n";
+  }
+  code += "};\n";
+  return {
+    code,
+    resolved
+  };
+}
 
 const unplugin = createUnplugin((opts) => {
   const assets = /* @__PURE__ */ Object.create(null);
@@ -194,28 +236,26 @@ const unplugin = createUnplugin((opts) => {
       if (!id.endsWith(".wasm") || !existsSync(id)) {
         return;
       }
-      const source = await promises.readFile(id);
-      const name = `wasm/${basename(id, ".wasm")}-${sha1(source)}.wasm`;
-      const parsed = parse(name, source);
-      assets[id] = {
+      this.addWatchFile(id);
+      const buff = await promises.readFile(id);
+      return buff.toString("binary");
+    },
+    async transform(code, id) {
+      if (!id.endsWith(".wasm")) {
+        return;
+      }
+      const buff = Buffer.from(code, "binary");
+      const name = `wasm/${basename(id, ".wasm")}-${sha1(buff)}.wasm`;
+      const parsed = parse(name, buff);
+      const asset = assets[name] = {
         name,
         id,
-        source,
+        source: buff,
         imports: parsed.imports,
         exports: parsed.exports
       };
-      return `export default "UNWASM DUMMY EXPORT";`;
-    },
-    transform(_code, id) {
-      if (!id.endsWith(".wasm")) {
-        return;
-      }
-      const asset = assets[id];
-      if (!asset) {
-        return;
-      }
       return {
-        code: getWasmBinding(asset, opts),
+        code: await getWasmBinding(asset, opts),
         map: { mappings: "" }
       };
     },

package/examples/build.mjs

@@ -0,0 +1,20 @@
+import { fileURLToPath } from "node:url";
+import { main as asc } from "assemblyscript/asc";
+
+async function compile(name) {
+  // https://www.assemblyscript.org/compiler.html#programmatic-usage
+  const res = await asc([`${name}.asc.ts`, "-o", `${name}.wasm`], {});
+
+  if (res.error) {
+    console.log(`Compilation failed for ${name}:`, res.error);
+    console.log(res.stderr.toString());
+  } else {
+    console.log(`Compiled: ${name}.wasm`);
+    console.log(res.stdout.toString());
+  }
+}
+
+process.chdir(fileURLToPath(new URL(".", import.meta.url)));
+
+await compile("sum");
+await compile("rand");

package/examples/env.mjs

@@ -0,0 +1 @@
+export const seed = () => Math.random() * Date.now()

package/examples/package.json

@@ -0,0 +1,5 @@
+{
+  "imports": {
+    "#env": "./env.mjs"
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unwasm",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "WebAssembly tools for JavaScript",
   "repository": "unjs/unwasm",
   "license": "MIT",
@@ -32,7 +32,9 @@
   "files": [
     "dist",
     "*.d.ts",
-    "examples/*.wasm"
+    "examples/*.wasm",
+    "examples/package.json",
+    "examples/*.mjs"
   ],
   "scripts": {
     "build": "unbuild && pnpm build:examples",
@@ -50,12 +52,13 @@
     "magic-string": "^0.30.5",
     "mlly": "^1.4.2",
     "pathe": "^1.1.1",
+    "pkg-types": "^1.0.3",
     "unplugin": "^1.6.0"
   },
   "devDependencies": {
     "@rollup/plugin-node-resolve": "^15.2.3",
-    "@types/node": "^20.10.5",
-    "@vitest/coverage-v8": "^1.1.0",
+    "@types/node": "^20.10.6",
+    "@vitest/coverage-v8": "^1.1.1",
     "assemblyscript": "^0.27.22",
     "changelogen": "^0.5.5",
     "eslint": "^8.56.0",
@@ -63,11 +66,11 @@
     "jiti": "^1.21.0",
     "miniflare": "^3.20231030.4",
     "prettier": "^3.1.1",
-    "rollup": "^4.9.1",
+    "rollup": "^4.9.2",
     "typescript": "^5.3.3",
     "unbuild": "^2.0.0",
     "vite": "^5.0.10",
-    "vitest": "^1.1.0"
+    "vitest": "^1.1.1"
   },
-  "packageManager": "pnpm@8.12.1"
+  "packageManager": "pnpm@8.13.1"
 }