Add another entrypoint using wasm-as-esm support (#178)

Some environments support loading WASM modules directly as ESM, and that gives
better results than the existing entry points. For example, Webpack is able to
include it inside the same bundle as the rest of the sources.

README.md

@@ -53,7 +53,28 @@ Encryption](https://en.wikipedia.org/wiki/End-to-end_encryption)) for
     }
     ```
 
-## Building
+    See the [API documentation](https://matrix-org.github.io/matrix-rust-sdk-crypto-wasm/) for more information.
+
+3. Build your project.
+
+    The packaging of this library aims to "just work" the same as any plain-javascript project would: it includes
+    separate entry points for Node.js-like environments (which read the WASM file via
+    [`fs.readFile()`](https://nodejs.org/api/fs.html#fsreadfilepath-options-callback)) and web-like environments (which
+    download the WASM file with [`fetch()`](https://developer.mozilla.org/en-US/docs/Web/API/Window/fetch)). There are
+    both CommonJS and ES Module entry points for each environment; an appropriate entrypoint should be selected
+    automatically.
+
+    If your environment supports the experimental [ES Module Integration Proposal for WebAssembly](https://github.com/WebAssembly/esm-integration),
+    you can instead use that, by setting the `matrix-org:wasm-esm` custom [export condition](https://nodejs.org/api/packages.html#conditional-exports).
+    This is only supported when the library is imported as an ES Module. For example:
+
+    - In Webpack, set [`experiments.asyncWebAssembly`](https://webpack.js.org/configuration/experiments/#experiments)
+      to `true` and [`resolve.conditionNames`](https://webpack.js.org/configuration/resolve/#resolveconditionnames)
+      to `["matrix-org:wasm-esm", "..."]` (the `"..."` preserves default condition names).
+    - In Node.js, invoke with commandline arguments [`--experimental-wasm-modules`](https://nodejs.org/api/esm.html#wasm-modules)
+      [`--conditions=wasm-esm`](https://nodejs.org/api/cli.html#-c-condition---conditionscondition).
+
+## Building matrix-sdk-crypto-wasm
 
 These WebAssembly bindings are written in [Rust]. To build them, you
 need to install the Rust compiler, see [the Install Rust

index-wasm-esm.mjs

@@ -0,0 +1,77 @@
+// Copyright 2024 The Matrix.org Foundation C.I.C.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// @ts-check
+
+/**
+ * This is the entry point for ESM environments which support the ES Module Integration Proposal for WebAssembly [1].
+ *
+ * [1]: https://github.com/webassembly/esm-integration
+ */
+
+import * as bindings from "./pkg/matrix_sdk_crypto_wasm_bg.js";
+
+// Although we could simply instantiate the WASM at import time with a top-level `await`,
+// we avoid that, to make it easier for callers to delay loading the WASM (and instead
+// wait until `initAsync` is called). (Also, Safari 14 doesn't support top-level `await`.)
+//
+// However, having done so, there is no way to synchronously load the WASM if the user ends
+// up using the bindings before calling `initAsync` (unlike under Node.js), so we just throw
+// an error.
+bindings.__wbg_set_wasm(
+    new Proxy(
+        {},
+        {
+            get() {
+                throw new Error(
+                    "@matrix-org/matrix-sdk-crypto-wasm was used before it was initialized. Call `initAsync` first.",
+                );
+            },
+        },
+    ),
+);
+
+/**
+ * Stores a promise of the `loadModuleAsync` call
+ * @type {Promise<void> | null}
+ */
+let modPromise = null;
+
+/**
+ * Loads and instantiates the WASM module asynchronously
+ *
+ * @returns {Promise<void>}
+ */
+async function loadModuleAsync() {
+    /** @type {typeof import("./pkg/matrix_sdk_crypto_wasm_bg.wasm.d.ts")} */
+    // @ts-expect-error TSC can't find the definitions file, for some reason.
+    const wasm = await import("./pkg/matrix_sdk_crypto_wasm_bg.wasm");
+    bindings.__wbg_set_wasm(wasm);
+    wasm.__wbindgen_start();
+}
+
+/**
+ * Load the WebAssembly module in the background, if it has not already been loaded.
+ *
+ * Returns a promise which will resolve once the other methods are ready.
+ *
+ * @returns {Promise<void>}
+ */
+export async function initAsync() {
+    if (!modPromise) modPromise = loadModuleAsync();
+    await modPromise;
+}
+
+// Re-export everything from the generated javascript wrappers
+export * from "./pkg/matrix_sdk_crypto_wasm_bg.js";

index.mjs

@@ -15,16 +15,21 @@
 // @ts-check
 
 /**
- * This is the entrypoint on non-node ESM environments (such as Element Web).
+ * This is the entrypoint on non-node ESM environments.
  * `asyncLoad` will load the WASM module using a `fetch` call.
  */
 
 import * as bindings from "./pkg/matrix_sdk_crypto_wasm_bg.js";
 
 const moduleUrl = new URL("./pkg/matrix_sdk_crypto_wasm_bg.wasm", import.meta.url);
 
-// We want to throw an error if the user tries to use the bindings before
-// calling `initAsync`.
+// Although we could simply instantiate the WASM at import time with a top-level `await`,
+// we avoid that, to make it easier for callers to delay loading the WASM (and instead
+// wait until `initAsync` is called). (Also, Safari 14 doesn't support top-level `await`.)
+//
+// However, having done so, there is no way to synchronously load the WASM if the user ends
+// up using the bindings before calling `initAsync` (unlike under Node.js), so we just throw
+// an error.
 bindings.__wbg_set_wasm(
     new Proxy(
         {},
@@ -39,7 +44,7 @@ bindings.__wbg_set_wasm(
 );
 
 /**
- * Stores a promise of the `loadModule` call
+ * Stores a promise of the `loadModuleAsync` call
  * @type {Promise<void> | null}
  */
 let modPromise = null;

package.json

@@ -20,6 +20,10 @@
     ],
     "exports": {
         ".": {
+            "matrix-org:wasm-esm": {
+                "types": "./index.d.ts",
+                "default": "./index-wasm-esm.mjs"
+            },
             "require": {
                 "types": "./index.d.ts",
                 "node": "./node.js",
@@ -35,6 +39,7 @@
     "files": [
         "index.mjs",
         "index.js",
+        "index-wasm-esm.mjs",
         "index.d.ts",
         "node.mjs",
         "node.js",