wasm-builtin-naming.md

Wasm Builtin Naming

JS String Builtins

"wasm:js-string"

corresponding to builtins: ['js-string'] in CompileOptions.

ESM Integration

"wasm:js/string-constants"

via passing { importedStringConstants: 'wasm:js/string-constants', builtins: ['js-string'] } in WebAssembly/esm-integration#115.

Text Encoding

Currently uses:

"wasm:text-encoding"

based off of original suggestions:

"wasm:text-encoder"
"wasm:text-decoder"

Custom Descriptors

"wasm:js-prototypes"

via builtins: ['js-prototypes']

Casing Rules

1. Module specifier name is kebab case
2. Import name is camel case (at least for JS builtins so far)

JS Prefixing

Motivation to add wasm:js/ prefix came up in bikeshed discussion WebAssembly/esm-integration#118 by @eqrion.

Was not formally discussed in CG, so bringing this up. As far as I understand the justification:

• wasm: chosen as the general builtin scheme over wasm-js: for builtins
• js/ prefix allows separating JS host builtins from non-JS host builtins

Questions

• Does the committee align with this logic?
• Should these guidelines be written up somewhere?

---

Migration Path

The recommendation going forward would then be for all JS builtins to be defined under the wasm:js/ prefix.

Given current experimental status, perhaps only JS String Builtins requires a migration path?

For the others, simply switching to wasm:js/ should be sufficient:

1. Update builtins: ['js-string'] to enable wasm:js/string as well as wasm:js-string for a migration path
2. Update builtins: ['js-prototypes'] to enable wasm:js/prototypes
3. Update builtins: ['text-encoding'] to enable wasm:js/text-encoding (or wasm:js/text-encoder and wasm:js/text-decoder)

The builtins: ['<builtinset>'] naming remains an inconsistency then, but perhaps we can consider JS CompileOptions as implying JS already to some extent so that repeating the js term here is less necessary?

Questions

• Do we have consensus for the proposed migration path, or are there suggested adjustments?
• Are we okay with builtins naming not fully relating to the import, at least for the original proposals?
• The ESM Integration always turns on all JS builtins - if we had a consistent definition for this we could more simply specify builtins: ['js']. would there be support for this and where should it be specified? In the ESM Integration itself?

---

New Builtin Suggestion: WebAssembly.JSTag

Would like to also discuss making WebAssembly.JSTag available as a builtin import, perhaps via:

(module
  (import "wasm:js/exceptions" "jsTag" (tag $js-tag (param externref)))

  (func (export "throwArg") (param $msg externref)
    local.get $msg
    throw $js-tag
  )
)

Usage:

import { throwArg } from './mod.wasm';
throwArg(new Error('this error gets thrown'));

Questions

• Would there be interest in this builtin?
• Since the exception handling proposal is already integrated, would a dedicated proposal be necessary?