feat: automatically provide imports object using import map (#11)

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

examples/env.mjs

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

examples/package.json

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

package.json

@@ -32,7 +32,9 @@
  "files": [
  "dist",
  "*.d.ts",
- "examples/*.wasm"
+ "examples/*.wasm",
+ "examples/package.json",
+ "examples/*.mjs"
  ],
  "scripts": {
  "build": "unbuild && pnpm build:examples",
@@ -50,6 +52,7 @@
  "magic-string": "^0.30.5",
  "mlly": "^1.4.2",
  "pathe": "^1.1.1",
+ "pkg-types": "^1.0.3",
  "unplugin": "^1.6.0"
  },
  "devDependencies": {
@@ -70,4 +73,4 @@
  "vitest": "^1.1.1"
  },
  "packageManager": "[email protected]"
-}
+}

src/plugin/index.ts

@@ -93,7 +93,7 @@ const unplugin = createUnplugin<UnwasmPluginOptions>((opts) => {
  const buff = await fs.readFile(id);
  return buff.toString("binary");
  },
- transform(code, id) {
+ async transform(code, id) {
  if (!id.endsWith(".wasm")) {
  return;
  }
@@ -111,7 +111,7 @@ const unplugin = createUnplugin<UnwasmPluginOptions>((opts) => {
  });
 
  return {
- code: getWasmBinding(asset, opts),
+ code: await getWasmBinding(asset, opts),
  map: { mappings: "" },
  };
  },

src/plugin/runtime.ts

@@ -1,3 +1,4 @@
+import { readPackageJSON } from "pkg-types";
 import {
  UMWASM_HELPERS_ID,
  UNWASM_EXTERNAL_PREFIX,
@@ -8,27 +9,35 @@ import {
 // https://marketplace.visualstudio.com/items?itemName=Tobermory.es6-string-html
 const js = String.raw;
 
-export function getWasmBinding(asset: WasmAsset, opts: UnwasmPluginOptions) {
+export async function getWasmBinding(
+ asset: WasmAsset,
+ opts: UnwasmPluginOptions,
+) {
+ // -- Auto load imports --
+ const autoImports = await getWasmImports(asset, opts);
+
  // --- Environment dependent code to initialize the wasm module using inlined base 64 or dynamic import ---
  const envCode: string = opts.esmImport
  ? js`
-async function _instantiate(imports) {
+${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)
 }
  `;
 
  // --- Binding code to export the wasm module exports ---
- const canTopAwait =
- opts.lazy !== true && Object.keys(asset.imports).length === 0;
+ const canTopAwait = opts.lazy !== true && autoImports.resolved;
 
  // eslint-disable-next-line unicorn/prefer-ternary
  if (canTopAwait) {
@@ -136,3 +145,49 @@ export function createLazyWasmModule(_instantiator) {
 }
  `;
 }
+
+export async function getWasmImports(
+ asset: WasmAsset,
+ opts: UnwasmPluginOptions,
+) {
+ const importNames = Object.keys(asset.imports || {});
+ if (importNames.length === 0) {
+ return {
+ code: "const _imports = { /* no imports */ }",
+ resolved: true,
+ };
+ }
+
+ // Try to resolve from nearest package.json
+ const pkgJSON = await readPackageJSON(asset.id);
+
+ let code = "const _imports = {";
+
+ let resolved = true;
+
+ for (const moduleName of importNames) {
+ const importNames = asset.imports[moduleName];
+ const pkgImport =
+ pkgJSON.imports?.[moduleName] || pkgJSON.imports?.[`#${moduleName}`];
+
+ if (pkgImport) {
+ code = `import * as _imports_${moduleName} from "${pkgImport}";\n${code}`;
+ } else {
+ resolved = false;
+ }
+ code += `\n ${moduleName}: {`;
+ for (const name of importNames) {
+ code += pkgImport
+ ? `\n ${name}: _imports_${moduleName}.${name},\n`
+ : `\n ${name}: () => { throw new Error("\`${moduleName}.${name}\` is not provided!")},\n`;
+ }
+ code += " },\n";
+ }
+
+ code += "};\n";
+
+ return {
+ code,
+ resolved,
+ };
+}

test/fixture/dynamic-import.mjs

@@ -1,11 +1,9 @@
-const { sum } = await import("@fixture/wasm/sum.wasm");
+export async function test() {
+ // Avoid top-level await because of miniflare curren't limitation.
+ // https://github.com/cloudflare/miniflare/issues/753
+ const { rand } = await import("@fixture/wasm/rand.wasm");
+ const { sum } = await import("@fixture/wasm/sum.wasm");
 
-const { imports } = await import("./_shared.mjs");
-const { rand } = await import("@fixture/wasm/rand.wasm").then((r) =>
- r.default(imports),
-);
-
-export function test() {
  if (sum(1, 2) !== 3) {
  return "FALED: sum";
  }

test/fixture/static-import.mjs

@@ -1,8 +1,5 @@
-import { imports } from "./_shared.mjs";
 import { sum } from "@fixture/wasm/sum.wasm";
-import initRand, { rand } from "@fixture/wasm/rand.wasm";
-
-await initRand(imports);
+import { rand } from "@fixture/wasm/rand.wasm";
 
 export function test() {
  if (sum(1, 2) !== 3) {

test/plugin.test.ts

@@ -68,7 +68,7 @@ async function _evalCloudflare(name: string) {
 import { test } from "./index.mjs";
 export default {
  async fetch(request, env, ctx) {
- return new Response(test());
+ return new Response(await test());
  }
 }
 `,