Proposal: Rename *Type to *Descriptor

[syrusakbary]

Hi all!

We are on the process of adopting the wasm-c-api in Wasmer, and there are a few suggestions we have over naming and so that we believe would be good to discuss for the c-api.

Right now, the meta types in the c-api are named FuncType, TableType, MemoryType and GlobalType. However the Javascript WebAssembly API uses the description nomenclature:

The WebAssembly.imports() function returns an array containing descriptions of all the declared imports of the given Module. The WebAssembly.Module.exports() function returns an array containing descriptions of all the declared exports of the given Module.

(from https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly/Module/imports)

We discussed it internally and thought it could be a bit easier (from an API usage perspective), to use a descriptor nomenclature instead of Type one.

Current:

Global::new(GlobalType { ... })

Proposed:

Global::new(GlobalDescriptor { ... })

Why Descriptor instead of Type?

In general, the people we discussed with have a different thing in mind when thinking about types. If we ask them what they think what a global type would be, they reply the value type (i32, i64, f32, f64, ...), or even the type with the mutability (but never with the initializer)... so that's why we believe the Type nomenclature might be causing some confusion.

I'd love to get more thoughts on this!

[binji]

The core spec does refer to these as types, see https://webassembly.github.io/spec/core/syntax/types.html#types. In addition, the js-types proposal renames these to types as well. I'm not certain why the JS API calls them descriptors currently, perhaps someone else can comment on that.

[rossberg]

What @binjji said. Technically, these are types, but types of ex/import entities (external values, as the spec calls them), not types of simple values.

I believe the JS API probably called them descriptors initially because it only used them for constructors, not as a general notion for describing/reflecting types.

[nlewycky]

I also misremembered the spec using the term descriptors for these, but indeed it does not! I guess I've gotten used to the JS terminology.

Regardless, I agree that the wasm C API should follow the terminology used in the spec. I think the point about global type and global type referring to "const | var valttype" and "valtype" is valid, but if we want to pursue that, we can discuss it on the spec repo.

[syrusakbary]

Thanks everyone for the feedback, I relayed it back to the team and we all agreed to go with the *Type terminology to get higher consistency with the standard.

Closing the issue 🙂

[syrusakbary]

I've been reading the WebAssembly specification (js) and I realized it could be useful to reopen this issue (or close it here and open it somewhere else?), as there is a mismatch between the nomenclature in the WebAssembly JS Spec and the WebAssembly specification.

Adding some extra information to this thread, as it might be useful to know for the future.

The WebAssembly JS spec page, refers to Memory, Table and Global types as MemoryDescriptor, TableDescriptor and GlobalDescriptor respectively:

dictionary MemoryDescriptor {
  required [EnforceRange] unsigned long initial;
  [EnforceRange] unsigned long maximum;
};

From https://webassembly.github.io/spec/js-api/index.html#memories

dictionary TableDescriptor {
  required TableKind element;
  required [EnforceRange] unsigned long initial;
  [EnforceRange] unsigned long maximum;
};

From: https://webassembly.github.io/spec/js-api/index.html#tables

dictionary GlobalDescriptor {
  required ValueType value;
  boolean mutable = false;
};

From: https://webassembly.github.io/spec/js-api/index.html#globals

Note: At Wasmer we are still adopting the Type nomenclature to follow the wasm-c-api, but I think it will good to iron/standardize this definitions?

[syrusakbary]

(If I should open this issue somewhere else, please let me know and I'll close it here!)

[rossberg]

@syrusakbary, see the JS Types proposal, which resolves this mismatch.

[syrusakbary]

Thanks!!