metro-file-map 0.81.0 → 0.81.2

package/package.json

@@ -1,8 +1,16 @@
 {
   "name": "metro-file-map",
-  "version": "0.81.0",
+  "version": "0.81.2",
   "description": "[Experimental] - 🚇 File crawling, watching and mapping for Metro",
   "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./package.json": "./package.json",
+    "./private/*": "./src/*.js",
+    "./src": "./src/index.js",
+    "./src/*.js": "./src/*.js",
+    "./src/*": "./src/*.js"
+  },
   "repository": {
     "type": "git",
     "url": "git@github.com:facebook/metro.git"
@@ -13,24 +21,19 @@
   },
   "license": "MIT",
   "dependencies": {
-    "anymatch": "^3.0.3",
     "debug": "^2.2.0",
     "fb-watchman": "^2.0.0",
     "flow-enums-runtime": "^0.0.6",
     "graceful-fs": "^4.2.4",
     "invariant": "^2.2.4",
-    "jest-worker": "^29.6.3",
+    "jest-worker": "^29.7.0",
     "micromatch": "^4.0.4",
-    "node-abort-controller": "^3.1.1",
     "nullthrows": "^1.1.1",
     "walker": "^1.0.7"
   },
   "devDependencies": {
     "slash": "^3.0.0"
   },
-  "optionalDependencies": {
-    "fsevents": "^2.3.2"
-  },
   "engines": {
     "node": ">=18.18"
   }

package/src/Watcher.js

@@ -7,10 +7,12 @@ exports.Watcher = void 0;
 var _node = _interopRequireDefault(require("./crawlers/node"));
 var _watchman = _interopRequireDefault(require("./crawlers/watchman"));
 var _common = require("./watchers/common");
-var _FSEventsWatcher = _interopRequireDefault(
-  require("./watchers/FSEventsWatcher")
+var _FallbackWatcher = _interopRequireDefault(
+  require("./watchers/FallbackWatcher")
+);
+var _NativeWatcher = _interopRequireDefault(
+  require("./watchers/NativeWatcher")
 );
-var _NodeWatcher = _interopRequireDefault(require("./watchers/NodeWatcher"));
 var _WatchmanWatcher = _interopRequireDefault(
   require("./watchers/WatchmanWatcher")
 );
@@ -60,8 +62,8 @@ class Watcher extends _events.default {
   async crawl() {
     this._options.perfLogger?.point("crawl_start");
     const options = this._options;
-    const ignore = (filePath) =>
-      options.ignore(filePath) ||
+    const ignoreForCrawl = (filePath) =>
+      options.ignoreForCrawl(filePath) ||
       path.basename(filePath).startsWith(this._options.healthCheckFilePrefix);
     const crawl = options.useWatchman ? _watchman.default : _node.default;
     let crawler = crawl === _watchman.default ? "watchman" : "node";
@@ -73,7 +75,7 @@ class Watcher extends _events.default {
       includeSymlinks: options.enableSymlinks,
       extensions: options.extensions,
       forceNodeFilesystemAPI: options.forceNodeFilesystemAPI,
-      ignore,
+      ignore: ignoreForCrawl,
       onStatus: (status) => {
         this.emit("status", status);
       },
@@ -123,17 +125,17 @@ class Watcher extends _events.default {
     }
   }
   async watch(onChange) {
-    const { extensions, ignorePattern, useWatchman } = this._options;
+    const { extensions, ignorePatternForWatch, useWatchman } = this._options;
     const WatcherImpl = useWatchman
       ? _WatchmanWatcher.default
-      : _FSEventsWatcher.default.isSupported()
-      ? _FSEventsWatcher.default
-      : _NodeWatcher.default;
-    let watcher = "node";
+      : _NativeWatcher.default.isSupported()
+      ? _NativeWatcher.default
+      : _FallbackWatcher.default;
+    let watcher = "fallback";
     if (WatcherImpl === _WatchmanWatcher.default) {
       watcher = "watchman";
-    } else if (WatcherImpl === _FSEventsWatcher.default) {
-      watcher = "fsevents";
+    } else if (WatcherImpl === _NativeWatcher.default) {
+      watcher = "native";
     }
     debug(`Using watcher: ${watcher}`);
     this._options.perfLogger?.annotate({
@@ -145,39 +147,38 @@ class Watcher extends _events.default {
     const createWatcherBackend = (root) => {
       const watcherOptions = {
         dot: true,
-        glob: [
+        globs: [
           "**/package.json",
           "**/" + this._options.healthCheckFilePrefix + "*",
           ...extensions.map((extension) => "**/*." + extension),
         ],
-        ignored: ignorePattern,
+        ignored: ignorePatternForWatch,
         watchmanDeferStates: this._options.watchmanDeferStates,
       };
       const watcher = new WatcherImpl(root, watcherOptions);
-      return new Promise((resolve, reject) => {
+      return new Promise(async (resolve, reject) => {
         const rejectTimeout = setTimeout(
           () => reject(new Error("Failed to start watch mode.")),
           MAX_WAIT_TIME
         );
-        watcher.once("ready", () => {
-          clearTimeout(rejectTimeout);
-          watcher.on("all", (type, filePath, root, metadata) => {
-            const basename = path.basename(filePath);
-            if (basename.startsWith(this._options.healthCheckFilePrefix)) {
-              if (type === _common.ADD_EVENT || type === _common.CHANGE_EVENT) {
-                debug(
-                  "Observed possible health check cookie: %s in %s",
-                  filePath,
-                  root
-                );
-                this._handleHealthCheckObservation(basename);
-              }
-              return;
+        watcher.onFileEvent((change) => {
+          const basename = path.basename(change.relativePath);
+          if (basename.startsWith(this._options.healthCheckFilePrefix)) {
+            if (change.event === _common.TOUCH_EVENT) {
+              debug(
+                "Observed possible health check cookie: %s in %s",
+                change.relativePath,
+                root
+              );
+              this._handleHealthCheckObservation(basename);
             }
-            onChange(type, filePath, root, metadata);
-          });
-          resolve(watcher);
+            return;
+          }
+          onChange(change);
         });
+        await watcher.startWatching();
+        clearTimeout(rejectTimeout);
+        resolve(watcher);
       });
     };
     this._backends = await Promise.all(
@@ -192,7 +193,7 @@ class Watcher extends _events.default {
     resolveHealthCheck();
   }
   async close() {
-    await Promise.all(this._backends.map((watcher) => watcher.close()));
+    await Promise.all(this._backends.map((watcher) => watcher.stopWatching()));
     this._activeWatcher = null;
   }
   async checkHealth(timeout) {

package/src/Watcher.js.flow

@@ -9,22 +9,22 @@
  */
 
 import type {
-  ChangeEventMetadata,
   Console,
   CrawlerOptions,
   FileData,
   Path,
   PerfLogger,
+  WatcherBackend,
+  WatcherBackendChangeEvent,
   WatchmanClocks,
 } from './flow-types';
 import type {WatcherOptions as WatcherBackendOptions} from './watchers/common';
-import type {AbortSignal} from 'node-abort-controller';
 
 import nodeCrawl from './crawlers/node';
 import watchmanCrawl from './crawlers/watchman';
-import {ADD_EVENT, CHANGE_EVENT} from './watchers/common';
-import FSEventsWatcher from './watchers/FSEventsWatcher';
-import NodeWatcher from './watchers/NodeWatcher';
+import {TOUCH_EVENT} from './watchers/common';
+import FallbackWatcher from './watchers/FallbackWatcher';
+import NativeWatcher from './watchers/NativeWatcher';
 import WatchmanWatcher from './watchers/WatchmanWatcher';
 import EventEmitter from 'events';
 import * as fs from 'fs';
@@ -50,8 +50,8 @@ type WatcherOptions = {
   extensions: $ReadOnlyArray<string>,
   forceNodeFilesystemAPI: boolean,
   healthCheckFilePrefix: string,
-  ignore: string => boolean,
-  ignorePattern: RegExp,
+  ignoreForCrawl: string => boolean,
+  ignorePatternForWatch: RegExp,
   previousState: CrawlerOptions['previousState'],
   perfLogger: ?PerfLogger,
   roots: $ReadOnlyArray<string>,
@@ -61,11 +61,6 @@ type WatcherOptions = {
   watchmanDeferStates: $ReadOnlyArray<string>,
 };
 
-interface WatcherBackend {
-  getPauseReason(): ?string;
-  close(): Promise<void>;
-}
-
 let nextInstanceId = 0;
 
 export type HealthCheckResult =
@@ -92,8 +87,8 @@ export class Watcher extends EventEmitter {
     this._options.perfLogger?.point('crawl_start');
 
     const options = this._options;
-    const ignore = (filePath: string) =>
-      options.ignore(filePath) ||
+    const ignoreForCrawl = (filePath: string) =>
+      options.ignoreForCrawl(filePath) ||
       path.basename(filePath).startsWith(this._options.healthCheckFilePrefix);
     const crawl = options.useWatchman ? watchmanCrawl : nodeCrawl;
     let crawler = crawl === watchmanCrawl ? 'watchman' : 'node';
@@ -107,7 +102,7 @@ export class Watcher extends EventEmitter {
       includeSymlinks: options.enableSymlinks,
       extensions: options.extensions,
       forceNodeFilesystemAPI: options.forceNodeFilesystemAPI,
-      ignore,
+      ignore: ignoreForCrawl,
       onStatus: status => {
         this.emit('status', status);
       },
@@ -163,28 +158,21 @@ export class Watcher extends EventEmitter {
     }
   }
 
-  async watch(
-    onChange: (
-      type: string,
-      filePath: string,
-      root: string,
-      metadata: ChangeEventMetadata,
-    ) => void,
-  ) {
-    const {extensions, ignorePattern, useWatchman} = this._options;
+  async watch(onChange: (change: WatcherBackendChangeEvent) => void) {
+    const {extensions, ignorePatternForWatch, useWatchman} = this._options;
 
-    // WatchmanWatcher > FSEventsWatcher > sane.NodeWatcher
+    // WatchmanWatcher > NativeWatcher > FallbackWatcher
     const WatcherImpl = useWatchman
       ? WatchmanWatcher
-      : FSEventsWatcher.isSupported()
-        ? FSEventsWatcher
-        : NodeWatcher;
+      : NativeWatcher.isSupported()
+        ? NativeWatcher
+        : FallbackWatcher;
 
-    let watcher = 'node';
+    let watcher = 'fallback';
     if (WatcherImpl === WatchmanWatcher) {
       watcher = 'watchman';
-    } else if (WatcherImpl === FSEventsWatcher) {
-      watcher = 'fsevents';
+    } else if (WatcherImpl === NativeWatcher) {
+      watcher = 'native';
     }
     debug(`Using watcher: ${watcher}`);
     this._options.perfLogger?.annotate({string: {watcher}});
@@ -193,7 +181,7 @@ export class Watcher extends EventEmitter {
     const createWatcherBackend = (root: Path): Promise<WatcherBackend> => {
       const watcherOptions: WatcherBackendOptions = {
         dot: true,
-        glob: [
+        globs: [
           // Ensure we always include package.json files, which are crucial for
           /// module resolution.
           '**/package.json',
@@ -201,44 +189,35 @@ export class Watcher extends EventEmitter {
           '**/' + this._options.healthCheckFilePrefix + '*',
           ...extensions.map(extension => '**/*.' + extension),
         ],
-        ignored: ignorePattern,
+        ignored: ignorePatternForWatch,
         watchmanDeferStates: this._options.watchmanDeferStates,
       };
-      const watcher = new WatcherImpl(root, watcherOptions);
+      const watcher: WatcherBackend = new WatcherImpl(root, watcherOptions);
 
-      return new Promise((resolve, reject) => {
+      return new Promise(async (resolve, reject) => {
         const rejectTimeout = setTimeout(
           () => reject(new Error('Failed to start watch mode.')),
           MAX_WAIT_TIME,
         );
 
-        watcher.once('ready', () => {
-          clearTimeout(rejectTimeout);
-          watcher.on(
-            'all',
-            (
-              type: string,
-              filePath: string,
-              root: string,
-              metadata: ChangeEventMetadata,
-            ) => {
-              const basename = path.basename(filePath);
-              if (basename.startsWith(this._options.healthCheckFilePrefix)) {
-                if (type === ADD_EVENT || type === CHANGE_EVENT) {
-                  debug(
-                    'Observed possible health check cookie: %s in %s',
-                    filePath,
-                    root,
-                  );
-                  this._handleHealthCheckObservation(basename);
-                }
-                return;
-              }
-              onChange(type, filePath, root, metadata);
-            },
-          );
-          resolve(watcher);
+        watcher.onFileEvent(change => {
+          const basename = path.basename(change.relativePath);
+          if (basename.startsWith(this._options.healthCheckFilePrefix)) {
+            if (change.event === TOUCH_EVENT) {
+              debug(
+                'Observed possible health check cookie: %s in %s',
+                change.relativePath,
+                root,
+              );
+              this._handleHealthCheckObservation(basename);
+            }
+            return;
+          }
+          onChange(change);
         });
+        await watcher.startWatching();
+        clearTimeout(rejectTimeout);
+        resolve(watcher);
       });
     };
 
@@ -256,7 +235,7 @@ export class Watcher extends EventEmitter {
   }
 
   async close() {
-    await Promise.all(this._backends.map(watcher => watcher.close()));
+    await Promise.all(this._backends.map(watcher => watcher.stopWatching()));
     this._activeWatcher = null;
   }
 

package/src/cache/DiskCacheManager.d.ts

@@ -12,7 +12,7 @@ import type {
   BuildParameters,
   CacheData,
   CacheManager,
-  FileData,
+  CacheManagerWriteOptions,
 } from '../flow-types';
 
 export interface DiskCacheConfig {
@@ -31,7 +31,8 @@ export class DiskCacheManager implements CacheManager {
   getCacheFilePath(): string;
   read(): Promise<CacheData | null>;
   write(
-    dataSnapshot: CacheData,
-    {changed, removed}: Readonly<{changed: FileData; removed: FileData}>,
+    getSnapshot: () => CacheData,
+    opts: CacheManagerWriteOptions,
   ): Promise<void>;
+  end(): Promise<void>;
 }

package/src/cache/DiskCacheManager.js

@@ -7,22 +7,42 @@ exports.DiskCacheManager = void 0;
 var _rootRelativeCacheKeys = _interopRequireDefault(
   require("../lib/rootRelativeCacheKeys")
 );
-var _gracefulFs = require("graceful-fs");
+var _fs = require("fs");
 var _os = require("os");
 var _path = _interopRequireDefault(require("path"));
+var _timers = require("timers");
 var _v = require("v8");
 function _interopRequireDefault(e) {
   return e && e.__esModule ? e : { default: e };
 }
+const debug = require("debug")("Metro:FileMapCache");
 const DEFAULT_PREFIX = "metro-file-map";
 const DEFAULT_DIRECTORY = (0, _os.tmpdir)();
+const DEFAULT_AUTO_SAVE_DEBOUNCE_MS = 5000;
 class DiskCacheManager {
-  constructor({ buildParameters, cacheDirectory, cacheFilePrefix }) {
-    this._cachePath = DiskCacheManager.getCacheFilePath(
+  #autoSaveOpts;
+  #cachePath;
+  #debounceTimeout = null;
+  #writePromise = Promise.resolve();
+  #hasUnwrittenChanges = false;
+  #tryWrite;
+  #stopListening;
+  constructor(
+    { buildParameters },
+    { autoSave = {}, cacheDirectory, cacheFilePrefix }
+  ) {
+    this.#cachePath = DiskCacheManager.getCacheFilePath(
       buildParameters,
       cacheFilePrefix,
       cacheDirectory
     );
+    if (autoSave) {
+      const { debounceMs = DEFAULT_AUTO_SAVE_DEBOUNCE_MS } =
+        autoSave === true ? {} : autoSave;
+      this.#autoSaveOpts = {
+        debounceMs,
+      };
+    }
   }
   static getCacheFilePath(buildParameters, cacheFilePrefix, cacheDirectory) {
     const { rootDirHash, relativeConfigHash } = (0,
@@ -35,13 +55,11 @@ class DiskCacheManager {
     );
   }
   getCacheFilePath() {
-    return this._cachePath;
+    return this.#cachePath;
   }
   async read() {
     try {
-      return (0, _v.deserialize)(
-        (0, _gracefulFs.readFileSync)(this._cachePath)
-      );
+      return (0, _v.deserialize)(await _fs.promises.readFile(this.#cachePath));
     } catch (e) {
       if (e?.code === "ENOENT") {
         return null;
@@ -49,13 +67,53 @@ class DiskCacheManager {
       throw e;
     }
   }
-  async write(dataSnapshot, { changed, removed }) {
-    if (changed.size > 0 || removed.size > 0) {
-      (0, _gracefulFs.writeFileSync)(
-        this._cachePath,
-        (0, _v.serialize)(dataSnapshot)
-      );
+  async write(
+    getSnapshot,
+    { changedSinceCacheRead, eventSource, onWriteError }
+  ) {
+    const tryWrite = (this.#tryWrite = () => {
+      this.#writePromise = this.#writePromise
+        .then(async () => {
+          if (!this.#hasUnwrittenChanges) {
+            return;
+          }
+          const data = getSnapshot();
+          this.#hasUnwrittenChanges = false;
+          await _fs.promises.writeFile(
+            this.#cachePath,
+            (0, _v.serialize)(data)
+          );
+          debug("Written cache to %s", this.#cachePath);
+        })
+        .catch(onWriteError);
+      return this.#writePromise;
+    });
+    if (this.#autoSaveOpts) {
+      const autoSave = this.#autoSaveOpts;
+      this.#stopListening?.();
+      this.#stopListening = eventSource.onChange(() => {
+        this.#hasUnwrittenChanges = true;
+        if (this.#debounceTimeout) {
+          this.#debounceTimeout.refresh();
+        } else {
+          this.#debounceTimeout = (0, _timers.setTimeout)(
+            () => tryWrite(),
+            autoSave.debounceMs
+          ).unref();
+        }
+      });
+    }
+    if (changedSinceCacheRead) {
+      this.#hasUnwrittenChanges = true;
+      await tryWrite();
+    }
+  }
+  async end() {
+    if (this.#debounceTimeout) {
+      (0, _timers.clearTimeout)(this.#debounceTimeout);
     }
+    this.#stopListening?.();
+    await this.#tryWrite?.();
   }
 }
 exports.DiskCacheManager = DiskCacheManager;

package/src/cache/DiskCacheManager.js.flow

@@ -12,38 +12,59 @@
 import type {
   BuildParameters,
   CacheData,
-  CacheDelta,
   CacheManager,
+  CacheManagerFactoryOptions,
+  CacheManagerWriteOptions,
 } from '../flow-types';
 
 import rootRelativeCacheKeys from '../lib/rootRelativeCacheKeys';
-import {readFileSync, writeFileSync} from 'graceful-fs';
+import {promises as fsPromises} from 'fs';
 import {tmpdir} from 'os';
 import path from 'path';
+import {Timeout, clearTimeout, setTimeout} from 'timers';
 import {deserialize, serialize} from 'v8';
 
+const debug = require('debug')('Metro:FileMapCache');
+
+type AutoSaveOptions = $ReadOnly<{
+  debounceMs: number,
+}>;
+
 type DiskCacheConfig = {
-  buildParameters: BuildParameters,
+  autoSave?: Partial<AutoSaveOptions> | boolean,
   cacheFilePrefix?: ?string,
   cacheDirectory?: ?string,
 };
 
 const DEFAULT_PREFIX = 'metro-file-map';
 const DEFAULT_DIRECTORY = tmpdir();
+const DEFAULT_AUTO_SAVE_DEBOUNCE_MS = 5000;
 
 export class DiskCacheManager implements CacheManager {
-  _cachePath: string;
-
-  constructor({
-    buildParameters,
-    cacheDirectory,
-    cacheFilePrefix,
-  }: DiskCacheConfig) {
-    this._cachePath = DiskCacheManager.getCacheFilePath(
+  +#autoSaveOpts: ?AutoSaveOptions;
+  +#cachePath: string;
+  #debounceTimeout: ?Timeout = null;
+  #writePromise: Promise<void> = Promise.resolve();
+  #hasUnwrittenChanges: boolean = false;
+  #tryWrite: ?() => Promise<void>;
+  #stopListening: ?() => void;
+
+  constructor(
+    {buildParameters}: CacheManagerFactoryOptions,
+    {autoSave = {}, cacheDirectory, cacheFilePrefix}: DiskCacheConfig,
+  ) {
+    this.#cachePath = DiskCacheManager.getCacheFilePath(
       buildParameters,
       cacheFilePrefix,
       cacheDirectory,
     );
+
+    // Normalise auto-save options.
+    if (autoSave) {
+      const {debounceMs = DEFAULT_AUTO_SAVE_DEBOUNCE_MS} =
+        autoSave === true ? {} : autoSave;
+      this.#autoSaveOpts = {debounceMs};
+    }
   }
 
   static getCacheFilePath(
@@ -63,12 +84,12 @@ export class DiskCacheManager implements CacheManager {
   }
 
   getCacheFilePath(): string {
-    return this._cachePath;
+    return this.#cachePath;
   }
 
   async read(): Promise<?CacheData> {
     try {
-      return deserialize(readFileSync(this._cachePath));
+      return deserialize(await fsPromises.readFile(this.#cachePath));
     } catch (e) {
       if (e?.code === 'ENOENT') {
         // Cache file not found - not considered an error.
@@ -80,11 +101,64 @@ export class DiskCacheManager implements CacheManager {
   }
 
   async write(
-    dataSnapshot: CacheData,
-    {changed, removed}: CacheDelta,
+    getSnapshot: () => CacheData,
+    {
+      changedSinceCacheRead,
+      eventSource,
+      onWriteError,
+    }: CacheManagerWriteOptions,
   ): Promise<void> {
-    if (changed.size > 0 || removed.size > 0) {
-      writeFileSync(this._cachePath, serialize(dataSnapshot));
+    // Initialise a writer function using a promise queue to ensure writes are
+    // sequenced.
+    const tryWrite = (this.#tryWrite = () => {
+      this.#writePromise = this.#writePromise
+        .then(async () => {
+          if (!this.#hasUnwrittenChanges) {
+            return;
+          }
+          const data = getSnapshot();
+          this.#hasUnwrittenChanges = false;
+          await fsPromises.writeFile(this.#cachePath, serialize(data));
+          debug('Written cache to %s', this.#cachePath);
+        })
+        .catch(onWriteError);
+      return this.#writePromise;
+    });
+
+    // Set up auto-save on changes, if enabled.
+    if (this.#autoSaveOpts) {
+      const autoSave = this.#autoSaveOpts;
+      this.#stopListening?.();
+      this.#stopListening = eventSource.onChange(() => {
+        this.#hasUnwrittenChanges = true;
+        if (this.#debounceTimeout) {
+          this.#debounceTimeout.refresh();
+        } else {
+          this.#debounceTimeout = setTimeout(
+            () => tryWrite(),
+            autoSave.debounceMs,
+          ).unref();
+        }
+      });
     }
+
+    // Write immediately if state has changed since the cache was read.
+    if (changedSinceCacheRead) {
+      this.#hasUnwrittenChanges = true;
+      await tryWrite();
+    }
+  }
+
+  async end() {
+    // Clear any timers
+    if (this.#debounceTimeout) {
+      clearTimeout(this.#debounceTimeout);
+    }
+
+    // Remove event listeners
+    this.#stopListening?.();
+
+    // Flush unwritten changes to disk (no-op if no changes)
+    await this.#tryWrite?.();
   }
 }