unwasm - npm Package Compare versions

Comparing version 0.2.0 to 0.3.0

package.json

 {
   "name": "unwasm",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "WebAssembly tools for JavaScript",
@@ -12,4 +12,8 @@ "repository": "unjs/unwasm",
     "./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"
     }
@@ -34,2 +38,3 @@ },
   "dependencies": {
+    "@webassemblyjs/wasm-parser": "^1.11.6",
     "magic-string": "^0.30.5",
@@ -36,0 +41,0 @@ "mlly": "^1.4.2",

plugin.d.ts

 export * from "./dist/plugin";
+
+export { default } from "./dist/plugin";

README.md

@@ -20,18 +20,21 @@ [![npm version][npm-version-src]][npm-version-href]
 
-- [ ] 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
@@ -41,29 +44,15 @@ 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.
+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 static import with imports object:**
+**Example:** Using dynamic 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({
+const { rand } = await import("unwasm/examples/rand.wasm").then((r) =>
+  r.default({
     env: {
@@ -76,15 +65,24 @@ 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.
+**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.
 
@@ -111,7 +109,7 @@ ```sh
 // rollup.config.js
-import unwasmPlugin from "unwasm/plugin";
+import { rollup as unwasm } from "unwasm/plugin";
 
 export default {
   plugins: [
-    unwasmPlugin.rollup({
+    unwasm({
       /* options */
@@ -125,5 +123,55 @@ }),
 
-- `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
@@ -130,0 +178,0 @@

New alerts

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Fixed alerts

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

20837

32.83%

Number of package files

12

33.33%

Lines of code

342

43.7%

Number of lines in readme file

195

32.65%

Worsened metrics

Dependency count

5

25%

Dependency changes

• + Added

  @webassemblyjs/wasm-parser@^1.11.6

• + Added

  @webassemblyjs/ast@1.14.1
  (transitive)

• + Added

  @webassemblyjs/floating-point-hex-parser@1.13.2
  (transitive)

• + Added

  @webassemblyjs/helper-api-error@1.13.2
  (transitive)

• + Added

  @webassemblyjs/helper-numbers@1.13.2
  (transitive)

• + Added

  @webassemblyjs/helper-wasm-bytecode@1.13.2
  (transitive)

• + Added

  @webassemblyjs/ieee754@1.13.2
  (transitive)

• + Added

  @webassemblyjs/leb128@1.13.2
  (transitive)

• + Added

  @webassemblyjs/utf8@1.13.2
  (transitive)

• + Added

  @webassemblyjs/wasm-parser@1.14.1
  (transitive)

• + Added

  @xtuc/ieee754@1.2.0
  (transitive)

• + Added

  @xtuc/long@4.2.2
  (transitive)