WebAssembly.Module.customSections()

This is an experimental technology
Because this technology's specification has not stabilized, check the compatibility table for usage in various browsers. Also note that the syntax and behavior of an experimental technology is subject to change in future versions of browsers as the specification changes.

The WebAssembly.customSections() function returns a copy of the contents of all custom sections in the given module with the given string name.

Syntax

var custSec = WebAssembly.Module.customSections(module, sectionName);

Parameters

module
The WebAssembly.Module object whose custom sections are being considered.
sectionName
The string name of the desired custom section.

Return value

A (possibly empty) array containing ArrayBuffer copies of the contents of all custom sections matching sectionName.

Exceptions

If module is not a WebAssembly.Module object instance, a TypeError is thrown.

Custom sections

A wasm module is comprised of a sequence of sections. Most of these sections are fully specified and validated by the wasm spec, but modules can also contain custom sections that are ignored and skipped over during validation. (Read High level structure for information on section structures, and how normal sections ("known sections") and custom sections are distinguished.)

This provides developers with a way to include custom data inside wasm modules for other purposes, for example the name custom section, which allows developers to provide names for all the functions and locals in the module (like "symbols" in a native build).

Note that the WebAssembly text format currently doesn't have a syntax specified for adding new custom sections; you can however add a name section to your wasm during conversion from text format over to .wasm. The wast2wasm command available as part of the wabt tool has a --debug-names option — specify this during conversion to get a .wasm with a names custom section, for example:

wast2wasm simple-name-section.was -o simple-name-section.wasm --debug-names

Example

The following example (see the custom-section.html source and live example) compiles and compiles the loaded simple-name-section.wasm byte code.

We then do a check using WebAssembly.Module.customSections, looking to see whether the module instance contains a "name" custom section by checking that its length is more than 0. Since there is a "name" section in the example, an ArrayBuffer object is returned.

fetch('simple-name-section.wasm').then(response =>
  response.arrayBuffer()
).then(bytes =>
  WebAssembly.compile(bytes)
).then(function(mod) {
  var nameSections = WebAssembly.Module.customSections(mod, "name");
  if (nameSections.length != 0) {
    console.log("Module contains a name section");
    console.log(nameSections[0]);
  };
});

Specifications

Specification Status Comment
Web Assembly JavaScript API
The definition of 'customSections()' in that specification.
Draft Initial draft definition.

Browser compatibility

Feature Chrome Edge Firefox (Gecko) Internet Explorer Opera Safari (WebKit)
Basic support 57 15[2] 52 (52)[1] No support 44 11
Feature Chrome for Android Android Webview Edge Mobile Firefox Mobile (Gecko) IE Mobile Opera Mobile Safari Mobile
Basic support 57 57 No support 52.0 (52)[1] No support No support 11

[1] WebAssembly is enabled in Firefox 52+, although disabled in the Firefox 52 Extended Support Release (ESR.)

[2] Currently supported behind the “Experimental JavaScript Features” flag. See this blog post for more details.

See also

Document Tags and Contributors

 Contributors to this page: chrisdavidmills, lukewagner, fscholz, svodnik
 Last updated by: chrisdavidmills,