feat: reuse installed packages across analyses

Author: pastelsky

.changeset/calm-dragons-share.md

@@ -0,0 +1,5 @@
+---
+'package-build-stats': major
+---
+
+Add reusable installed-package handles so multiple analyses can share one workspace, and rename `getAllPackageExports` to `getPackageExports`.

README.md

@@ -45,6 +45,34 @@ const results = await getPackageStats('lodash', { client: 'pnpm' })
 const results = await getPackageStats('lodash', { client: 'yarn' })
 ```
 
+#### Reusing an installation
+
+The analysis functions install and clean up packages automatically. Services
+that run several analyses for the same package can reuse one installation:
+
+```js
+import {
+  disposePackage,
+  getPackageExportSizes,
+  getPackageExports,
+  getPackageStats,
+  installPackage,
+} from 'package-build-stats'
+
+const installedPackage = await installPackage('lodash@4.17.21')
+
+try {
+  const stats = await getPackageStats(installedPackage)
+  const exports = await getPackageExports(installedPackage)
+  const exportSizes = await getPackageExportSizes(installedPackage)
+} finally {
+  await disposePackage(installedPackage)
+}
+```
+
+Run analyses sharing an installation sequentially because they share a build
+workspace.
+
 #### Passing options to the build
 
 ```js

index.js

@@ -8,7 +8,7 @@ const { json, status } = server.reply
 import {
   getPackageStats,
   getPackageExportSizes,
-  getAllPackageExports,
+  getPackageExports,
 } from './build/index.js'
 
 const PORT = Number(process.env.PORT ?? 3000)
@@ -141,7 +141,7 @@ const application = await server({ port: PORT }, [
     }),
   ),
   packageRoute('/exports', (packageString, query) =>
-    getAllPackageExports(packageString, { debug: !!query.debug }),
+    getPackageExports(packageString, { debug: !!query.debug }),
   ),
   get('/__debug/memory', async () => json(getMemorySnapshot())),
   get('/__debug/heapdump', async () => {