@napi-rs/cli 3.9.0 → 3.10.0

package/src/utils/__tests__/serialize.spec.ts

@@ -0,0 +1,55 @@
+import test from 'ava'
+
+import { serializeJson, serializeToml, serializeYaml } from '../serialize.js'
+
+test('serializeJson uses 2-space indent and a trailing newline', (t) => {
+  t.is(
+    serializeJson({ name: 'pkg', files: ['a.node'] }),
+    `{
+  "name": "pkg",
+  "files": [
+    "a.node"
+  ]
+}
+`,
+  )
+})
+
+test('serializeJson always ends with exactly one newline', (t) => {
+  const serialized = serializeJson({ ok: true })
+  t.true(serialized.endsWith('\n'))
+  t.false(serialized.endsWith('\n\n'))
+})
+
+test('serializeToml strips the leading blank line @std/toml inserts', (t) => {
+  const serialized = serializeToml({
+    package: { name: 'demo', version: '0.1.0' },
+    dependencies: {
+      napi: { version: '3.0.0', features: ['napi4'] },
+    },
+  })
+  t.false(serialized.startsWith('\n'))
+  t.true(serialized.startsWith('[package]\n'))
+  t.true(serialized.endsWith('\n'))
+  t.false(serialized.endsWith('\n\n'))
+})
+
+test('serializeYaml always ends with a trailing newline', (t) => {
+  const serialized = serializeYaml({ on: { push: null } })
+  t.true(serialized.endsWith('\n'))
+  t.false(serialized.endsWith('\n\n'))
+})
+
+test('serializeToml does not rewrite commas inside quoted strings', (t) => {
+  const serialized = serializeToml({
+    lib: { include: ['src/a,b.rs'] },
+    package: {
+      name: 'demo',
+      description: 'uses = [a,b] in a scalar',
+    },
+  })
+  t.true(serialized.includes('include = ["src/a,b.rs"]'))
+  t.true(serialized.includes('description = "uses = [a,b] in a scalar"'))
+  t.false(serialized.includes('src/a, b.rs'))
+  t.false(serialized.includes('= [a, b]'))
+})

package/src/utils/__tests__/target.spec.ts

@@ -1,13 +1,49 @@
+import { realpathSync } from 'node:fs'
+import { chmod, mkdtemp, mkdir, rm, writeFile } from 'node:fs/promises'
 import os from 'os'
+import { join } from 'node:path'
 
 import test from 'ava'
 
 import {
+  wasiLibcHasNewFutexAbi,
   parseTriple,
   getSystemDefaultTarget,
+  rustBundledWasiLibc,
+  wasiSdkMajorVersion,
   AVAILABLE_TARGETS,
 } from '../target.js'
 
+async function withWasiSdkDir(
+  setup: (wasiSdkPath: string) => Promise<void>,
+  assertion: (wasiSdkPath: string) => void,
+) {
+  const wasiSdkPath = await mkdtemp(join(os.tmpdir(), 'napi-rs-wasi-sdk-'))
+  try {
+    await setup(wasiSdkPath)
+    assertion(wasiSdkPath)
+  } finally {
+    await rm(wasiSdkPath, { recursive: true, force: true })
+  }
+}
+
+async function writeVersionFile(wasiSdkPath: string, content: string) {
+  await writeFile(join(wasiSdkPath, 'VERSION'), content)
+}
+
+async function writeVersionHeader(wasiSdkPath: string, content: string) {
+  const headerDir = join(
+    wasiSdkPath,
+    'share',
+    'wasi-sysroot',
+    'include',
+    'wasm32-wasip1-threads',
+    'wasi',
+  )
+  await mkdir(headerDir, { recursive: true })
+  await writeFile(join(headerDir, 'version.h'), content)
+}
+
 test('should parse triple correctly', (t) => {
   t.snapshot(AVAILABLE_TARGETS.map(parseTriple))
 })
@@ -17,3 +53,188 @@ test('should get system default target correctly', (t) => {
 
   t.is(target.platform, os.platform())
 })
+
+test('should read the wasi-sdk major version from VERSION', async (t) => {
+  await withWasiSdkDir(
+    (wasiSdkPath) => writeVersionFile(wasiSdkPath, '34.0\n'),
+    (wasiSdkPath) => t.is(wasiSdkMajorVersion(wasiSdkPath), 34),
+  )
+})
+
+test('should ignore the build suffix in VERSION', async (t) => {
+  await withWasiSdkDir(
+    (wasiSdkPath) => writeVersionFile(wasiSdkPath, '33.0+m\n'),
+    (wasiSdkPath) => t.is(wasiSdkMajorVersion(wasiSdkPath), 33),
+  )
+})
+
+test('should read a pre wasi-sdk 30 VERSION', async (t) => {
+  await withWasiSdkDir(
+    (wasiSdkPath) => writeVersionFile(wasiSdkPath, '27.0\n'),
+    (wasiSdkPath) => t.is(wasiSdkMajorVersion(wasiSdkPath), 27),
+  )
+})
+
+test('should fall back to the wasi/version.h header', async (t) => {
+  await withWasiSdkDir(
+    (wasiSdkPath) =>
+      writeVersionHeader(
+        wasiSdkPath,
+        '#define __wasi_sdk_major__ 30\n#define __wasi_sdk_minor__ 0\n',
+      ),
+    (wasiSdkPath) => t.is(wasiSdkMajorVersion(wasiSdkPath), 30),
+  )
+})
+
+test('should prefer VERSION over the wasi/version.h header', async (t) => {
+  await withWasiSdkDir(
+    async (wasiSdkPath) => {
+      await writeVersionFile(wasiSdkPath, '34.0\n')
+      await writeVersionHeader(wasiSdkPath, '#define __wasi_sdk_major__ 33\n')
+    },
+    (wasiSdkPath) => t.is(wasiSdkMajorVersion(wasiSdkPath), 34),
+  )
+})
+
+test('should return null when no version signal exists', async (t) => {
+  await withWasiSdkDir(
+    () => Promise.resolve(),
+    (wasiSdkPath) => t.is(wasiSdkMajorVersion(wasiSdkPath), null),
+  )
+})
+
+test('should return null instead of throwing on a malformed VERSION', async (t) => {
+  await withWasiSdkDir(
+    (wasiSdkPath) => writeVersionFile(wasiSdkPath, 'not a version at all\n'),
+    (wasiSdkPath) => {
+      t.notThrows(() => wasiSdkMajorVersion(wasiSdkPath))
+      t.is(wasiSdkMajorVersion(wasiSdkPath), null)
+    },
+  )
+})
+
+test('should return null when the wasi-sdk path does not exist', (t) => {
+  t.is(wasiSdkMajorVersion(join(os.tmpdir(), 'napi-rs-missing-wasi-sdk')), null)
+})
+
+test('should detect the new futex ABI from a wasi-libc archive', async (t) => {
+  const dir = await mkdtemp(join(os.tmpdir(), 'napi-rs-wasi-libc-'))
+  try {
+    // wasi-libc moved the futex helpers into `futex.c` when it dropped the
+    // unused `int op` parameter. `__wait.c` survives either way, so only the
+    // presence of `futex.c` separates the two ABIs.
+    const newAbi = join(dir, 'libc-new.a')
+    const legacyAbi = join(dir, 'libc-legacy.a')
+    await writeFile(newAbi, '!<arch>\n__wait.c.obj\nfutex.c.obj\n')
+    await writeFile(
+      legacyAbi,
+      '!<arch>\n__wait.c.obj\n__wasilibc_busywait.c.obj\n',
+    )
+
+    t.true(wasiLibcHasNewFutexAbi(newAbi))
+    t.false(wasiLibcHasNewFutexAbi(legacyAbi))
+  } finally {
+    await rm(dir, { recursive: true, force: true })
+  }
+})
+
+test('should return null when the wasi-libc archive is unavailable', (t) => {
+  t.is(wasiLibcHasNewFutexAbi(null), null)
+  t.is(
+    wasiLibcHasNewFutexAbi(join(os.tmpdir(), 'napi-rs-missing-libc.a')),
+    null,
+  )
+})
+
+// A fake `rustc` must be an executable file, and `execFileSync` cannot run a
+// Windows `.cmd` shim without a shell. The behaviour under test does not
+// depend on the platform, so cover it on POSIX only.
+const posixOnly = process.platform === 'win32' ? test.serial.skip : test.serial
+
+/**
+ * Installs a `rustc` that reports its own working directory as the sysroot,
+ * so a test can tell which directory the probe ran in.
+ */
+async function withFakeRustc(
+  envVar: 'RUSTC' | 'CARGO_BUILD_RUSTC',
+  body: (dir: string) => Promise<void> | void,
+) {
+  const dir = await mkdtemp(join(os.tmpdir(), 'napi-rs-fake-rustc-'))
+  const rustc = join(dir, 'rustc')
+  // `$PWD` comes from the inherited environment, so ask the kernel for the
+  // real working directory. `-P` also resolves the `/var` symlink on macOS.
+  await writeFile(rustc, '#!/bin/sh\necho "$(pwd -P)/sysroot"\n')
+  await chmod(rustc, 0o755)
+  const previous = process.env[envVar]
+  process.env[envVar] = rustc
+  try {
+    await body(dir)
+  } finally {
+    if (previous === undefined) {
+      delete process.env[envVar]
+    } else {
+      process.env[envVar] = previous
+    }
+  }
+}
+
+posixOnly('probes the Rust sysroot from the build cwd', async (t) => {
+  await withFakeRustc('RUSTC', async (dir) => {
+    const caller = join(dir, 'caller')
+    const project = join(dir, 'project')
+    await mkdir(caller)
+    await mkdir(project)
+
+    // `rustc` is a rustup shim, so the directory it runs in picks the
+    // toolchain. Cargo is spawned with the build cwd; the probe must match it.
+    t.is(
+      rustBundledWasiLibc('wasm32-wasip1-threads', project),
+      join(
+        realpathSync(project),
+        'sysroot',
+        'lib',
+        'rustlib',
+        'wasm32-wasip1-threads',
+        'lib',
+        'self-contained',
+        'libc.a',
+      ),
+    )
+    t.not(
+      rustBundledWasiLibc('wasm32-wasip1-threads', caller),
+      rustBundledWasiLibc('wasm32-wasip1-threads', project),
+    )
+  })
+})
+
+posixOnly('falls back to CARGO_BUILD_RUSTC when RUSTC is unset', async (t) => {
+  const previousRustc = process.env.RUSTC
+  delete process.env.RUSTC
+  try {
+    await withFakeRustc('CARGO_BUILD_RUSTC', (dir) => {
+      t.true(
+        rustBundledWasiLibc('wasm32-wasip1-threads', dir)?.startsWith(
+          realpathSync(dir),
+        ),
+      )
+    })
+  } finally {
+    if (previousRustc !== undefined) {
+      process.env.RUSTC = previousRustc
+    }
+  }
+})
+
+posixOnly('returns null when the compiler cannot be run', (t) => {
+  const previous = process.env.RUSTC
+  process.env.RUSTC = join(os.tmpdir(), 'napi-rs-no-such-rustc')
+  try {
+    t.is(rustBundledWasiLibc('wasm32-wasip1-threads'), null)
+  } finally {
+    if (previous === undefined) {
+      delete process.env.RUSTC
+    } else {
+      process.env.RUSTC = previous
+    }
+  }
+})

package/src/utils/__tests__/typegen.spec.ts

@@ -1,3 +1,5 @@
+import { mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
 import { join } from 'path'
 import { fileURLToPath } from 'url'
 
@@ -5,6 +7,24 @@ import test from 'ava'
 
 import { correctStringIdent, processTypeDef } from '../typegen.js'
 
+async function processInlineTypeDef(
+  lines: Array<Record<string, unknown>>,
+  constEnum = true,
+  runtimeStringEnum = false,
+) {
+  const dir = await mkdtemp(join(tmpdir(), 'napi-typegen-'))
+  const file = join(dir, 'defs')
+  await writeFile(
+    file,
+    lines.map((line) => JSON.stringify(line)).join('\n') + '\n',
+  )
+  try {
+    return await processTypeDef(file, constEnum, runtimeStringEnum)
+  } finally {
+    await rm(dir, { recursive: true, force: true })
+  }
+}
+
 test('should ident string correctly', (t) => {
   const input = `
   /**
@@ -83,3 +103,98 @@ test('runtimeStringEnum is a no-op when constEnum is set', async (t) => {
 
   t.snapshot(dts)
 })
+
+test('simple type aliases stay on one line', async (t) => {
+  const { dts } = await processInlineTypeDef([
+    { kind: 'type', name: 'CustomU32', def: 'number' },
+  ])
+  t.true(dts.includes('export type CustomU32 = number'))
+  t.false(/export type CustomU32 =\s*\n/.test(dts))
+})
+
+test('empty classes do not contain a blank body', async (t) => {
+  const { dts } = await processInlineTypeDef([
+    { kind: 'struct', name: 'Blake2BKey', def: '' },
+  ])
+  t.true(dts.includes('export declare class Blake2BKey {}'))
+  t.false(dts.includes('class Blake2BKey {\n\n}'))
+})
+
+test('no-const-enum string enums emit a spaced union', async (t) => {
+  const { dts } = await processTypeDef(flagFixture, false, false)
+  t.true(dts.includes("export type Status = 'Active' | 'Inactive'"))
+  t.false(dts.includes("'Active'|"))
+})
+
+test('no-const-enum string enums keep commas inside variant docs', async (t) => {
+  const { dts } = await processInlineTypeDef(
+    [
+      {
+        kind: 'string_enum',
+        name: 'Status',
+        def: "/** First, documented variant */\n Active = 'Active',\n Inactive = 'Inactive'",
+      },
+    ],
+    false,
+    false,
+  )
+  t.true(dts.includes("export type Status = 'Active' | 'Inactive'"))
+  t.false(dts.includes('/** First |'))
+})
+
+test('no-const-enum string enums keep Unicode variant names', async (t) => {
+  const { dts } = await processInlineTypeDef(
+    [
+      {
+        kind: 'string_enum',
+        name: 'Status',
+        def: "成功 = '成功',\n Failed = 'Failed'",
+      },
+    ],
+    false,
+    false,
+  )
+  t.true(dts.includes("export type Status = '成功' | 'Failed'"))
+})
+
+test('no-const-enum string enums keep quoted JS property names', async (t) => {
+  const { dts } = await processInlineTypeDef(
+    [
+      {
+        kind: 'string_enum',
+        name: 'Header',
+        def: "'content-type' = 'content-type',\n Plain = 'plain'",
+      },
+    ],
+    false,
+    false,
+  )
+  t.true(dts.includes("export type Header = 'content-type' | 'plain'"))
+})
+
+test('no-const-enum string enums keep commas and escapes inside values', async (t) => {
+  const { dts } = await processInlineTypeDef(
+    [
+      {
+        kind: 'string_enum',
+        name: 'Label',
+        def: "Csv = 'a,b',\n Quoted = 'say \\'hi\\'',\n Count = 2",
+      },
+    ],
+    false,
+    false,
+  )
+  t.true(dts.includes("export type Label = 'a,b' | 'say \\'hi\\'' | 2"))
+})
+
+test('correctStringIdent keeps nested object-type fields indented', (t) => {
+  const input = `export declare function bufferComplexOverride(value: {
+  Buffer(): "line"
+mapped: { [Buffer in keyof T]: T[Buffer] }
+external: Buffer
+}): void`
+  const formatted = correctStringIdent(input, 0)
+  t.true(formatted.includes('  mapped: { [Buffer in keyof T]: T[Buffer] }'))
+  t.true(formatted.includes('  external: Buffer'))
+  t.false(formatted.includes('\nmapped:'))
+})

package/src/utils/config.ts

@@ -95,6 +95,27 @@ export interface UserNapiConfig {
      * @default 4000 pages (250 MiB), or 1024 pages (64 MiB) for the deferred workerd loader
      */
     initialMemory?: number
+    /**
+     * Initial linear memory, in 64 KiB pages, for the **threadless**
+     * (`wasm32-wasip1`) loaders only: the Node CJS loader, the browser loader
+     * and the deferred `./workerd` loader.
+     *
+     * The threaded loaders allocate one `shared: true` memory that every
+     * wasi-threads worker maps, so every worker stack and every thread's
+     * allocations come out of it and growing it is a cross-thread event; it is
+     * sized for the whole pool up front. The threadless loaders drive a single
+     * thread through a plain growable `ArrayBuffer`: they only have to clear
+     * the module's own link-time floor (`-zstack-size` plus static data) and
+     * grow on demand, which is what lets the same build fit a host with a hard
+     * isolate cap such as workerd's 128 MiB.
+     *
+     * Falls back to `initialMemory` when unset, so existing projects are
+     * unaffected.
+     *
+     * @default `initialMemory` (4000 pages), or 1024 pages for the deferred
+     *   `./workerd` loader
+     */
+    threadlessInitialMemory?: number
     /**
      * @default 65536 pages (4GiB)
      */
@@ -119,6 +140,35 @@ export interface UserNapiConfig {
      */
     optionalDependency?: boolean
 
+    /**
+     * Whether the generated WASI loaders bootstrap the `napi-async-runtime`
+     * CurrentThread JavaScript hosts.
+     *
+     * A binding built with the `napi-async-runtime` crate runs the
+     * `CurrentThread` flavor on every WebAssembly target (it is the only
+     * flavor there). Its futures make no progress until a task host is
+     * registered, and its timers never fire until a timer host is, so the
+     * loader must install both right after instantiation and unregister them
+     * before the environment is destroyed.
+     *
+     * Enabling this emits that bootstrap in the node, browser and deferred
+     * (workerd) loaders, and declares `@napi-rs/async-runtime` in the
+     * generated `<packageName>-wasm32-*` packages. The loader delegates the
+     * whole host contract — the seven exports, contract version 4, the
+     * reservation identity, the liveness probe and the rollback — to that
+     * package, so a binding that does not actually expose the contract fails
+     * loudly at load with `ERR_NAPI_ASYNC_RUNTIME_BINDING_MISMATCH`.
+     *
+     * The bootstrap runs after instantiation, so after `#[module_init]`: the
+     * host registration functions are exports of the binding itself. Code that
+     * runs during module registration must not create timers (`sleep_until`
+     * fails loud at creation without a timer host) and cannot expect task
+     * progress until the loader has returned.
+     *
+     * @default false
+     */
+    asyncRuntime?: boolean
+
     /**
      * Browser wasm binding configuration
      */

package/src/utils/index.ts

@@ -1,5 +1,6 @@
 export * from './log.js'
 export * from './misc.js'
+export * from './serialize.js'
 export * from './target.js'
 export * from './version.js'
 export * from './metadata.js'