feat: add FsWatcher interface (#10798)

cli/dts/lib.deno.ns.d.ts

@@ -1949,6 +1949,25 @@ declare namespace Deno {
     paths: string[];
   }
 
+  /**
+   * FsWatcher is returned by `Deno.watchFs` function when you start watching
+   * the file system. You can iterate over this interface to get the file
+   * system events, and also you can stop watching the file system by calling
+   * `.close()` method.
+   */
+  export interface FsWatcher extends AsyncIterable<FsEvent> {
+    /** The resource id of the `FsWatcher`. */
+    readonly rid: number;
+    /** Stops watching the file system and closes the watcher resource. */
+    close(): void;
+    /** @deprecated
+     * Stops watching the file system and closes the watcher resource.
+     * Will be removed at 2.0.
+     */
+    return?(value?: any): Promise<IteratorResult<FsEvent>>;
+    [Symbol.asyncIterator](): AsyncIterableIterator<FsEvent>;
+  }
+
   /** Watch for file system events against one or more `paths`, which can be files
    * or directories.  These paths must exist already.  One user action (e.g.
    * `touch test.file`) can  generate multiple file system events.  Likewise,
@@ -1967,15 +1986,13 @@ declare namespace Deno {
    *
    * Requires `allow-read` permission.
    *
-   * Call `watcher.return()` to stop watching.
+   * Call `watcher.close()` to stop watching.
    *
    * ```ts
    * const watcher = Deno.watchFs("/");
    *
    * setTimeout(() => {
-   *   if (watcher.return) {
+   *   watcher.close();
-   *     watcher.return();
-   *   }
    * }, 5000);
    *
    * for await (const event of watcher) {
@@ -1986,7 +2003,7 @@ declare namespace Deno {
   export function watchFs(
     paths: string | string[],
     options?: { recursive: boolean },
-  ): AsyncIterableIterator<FsEvent>;
+  ): FsWatcher;
 
   export class Process<T extends RunOptions = RunOptions> {
     readonly rid: number;

cli/tests/unit/fs_events_test.ts

@@ -26,7 +26,7 @@ unitTest({ perms: { read: true } }, function watchFsInvalidPath() {
 });
 
 async function getTwoEvents(
-  iter: AsyncIterableIterator<Deno.FsEvent>,
+  iter: Deno.FsWatcher,
 ): Promise<Deno.FsEvent[]> {
   const events = [];
   for await (const event of iter) {
@@ -61,6 +61,8 @@ unitTest(
   },
 );
 
+// TODO(kt3k): This test is for the backward compatibility of `.return` method.
+// This should be removed at 2.0
 unitTest(
   { perms: { read: true, write: true } },
   async function watchFsReturn(): Promise<void> {
@@ -78,3 +80,21 @@ unitTest(
     assertEquals(events, []);
   },
 );
+
+unitTest(
+  { perms: { read: true, write: true } },
+  async function watchFsClose(): Promise<void> {
+    const testDir = await Deno.makeTempDir();
+    const iter = Deno.watchFs(testDir);
+
+    // Asynchronously loop events.
+    const eventsPromise = getTwoEvents(iter);
+
+    // Close the watcher.
+    await iter.close();
+
+    // Expect zero events.
+    const events = await eventsPromise;
+    assertEquals(events, []);
+  },
+);

runtime/js/40_fs_events.js

@@ -33,11 +33,17 @@
       }
     }
 
+    // TODO(kt3k): This is deprecated. Will be removed in v2.0.
+    // See https://github.com/denoland/deno/issues/10577 for details
     return(value) {
       core.close(this.rid);
       return Promise.resolve({ value, done: true });
     }
 
+    close() {
+      core.close(this.rid);
+    }
+
     [Symbol.asyncIterator]() {
       return this;
     }