[spec review] JS API

[flagxor]

Detail oriented review of draft text:
https://webassembly.github.io/spec/js-api/index.html

Please try to be ready to discuss issues by the in person spec meeting.

[erights]

The instantiate overloading is bad JS style. Type overloading on an input argument is fine as a way to get coercion-like functionality. In this case, if given bytes, compile it to a moduleObject so the client needn't bother. However, having the output type depend on the input type, in a dynamically typed language, means that a reader does not know, looking at the call site, which output type to expect unless they know what input type is being provided.

In this case, the full signature of each of these overloadings is adequately motivated. But they should not be overloads. They should have different names. (This is one of many ways that WebIDL and its ancestry in statically typed CorbaIDL systematically leads to the design of bad JS APIs.)

[chicoxyzzy]

Should grow_mem and size_mem be renamed to grow_memory and size_memory to be consistent with core spec?
#627 (comment)

[rossberg]

@chicoxyzzy, these are from the core spec. The core spec uses "mem" for internal naming throughout, since it occurs a lot and therefore cuts down verbosity notably.

[chicoxyzzy]

@rossberg in @binji's comment I mentioned above it said that CG

decided to go with memory

[chicoxyzzy]

for internal naming

Ah, now I got it, sorry

[erights]

(Comment deleted as mistaken and irrelevant)

[littledan]

@erights Thanks for the review. I don't think it would be possible to change the signature at this point, given that this API has already shipped to the web in several browsers some time ago.

[erights]

This document suffers from standing between different spec worlds written in different spec styles:

• The wasm spec
• The w3c spec conventions
• The EcmaScript spec

The two main ways this shows up:

• Treatment of mutable state
• Terminology and distinctions

Treatment of mutable state

The wasm spec is written in a purely functional store-passing style, where there's a global (per agent) synchronous store mapping from (abstract?) addresses to (locations containing?) values. Each mutating operation is written to accept a store as input and to emit the mutated store as output, which then gets threaded through the subsequent operations. This encodes the imperative notion of a naive sequence of operations in time into a position along the thread of threaded store passing.

The EcmaScript spec, and the general w3c spec style, is to use the same imperative sequence in the spec metalanguage as is used in the language being described. State change in the described language is described directly as change of semantic state in the meta language.

Mixing the two is a bit incoherent, and worse, accident prone. It is incoherent because a change to the state of a JavaScript object is specified in the EcmaScript or general w3c imperative style, thereby omitting this state from the global (per agent) synchronous being threaded forward. For example, in the steps under

The grow(d) method, when invoked, performs the following steps:

where it says

Set the surrounding agent's associated store to store.

we would thereby wipeout the changes to the store caused within the call to grow_table immediately above. The good news is that this is so clearly not the intention that there is little danger anyone will misunderstand the spec to mean what it literally says ;). Nevertheless, we should find a way to avoid straddling the two ways to model state in the meta-language.

Attn @flagxor @rossberg @littledan

Terminology and Distinctions

This spec uses phrases like "queue a task", linking to https://html.spec.whatwg.org/multipage/webappapis.html#queue-a-task as the definition. However, this "task" notion is specific to browsers and has no relevance to JavaScript in general. The most closely corresponded EcmaScript spec concept is the (horribly named) "job", which is the unit of work queued on EcmaScript's "job queues". Unlike a browser "task", a job is serviced by a single turn of the event loop. EcmaScript has no "task" vs "microtask" dichotomy and instead has multiple job queues. The browser concepts of "task" and "microtask" are mapped into a structure of jobs; but this decomposition is by no means universal. Other embeddings of wasm into JavaScript outside the browser may very well have no browser-like "task" concept.

Attn @domenic @littledan @flagxor

[erights]

This spec introduces a bunch of new Error types that are true subclasses of Error. Besides having all behavior associated with NativeError, the spec is also clear that it should have whatever stack behavior is associated with other Errors. This is all good I think.

I note here that we've avoided introducing new Error types in tc39, perhaps not for any good reason. Now that classes can genuinely extend, by subclassing, built in types, perhaps such new Error types can even be accurately polyfilled by such user-written subclasses. I think these options should be raised on the tc39 side as a general issue. Just noting it here.

[erights]

The spec makes clear that each imported (moduleName, componentName) pair is looked up on the two level importObject by redundantly looking up the moduleName each time. It seems both more intuitive and more efficient, though requires more mechanism to spec, for any one moduleName to be looked up only once, to obtain the object on which all associated componentNames will be looked up.

[erights]

In that instantiating section, where it says

If externtype is of the form 𝖿𝗎𝗇𝖼 functype,

the bound functype is not subsequently used. It would be nice if some convention were used to ease the burden on spec readers of fruitlessly searching for such uses. In code we often use underbar or "unused" for such things.

This comes up several times.

[erights]

Let index be the number of external functions in imports. This value index is known as the index of the host function funcaddr.

That index is not used. Since this step has no other purpose, it should be removed.