unwasm 0.1.0 → 0.2.0

package/README.md

@@ -1,53 +1,110 @@
-# 🇼 unwasm
-
 [![npm version][npm-version-src]][npm-version-href]
 [![npm downloads][npm-downloads-src]][npm-downloads-href]
 [![Codecov][codecov-src]][codecov-href]
 
+# unwasm
+
 Universal [WebAssembly](https://webassembly.org/) tools for JavaScript.
 
 ## Goal
 
-This project aims to make a common and future-proof solution for WebAssembly modules support suitable for various JavaScript runtimes, Frameworks, and build Tools following [WebAssembly/ES Module Integration](https://github.com/WebAssembly/esm-integration/tree/main/proposals/esm-integration) proposal from WebAssembly Community Group as much as possible.
+This project aims to make a common and future-proof solution for WebAssembly modules support suitable for various JavaScript runtimes, frameworks, and build Tools following [WebAssembly/ES Module Integration](https://github.com/WebAssembly/esm-integration/tree/main/proposals/esm-integration) proposal from WebAssembly Community Group as much as possible while also trying to keep compatibility with current ecosystem libraries.
 
 ## Roadmap
 
 The development will be split into multiple stages.
 
 > [!IMPORTANT]
-> This Project is under development! Join the linked discussions to be involved!
+> This Project is under development! See the linked discussions to be involved!
 
-- [ ] Universal builder plugins ([unjs/unwasm#2](https://github.com/unjs/unwasm/issues/2)) built with [unjs/unplugin](https://github.com/unjs/unplugin) 
+- [ ] Universal builder plugins built with [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)) 
+- [ ] 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))
-- [ ] Integration with [Wasmer](https://github.com/wasmerio) ([unjs/unwasm#6](https://github.com/unjs/unwasm/issues/6)) 
+- [ ] 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))
 
-## Install
+## 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.
+
+WebAssembly modules that don't require any imports, can be imported simply like you import any other ESM module.
+
+**Using static import:**
+
+```js
+import { sum } from "unwasm/examples/sum.wasm";
+```
+
+**Using dynamic import:**
+
+```js
+const { sum } = await import("unwasm/examples/sum.wasm").then(
+  (mod) => mod.default,
+);
+```
+
+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(),
+  },
+});
+```
+
+**Using dynamic import with imports object:**
+
+```js
+const { rand } = await import("unwasm/examples/rand.wasm").then((mod) =>
+  mod.$init({
+    env: {
+      seed: () => () => Math.random() * Date.now(),
+    },
+  }),
+);
+```
+
+> [!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.
+
+> [!NOTE]
+> Named exports with the `$` prefix are reserved for unwasm. In case your module uses them, you can access them from the `$exports` property.
+
+## Usage
+
+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.
+
+### Install
 
-Install package from [npm](https://www.npmjs.com/package/unwasm):
+First, install the [`unwasm` npm package](https://www.npmjs.com/package/unwasm):
 
 ```sh
 # npm
-npm install unwasm
+npm install --dev unwasm
 
 # yarn
-yarn add unwasm
+yarn add -D unwasm
 
 # pnpm
-pnpm install unwasm
+pnpm i -D unwasm
 
 # bun
-bun install unwasm
+bun i -D unwasm
 ```
 
-## Using build plugin
+### Builder Plugins
 
 ###### Rollup
 
 ```js
+// rollup.config.js
 import unwasmPlugin from "unwasm/plugin";
 
 export default {
@@ -59,7 +116,7 @@ export default {
 };
 ```
 
-### Options
+### 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`)
@@ -71,6 +128,7 @@ export default {
 - Enable [Corepack](https://github.com/nodejs/corepack) using `corepack enable`
 - Install dependencies using `pnpm install`
 - Run interactive tests using `pnpm dev`
+- Optionally install [es6-string-html](https://marketplace.visualstudio.com/items?itemName=Tobermory.es6-string-html) extension to make it easier to work with string templates.
 
 ## License
 

package/dist/{plugin.d.mts → plugin/index.d.mts}

@@ -14,8 +14,9 @@ interface UnwasmPluginOptions {
      */
     lazy?: boolean;
 }
+
 declare const _default: {
     rollup: (opts: UnwasmPluginOptions) => Plugin<any>;
 };
 
-export { type UnwasmPluginOptions, _default as default };
+export { _default as default };

package/dist/{plugin.d.ts → plugin/index.d.ts}

@@ -14,8 +14,9 @@ interface UnwasmPluginOptions {
      */
     lazy?: boolean;
 }
+
 declare const _default: {
     rollup: (opts: UnwasmPluginOptions) => Plugin<any>;
 };
 
-export { type UnwasmPluginOptions, _default as default };
+export { _default as default };

package/dist/plugin/index.mjs

@@ -0,0 +1,233 @@
+import { existsSync, promises } from 'node:fs';
+import { basename } from 'pathe';
+import MagicString from 'magic-string';
+import { createUnplugin } from 'unplugin';
+import { createHash } from 'node:crypto';
+
+const UNWASM_EXTERNAL_PREFIX = "\0unwasm:external:";
+const UMWASM_HELPERS_ID = "\0unwasm:helpers";
+function sha1(source) {
+  return createHash("sha1").update(source).digest("hex").slice(0, 16);
+}
+
+const js = String.raw;
+function getWasmBinding(asset, opts) {
+  const envCode = opts.esmImport ? js`
+async function _instantiate(imports) {
+  const _mod = await import("${UNWASM_EXTERNAL_PREFIX}${asset.id}").then(r => r.default || r);
+  return WebAssembly.instantiate(_mod, imports)
+}
+  ` : js`
+import { base64ToUint8Array } from "${UMWASM_HELPERS_ID}";
+
+function _instantiate(imports) {
+  const _data = base64ToUint8Array("${asset.source.toString("base64")}")
+  return WebAssembly.instantiate(_data, imports)
+}
+  `;
+  return js`
+import { createUnwasmModule } from "${UMWASM_HELPERS_ID}";
+${envCode}
+const _mod = createUnwasmModule(_instantiate);
+
+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);
+}
+
+function getExports(input) {
+  return input?.instance?.exports || input?.exports || input;
+}
+
+export function base64ToUint8Array(str) {
+  const data = atob(str);
+  const size = data.length;
+  const bytes = new Uint8Array(size);
+  for (let i = 0; i < size; i++) {
+    bytes[i] = data.charCodeAt(i);
+  }
+  return bytes;
+}
+
+export function createUnwasmModule(_instantiator) {
+  const _exports = Object.create(null);
+  let _loaded;
+  let _promise;
+
+  const $init = (imports) => {
+    if (_loaded) {
+      return Promise.resolve(_proxy);
+    }
+    if (_promise) {
+      return _promise;
+    }
+    return _promise = _instantiator(imports)
+      .then(r => {
+        Object.assign(_exports, getExports(r));
+        _loaded = true;
+        _promise = undefined;
+        return _proxy;
+      })
+      .catch(error => {
+        _promise = undefined;
+        console.error('[wasm]', error);
+        throw error;
+      });
+  }
+
+  const $exports = new Proxy(_exports, {
+    get(_, prop) {
+      if (_loaded) {
+        return _exports[prop];
+      }
+      return (...args) => {
+        return _loaded
+          ? _exports[prop]?.(...args)
+          : $init().then(() => $exports[prop]?.(...args));
+      };
+    },
+  });
+
+  const _instance = {
+    $init,
+    $exports,
+  };
+
+  const _proxy = new Proxy(_instance, {
+    get(_, prop) {
+      // Reserve all to avoid future breaking changes
+      if (prop.startsWith('$')) {
+        return _instance[prop];
+      }
+      return $exports[prop];
+    }
+  });
+
+  return _proxy;
+}
+  `;
+}
+
+const unplugin = createUnplugin((opts) => {
+  const assets = /* @__PURE__ */ Object.create(null);
+  return {
+    name: "unwasm",
+    rollup: {
+      async resolveId(id, importer) {
+        if (id === UMWASM_HELPERS_ID) {
+          return id;
+        }
+        if (id.startsWith(UNWASM_EXTERNAL_PREFIX)) {
+          return {
+            id,
+            external: true
+          };
+        }
+        if (id.endsWith(".wasm")) {
+          const r = await this.resolve(id, importer, { skipSelf: true });
+          if (r?.id && r.id !== id) {
+            return {
+              id: r.id.startsWith("file://") ? r.id.slice(7) : r.id,
+              external: false,
+              moduleSideEffects: false,
+              syntheticNamedExports: true
+            };
+          }
+        }
+      },
+      generateBundle() {
+        if (opts.esmImport) {
+          for (const asset of Object.values(assets)) {
+            this.emitFile({
+              type: "asset",
+              source: asset.source,
+              fileName: asset.name
+            });
+          }
+        }
+      }
+    },
+    async load(id) {
+      if (id === UMWASM_HELPERS_ID) {
+        return getPluginUtils();
+      }
+      if (!id.endsWith(".wasm") || !existsSync(id)) {
+        return;
+      }
+      const source = await promises.readFile(id);
+      const name = `wasm/${basename(id, ".wasm")}-${sha1(source)}.wasm`;
+      assets[id] = { name, id, source };
+      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),
+        map: { mappings: "" },
+        syntheticNamedExports: true
+      };
+    },
+    renderChunk(code, chunk) {
+      if (!opts.esmImport) {
+        return;
+      }
+      if (!(chunk.moduleIds.some((id) => id.endsWith(".wasm")) || chunk.imports.some((id) => id.endsWith(".wasm"))) || !code.includes(UNWASM_EXTERNAL_PREFIX)) {
+        return;
+      }
+      const s = new MagicString(code);
+      const resolveImport = (id) => {
+        if (typeof id !== "string") {
+          return;
+        }
+        const asset = assets[id];
+        if (!asset) {
+          return;
+        }
+        const nestedLevel = chunk.fileName.split("/").length - 1;
+        const relativeId = (nestedLevel ? "../".repeat(nestedLevel) : "./") + asset.name;
+        return {
+          relativeId,
+          asset
+        };
+      };
+      const ReplaceRE = new RegExp(`${UNWASM_EXTERNAL_PREFIX}([^"']+)`, "g");
+      for (const match of code.matchAll(ReplaceRE)) {
+        const resolved = resolveImport(match[1]);
+        const index = match.index;
+        const len = match[0].length;
+        if (!resolved || !index) {
+          console.warn(
+            `Failed to resolve WASM import: ${JSON.stringify(match[1])}`
+          );
+          continue;
+        }
+        s.overwrite(index, index + len, resolved.relativeId);
+      }
+      if (s.hasChanged()) {
+        return {
+          code: s.toString(),
+          map: s.generateMap({ includeContent: true })
+        };
+      }
+    }
+  };
+});
+const rollup = unplugin.rollup;
+const index = {
+  rollup
+};
+
+export { index as default };

package/package.json

@@ -1,22 +1,26 @@
 {
   "name": "unwasm",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "WebAssembly tools for JavaScript",
   "repository": "unjs/unwasm",
   "license": "MIT",
   "sideEffects": false,
   "type": "module",
   "exports": {
+    "./examples/*": "./examples/*",
     "./plugin": {
-      "types": "./dist/plugin.d.mts",
-      "import": "./dist/plugin.mjs"
+      "types": "./dist/plugin/index.d.mts",
+      "import": "./dist/plugin/index.mjs"
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "*.d.ts",
+    "examples/*.wasm"
   ],
   "scripts": {
-    "build": "unbuild",
+    "build": "unbuild && pnpm build:examples",
+    "build:examples": "node ./examples/build.mjs",
     "dev": "vitest dev",
     "lint": "eslint --cache --ext .ts,.js,.mjs,.cjs . && prettier -c src test",
     "lint:fix": "eslint --cache --ext .ts,.js,.mjs,.cjs . --fix && prettier -c src test -w",
@@ -35,10 +39,12 @@
     "@rollup/plugin-node-resolve": "^15.2.3",
     "@types/node": "^20.10.5",
     "@vitest/coverage-v8": "^1.1.0",
+    "assemblyscript": "^0.27.22",
     "changelogen": "^0.5.5",
     "eslint": "^8.56.0",
     "eslint-config-unjs": "^0.2.1",
     "jiti": "^1.21.0",
+    "miniflare": "^3.20231030.4",
     "prettier": "^3.1.1",
     "rollup": "^4.9.1",
     "typescript": "^5.3.3",

package/plugin.d.ts

@@ -0,0 +1 @@
+export * from "./dist/plugin";

package/dist/plugin.mjs

@@ -1,129 +0,0 @@
-import { existsSync, promises } from 'node:fs';
-import { basename } from 'pathe';
-import MagicString from 'magic-string';
-import { createUnplugin } from 'unplugin';
-import { createHash } from 'node:crypto';
-
-function sha1(source) {
-  return createHash("sha1").update(source).digest("hex").slice(0, 16);
-}
-
-const WASM_EXTERNAL_ID = "\0unwasm:external:";
-const unplugin = createUnplugin((opts) => {
-  const assets = /* @__PURE__ */ Object.create(null);
-  return {
-    name: "unwasm",
-    rollup: {
-      async resolveId(id, importer) {
-        if (id.startsWith(WASM_EXTERNAL_ID)) {
-          return {
-            id,
-            external: true
-          };
-        }
-        if (id.endsWith(".wasm")) {
-          const r = await this.resolve(id, importer, { skipSelf: true });
-          if (r?.id && r?.id !== id) {
-            return {
-              id: r.id.startsWith("file://") ? r.id.slice(7) : r.id,
-              external: false,
-              moduleSideEffects: false,
-              syntheticNamedExports: false
-            };
-          }
-        }
-      },
-      generateBundle() {
-        if (opts.esmImport) {
-          for (const asset of Object.values(assets)) {
-            this.emitFile({
-              type: "asset",
-              source: asset.source,
-              fileName: asset.name
-            });
-          }
-        }
-      }
-    },
-    async load(id) {
-      if (!id.endsWith(".wasm") || !existsSync(id)) {
-        return;
-      }
-      const source = await promises.readFile(id);
-      const name = `wasm/${basename(id, ".wasm")}-${sha1(source)}.wasm`;
-      assets[id] = { name, source };
-      return `export default "WASM";`;
-    },
-    transform(_code, id) {
-      if (!id.endsWith(".wasm")) {
-        return;
-      }
-      const asset = assets[id];
-      if (!asset) {
-        return;
-      }
-      let _dataStr;
-      if (opts.esmImport) {
-        _dataStr = `await import("${WASM_EXTERNAL_ID}${id}").then(r => r?.default || r)`;
-      } else {
-        const base64Str = asset.source.toString("base64");
-        _dataStr = `(()=>{const d=atob("${base64Str}");const s=d.length;const b=new Uint8Array(s);for(let i=0;i<s;i++)b[i]=d.charCodeAt(i);return b})()`;
-      }
-      let _str = `await WebAssembly.instantiate(${_dataStr}, { env: { "Math.random": () => Math.random, "Math.floor": () => Math.floor } }).then(r => r?.exports||r?.instance?.exports || r);`;
-      if (opts.lazy) {
-        _str = `(()=>{const e=async()=>{return ${_str}};let _p;const p=()=>{if(!_p)_p=e();return _p;};return {then:cb=>p().then(cb),catch:cb=>p().catch(cb)}})()`;
-      }
-      return {
-        code: `export default ${_str};`,
-        map: { mappings: "" },
-        syntheticNamedExports: true
-      };
-    },
-    renderChunk(code, chunk) {
-      if (!chunk.moduleIds.some((id) => id.endsWith(".wasm")) || !code.includes(WASM_EXTERNAL_ID)) {
-        return;
-      }
-      const s = new MagicString(code);
-      const resolveImport = (id) => {
-        if (typeof id !== "string") {
-          return;
-        }
-        const asset = assets[id];
-        if (!asset) {
-          return;
-        }
-        const nestedLevel = chunk.fileName.split("/").length - 1;
-        const relativeId = (nestedLevel ? "../".repeat(nestedLevel) : "./") + asset.name;
-        return {
-          relativeId,
-          asset
-        };
-      };
-      const ReplaceRE = new RegExp(`${WASM_EXTERNAL_ID}([^"']+)`, "g");
-      for (const match of code.matchAll(ReplaceRE)) {
-        const resolved = resolveImport(match[1]);
-        const index = match.index;
-        const len = match[0].length;
-        if (!resolved || !index) {
-          console.warn(
-            `Failed to resolve WASM import: ${JSON.stringify(match[1])}`
-          );
-          continue;
-        }
-        s.overwrite(index, index + len, resolved.relativeId);
-      }
-      if (s.hasChanged()) {
-        return {
-          code: s.toString(),
-          map: s.generateMap({ includeContent: true })
-        };
-      }
-    }
-  };
-});
-const rollup = unplugin.rollup;
-const plugin = {
-  rollup
-};
-
-export { plugin as default };