watchpack

watchpack uses a three-level architecture to optimize file watching and ensure that only a single watcher exists for each directory, keeping the total watcher count low.

• WatcherManager & DirectoryWatchers: The high-level API requests DirectoryWatchers from a WatcherManager. This ensures that even if multiple parts of an application request to watch the same directory, only one DirectoryWatcher is actually created.
• Watcher: A user-facing Watcher is obtained from a DirectoryWatcher. It provides a filtered view of the directory's activity.
• Reference Counting: Both DirectoryWatcher and Watcher use reference counting to determine when it is safe to close them.
• No Direct File Watching: Files are never watched directly; instead, they are tracked via their parent directories. This is a key mechanism for maintaining a low watcher count.
• Symlinks: By default, symlinks are not followed; instead, the symlink itself is watched. This behavior can be changed via configuration.
• Historical Watching: Watching can be started at a specific point in the past (using startTime), allowing you to start watching after you have already performed initial file reads.

To add a new performance scenario, follow these steps:

1. Create a new directory under bench/cases/<name>/.
2. Create an index.bench.mjs file in that directory.
3. Export a default register(bench, ctx) function.
4. Use bench.add(name, fn) to register tasks.

Best Practices:

• Fixture Setup: Pre-build expensive fixtures outside the benchmark callback so only the hot path is measured. The ctx.fixtureDir points to cases/<name>/fixture/.
• Stability: Each bench.add body should loop over a fixed batch of inputs to ensure the measurement window sees enough work to be stable (minimum tens of microseconds).
• Determinism: Avoid non-determinism; use fixed request lists and avoid Math.random().
• Granularity: Focus one case on one scenario. For different shapes (e.g., warm vs. cold cache), create a new case directory instead of adding multiple bench.add calls to an existing one.

The ctx argument contains:

• caseName: The name of the case.
• caseDir: The directory of the case.
• fixtureDir: The directory for fixtures (cases/<name>/fixture/).

// Example structure for bench/cases/<name>/index.bench.mjs
export default function register(bench, ctx) {
  // Pre-build fixtures outside the callback
  const fixture = setupFixture(ctx.fixtureDir);

  bench.add("my-task", () => {
    // Loop over a fixed batch of inputs for stability
    for (let i = 0; i < 100; i++) {
      runTask(fixture);
    }
  });
}

Call wp.watch() to start monitoring specific items. Calling this method again will override the previous files and directories being watched.

Parameters:

• files (Iterable<string>): Files or directories. For files, content and existence are tracked. For directories, only existence and timestamp changes are tracked.
• directories (Iterable<string>): Only directories. Tracks directory content (and children) and existence. Assumed to exist; if not found, a remove event is emitted.
• missing (Iterable<string>): Items expected to not exist. Only existence changes are tracked. No remove event is emitted when these are not found initially.
• startTime (number, optional): A timestamp representing when watching should have started (e.g., Date.now() - 10000).

wp.watch({
	files: listOfFiles,
	directories: listOfDirectories,
	missing: listOfNotExistingItems,
	startTime: Date.now() - 10000,
});

To use watchpack, instantiate the Watchpack class with an options object.

Options:

• aggregateTimeout (number): Time in milliseconds to wait after a change before firing the aggregated event. If undefined, the aggregated event will not fire.
• poll (boolean | number):
  • true: Use polling with the default interval.
  • number: Use polling with the specified interval (e.g., 10000 for 10s).
  • undefined (default): Use native watching methods.
  • Note: Enable polling when watching over a network path. The WATCHPACK_POLLING environment variable overrides this option.
• followSymlinks (boolean):
  • true: Follows symlinks and watches both the symlink and the real files (higher performance hit).
  • false (default): Watches only the specified item (real file or symlink).
• ignored (string | string[] | RegExp | function): Defines what should be ignored.
  • string: A glob pattern.
  • string[]: Multiple glob patterns.
  • RegExp: A regular expression.
  • (entry) => boolean: An arbitrary function returning truthy to ignore an entry.
  • Note: Path separators are normalized to /. All subdirectories of an ignored entry are also ignored.

const Watchpack = require("watchpack");

const wp = new Watchpack({
	aggregateTimeout: 1000,
	poll: true,
	followSymlinks: true,
	ignored: "**/.git",
});

Watchpack emits several events to notify you of filesystem changes.

• change: Emitted when a file changes.

  • Callback: (filePath, mtime, explanation) => void
  • filePath: The changed file.
  • mtime: Last modified time.
  • explanation: Textual info on how the change was detected.

• remove: Emitted when a file or directory is removed.

  • Callback: (filePath, explanation) => void
  • filePath: The removed item.
  • explanation: Textual info on how the change was detected.

• aggregated: Emitted after a period of inactivity defined by aggregateTimeout.

  • Callback: (changes, removals) => void
  • changes: A Set of all changed files.
  • removals: A Set of all removed files.
  • Note: Watchpack gives up ownership of these Sets; do not modify them.

wp.on("change", (filePath, mtime, explanation) => {
	// handle change
});

wp.on("remove", (filePath, explanation) => {
	// handle removal
});

wp.on("aggregated", (changes, removals) => {
	// handle aggregated changes
});