Editorial review: Improve docs for Wasm mutable globals

[chrisdavidmills]

Description

This PR documents Wasm mutable globals. We had a bit of this already, which this PR largely cleans up. Specifically, it:

• Changes global from an instruction to a definition, and adds a lot more detail, including using the new template.
• Adds a lot more detail to global.get and global.set, including using the new template.
• Updates the WebAssembly.Global JS API docs to add more detail and add pages for value and valueOf

Motivation

Additional details

Related issues and pull requests

[github-actions]

Preview URLs (10 pages)

• /en-US/docs/WebAssembly/Reference/Definitions/global
• /en-US/docs/WebAssembly/Reference/Definitions
• /en-US/docs/WebAssembly/Reference/JavaScript_interface/Global/Global
• /en-US/docs/WebAssembly/Reference/JavaScript_interface/Global/valueOf
• /en-US/docs/WebAssembly/Reference/JavaScript_interface/Global/value
• /en-US/docs/WebAssembly/Reference/JavaScript_interface/Global
• /en-US/docs/WebAssembly/Reference/Variables/global.get
• /en-US/docs/WebAssembly/Reference/Variables/global.set
• /en-US/docs/WebAssembly/Reference/Variables
• /en-US/docs/WebAssembly

Flaws (1)

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

Found an unexpected or unresolvable flaw? Please report it here.

URL: /en-US/docs/WebAssembly/Reference/Definitions/global
Title: global: Wasm definition
Flaw count: 1

• macros:
  • Macro jsxref produces link /en-US/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly/Global/Global which is a redirect

External URLs (9)

URL: /en-US/docs/WebAssembly
Title: WebAssembly

• https://emscripten.org/ (1 time)
• https://github.com/JasonWeathersby/WASMSobel (1 time)
• https://hacks.mozilla.org/category/webassembly/ (1 time)
• https://research.mozilla.org/ (1 time)
• https://web.dev/articles/emscripting-a-c-library (1 time)
• https://webassembly.org/ (1 time)
• https://www.w3.org/community/webassembly/ (2 times)
• https://www.w3.org/groups/wg/wasm/ (1 time)

---

URL: /en-US/docs/WebAssembly/Reference/Definitions/global
Title: global: Wasm definition

• https://webassembly.github.io/spec/core/valid/instructions.html (1 time) (Note! This may be a new URL 👀)

(comment last updated: 2026-04-27 17:04:29)

[bvisness]

Overall this looks solid and long overdue!

[bvisness]

I think it all looks good to me now except for the list-of-types thing and the constant-expression thing.

[chrisdavidmills]

I think it all looks good to me now except for the list-of-types thing and the constant-expression thing.

Superb, thanks @bvisness. I think I've fixed them appropriately, but let me know if you think they need some more work.

In the meantime, I think this can be safely passed on to the editorial review stage. @hamishwillee, fancy a bit more Wasm? You know you do ;-)

[hamishwillee]

FMI what happens if the conditions are not true? I mean it might fail, but what are the side effects, if any, of failure?

[chrisdavidmills]

Yeah, sorry, a TypeError is thrown. There are no side effects as such, just the value is not changed because it is immutable.

[chrisdavidmills]

I've updated the page to explain in more detail what happens if those conditions are not true. Really oddly, if you set the value to a different data type, like a string, the value is set to 0, and the global becomes mutable. I observed this behavior in both Firefox and Chrome.

@bvisness is this expected behavior? Sounds like a bug to me.

[hamishwillee]

Wierd. From a docs point of view your fix is good though.

[hamishwillee]

@hamishwillee, fancy a bit more Wasm? You know you do ;-)

I hate you :-)

Looks pretty good. A few nits/points for discussion.

[hamishwillee]

Thanks very much @chrisdavidmills

I've approved, but if it were me I might wait for a response from @bvisness on #43843 (comment) before merging.

[chrisdavidmills]

Thanks very much @chrisdavidmills

I've approved, but if it were me I might wait for a response from @bvisness on #43843 (comment) before merging.

Cool, thanks very much for your work on this, @hamishwillee. I'll get the Wasm engineers to comment on this asap.

[bvisness]

This is straightforwardly contradicted by the content below, no? If you declare it with an i32 but try to set it to a string, you don't get a TypeError, you get a coerced value of some kind.

Personally, I do not think it is worth belaboring the fact that ill-typed values get coerced to something else. This is obvious and pervasive across not just WebAssembly APIs but all web APIs. For example, parseInt takes a string argument, but you can call it with a number, and the first thing the spec does is to run ToString on it. This is not documented because to do so would be exhausting and unhelpful (e.g. what happens with numbers, arrays, objects, null, undefined, BigInt? who cares?)

Specifically, for WebAssembly, any time a JS value is passed to WebAssembly, it is passed through the ToWebAssemblyValue operation, which typically just calls operations like ToInt32 and ToNumber in the JS spec. In this case, because the global has type i32, it is calling ToInt32, which snakes around in a bunch of confusing logic but at the end of the day does a best-effort attempt to convert a string to a number. Your "hello" example converts to zero, but "123" converts to 123, "3.14" converts to 3, and "0xDEADBEEF" converts to -559038737. Therefore your disclaimer is actually incomplete and unhelpful.

In the end, this is just typical JS stuff and shouldn't be documented here.

[chrisdavidmills]

OK, sorry, that wasn't very well thought out. I've removed all the stuff about typing and coercion, and just kept it simple:

The value property of a Global object instance allows you to directly get or set the global's value.

For the setter to work, the global must be mutable (the mutable option was set to true when it was declared). If this is not the case, a TypeError exception is thrown.

[bvisness]

Per the above, this is wrong because only some strings coerce to 0; others coerce to actual numeric values.

[bvisness]

The updates look good to me!

[chrisdavidmills]

The updates look good to me!

Excellent. Let's get it merged!