1 files changed, 156 insertions, 0 deletions
diff --git a/packages/bun-types/fs.d.ts b/packages/bun-types/fs.d.ts
index 5fb552b7c..3338bcb82 100644
--- a/packages/bun-types/fs.d.ts
+++ b/packages/bun-types/fs.d.ts
@@ -4067,6 +4067,162 @@ declare module "fs" {
     filename: PathLike,
     listener?: WatchListener<string>,
   ): FSWatcher;
+
+  /**
+   * A successful call to {@link watchFile} will return a new fs.StatWatcher object.
+   * @since 0.7.1
+   */
+  export interface StatWatcher extends EventEmitter {
+    /**
+     * When called, requests that the Node.js event loop not exit so long as the watcher is active.
+     *
+     * Calling watcher.ref() multiple times will have no effect.
+     */
+    ref(): this;
+
+    /**
+     * When called, the active watcher will not require the Node.js event loop to remain active.
+     * If there is no other activity keeping the event loop running, the process may exit before
+     * the watcher's callback is invoked.
+     *
+     * Calling watcher.unref() multiple times will have no effect.
+     */
+    unref(): this;
+  }
+
+  /**
+   * Watch for changes on `filename`. The callback `listener` will be called each
+   * time the file is accessed.
+   *
+   * The `options` argument may be omitted. If provided, it should be an object. The`options` object may contain a boolean named `persistent` that indicates
+   * whether the process should continue to run as long as files are being watched.
+   * The `options` object may specify an `interval` property indicating how often the
+   * target should be polled in milliseconds.
+   *
+   * The `listener` gets two arguments the current stat object and the previous
+   * stat object:
+   *
+   * ```js
+   * import { watchFile } from "node:fs";
+   *
+   * watchFile("example.txt", (curr, prev) => {
+   *   console.log(`the current mtime is: ${curr.mtime}`);
+   *   console.log(`the previous mtime was: ${prev.mtime}`);
+   * });
+   * ```
+   *
+   * These stat objects are instances of `fs.Stat`. If the `bigint` option is `true`,
+   * the numeric values in these objects are specified as `BigInt`s.
+   *
+   * To be notified when the file was modified, not just accessed, it is necessary
+   * to compare `curr.mtimeMs` and `prev.mtimeMs`.
+   *
+   * When an `fs.watchFile` operation results in an `ENOENT` error, it
+   * will invoke the listener once, with all the fields zeroed (or, for dates, the
+   * Unix Epoch). If the file is created later on, the listener will be called
+   * again, with the latest stat objects. This is a change in functionality since
+   * v0.10.
+   *
+   * Using {@link watch} is more efficient than `fs.watchFile` and`fs.unwatchFile`.
+   * `fs.watch` should be used instead of `fs.watchFile` and`fs.unwatchFile` when possible.
+   *
+   * When a file being watched by `fs.watchFile()` disappears and reappears,
+   * then the contents of `previous` in the second callback event (the file's
+   * reappearance) will be the same as the contents of `previous` in the first
+   * callback event (its disappearance).
+   *
+   * This happens when:
+   *
+   * * the file is deleted, followed by a restore
+   * * the file is renamed and then renamed a second time back to its original name
+   *
+   * @since 0.7.1
+   */
+  export type WatchFileOptions = {
+    bigint?: boolean;
+    persistent?: boolean;
+    interval?: number;
+  };
+
+  export type StatsListener = (curr: Stats, prev: Stats) => void;
+  export type BigIntStatsListener = (curr: BigIntStats, prev: BigIntStats) => void;
+
+  /**
+   * Watch for changes on `filename`. The callback `listener` will be called each
+   * time the file is accessed.
+   *
+   * The `options` argument may be omitted. If provided, it should be an object. The`options` object may contain a boolean named `persistent` that indicates
+   * whether the process should continue to run as long as files are being watched.
+   * The `options` object may specify an `interval` property indicating how often the
+   * target should be polled in milliseconds.
+   *
+   * The `listener` gets two arguments the current stat object and the previous
+   * stat object:
+   *
+   * ```js
+   * import { watchFile } from "node:fs";
+   *
+   * watchFile("example.txt", (curr, prev) => {
+   *   console.log(`the current mtime is: ${curr.mtime}`);
+   *   console.log(`the previous mtime was: ${prev.mtime}`);
+   * });
+   * ```
+   *
+   * These stat objects are instances of `fs.Stat`. If the `bigint` option is `true`,
+   * the numeric values in these objects are specified as `BigInt`s.
+   *
+   * To be notified when the file was modified, not just accessed, it is necessary
+   * to compare `curr.mtimeMs` and `prev.mtimeMs`.
+   *
+   * When an `fs.watchFile` operation results in an `ENOENT` error, it
+   * will invoke the listener once, with all the fields zeroed (or, for dates, the
+   * Unix Epoch). If the file is created later on, the listener will be called
+   * again, with the latest stat objects. This is a change in functionality since
+   * v0.10.
+   *
+   * Using {@link watch} is more efficient than `fs.watchFile` and`fs.unwatchFile`.
+   * `fs.watch` should be used instead of `fs.watchFile` and`fs.unwatchFile` when possible.
+   *
+   * When a file being watched by `fs.watchFile()` disappears and reappears,
+   * then the contents of `previous` in the second callback event (the file's
+   * reappearance) will be the same as the contents of `previous` in the first
+   * callback event (its disappearance).
+   *
+   * This happens when:
+   *
+   * * the file is deleted, followed by a restore
+   * * the file is renamed and then renamed a second time back to its original name
+   *
+   * @since 0.7.1
+   */
+  export function watchFile(
+    filename: PathLike,
+    options:
+      | (WatchFileOptions & {
+          bigint?: false | undefined;
+        })
+      | undefined,
+    listener: StatsListener,
+  ): StatWatcher;
+
+  export function watchFile(
+    filename: PathLike,
+    options:
+      | (WatchFileOptions & {
+          bigint: true;
+        })
+      | undefined,
+    listener: BigIntStatsListener,
+  ): StatWatcher;
+
+  /**
+   * Watch for changes on `filename`. The callback `listener` will be called each time the file is accessed.
+   * @param filename A path to a file or directory. If a URL is provided, it must use the `file:` protocol.
+   */
+  export function watchFile(
+    filename: PathLike,
+    listener: StatsListener,
+  ): StatWatcher;
 }
 
 declare module "node:fs" {