[RFC]: add `@stdlib/wasm/instantiate`
- Dominant language
- JavaScript
- Stars
- 6k
- Forks
- 1.3k
- Avg merge
- 1d 3h
- Merged PRs (30d)
- 611
Description
### Description
This RFC proposes to add `@stdlib/wasm/instantiate`
## Findings
`@stdlib/wasm/module-wrapper` still calls platform globals for compilation and instantiation. Async paths use `WebAssembly.instantiate`; sync paths use `WebAssembly.Module` and `WebAssembly.Instance`. Those TODOs point at `@stdlib/wasm/instantiate` (and related packages).
The existing `@stdlib/wasm/memory` package is the right pattern: feature-detect with `@stdlib/assert/has-wasm-support`, export a strict native alias when supported, otherwise a polyfill that throws `not implemented`. `@stdlib/wasm/instantiate` should follow that same shape, except the export is a **function** (not a constructor).
`@stdlib/promise/ctor` (with polyfill) already under review in #14140 and will be used by `module-wrapper` for `initialize()`. That item is done and is not part of this work.
`WebAssembly.instantiate` and `new WebAssembly.Instance(...)` are different APIs. The TODOs map both names to `@stdlib/wasm/instantiate`, but they should stay separate: `instantiate` for the async function, and a later `@stdlib/wasm/instance` for the sync constructor (same idea as `memory` / `module`).
Native `instantiate` has two overloads that must pass through unchanged:
- bytes → `Promise<{ module, instance }>`
- compiled module → `Promise`
## Future plan
1. Ship `@stdlib/wasm/instantiate` as a thin alias of `WebAssembly.instantiate` (package, tests, docs, namespace export). **Done.**
2. Add `@stdlib/wasm/module` for `WebAssembly.Module`.
3. Add `@stdlib/wasm/instance` for `WebAssembly.Instance`.
4. Update `module-wrapper` to use the new packages and remove the remaining TODOs.
5. Optionally extract `PAGE_SIZE` to `@stdlib/constants/wasm/page-size`.
### Related Issues
Related PR #14140
### Questions
No.
### Other
No.
### Checklist
- [x] I have read and understood the [Code of Conduct](https://github.com/stdlib-js/stdlib/blob/develop/CODE_OF_CONDUCT.md).
- [x] Searched for existing issues and pull requests.
- [x] The issue name begins with `RFC:`.
Contributor guide
Assessment
This issue has not been assessed yet.