stdlib-js / stdlib-js/stdlib

[RFC]: add `@stdlib/wasm/instantiate`

Aperta
#14,208 0 commenti 0 reazioni 1 assegnatario Rivendicata da @0PrashantYadav0 Vedi su GitHub
Accepted Feature RFC WebAssembly
Lingua principale
JavaScript
Stelle
6k
Fork
1.3k
Merge medio
1g 3h
PR unite (30g)
611

Descrizione

### 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:`.

Guida per i contributori

Apri la guida per i contributori

Valutazione

Questa issue non è ancora stata valutata.

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.