WebAssembly.Tag

Baseline Widely available *

This feature is well established and works across many devices and browser versions. It’s been available across browsers since May 2022.

* Some parts of this feature may have varying levels of support.

The WebAssembly.Tag object defines a type of a WebAssembly exception that can be thrown to/from WebAssembly code.

When creating a WebAssembly.Exception, the tag defines the data types and order of the values carried by the exception. The same unique tag instance must be used to access the values of the exception (for example, when using Exception.prototype.getArg()).

Constructing an instance of Tag creates a new unique tag. This tag can be passed to a WebAssembly module as a tag import, where it will become a typed tag defined in the tag section of the WebAssembly module. You can also export a tag defined in a module and use it to inspect exceptions thrown from the module.

Note: You can't access the values of an exception with a new tag that just happens to have the same parameters; it's a different tag! This ensures that WebAssembly modules can keep exception information internal if required. Code can still catch and rethrow exceptions that it does not understand.

Constructor

WebAssembly.Tag()

Creates a new WebAssembly.Tag object.

Instance methods

Tag.prototype.type()

Returns the object defining the data-types array for the tag (as set in its constructor).

Examples

This code snippet creates a new Tag instance.

const tagToImport = new WebAssembly.Tag({ parameters: ["i32", "f32"] });

The snippet below shows how we might pass it to a module example.wasm during instantiation, using an "import object".

js
const importObject = {
  extmod: {
    exttag: tagToImport,
  },
};

WebAssembly.instantiateStreaming(fetch("example.wasm"), importObject).then(
  (obj) => {
    // …
  },
);

The WebAssembly module might then import the tag as shown below:

wat
(module
  (import "extmod" "exttag" (tag $tagname (param i32 f32))
)

If the tag was used to throw an exception that propagated to JavaScript, we could use the tag to inspect its values.

Note: There are many alternatives. We could also use the tag to create a WebAssembly.Exception and throw that from a function called by WebAssembly.