Document wasm JS builtins

[chrisdavidmills]

Description

Chrome 130 supports WebAssembly JS String builtins.

Specifically, This PR adds:

• A guide explaining what builtins are and how to use them.
• Information about the new compileOptions parameter used to enable these built-ins, which is available to:
  • WebAssembly.compile()
  • WebAssembly.compileStreaming()
  • WebAssembly.instantiate()
  • WebAssembly.instantiateStreaming()
  • WebAssembly.validate()
  • The WebAssembly.Module() constructor

Motivation

Additional details

See https://chromestatus.com/feature/6695587390423040 for the data source.

Related issues and pull requests

[github-actions]

Preview URLs (8 pages)

• /en-US/docs/WebAssembly/JavaScript_builtins
• /en-US/docs/WebAssembly/JavaScript_interface/Module/Module
• /en-US/docs/WebAssembly/JavaScript_interface/compileStreaming_static
• /en-US/docs/WebAssembly/JavaScript_interface/compile_static
• /en-US/docs/WebAssembly/JavaScript_interface/instantiateStreaming_static
• /en-US/docs/WebAssembly/JavaScript_interface/instantiate_static
• /en-US/docs/WebAssembly/JavaScript_interface/validate_static
• /en-US/docs/WebAssembly/JavaScript_interface

Flaws (1)

Note! 7 documents with no flaws that don't need to be listed. 🎉

URL: /en-US/docs/WebAssembly/JavaScript_builtins
Title: WebAssembly JavaScript builtins
Flaw count: 1

• macros:
  • /en-US/docs/Web/API/Console/log redirects to /en-US/docs/Web/API/console/log_static

External URLs (10)

URL: /en-US/docs/WebAssembly/JavaScript_builtins
Title: WebAssembly JavaScript builtins

• https://github.com/WebAssembly/binaryen (1 time) (Note! This may be a new URL 👀)
• https://github.com/WebAssembly/binaryen?tab=readme-ov-file (1 time) (Note! This may be a new URL 👀)
• https://github.com/WebAssembly/js-string-builtins/blob/main/proposals/js-string-builtins/Overview.md (3 times) (Note! This may be a new URL 👀)
• https://mdn.github.io/webassembly-examples/js-builtin-examples/instantiate/ (1 time) (Note! This may be a new URL 👀)

---

URL: /en-US/docs/WebAssembly/JavaScript_interface/compile_static
Title: WebAssembly.compile()

• https://mdn.github.io/webassembly-examples/js-builtin-examples/compile/ (1 time) (Note! This may be a new URL 👀)

---

URL: /en-US/docs/WebAssembly/JavaScript_interface/compileStreaming_static
Title: WebAssembly.compileStreaming()

• https://mdn.github.io/webassembly-examples/js-builtin-examples/compile-streaming/ (1 time) (Note! This may be a new URL 👀)

---

URL: /en-US/docs/WebAssembly/JavaScript_interface/instantiateStreaming_static
Title: WebAssembly.instantiateStreaming()

• https://mdn.github.io/webassembly-examples/js-builtin-examples/instantiate-streaming/ (1 time) (Note! This may be a new URL 👀)

---

URL: /en-US/docs/WebAssembly/JavaScript_interface/validate_static
Title: WebAssembly.validate()

• https://mdn.github.io/webassembly-examples/js-builtin-examples/validate/ (1 time) (Note! This may be a new URL 👀)

---

URL: /en-US/docs/WebAssembly/JavaScript_interface/instantiate_static
Title: WebAssembly.instantiate()

• https://mdn.github.io/webassembly-examples/js-builtin-examples/instantiate/ (1 time) (Note! This may be a new URL 👀)

---

URL: /en-US/docs/WebAssembly/JavaScript_interface/Module/Module
Title: WebAssembly.Module() constructor

• https://mdn.github.io/webassembly-examples/js-builtin-examples/module-constructor/ (1 time) (Note! This may be a new URL 👀)

(comment last updated: 2024-12-13 13:45:39)

[jakobkummerow]

builtins is just as optional as importedStringConstants, so this line should have {{optional_inline}}.

Same in the five other copies of this paragraph.

[chrisdavidmills]

Good call; I've updated these to add the "optional" label in my next commit.

[jakobkummerow]

Nope, this won't work. compileOptions, if present, must be the third argument. You'll have to pass an empty object ({}) as importObject if the module needs no imports (which is exceedingly rare in practice).

[chrisdavidmills]

D'oh, that was silly. I have fixed these instances.

[jakobkummerow]

Same here: compileOptions, if present, must be the third parameter (as in line 80).

[chrisdavidmills]

Fixed

[jakobkummerow]

Same here: compileOptions must be the third parameter.

[chrisdavidmills]

Fixed.

[jakobkummerow]

Yes, but that's not at all how you'd feature-detect the JS String Builtins. When this feature is present, then type checks will be stricter than without it (because it imposes certain rules on the imports that will get "magic" treatment).

So to detect this feature, you define a module that's invalid with the feature present, but valid without it, and return true when validation failed. A simple/short way to do this is:

(module
  (function (import "wasm:js-string" "cast")))

Without JS String Builtins, that's perfectly valid, because you can import any function you want with any signature you want (in this case: no parameters and no return values).
With JS String Builtins, this module is invalid, because the now-special-cased "wasm:js-string" "cast" function must have a specific signature (consuming an externref, returning a non-nullable (ref extern)).

In wire bytes, that module is so short that you can just embed the literal:

function IsJsStringBuiltinsSupported() {
  let bytes = new Uint8Array([
    0,   97,  115, 109, 1,   0,   0,  0,   1,   4,   1,   96,  0,
    0,   2,   23,  1,   14,  119, 97, 115, 109, 58,  106, 115, 45,
    115, 116, 114, 105, 110, 103, 4,  99,  97,  115, 116, 0,   0
  ]);
  return !WebAssembly.validate(bytes, {builtins: ["js-string"]});  // Note '!'!
}

That said, detecting this feature is often not even necessary, because it can so easily be polyfilled. You can simply provide real imports to take the place of the magic imports, and if the engine supports JS String Builtins, it'll ignore those fallbacks.

[chrisdavidmills]

Ah, thanks, this is really helpful! I've repurposed my existing example as a basic "this is how to validate a module along with builtins", and taken the liberty of including your above explanation as an additional feature detection example. I hope you don't mind, but this is too useful to not include.

[chrisdavidmills]

It'll be present when I push my next commit.

[jakobkummerow]

We're not implementing builtin types, but operations. As far as WebAssembly types are concerned, every imported string is just a generic externref.

[chrisdavidmills]

OK, understood. I've gone through the pages and made sure to find other ways to refer to "different available builtins" than "builtin types", given that "type" has a specific meaning that may confuse.

[jakobkummerow]

"Other builtins are likely to be supported in the future."

It's not about types, and not about the JS concept of "primitive" types/values. For example, one of the next candidates could be DataView-related operations, but that's totally TBD (i.e. probably too early to mention here).

[chrisdavidmills]

Good call; I've used your wording here. I've also scanned through the pages and made sure that there are no other problematic uses of "primitives" remaining.

[jakobkummerow]

"## WebAssembly JavaScript Builtins"

[chrisdavidmills]

I've changed this to "## Available WebAssembly JavaScript builtins": I wanted to be clear that here we are discussing which builtins are available (which is what led me to use "types" in the first place ;-) ), rather than just discussing builtins in general.

[jakobkummerow]

If you switch to the term "namespace" above, then please also switch here.

Might also be worth mentioning that the choice is made by the authors of the toolchain that will generate the Wasm modules. Once you have a .wasm file and want to embed it in your JavaScript, you can't freely choose this namespace any more; you have to use what that .wasm file expects.

[chrisdavidmills]

OK, I've updated "identifier" to namespace in the different pages, and taken heed of your suggested wording.

[jakobkummerow]

Below (line 104), you use the term "namespace". Might be good to use the same term here, to avoid confusion. Perhaps phrase it roughly like: "..., which selects one import namespace for imported global string constants that the engine will populate automatically".

(You can use these imported string constants for anything you want, not just for the imported JS String Builtins. For example, you could import additional custom functions that work on strings.)