Optimize PackageCache: use Map/Set, cache null results, eliminate per-hit allocations

Summary:
Optimize PackageCache: use Map/Set, cache null results, eliminate per-hit allocations

## Summary

Refactors `PackageCache` with three optimizations that together yield a **19% speedup** (median) on `getPackageForModule` calls during `js1 build buckfiles`, despite switching from `Object.create(null)` to `Map`/`Set`.

### Changes

1. **Use `Map`/`Set` and `#private` fields** — Replaces `Object.create(null)` dict objects and `_`-prefixed fields with `Map`/`Set` and `#` private class fields for proper encapsulation. In isolation this is ~8-12% slower per-operation than null-prototype objects, but enables the optimizations below.

2. **Single-map result cache** — Replaces the two-map lookup pattern (`_packagePathAndSubpathByModulePath` → `_packageCache`) with a single `#resultByModulePath` map that caches the pre-built result object. Cache hits go from two `Map.get` calls + one object allocation to a single `Map.get` returning the cached object directly. This eliminates ~2.5M object allocations per build.

3. **Cache null results** — Previously, when `getClosestPackage`/`hierarchicalLookup` returned `null` (no enclosing `package.json`), the result was not cached, causing the same expensive tree walk on every repeat query. Trace analysis revealed that 123,017 unique paths (76% of all unique paths) have no enclosing `package.json`, and they account for 3,048,485 total calls (99% of call volume). Caching null results eliminates 413,138 redundant `hierarchicalLookup` calls, boosting the hit rate from 81% to 95%.

4. **Readonly return types** — `getPackage` and `getPackageForModule` now return `Readonly<>` types, preventing consumers from accidentally mutating cached objects.

Reviewed By: huntie

Differential Revision: D98745578

fbshipit-source-id: 3247bf39233c7fc556708fd8e2a0afd155b7a991

Author: robhogan

packages/metro/src/node-haste/PackageCache.js

@@ -12,137 +12,138 @@
 import type {PackageJson} from 'metro-resolver/private/types';
 
 import {readFileSync} from 'fs';
-import {dirname} from 'path';
+import {dirname, sep} from 'path';
 
 type GetClosestPackageFn = (absoluteFilePath: string) => ?{
   packageJsonPath: string,
   packageRelativePath: string,
 };
 
+type PackageForModule = Readonly<{
+  packageJson: PackageJson,
+  rootPath: string,
+  packageRelativePath: string,
+}>;
+
 export class PackageCache {
-  _getClosestPackage: GetClosestPackageFn;
-  _packageCache: {
-    [filePath: string]: {
+  #getClosestPackage: GetClosestPackageFn;
+  #packageCache: Map<
+    string,
+    {
       rootPath: string,
       packageJson: PackageJson,
     },
-    __proto__: null,
-    ...
-  };
-  // Cache for "closest package.json" queries by module path.
-  _packagePathAndSubpathByModulePath: {
-    [filePath: string]: ?{
-      packageJsonPath: string,
-      packageRelativePath: string,
-    },
-    __proto__: null,
-    ...
-  };
-  // The inverse of _packagePathByModulePath.
-  _modulePathsByPackagePath: {
-    [filePath: string]: Set<string>,
-    __proto__: null,
-    ...
-  };
+  >;
+  // Single cache: module path → pre-built result object, or null (no allocation on hit)
+  #resultByModulePath: Map<string, PackageForModule | null>;
+  // Reverse index for invalidation: package.json path → set of module paths
+  #modulePathsByPackagePath: Map<string, Set<string>>;
+  // Module paths that resolved to no package.json (null), for invalidation
+  #modulePathsWithNoPackage: Set<string>;
 
   constructor(options: {getClosestPackage: GetClosestPackageFn, ...}) {
-    this._getClosestPackage = options.getClosestPackage;
-    this._packageCache = Object.create(null);
-    this._packagePathAndSubpathByModulePath = Object.create(null);
-    this._modulePathsByPackagePath = Object.create(null);
+    this.#getClosestPackage = options.getClosestPackage;
+    this.#packageCache = new Map();
+    this.#resultByModulePath = new Map();
+    this.#modulePathsByPackagePath = new Map();
+    this.#modulePathsWithNoPackage = new Set();
   }
 
-  getPackage(filePath: string): {
+  getPackage(filePath: string): Readonly<{
     rootPath: string,
     packageJson: PackageJson,
-  } {
-    if (!this._packageCache[filePath]) {
-      this._packageCache[filePath] = {
+  }> {
+    let cached = this.#packageCache.get(filePath);
+    if (cached == null) {
+      cached = {
         rootPath: dirname(filePath),
         packageJson: JSON.parse(readFileSync(filePath, 'utf8')),
       };
+      this.#packageCache.set(filePath, cached);
     }
-    return this._packageCache[filePath];
+    return cached;
   }
 
-  getPackageForModule(absoluteModulePath: string): ?{
-    packageJson: PackageJson,
-    rootPath: string,
-    packageRelativePath: string,
-  } {
-    let packagePathAndSubpath =
-      this._packagePathAndSubpathByModulePath[absoluteModulePath];
-    if (
-      packagePathAndSubpath &&
-      this._packageCache[packagePathAndSubpath.packageJsonPath]
-    ) {
-      const {rootPath, packageJson} =
-        this._packageCache[packagePathAndSubpath.packageJsonPath];
-      return {
-        packageJson,
-        rootPath,
-        packageRelativePath: packagePathAndSubpath.packageRelativePath,
-      };
+  getPackageForModule(absoluteModulePath: string): ?PackageForModule {
+    const cached = this.#resultByModulePath.get(absoluteModulePath);
+
+    // Distinguish between `null` (positively no closest package) and
+    // `undefined` (no cached result yet)
+    // eslint-disable-next-line lint/strictly-null
+    if (cached !== undefined) {
+      return cached;
     }
 
-    packagePathAndSubpath = this._getClosestPackage(absoluteModulePath);
-    if (!packagePathAndSubpath) {
+    const closest = this.#getClosestPackage(absoluteModulePath);
+    if (closest == null) {
+      this.#resultByModulePath.set(absoluteModulePath, null);
+      this.#modulePathsWithNoPackage.add(absoluteModulePath);
       return null;
     }
 
-    const packagePath = packagePathAndSubpath.packageJsonPath;
+    const packagePath = closest.packageJsonPath;
 
-    this._packagePathAndSubpathByModulePath[absoluteModulePath] =
-      packagePathAndSubpath;
-    const modulePaths =
-      this._modulePathsByPackagePath[packagePath] ?? new Set();
+    // Track module→package for invalidation
+    let modulePaths = this.#modulePathsByPackagePath.get(packagePath);
+    if (modulePaths == null) {
+      modulePaths = new Set();
+      this.#modulePathsByPackagePath.set(packagePath, modulePaths);
+    }
     modulePaths.add(absoluteModulePath);
-    this._modulePathsByPackagePath[packagePath] = modulePaths;
 
     const pkg = this.getPackage(packagePath);
-
     if (pkg == null) {
       return null;
     }
 
-    const {rootPath, packageJson} = pkg;
-
-    return {
-      packageJson,
-      packageRelativePath: packagePathAndSubpath.packageRelativePath,
-      rootPath,
+    // Cache the pre-built result object — no allocation on future hits
+    const result: PackageForModule = {
+      packageJson: pkg.packageJson,
+      packageRelativePath: closest.packageRelativePath,
+      rootPath: pkg.rootPath,
     };
+    this.#resultByModulePath.set(absoluteModulePath, result);
+    return result;
   }
 
   invalidate(filePath: string) {
-    if (this._packageCache[filePath]) {
-      delete this._packageCache[filePath];
-    }
-    const packagePathAndSubpath =
-      this._packagePathAndSubpathByModulePath[filePath];
-    if (packagePathAndSubpath) {
-      // filePath is a module inside a package.
-      const packagePath = packagePathAndSubpath.packageJsonPath;
-      delete this._packagePathAndSubpathByModulePath[filePath];
-      // This change doesn't invalidate any cached "closest package.json"
-      // queries for the package's other modules. Clean up only this module.
-      const modulePaths = this._modulePathsByPackagePath[packagePath];
-      if (modulePaths) {
-        modulePaths.delete(filePath);
-        if (modulePaths.size === 0) {
-          delete this._modulePathsByPackagePath[packagePath];
+    this.#packageCache.delete(filePath);
+
+    // Clean up any cached result for this module path (including null).
+    // Derive the package.json path from the cached result to clean up the
+    // reverse index.
+    const cachedResult = this.#resultByModulePath.get(filePath);
+    this.#resultByModulePath.delete(filePath);
+    this.#modulePathsWithNoPackage.delete(filePath);
+
+    if (cachedResult != null) {
+      const packagePath = cachedResult.rootPath + sep + 'package.json';
+      const modules = this.#modulePathsByPackagePath.get(packagePath);
+      if (modules != null) {
+        modules.delete(filePath);
+        if (modules.size === 0) {
+          this.#modulePathsByPackagePath.delete(packagePath);
         }
       }
     }
-    if (this._modulePathsByPackagePath[filePath]) {
-      // filePath is a package. This change invalidates all cached "closest
-      // package.json" queries for modules inside this package.
-      const modulePaths = this._modulePathsByPackagePath[filePath];
+
+    // If filePath is a package.json, invalidate all module lookups pointing to it
+    const modulePaths = this.#modulePathsByPackagePath.get(filePath);
+    if (modulePaths != null) {
       for (const modulePath of modulePaths) {
-        delete this._packagePathAndSubpathByModulePath[modulePath];
+        this.#resultByModulePath.delete(modulePath);
+      }
+      this.#modulePathsByPackagePath.delete(filePath);
+    }
+
+    // If a package.json was created, modified, or deleted, invalidate all
+    // null-cached module results, since modules that previously had no
+    // enclosing package.json may now resolve to this one.
+    if (filePath.endsWith(sep + 'package.json')) {
+      for (const modulePath of this.#modulePathsWithNoPackage) {
+        this.#resultByModulePath.delete(modulePath);
       }
-      modulePaths.clear();
-      delete this._modulePathsByPackagePath[filePath];
+      this.#modulePathsWithNoPackage.clear();
     }
   }
 }