@napi-rs/cli 3.9.1 → 3.10.1

package/src/api/create-npm-dirs.ts

@@ -49,6 +49,7 @@ export interface PackageMeta {
 }
 
 const WASM_RUNTIME_PACKAGE_NAME = '@napi-rs/wasm-runtime'
+const ASYNC_RUNTIME_PACKAGE_NAME = '@napi-rs/async-runtime'
 
 interface PendingMetadataWrite {
   content: string
@@ -66,25 +67,25 @@ interface OwnedWasiPackage {
   target: Target
 }
 
-async function getLatestWasmRuntimeVersion() {
+async function getLatestPackageVersion(packageName: string) {
   const npmRegistryBase =
     process.env.npm_config_registry?.replace(/\/?$/, '/') ??
     'https://registry.npmjs.org/'
-  const packageMetadataUrl = `${npmRegistryBase}${WASM_RUNTIME_PACKAGE_NAME}`
+  const packageMetadataUrl = `${npmRegistryBase}${packageName}`
   let response: Response
 
   try {
     response = await fetch(packageMetadataUrl)
   } catch (error) {
     throw new Error(
-      `Failed to fetch ${packageMetadataUrl} while resolving ${WASM_RUNTIME_PACKAGE_NAME}. Check your network connection and npm registry availability.`,
+      `Failed to fetch ${packageMetadataUrl} while resolving ${packageName}. Check your network connection and npm registry availability.`,
       { cause: error },
     )
   }
 
   if (!response.ok) {
     throw new Error(
-      `Failed to fetch ${packageMetadataUrl} while resolving ${WASM_RUNTIME_PACKAGE_NAME}: npm registry responded with ${response.status} ${response.statusText || 'Unknown Status'}`,
+      `Failed to fetch ${packageMetadataUrl} while resolving ${packageName}: npm registry responded with ${response.status} ${response.statusText || 'Unknown Status'}`,
     )
   }
 
@@ -94,7 +95,7 @@ async function getLatestWasmRuntimeVersion() {
     packageMeta = (await response.json()) as PackageMeta
   } catch (error) {
     throw new Error(
-      `Failed to parse npm registry metadata for ${WASM_RUNTIME_PACKAGE_NAME} from ${packageMetadataUrl}`,
+      `Failed to parse npm registry metadata for ${packageName} from ${packageMetadataUrl}`,
       { cause: error },
     )
   }
@@ -103,7 +104,7 @@ async function getLatestWasmRuntimeVersion() {
 
   if (typeof latestVersion !== 'string' || latestVersion.trim().length === 0) {
     throw new Error(
-      `npm registry metadata for ${WASM_RUNTIME_PACKAGE_NAME} from ${packageMetadataUrl} did not include a latest dist-tag`,
+      `npm registry metadata for ${packageName} from ${packageMetadataUrl} did not include a latest dist-tag`,
     )
   }
 
@@ -446,9 +447,15 @@ async function createNpmDirsUnlocked(
       ),
     )
   ).flat()
-  const wasmRuntimeVersion = targets.some((target) => target.arch === 'wasm32')
-    ? await getLatestWasmRuntimeVersion()
-    : undefined
+  const hasWasmTarget = targets.some((target) => target.arch === 'wasm32')
+  const [wasmRuntimeVersion, asyncRuntimeVersion] = await Promise.all([
+    hasWasmTarget
+      ? getLatestPackageVersion(WASM_RUNTIME_PACKAGE_NAME)
+      : undefined,
+    hasWasmTarget && wasm?.asyncRuntime === true
+      ? getLatestPackageVersion(ASYNC_RUNTIME_PACKAGE_NAME)
+      : undefined,
+  ])
   const pendingWrites: PendingMetadataWrite[] = []
 
   for (const target of targets) {
@@ -560,6 +567,11 @@ async function createNpmDirsUnlocked(
         '@napi-rs/wasm-runtime': `~${wasmRuntimeVersion}`,
         '@emnapi/core': emnapiVersion,
         '@emnapi/runtime': emnapiVersion,
+        // The compatibility axis is the host contract version (4), which is
+        // stable across a semver major, so a caret range is correct here.
+        ...(asyncRuntimeVersion
+          ? { '@napi-rs/async-runtime': `^${asyncRuntimeVersion}` }
+          : {}),
         ...(wasm?.browser?.buffer === true &&
         (wasm.browser.fs !== true || !wasiTargetHasThreads(target))
           ? { buffer: directBufferDependency }

package/src/api/pre-publish.ts

@@ -113,6 +113,10 @@ const wasiRuntimeDependencies = [
   '@napi-rs/wasm-runtime',
   '@emnapi/core',
   '@emnapi/runtime',
+  // Only the loaders generated for an addon with `napi.wasm.asyncRuntime` set
+  // import it. `releasePackageRuntimeImports` matches by prefix, so the package
+  // root and any subpath (`@napi-rs/async-runtime/workerd`) both count.
+  '@napi-rs/async-runtime',
   'buffer',
 ]
 const require = createRequire(import.meta.url)
@@ -2618,7 +2622,7 @@ export async function commitPrePublishFileSystemTransaction({
   await commitFileSystemTransaction(transactionRoot, writes, removals)
 }
 
-async function validateReleasePackageContents({
+export async function validateReleasePackageContents({
   pkgDir,
   rootDir,
   packageName,
@@ -3011,6 +3015,30 @@ function validateWasiReleasePackageManifest(
       `Release package ${packageJson.name} must omit buffer when its loaders do not import it`,
     )
   }
+
+  // `create-npm-dirs` resolves the version from the registry rather than
+  // pinning it here, so only the range's shape can be checked. The require /
+  // forbid pair is what matters: an undeclared import breaks the published
+  // package at load, and a declared dependency no loader imports is dead
+  // weight on every consumer of this flavor.
+  if (packagedRuntimeImports.has('@napi-rs/async-runtime')) {
+    const asyncRuntimeVersion = requireStringDependency(
+      packageJson.name,
+      dependencies,
+      '@napi-rs/async-runtime',
+    )
+    try {
+      new Range(asyncRuntimeVersion)
+    } catch {
+      throw new Error(
+        `Release package ${packageJson.name} has invalid @napi-rs/async-runtime dependency ${asyncRuntimeVersion}`,
+      )
+    }
+  } else if (dependencies['@napi-rs/async-runtime'] !== undefined) {
+    throw new Error(
+      `Release package ${packageJson.name} must omit @napi-rs/async-runtime when its loaders do not import it`,
+    )
+  }
 }
 
 function requireStringDependency(

package/src/api/templates/binding-target.ts

@@ -0,0 +1,176 @@
+/**
+ * The `__napiBindingTarget` contract, shared by every generated loader.
+ *
+ * This module deliberately imports nothing: both `js-binding.ts` and
+ * `load-wasi-template.ts` depend on it, and `load-wasi-template.ts` otherwise
+ * has no top-level imports at all. Keeping the contract at the bottom of the
+ * graph is what lets both templates emit the same runtime helper without
+ * duplicating its source.
+ */
+
+/**
+ * Named export every generated loader uses to report which binding artifact
+ * actually loaded: `'native'` for a `.node` addon, otherwise the
+ * `platformArchABI` of the WASI flavor (`'wasm32-wasi'`, `'wasm32-wasip1'`).
+ */
+export const NAPI_BINDING_TARGET_EXPORT = '__napiBindingTarget'
+
+/**
+ * `code` on the error the emitted loader throws when the binding it loaded
+ * already owns {@link NAPI_BINDING_TARGET_EXPORT}. Named after the other
+ * loader-thrown codes (`ERR_NAPI_WASI_LIFECYCLE_REENTRY`,
+ * `ERR_NAPI_WASI_CLEANUP_PENDING`, `ERR_NAPI_ASYNC_RUNTIME_BINDING_MISMATCH`)
+ * so a consumer can branch on it instead of on the message.
+ */
+export const ERR_NAPI_BINDING_TARGET_CONFLICT =
+  'ERR_NAPI_BINDING_TARGET_CONFLICT'
+
+/** Name of the runtime helper {@link BINDING_TARGET_STAMP_HELPER} declares. */
+export const NAPI_BINDING_TARGET_STAMP_FN = '__napiStampBindingTarget'
+
+/**
+ * Reject an export of {@link NAPI_BINDING_TARGET_EXPORT} at build time.
+ *
+ * `idents` is the type-def export list, so this only sees what napi-rs type
+ * generation reports. A name attached imperatively by a
+ * `#[napi(module_exports)]` hook emits no type-def entry and is invisible here
+ * — the same blind spot `typeDefAvailable` documents for the sibling check.
+ * {@link BINDING_TARGET_STAMP_HELPER} is what catches those, at load time.
+ *
+ * What this check is load-bearing for: a duplicated ident would emit a
+ * duplicate `export const` in the ESM loader (a syntax error), and would make
+ * the CJS loader overwrite its own reported target. It also keeps the generated
+ * `.d.ts` free of a duplicate identifier.
+ *
+ * All three are consequences of emitting something, so callers must only ask
+ * when the build emits it: the loader templates check themselves, and the root
+ * `.d.ts` is checked behind `bindingTargetDeclarationPredicate`. A build that
+ * writes no loader reserves nothing.
+ */
+export function assertBindingTargetIdentFree(idents: string[]): void {
+  if (idents.indexOf(NAPI_BINDING_TARGET_EXPORT) !== -1) {
+    throw new Error(
+      `\`${NAPI_BINDING_TARGET_EXPORT}\` is reserved by the generated binding loader. Rename the napi export, e.g. #[napi(js_name = "...")].`,
+    )
+  }
+}
+
+/**
+ * Runtime helper emitted into every loader that stamps
+ * {@link NAPI_BINDING_TARGET_EXPORT} onto an exports object it does not own.
+ *
+ * Five outcomes, in order:
+ *
+ * | exports object state            | result                                    |
+ * | ------------------------------- | ----------------------------------------- |
+ * | own property, same value        | no-op, returns `target`                   |
+ * | own property, different value   | throw, `ERR_NAPI_BINDING_TARGET_CONFLICT` |
+ * | non-extensible, no own property | skip, returns `target`                    |
+ * | refuses the definition          | skip, returns `target`                    |
+ * | otherwise                       | stamp, returns `target`                   |
+ *
+ * The stamp is `Object.defineProperty`, not an assignment. `hasOwnProperty`
+ * above sees own properties only and `Object.isExtensible` only own
+ * extensibility, so an ordinary assignment would still walk the prototype chain
+ * into an inherited accessor on a user-controlled object: its setter can throw,
+ * failing an otherwise successful load, or absorb the write and create nothing,
+ * leaving the named export the generated declaration promises resolving to
+ * `undefined`. `[[Define]]` consults no prototype, and the descriptor is the one
+ * a successful assignment would have produced. The `try` around it covers the
+ * one shape that can still refuse — an exotic object such as a `Proxy` whose
+ * `defineProperty` trap returns `false` — under the same rule as the
+ * non-extensible skip: metadata never fails a load.
+ *
+ * Every branch that does not throw returns `target`, because the CommonJS emit
+ * sites assign the return value —
+ * `module.exports.__napiBindingTarget = __napiStampBindingTarget(...)` — rather
+ * than calling it as a statement. Node's CJS -> ESM named export detection is
+ * `cjs-module-lexer`, a static scanner: it reports `__napiBindingTarget` as a
+ * named export only when it can see a `module.exports.<name> =` assignment, and
+ * a bare call is invisible to it, so `import { __napiBindingTarget }` from a
+ * generated CJS loader stops linking entirely.
+ *
+ * That assignment always succeeds, and it is never what a consumer reads: its
+ * target is the loader's own `module.exports`, an ordinary extensible object,
+ * and the alias on the next line replaces it with the binding itself. The value
+ * an import resolves to is therefore the one the stamp put on the binding, so
+ * when the guard skips — a sealed or frozen exports object — the CommonJS
+ * entries report `undefined`. `build.spec.ts` pins exactly that, in `a frozen
+ * addon keeps __napiBindingTarget importable, just undefined`. The ESM loaders
+ * are unaffected: theirs is a module-level `export const`, not a property of
+ * the object they hand out.
+ * (`Object.defineProperty` is not an alternative shape for the lexer, whatever
+ * it is inside the guard: the lexer matches a literal `module.exports.<name> =`
+ * and reports nothing for a data-descriptor `defineProperty` call, so the named
+ * import stops linking entirely — measured against Node's own detection.)
+ *
+ * The assignment target is never the object being stamped. Both CommonJS
+ * loaders stamp the addon's exports object but assign onto their own
+ * `module.exports`, which they replace with that object afterwards: an addon
+ * accessor can report the expected value from a getter and still throw from its
+ * setter, and only the guard's `hasOwnProperty`-and-read path is safe to run
+ * against it.
+ *
+ * Placement is the same rule in every loader that stamps a binding object:
+ * exactly one stamp, after the async runtime host installation — which hands
+ * that object to addon-provided registration functions that may reshape it —
+ * and inside the initialization guard that can undo a failed load: the `try`
+ * that rolls the WASI environment back, or the one that marks a deferred
+ * instance failed.
+ *
+ * The equal-value short circuit is required, not cosmetic: the root CJS loader
+ * aliases the object it loaded, so a `NAPI_RS_NATIVE_LIBRARY_PATH` override
+ * that is itself a generated WASI loader — and every WASI fallback candidate —
+ * hands back an object already carrying the value about to be stamped.
+ *
+ * Node 12 compatible (no optional chaining, no nullish coalescing) and valid in
+ * both sloppy CJS and strict ESM, because all four loaders emit it verbatim.
+ */
+export const BINDING_TARGET_STAMP_HELPER = `function ${NAPI_BINDING_TARGET_STAMP_FN}(exportsObject, target) {
+  if (
+    Object.prototype.hasOwnProperty.call(exportsObject, '${NAPI_BINDING_TARGET_EXPORT}')
+  ) {
+    if (exportsObject.${NAPI_BINDING_TARGET_EXPORT} === target) {
+      // Already ours: the root entry aliases the object it loaded, so a WASI
+      // fallback candidate — or a \`NAPI_RS_NATIVE_LIBRARY_PATH\` override that
+      // is a generated loader — arrives already stamped with this same value.
+      return target
+    }
+    const error = new Error(
+      '\`${NAPI_BINDING_TARGET_EXPORT}\` is reserved by the generated binding loader, but the loaded binding already exports it. Rename the export, e.g. #[napi(js_name = "...")].',
+    )
+    error.code = '${ERR_NAPI_BINDING_TARGET_CONFLICT}'
+    throw error
+  }
+  if (!Object.isExtensible(exportsObject)) {
+    // A \`#[napi(module_exports)]\` hook may seal or freeze this object
+    // (\`Object::seal\` / \`Object::freeze\`). Reporting the artifact is metadata,
+    // never a reason to fail an otherwise successful load, so the stamp is
+    // skipped. What a consumer still sees then follows the entry point: the
+    // browser and deferred loaders declare \`${NAPI_BINDING_TARGET_EXPORT}\` at module
+    // level and go on reporting it, while the CommonJS entries hand back this
+    // very object as \`module.exports\`, so there the value is absent.
+    return target
+  }
+  try {
+    // [[Define]], not [[Set]]: an ordinary assignment walks the prototype
+    // chain, so an inherited accessor could swallow the value or throw and
+    // fail an otherwise successful load. The descriptor is what a successful
+    // assignment would have produced.
+    Object.defineProperty(exportsObject, '${NAPI_BINDING_TARGET_EXPORT}', {
+      configurable: true,
+      enumerable: true,
+      value: target,
+      writable: true,
+    })
+  } catch {
+    // Same rule as the non-extensible skip above: reporting the artifact is
+    // metadata, never a reason to fail an otherwise successful load. An exotic
+    // object (a Proxy whose defineProperty trap refuses) is skipped, not
+    // thrown over.
+  }
+  // The CommonJS loaders assign this return value so \`cjs-module-lexer\` — and
+  // therefore Node's CJS -> ESM named export detection — can see
+  // \`${NAPI_BINDING_TARGET_EXPORT}\` statically.
+  return target
+}`

package/src/api/templates/index.ts

@@ -1 +1,2 @@
+export * from './binding-target.js'
 export * from './js-binding.js'

package/src/api/templates/js-binding.ts

@@ -1,5 +1,12 @@
 import { wasiLoaderSuffix } from '../../utils/index.js'
 
+import {
+  assertBindingTargetIdentFree,
+  BINDING_TARGET_STAMP_HELPER,
+  NAPI_BINDING_TARGET_EXPORT,
+  NAPI_BINDING_TARGET_STAMP_FN,
+} from './binding-target.js'
+
 function resolveWasiFlavors(wasiFlavors?: string[]): string[] {
   return wasiFlavors && wasiFlavors.length > 0 ? wasiFlavors : ['wasm32-wasi']
 }
@@ -62,6 +69,7 @@ function createWasiFallbackChain(
       }
         wasiBinding = require('${specifier}')
         nativeBinding = wasiBinding
+        __napiLoadedBindingTarget = '${flavor}'
         wasiBindingLoaded = true
       }
     } catch (err) {
@@ -126,6 +134,7 @@ export function createCjsBinding(
   wasiFlavors?: string[],
   localWasiName?: string,
 ): string {
+  assertBindingTargetIdentFree(idents)
   return `${bindingHeader}
 ${createCommonBinding(
   localName,
@@ -134,6 +143,23 @@ ${createCommonBinding(
   wasiFlavors,
   localWasiName,
 )}
+${BINDING_TARGET_STAMP_HELPER}
+// Stamp before the alias, not after. The guard only reads \`nativeBinding\`
+// (\`hasOwnProperty\` plus a comparison), which is safe against any addon
+// accessor; an assignment is not, because a \`#[napi(module_exports)]\` hook can
+// expose a getter reporting this very value and a setter that throws. So the
+// assignment lands on the loader's own \`module.exports\`, still the original
+// object here, and the alias below replaces it.
+//
+// The assignment is what keeps the marker a statically visible CommonJS export:
+// \`cjs-module-lexer\` is Node's CJS -> ESM named export detection, it cannot see
+// a bare call, and the later \`module.exports = nativeBinding\` does not undo the
+// detection. The assignment itself always succeeds — its target is this
+// loader's own, still extensible \`module.exports\` — and the alias below then
+// discards the value it wrote. What a consumer reads is whatever the guard put
+// on \`nativeBinding\`, so on a frozen binding, where the guard skips, the
+// linked import resolves to \`undefined\`.
+module.exports.${NAPI_BINDING_TARGET_EXPORT} = ${NAPI_BINDING_TARGET_STAMP_FN}(nativeBinding, __napiLoadedBindingTarget)
 module.exports = nativeBinding
 ${idents
   .map((ident) => `module.exports.${ident} = nativeBinding.${ident}`)
@@ -149,11 +175,17 @@ export function createEsmBinding(
   wasiFlavors?: string[],
   localWasiName?: string,
 ): string {
+  assertBindingTargetIdentFree(idents)
+  // Both branches must carry it, or a zero-ident package silently loses the
+  // export.
+  const bindingTargetExport = `export const ${NAPI_BINDING_TARGET_EXPORT} = __napiLoadedBindingTarget`
   const exportsCode =
     idents.length > 0
       ? `const { ${idents.join(', ')} } = nativeBinding
-${idents.map((ident) => `export { ${ident} }`).join('\n')}`
-      : 'export default nativeBinding'
+${idents.map((ident) => `export { ${ident} }`).join('\n')}
+${bindingTargetExport}`
+      : `export default nativeBinding
+${bindingTargetExport}`
   return `${bindingHeader}
 import { createRequire } from 'module'
 const require = createRequire(import.meta.url)
@@ -213,6 +245,10 @@ ${identLow}}${versionCheck}`
 
   return `const { readFileSync } = require('fs')
 let nativeBinding = null
+// Which artifact actually loaded. The WASI fallback chain overwrites it with
+// the flavor it resolved; the late native retry below leaves it alone because
+// it only runs while no WASI candidate has been loaded.
+let __napiLoadedBindingTarget = 'native'
 const loadErrors = []
 
 const isMusl = () => {
@@ -271,7 +307,16 @@ const isMuslFromChildProcess = () => {
 function requireNative() {
   if (process.env.NAPI_RS_NATIVE_LIBRARY_PATH) {
     try {
-      return require(process.env.NAPI_RS_NATIVE_LIBRARY_PATH)
+      const overrideBinding = require(process.env.NAPI_RS_NATIVE_LIBRARY_PATH)
+      // The override may be a generated WASI loader, which already reports its
+      // own flavor. Adopt it: \`module.exports\` aliases this object, so claiming
+      // 'native' would both misreport the artifact and overwrite the loader's
+      // marker through the alias.
+      __napiLoadedBindingTarget =
+        overrideBinding && typeof overrideBinding.${NAPI_BINDING_TARGET_EXPORT} === 'string'
+          ? overrideBinding.${NAPI_BINDING_TARGET_EXPORT}
+          : 'native'
+      return overrideBinding
     } catch (err) {
       loadErrors.push(err)
     }