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 (9 pages)

• /en-US/docs/WebAssembly/Imported_string_constants
• /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

External URLs (11)

URL: /en-US/docs/WebAssembly/Imported_string_constants
Title: WebAssembly Imported global string constants

• 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_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 (15 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-20 09:34:21)

[tomayac]

LGMT, with just a couple of typo nits. Generally I think it should be "Wasm", no "wasm".

[hamishwillee]

Demonstrate this please.

[chrisdavidmills]

We were going to add a separate section or article in the new year but with your recommendation to move the feature detection example to the main article, I might try to include this too. But I might still leave it to the new year as a separate task so we can get this merged before you disappear for your holidays ;-)

[chrisdavidmills]

OK, leaving it until the new year.

[hamishwillee]

FWIW I like this section - I didn't understand it when I scan-read the explainer. Seems a painful requirement to have to write your own testing function like this when everyone will have to do it.

[jakobkummerow]

But as line 119 says, most people won't need this. (And those that do can copy-paste these few lines?)

[chrisdavidmills]

Plus, people write their own feature detection code all the time or copy and paste it from MDN or SO. So I don't think this is anything out of the ordinary.

[hamishwillee]

Re the testing function I think I was confused by why we said they won't need this - I think you mean "there are alternatives".

I guess my take was that it is a lot harder than feature checking against existence of a Javascript property on a prototype. It isn't all that onerous though.

[hamishwillee]

@chrisdavidmills Looks great. Some comment inline. I am around Friday and Monday if you want to iterate this to completion quickly.

[chrisdavidmills]

@chrisdavidmills Looks great. Some comment inline. I am around Friday and Monday if you want to iterate this to completion quickly.

@hamishwillee damn you and your pesky really useful review comments! (cheers mate, that was awesome). I've responded to all your stuff; hopefully, we can get this in before Xmas.

[jakobkummerow]

LGTM with comments.

[jakobkummerow]

LGTM.

(I'll be out for the holidays now, so please don't wait for reviews from me for any future revisions.)

[jakobkummerow]

Might be worth pointing out here that "equals" is the only function of the bunch that doesn't throw/trap for null inputs, so Wasm modules don't need to separately check for non-null-ness before calling "equals". (All the other functions have no reasonable way to handle null inputs, so they throw for them.)

[chrisdavidmills]

Added.

[jakobkummerow]

I suppose this is where we should add a link to the polyfill (in a separate PR next year).

[chrisdavidmills]

Yes indeed!

[hamishwillee]

By "In many cases it is not necessary to feature detect builtins" I think you are actually saying "there are alternatives to feature checking" - right? If so, this is a little ambiguous - it could mean you don't have to because it doesn't matter if they work or not.

So maybe

There are alternatives to feature checking for builtin support. For example, you can polyfil or .xxxx ...

[chrisdavidmills]

Yeah, I like this approach. Updated.

[hamishwillee]

Having a separate doc works well for me!

Arguably you don't need the justification/explanation of the old way - you could present this without the reasons the new ways is better and get the the "how you do it" much faster. I would have done it that way, but happy with this as well, because I kind of like knowing "why's". Either way, it is very clear.

FWIW part of the problem I had with this before reading the doc is the term "import", as in we import strings into the module.

When I think of import I think of something coming from somewhere else, so in the original mechanism we import strings defined in JavaScript. Here we magically import strings, but we define them in place.
Or to put it another way, the semantics from a WASM point of view are import, but from a developer point of view it is define.

I don't know if that concern/misunderstanding makes sense, but might be nice to say a few words, if possible. Could be something that no one in the WASM space would have a problem with.

[chrisdavidmills]

Hmm, I feel like this is a bit of an overwrought worry — if you don't care about the old way, and/or know it well, then you can just skip ahead to the second section. But the first section does help relative newcomers understand why this feature is needed (this was literally the first question in my mind when I started to learn about it), including why this is semantically still importing.

[hamishwillee]

@chrisdavidmills (and @jakobkummerow ) there are a few grumbles inline, but I think this is really good. What's your roadmap for publishing given the sidebar isn't present yet?

Or to put it another way, I can see your responses on (my) Monday. If I'm happy do you want me to approve/merge?

[chrisdavidmills]

@chrisdavidmills (and @jakobkummerow ) there are a few grumbles inline, but I think this is really good. What's your roadmap for publishing given the sidebar isn't present yet?

Or to put it another way, I can see your responses on (my) Monday. If I'm happy do you want me to approve/merge?

@hamishwillee the new sidebar code got merged yesterday, so we are all good there.

I agreed with most of your last few comments and made the changes. I don't think there is anything controversial left on the table, so I'm gonna merge it now. Thanks all!