69 lines
3.6 KiB
Markdown
69 lines
3.6 KiB
Markdown
|
# @napi-rs/wasm-runtime
|
||
|
|
|
||
|
|
Runtime helpers and browser polyfills for napi-rs WebAssembly addons.
|
||
|
|
|
||
|
|
## emnapi compatibility
|
||
|
|
|
||
|
|
Use matching versions of `@emnapi/core` and `@emnapi/runtime`:
|
||
|
|
|
||
|
|
- v1: `^1.7.1`. Core includes async work and threadsafe functions and ignores the
|
||
|
|
plugins option. Loading this package does not resolve the v2-only
|
||
|
|
`@emnapi/core/plugins` export.
|
||
|
|
- v2: the peer range is exactly `2.0.0-beta.2` or `2.0.0-beta.3`, and this
|
||
|
|
package bundles the async-work and TSFN plugins from `2.0.0-beta.3`. They
|
||
|
|
depend on private core context fields, which are the same in both betas
|
||
|
|
(`2.0.0-beta.3` changed only the TSFN release order). `2.0.0-beta.1` renamed
|
||
|
|
the context field `napiModule` to `addonModule`; the bundled plugins accept
|
||
|
|
both names, so bindings that pin a 2.0.0 alpha keep loading. A later
|
||
|
|
prerelease that changes the context again needs a new release of this
|
||
|
|
package.
|
||
|
|
|
||
|
|
The v2 peer range stays narrow on purpose. With an open range, npm can hoist a
|
||
|
|
binding's 2.0.0 alpha core next to this package, and then v1 bindings that
|
||
|
|
load through the ESM entry, or through tools that skip the CommonJS copy
|
||
|
|
lookup below, get a v2 core. With the narrow range, npm installs a v1 core for
|
||
|
|
this package when a binding pins another v2 prerelease. The binding's own
|
||
|
|
emnapi copy still runs it, as described below.
|
||
|
|
|
||
|
|
The CommonJS entry keeps emnapi copies apart when this package's peers resolve
|
||
|
|
to a different copy than a binding's own `@emnapi/core` and `@emnapi/runtime`
|
||
|
|
(two bindings pinning different emnapi versions, say):
|
||
|
|
|
||
|
|
- `instantiateNapiModule(Sync)` runs the core of the copy whose runtime created
|
||
|
|
`options.context`. It finds that runtime in `require.cache` and resolves the
|
||
|
|
core from the module that required it (the binding's loader).
|
||
|
|
- `getDefaultContext`, `createContext`, `MessageHandler`, and instantiation
|
||
|
|
without a context use the copy of the calling package when it declares both
|
||
|
|
emnapi packages as dependencies: the CommonJS module that is still loading
|
||
|
|
and required this package, or, in a worker thread, the worker's entry file.
|
||
|
|
- When the selected core is v2, the bundled plugins are replaced by that core's
|
||
|
|
own `@emnapi/core/plugins`.
|
||
|
|
- Anything else uses this package's peers. A context of the other emnapi
|
||
|
|
generation from no known copy throws a `TypeError` that says so.
|
||
|
|
|
||
|
|
The ESM entry is resolved by bundlers and cannot do this. It uses the bundled
|
||
|
|
plugins with the `addonModule` alias.
|
||
|
|
|
||
|
|
For raw `instantiateNapiModule` / `instantiateNapiModuleSync` calls loading a
|
||
|
|
single-threaded napi-rs addon, pass
|
||
|
|
`plugins: [emnapiAsyncWorkPlugin, emnapiTSFNPlugin]` from this package. Generated
|
||
|
|
napi-rs loaders already supply these plugins.
|
||
|
|
|
||
|
|
## Updating the bundled plugins
|
||
|
|
|
||
|
|
Update the exact v2 development dependencies together with the workspace
|
||
|
|
resolutions. `build` checks that the resolved core version is the exact
|
||
|
|
development version and one of the v2 versions in the peer range, and
|
||
|
|
`prepack` rebuilds the bundles so a package cannot silently reuse output from
|
||
|
|
an earlier build. Before a release, compare the new plugin context with the
|
||
|
|
oldest supported alpha (`2.0.0-alpha.3` is the oldest still pinned by published
|
||
|
|
bindings), and keep the CI matrix covering it. Keep earlier v2 versions in the
|
||
|
|
peer range while published bindings pin them (rolldown 1.2.16 pins
|
||
|
|
`2.0.0-beta.2`); removing one makes npm install a v1 core for this package
|
||
|
|
next to those bindings.
|
||
|
|
|
||
|
|
`yarn workspace @napi-rs/wasm-runtime test` exercises actual WebAssembly
|
||
|
|
initialization, async work, TSFN calls from a worker, worker load failures, and
|
||
|
|
cleanup through both module formats. CI also installs the packed tarball with
|
||
|
|
real v1 and v2 peers outside the workspace to avoid root resolution overrides.
|