feat: add runtime fallback and webcontainer support

.changeset/wet-hounds-sneeze.md

@@ -0,0 +1,5 @@
+---
+"napi-postinstall": minor
+---
+
+feat: add runtime fallback and webcontainer support

.github/workflows/ci.yml

@@ -36,6 +36,7 @@ jobs:
 
       - name: Install Dependencies
         run: |
+          npm i -g pnpm
           corepack enable npm
           corepack enable
           yarn --immutable

README.md

@@ -76,6 +76,7 @@ This will check and prepare the napi binding packages for you automatically.
 #### Types
 
 ```ts
+// napi-postinstall
 export interface PackageJson {
   name: string
   version: string
@@ -85,16 +86,30 @@ export declare function checkAndPreparePackage(
   packageNameOrPackageJson: PackageJson | string,
   checkVersion?: boolean,
 ): Promise<void>
+
+// napi-postinstall/fallback
+declare function fallback<T = unknown>(
+  packageJsonPath: string,
+  checkVersion?: boolean,
+): T
+export = fallback
 ```
 
 #### Example
 
 ```js
-import { checkAndPreparePackage, isNpm } from 'napi-postinstall'
+// index.js
+const { checkAndPreparePackage, isNpm } = require('napi-postinstall')
 
 if (isNpm()) {
-  checkAndPreparePackage('unrs-resolver' /* <napi-package-name> */)
+  void checkAndPreparePackage('unrs-resolver' /* <napi-package-name> */)
 }
+
+// fallback.js
+module.exports = require('napi-postinstall/fallback')(
+  require.resolve('../package.json') /* <napi-package-json-path> */,
+  true /* <check-version> */,
+)
 ```
 
 ## Sponsors and Backers

package.json

@@ -19,6 +19,10 @@
       "types": "./lib/index.d.ts",
       "default": "./lib/index.js"
     },
+    "./fallback": {
+      "types": "./lib/fallback.d.ts",
+      "default": "./lib/fallback.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [

src/constants.ts

@@ -1,6 +1,6 @@
 import * as path from 'node:path'
 
-import { PackageJson } from './types.js'
+import type { PackageJson } from './types.js'
 
 export const DEFAULT_NPM_REGISTRY = 'https://registry.npmjs.org/'
 

src/fallback.ts

@@ -0,0 +1,137 @@
+import { execFileSync } from 'node:child_process'
+import * as fs from 'node:fs'
+import * as os from 'node:os'
+import * as path from 'node:path'
+
+import { WASM32_WASI } from './constants.js'
+import { errorMessage, getNapiInfoFromPackageJson } from './helpers.js'
+import type { PackageJson } from './types.js'
+
+const EXECUTORS = {
+  npm: 'npx',
+  pnpm: 'pnpm',
+  yarn: 'yarn',
+  bun: 'bun',
+  deno: (args: string[]) => ['deno', 'run', `npm:${args[0]}`, ...args.slice(1)],
+}
+
+function constructCommand(
+  value: string[] | string | ((args: string[]) => string[]),
+  args: string[],
+) {
+  const list =
+    typeof value === 'function'
+      ? value(args)
+      : // eslint-disable-next-line unicorn-x/prefer-spread
+        ([] as string[]).concat(value, args)
+  return {
+    command: list[0],
+    args: list.slice(1),
+  }
+}
+
+/**
+ * Fallback for webcontainer and docker environments like
+ * @see https://github.com/un-ts/eslint-plugin-import-x/issues/337.
+ *
+ * @param packageJsonPath The absolute path to the package.json file.
+ * @param checkVersion Whether to check version matching
+ */
+function fallback<T = unknown>(
+  packageJsonPath: string,
+  checkVersion?: boolean,
+) {
+  const packageJson = require(packageJsonPath) as PackageJson
+
+  const { name, version: pkgVersion, optionalDependencies } = packageJson
+
+  const { napi, version = pkgVersion } = getNapiInfoFromPackageJson(
+    packageJson,
+    checkVersion,
+  )
+
+  if (checkVersion && pkgVersion !== version) {
+    throw new Error(
+      errorMessage(
+        `Inconsistent package versions found for \`${name}\` v${pkgVersion} vs \`${napi.packageName}\` v${version}.`,
+      ),
+    )
+  }
+
+  if (process.versions.webcontainer) {
+    const bindingPkgName = `${napi.packageName}-${WASM32_WASI}`
+
+    if (!optionalDependencies?.[bindingPkgName]) {
+      throw new Error(
+        errorMessage(
+          `\`${WASM32_WASI}\` target is unavailable for \`${name}\` v${version}`,
+        ),
+      )
+    }
+
+    const baseDir = path.resolve(os.tmpdir(), `${name}-${version}`)
+
+    const bindingEntry = path.resolve(
+      baseDir,
+      `node_modules/${bindingPkgName}/${napi.binaryName}.wasi.cjs`,
+    )
+
+    if (!fs.existsSync(bindingEntry)) {
+      fs.rmSync(baseDir, { recursive: true, force: true })
+      fs.mkdirSync(baseDir, { recursive: true })
+
+      const bindingPkg = `${bindingPkgName}@${version}`
+
+      console.log(
+        errorMessage(`Downloading \`${bindingPkg}\` on WebContainer...`),
+      )
+
+      execFileSync('pnpm', ['i', bindingPkg], {
+        cwd: baseDir,
+        stdio: 'inherit',
+      })
+    }
+
+    return require(bindingEntry) as T
+  }
+
+  const userAgent = ((process.env.npm_config_user_agent || '').split('/')[0] ||
+    'npm') as keyof typeof EXECUTORS
+
+  const executor = EXECUTORS[userAgent]
+
+  if (!executor) {
+    throw new Error(
+      errorMessage(
+        `Unsupported package manager: ${userAgent}. Supported managers are: ${Object.keys(
+          EXECUTORS,
+        ).join(', ')}.`,
+      ),
+    )
+  }
+
+  const { command, args } = constructCommand(executor, [
+    'napi-postinstall',
+    name,
+    version,
+    checkVersion ? '1' : '0',
+  ])
+
+  const pkgDir = path.dirname(packageJsonPath)
+
+  execFileSync(command, args, {
+    cwd: pkgDir,
+    stdio: 'inherit',
+  })
+
+  // eslint-disable-next-line unicorn-x/prefer-string-replace-all
+  process.env[`SKIP_${name.replace(/-/g, '_').toUpperCase()}_FALLBACK`] = '1'
+
+  const PKG_RESOLVED_PATH = require.resolve(pkgDir)
+
+  delete require.cache[PKG_RESOLVED_PATH]
+
+  return require(pkgDir) as T
+}
+
+export = fallback

src/helpers.ts

@@ -4,7 +4,7 @@ import * as path from 'node:path'
 
 import { DEFAULT_NPM_REGISTRY, LOG_PREFIX } from './constants.js'
 import { parseTriple } from './target.js'
-import { NapiInfo, PackageJson } from './types.js'
+import type { NapiInfo, PackageJson } from './types.js'
 
 export function getGlobalNpmRegistry() {
   try {

src/target.ts

@@ -1,7 +1,7 @@
 // based on https://github.com/napi-rs/napi-rs/blob/2eb2ab619f9fb924453e21d2198fe67ea21b9680/cli/src/utils/target.ts
 
 import { EABI, WASI, WASM32, WASM32_WASI } from './constants.js'
-import { NodeJSArch, Platform, Target } from './types.js'
+import type { NodeJSArch, Platform, Target } from './types.js'
 
 const CpuToNodeArch: Record<string, NodeJSArch> = {
   x86_64: 'x64',

test/fallback.spec.ts

@@ -0,0 +1,29 @@
+import unrsResolver = require('unrs-resolver')
+
+// @ts-expect-error -- don't use `import fallback = require('napi-postinstall/fallback')` due to vitest code coverage
+import fallback_ from 'napi-postinstall/fallback'
+
+const fallback = fallback_ as typeof import('napi-postinstall/fallback')
+
+describe('fallback', () => {
+  afterEach(() => {
+    delete process.env.SKIP_UNRS_RESOLVER_FALLBACK
+    delete process.versions.webcontainer
+  })
+
+  it('should resolve napi package successfully and set skip env after processing', () => {
+    expect(fallback(require.resolve('unrs-resolver/package.json'))).toBe(
+      unrsResolver,
+    )
+    expect(process.env.SKIP_UNRS_RESOLVER_FALLBACK).toBe('1')
+  })
+
+  it('should support webcontainer', () => {
+    process.versions.webcontainer = '1'
+    const resolved = fallback<typeof unrsResolver>(
+      require.resolve('unrs-resolver/package.json'),
+    )
+    expect(resolved).not.toBe(unrsResolver)
+    expect(typeof resolved.sync).toBe('function')
+  })
+})

tsconfig.json

@@ -5,7 +5,8 @@
     "esModuleInterop": false,
     "rootDir": ".",
     "paths": {
-      "napi-postinstall": ["./src/index.ts"]
+      "napi-postinstall": ["./src/index.ts"],
+      "napi-postinstall/fallback": ["./src/fallback.ts"]
     },
     "target": "ES2020"
   }