feat: support external installation services

Author: pastelsky

.changeset/tidy-lions-install.md

@@ -0,0 +1,6 @@
+---
+'package-build-stats': minor
+---
+
+Allow analysis functions to use an optional package installation service while
+retaining local installation as the default and fallback.

README.md

@@ -45,6 +45,25 @@ const results = await getPackageStats('lodash', { client: 'pnpm' })
 const results = await getPackageStats('lodash', { client: 'yarn' })
 ```
 
+Analysis functions install packages locally by default. A service can instead
+provide a reusable installation without changing those APIs:
+
+```js
+await getPackageStats('lodash', {
+  installationService: { url: 'http://127.0.0.1:7003' },
+})
+```
+
+The service implements `POST /installations` to return
+`{ packageString, packageName, installPath, packagePath }`. Generated entries
+and bundles are written to a separate per-analysis directory, so the returned
+installation can be safely reused. Transport failures fall back to a local
+install unless `fallbackToLocal` is `false`.
+
+The `package-build-stats/installation` subpath exports `installPackage` and
+`disposePackage` for implementing that service. Standalone callers do not need
+an installation service.
+
 #### Passing options to the build
 
 ```js

package.json

@@ -19,6 +19,18 @@
   ],
   "main": "build/index.js",
   "types": "build/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./build/index.d.ts",
+      "default": "./build/index.js"
+    },
+    "./installation": {
+      "types": "./build/installation.d.ts",
+      "default": "./build/installation.js"
+    },
+    "./package.json": "./package.json",
+    "./*": "./*"
+  },
   "scripts": {
     "start": "node index.js",
     "dev": "DEBUG=bp* node --watch index.js",

src/common.types.ts

@@ -1,6 +1,11 @@
 export const packageManagers = ['npm', 'yarn', 'pnpm', 'bun'] as const
 export type PackageManager = (typeof packageManagers)[number]
 
+export type InstallationServiceOptions = {
+  url: string
+  fallbackToLocal?: boolean
+}
+
 type AllOptions = {
   customImports?: Array<string>
   splitCustomImports?: boolean
@@ -15,6 +20,7 @@ type AllOptions = {
   isLocal?: boolean
   installTimeout?: number
   signal?: AbortSignal
+  installationService?: InstallationServiceOptions
 }
 
 export type BuildPackageOptions = Pick<
@@ -38,6 +44,7 @@ export type InstallPackageOptions = Pick<
   | 'installTimeout'
   | 'debug'
   | 'signal'
+  | 'installationService'
 >
 
 export type GetPackageStatsOptions = Pick<
@@ -50,6 +57,7 @@ export type GetPackageStatsOptions = Pick<
   | 'installTimeout'
   | 'minify'
   | 'signal'
+  | 'installationService'
 >
 
 export type Externals = {

src/config/makeRspackConfig.ts

@@ -4,6 +4,7 @@ import escapeRegex from 'escape-string-regexp'
 import type { Entry, Configuration } from '@rspack/core'
 import rspack from '@rspack/core'
 import { createRequire } from 'node:module'
+import path from 'node:path'
 
 import OxcJsMinimizerRspackPlugin from './OxcJsMinimizerRspackPlugin.js'
 
@@ -17,12 +18,14 @@ type MakeRspackConfigOptions = {
   debug?: boolean
   minify?: boolean
   entry: Entry
+  dependencyPath?: string
   outputPath: string
 }
 
 export default function makeRspackConfig({
   packageName: _packageName,
   entry,
+  dependencyPath,
   externals,
   debug: _debug,
   minify = true,
@@ -74,7 +77,9 @@ export default function makeRspackConfig({
       chunkModules: true,
     },
     resolve: {
-      modules: ['node_modules'],
+      modules: dependencyPath
+        ? [path.join(dependencyPath, 'node_modules'), 'node_modules']
+        : ['node_modules'],
       conditionNames: ['svelte', '...'],
       extensions: [
         '.web.tsx',

src/getPackageExportSizes.ts

@@ -1,60 +1,30 @@
 import Telemetry from './utils/telemetry.utils.js'
 import { performance } from 'node:perf_hooks'
-import path from 'node:path'
 
 import createDebug from 'debug'
 
 const debug = createDebug('bp:worker')
 
-import {
-  getExternals,
-  parsePackageString,
-  throwIfAborted,
-} from './utils/common.utils.js'
+import { getExternals, throwIfAborted } from './utils/common.utils.js'
 import { getAllExports } from './utils/exports.utils.js'
-import InstallationUtils from './utils/installation.utils.js'
 import BuildUtils from './utils/build.utils.js'
 import type {
   GetPackageStatsOptions,
   InstallPackageOptions,
 } from './common.types.js'
-
-async function installPackage(
-  packageString: string,
-  installPath: string,
-  options: InstallPackageOptions,
-) {
-  const { isLocal } = parsePackageString(packageString)
-
-  await InstallationUtils.installPackage(packageString, installPath, {
-    isLocal,
-    client: options.client,
-    limitConcurrency: options.limitConcurrency,
-    networkConcurrency: options.networkConcurrency,
-    installTimeout: options.installTimeout,
-    signal: options.signal,
-  })
-}
+import { preparePackage, type PreparedPackage } from './packageInstallation.js'
 
 export async function getAllPackageExports(
   packageString: string,
   options: InstallPackageOptions = {},
 ) {
   const startTime = performance.now()
-  const { name: packageName, normalPath } = parsePackageString(packageString)
-  const installPath = await InstallationUtils.preparePath(
-    packageName,
-    options.client,
-    options.signal,
-  )
+  let preparedPackage: PreparedPackage | undefined
 
   try {
+    preparedPackage = await preparePackage(packageString, options, false)
+    const { packageName, packagePath, installPath } = preparedPackage
     throwIfAborted(options.signal)
-    await installPackage(packageString, installPath, options)
-    throwIfAborted(options.signal)
-    // The package is installed in node_modules subdirectory
-    const packagePath =
-      normalPath || path.join(installPath, 'node_modules', packageName)
     const results = await getAllExports(
       packageString,
       packagePath,
@@ -68,7 +38,7 @@ export async function getAllPackageExports(
     Telemetry.packageExports(packageString, startTime, false, err)
     throw err
   } finally {
-    await InstallationUtils.cleanupPath(installPath)
+    await preparedPackage?.cleanup()
   }
 }
 
@@ -78,34 +48,17 @@ export async function getPackageExportSizes(
 ) {
   const startTime = performance.now()
   const timings: Record<string, number> = {}
-
-  const { name: packageName, normalPath } = parsePackageString(packageString)
-
-  const preparePathStart = performance.now()
-  const installPath = await InstallationUtils.preparePath(
-    packageName,
-    options.client,
-    options.signal,
-  )
-  timings.preparePath = performance.now() - preparePathStart
-  console.log(
-    `[PERF] [ExportSizes] preparePath: ${timings.preparePath.toFixed(2)}ms`,
-  )
+  let preparedPackage: PreparedPackage | undefined
 
   try {
-    throwIfAborted(options.signal)
     const installStart = performance.now()
-    await installPackage(packageString, installPath, options)
+    preparedPackage = await preparePackage(packageString, options)
+    const { packageName, packagePath, installPath, buildPath } = preparedPackage
     throwIfAborted(options.signal)
     timings.install = performance.now() - installStart
     console.log(
       `[PERF] [ExportSizes] installPackage: ${timings.install.toFixed(2)}ms`,
     )
-
-    // The package is installed in node_modules subdirectory
-    const packagePath =
-      normalPath || path.join(installPath, 'node_modules', packageName)
-
     const getAllExportsStart = performance.now()
     const exportMap = await getAllExports(
       packageString,
@@ -152,7 +105,8 @@ export async function getPackageExportSizes(
       // oxlint-disable-next-line no-await-in-loop
       const chunkDetails = await BuildUtils.buildPackageIgnoringMissingDeps({
         name: packageName,
-        installPath,
+        installPath: buildPath,
+        dependencyPath: installPath,
         externals,
         options: {
           customImports: chunk,
@@ -206,6 +160,6 @@ export async function getPackageExportSizes(
     Telemetry.packageExportsSizes(packageString, startTime, false, options, err)
     throw err
   } finally {
-    await InstallationUtils.cleanupPath(installPath)
+    await preparedPackage?.cleanup()
   }
 }

src/getPackageStats.ts

@@ -6,16 +6,12 @@
 import fs from 'node:fs/promises'
 import path from 'node:path'
 import { performance } from 'node:perf_hooks'
-import {
-  getExternals,
-  parsePackageString,
-  throwIfAborted,
-} from './utils/common.utils.js'
-import InstallationUtils from './utils/installation.utils.js'
+import { getExternals, throwIfAborted } from './utils/common.utils.js'
 import BuildUtils from './utils/build.utils.js'
 import { UnexpectedBuildError } from './errors/CustomError.js'
 import type { GetPackageStatsOptions } from './common.types.js'
 import Telemetry from './utils/telemetry.utils.js'
+import { preparePackage, type PreparedPackage } from './packageInstallation.js'
 
 function getPackageJSONDetails(packageName: string, installPath: string) {
   const startTime = performance.now()
@@ -59,29 +55,12 @@ export default async function getPackageStats(
 ) {
   const startTime = performance.now()
   const timings: Record<string, number> = {}
-
-  const { name: packageName, isLocal } = parsePackageString(packageString)
-
-  const preparePathStart = performance.now()
-  const installPath = await InstallationUtils.preparePath(
-    packageName,
-    options.client,
-    options.signal,
-  )
-  timings.preparePath = performance.now() - preparePathStart
-  console.log(`[PERF] preparePath: ${timings.preparePath.toFixed(2)}ms`)
+  let preparedPackage: PreparedPackage | undefined
 
   try {
-    throwIfAborted(options.signal)
     const installStart = performance.now()
-    await InstallationUtils.installPackage(packageString, installPath, {
-      isLocal,
-      client: options.client,
-      limitConcurrency: options.limitConcurrency,
-      networkConcurrency: options.networkConcurrency,
-      installTimeout: options.installTimeout,
-      signal: options.signal,
-    })
+    preparedPackage = await preparePackage(packageString, options)
+    const { packageName, installPath, buildPath } = preparedPackage
     throwIfAborted(options.signal)
     timings.install = performance.now() - installStart
     console.log(`[PERF] installPackage: ${timings.install.toFixed(2)}ms`)
@@ -97,7 +76,8 @@ export default async function getPackageStats(
       getPackageJSONDetails(packageName, installPath),
       BuildUtils.buildPackageIgnoringMissingDeps({
         name: packageName,
-        installPath,
+        installPath: buildPath,
+        dependencyPath: installPath,
         externals,
         options: {
           debug: options.debug,
@@ -145,8 +125,6 @@ export default async function getPackageStats(
     )
     throw e
   } finally {
-    if (!options.debug) {
-      await InstallationUtils.cleanupPath(installPath)
-    }
+    await preparedPackage?.cleanup(options.debug)
   }
 }

src/index.ts

@@ -1,4 +1,5 @@
 export { default as getPackageStats } from './getPackageStats.js'
+export type { InstallationServiceOptions } from './common.types.js'
 export * from './errors/CustomError.js'
 export * from './getPackageExportSizes.js'
 export { emitter as eventQueue } from './utils/telemetry.utils.js'

src/installation.ts

@@ -0,0 +1,5 @@
+export {
+  disposePackage,
+  installPackage,
+  type PackageInstallation,
+} from './packageInstallation.js'