Add another entrypoint using wasm-as-esm support

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",