Skip to content

[js-api] Fix editorial slips for JS API document - #2254

Merged
f52985 merged 5 commits into
WebAssembly:mainfrom
kaist-plrg:fix/js-api-self-contained-editorial
Oct 1, 2026
Merged

f52985 merged 5 commits into
WebAssembly:mainfrom
kaist-plrg:fix/js-api-self-contained-editorial

Conversation

@f52985

@f52985 f52985 commented Sep 30, 2026

Copy link
Copy Markdown
Collaborator

Context

We're building a framework that turns the JS API document's prose into a real interpreter, the same way ESMeta already does for ECMA-262 — extracting each <div algorithm>'s steps into an AST, lowering it to an IR, and running the result against the actual WebAssembly JS-API test suite. During that process, we found a few issues in this spec.

This PR (plus its two companions) covers the ones that are purely editorial — no semantic impact, just text that doesn't match this document's own conventions. That's why we bundled them into one PR instead of three separate ones. This particular PR only needs this document itself to check. The other two PRs split off the ones that do need that (places where the Core Spec moved on and this file didn't follow), and a recurring mistake with ECMA-262's ?/! shorthand.

(We also ran into a bunch of other issues along the way — real bugs, unclear prose, a few spots where the fix needs a judgment call. Those are bigger asks than these, so we'll send them one at a time instead of dumping everything into one PR.)

Changes

  • Two unlinked reject calls.
  • Empty ordered map literal written as the list notation « » instead of
    «[ ]» (read the imports).
  • contains phrasing for a map-membership check, instead of the
    map/exists idiom used everywhere else.
  • WebAssembly.JSTag's getter missing the <div algorithm> wrapper every
    other algorithm in this document has.
  • Memory/Table constructors reading descriptor["address"] without
    routing it through ToValueType, unlike every other enum-typed member.
  • the [=mem_size=](...) carrying a spurious leading article.
  • An unlinked "the memory address".
  • Global's value getter/setter sharing one <div algorithm>, unlike every
    other algorithm in this document. Split into two, each named explicitly via
    algorithm= the same way read the imports/memory.grow already are
    elsewhere in this file — the setter has no <dfn> of its own to infer a
    name from (it's the same IDL attribute as the getter, which keeps the one
    <dfn> for both), and the getter's explicit name is purely for symmetry.
  • is [=exception=] |exnaddr| — an ambiguous bare link (two dfns share the
    same text, resolved arbitrarily by Bikeshed today) that's also missing the
    "of the form" this document always uses to destructure a payload-carrying
    case.
  • ToJSValue's ref.i31 case missing "interpreted as a mathematical value",
    unlike its i64/i32/f32/f64 sibling cases.
  • Two match_valtype(...) conditions missing the "is true" suffix every
    other boolean-returning condition in this document uses.
  • A scalar |hostaddr| given a type-link annotation that only tag-carrying
    SpecTec values get elsewhere.
  • |addrtype| compared against raw quoted "i32"/"i64" literals instead
    of the [=i32=]/[=i64=] links used for every other numtype/valtype
    comparison.
  • An unpiped keys identifier in [[OwnPropertyKeys]].
  • Twelve external value variant links (func/global/mem/table) use
    Bikeshed pipe-display aliasing ([=external value|func=]) instead of the
    for-scoped form ([=external value/func=]) the sibling tag variant
    already uses correctly. link-defaults only registered tag; the other
    four get the same registration here.

Several small mismatches between this document's own text and the
established idioms it already uses elsewhere in the same file:

- empty ordered map literal written as the list notation « » instead
  of «[ ]» (read the imports)
- an unpiped 'keys' identifier in [[OwnPropertyKeys]]
- Global's value getter/setter sharing one <div algorithm>, unlike
  every other algorithm in the document. Both halves are now named
  explicitly via algorithm=, the same way 'read the imports'/
  'memory.grow' already are elsewhere in this file - the setter has
  no <dfn> of its own to infer a name from (it's the same IDL
  attribute as the getter, which keeps the one <dfn> for both), and
  the getter's explicit name is purely for symmetry with it
- 'contains' phrasing for a map-membership check, instead of the
  map/exists idiom used everywhere else
- an ambiguous bare [=exception=] link where two dfns share the same
  text, resolved arbitrarily by Bikeshed today
- ToJSValue's ref.i31 case missing 'interpreted as a mathematical
  value', unlike its i64/i32/f32/f64 sibling cases
- an unlinked 'the memory address' and two unlinked 'reject' calls
- 'the [=mem_size=](...)' carrying a spurious leading article
- two match_valtype(...) conditions missing the 'is true' suffix
  every other boolean-returning condition in the document uses
- a scalar |hostaddr| given a type-link annotation that only
  tag-carrying SpecTec values get elsewhere
- |addrtype| compared against raw quoted "i32"/"i64" literals
  instead of the [=i32=]/[=i64=] links used for every other
  numtype/valtype comparison
- Memory/Table constructors reading descriptor["address"] without
  routing it through ToValueType like every other enum-typed member
- WebAssembly.JSTag's getter missing the <div algorithm> wrapper
  every other algorithm in the document has
- 'is [=exception=] |exnaddr|' missing the 'of the form' this
  document always uses to destructure a payload-carrying case
- twelve 'external value' variant links (func/global/mem/table)
  using Bikeshed pipe-display aliasing ([=external value|func=])
  instead of the for-scoped form ([=external value/func=]) already
  used correctly for the sibling 'tag' variant, and by the adjacent
  external-type block for all five of its own variants. The
  link-defaults block only ever registered 'tag' as a for-scoped
  sub-term of 'external value', so the other four are given the
  same registration here.

None of these require knowing anything about the Wasm Core Spec's own
representation - each is checkable by reading this document alone.
Comment thread document/js-api/index.bs
Comment thread document/js-api/index.bs Outdated
Comment thread document/js-api/index.bs Outdated
Comment thread document/js-api/index.bs Outdated
f52985 and others added 3 commits October 1, 2026 10:57
Co-authored-by: Ms2ger <Ms2ger@gmail.com>
Co-authored-by: Ms2ger <Ms2ger@gmail.com>
Co-authored-by: Ms2ger <Ms2ger@gmail.com>
@f52985 f52985 closed this Oct 1, 2026
@f52985 f52985 reopened this Oct 1, 2026
@f52985
f52985 merged commit 957c932 into WebAssembly:main Oct 1, 2026
11 checks passed
@f52985
f52985 deleted the fix/js-api-self-contained-editorial branch October 1, 2026 11:33
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants