BREAKING CHANGE: rename Deno.fsEvents() to Deno.watchFs() (#4886)

cli/js/deno.ts

@@ -38,7 +38,7 @@ export {
   OpenMode,
 } from "./files.ts";
 export { read, readSync, write, writeSync } from "./ops/io.ts";
-export { FsEvent, fsEvents } from "./ops/fs_events.ts";
+export { FsEvent, watchFs } from "./ops/fs_events.ts";
 export {
   EOF,
   copy,

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

@@ -2169,15 +2169,12 @@ declare namespace Deno {
    */
   export function resources(): ResourceMap;
 
-  /** **UNSTABLE**: new API. Needs docs. */
   export interface FsEvent {
     kind: "any" | "access" | "create" | "modify" | "remove";
     paths: string[];
   }
 
-  /** **UNSTABLE**: new API, yet to be vetted.
+  /** Watch for file system events against one or more `paths`, which can be files
-   *
-   * 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,
    * one user action can result in multiple file paths in one event (e.g. `mv
@@ -2185,14 +2182,15 @@ declare namespace Deno {
    * for directories, will watch the specified directory and all sub directories.
    * Note that the exact ordering of the events can vary between operating systems.
    *
-   *       const iter = Deno.fsEvents("/");
+   *       const watcher = Deno.watchFs("/");
-   *       for await (const event of iter) {
+   *       for await (const event of watcher) {
-   *          console.log(">>>> event", event);  // e.g. { kind: "create", paths: [ "/foo.txt" ] }
+   *          console.log(">>>> event", event);
+   *          // { kind: "create", paths: [ "/foo.txt" ] }
    *       }
    *
    * Requires `allow-read` permission.
    */
-  export function fsEvents(
+  export function watchFs(
     paths: string | string[],
     options?: { recursive: boolean }
   ): AsyncIterableIterator<FsEvent>;

cli/js/ops/fs_events.ts

@@ -7,7 +7,7 @@ export interface FsEvent {
   paths: string[];
 }
 
-class FsEvents implements AsyncIterableIterator<FsEvent> {
+class FsWatcher implements AsyncIterableIterator<FsEvent> {
   readonly rid: number;
 
   constructor(paths: string[], options: { recursive: boolean }) {
@@ -31,9 +31,9 @@ class FsEvents implements AsyncIterableIterator<FsEvent> {
   }
 }
 
-export function fsEvents(
+export function watchFs(
   paths: string | string[],
   options = { recursive: true }
 ): AsyncIterableIterator<FsEvent> {
-  return new FsEvents(Array.isArray(paths) ? paths : [paths], options);
+  return new FsWatcher(Array.isArray(paths) ? paths : [paths], options);
 }

cli/js/tests/fs_events_test.ts

@@ -3,10 +3,10 @@ import { unitTest, assert } from "./test_util.ts";
 
 // TODO(ry) Add more tests to specify format.
 
-unitTest({ perms: { read: false } }, function fsEventsPermissions() {
+unitTest({ perms: { read: false } }, function watchFsPermissions() {
   let thrown = false;
   try {
-    Deno.fsEvents(".");
+    Deno.watchFs(".");
   } catch (err) {
     assert(err instanceof Deno.errors.PermissionDenied);
     thrown = true;
@@ -14,10 +14,10 @@ unitTest({ perms: { read: false } }, function fsEventsPermissions() {
   assert(thrown);
 });
 
-unitTest({ perms: { read: true } }, function fsEventsInvalidPath() {
+unitTest({ perms: { read: true } }, function watchFsInvalidPath() {
   let thrown = false;
   try {
-    Deno.fsEvents("non-existant.file");
+    Deno.watchFs("non-existant.file");
   } catch (err) {
     console.error(err);
     if (Deno.build.os === "win") {
@@ -47,9 +47,9 @@ async function getTwoEvents(
 
 unitTest(
   { perms: { read: true, write: true } },
-  async function fsEventsBasic(): Promise<void> {
+  async function watchFsBasic(): Promise<void> {
     const testDir = await Deno.makeTempDir();
-    const iter = Deno.fsEvents(testDir);
+    const iter = Deno.watchFs(testDir);
 
     // Asynchornously capture two fs events.
     const eventsPromise = getTwoEvents(iter);

std/manual.md

@@ -470,8 +470,8 @@ The above for-await loop exits after 5 seconds when sig.dispose() is called.
 To poll for file system events:
 
 ```ts
-const iter = Deno.fsEvents("/");
+const watcher = Deno.watchFs("/");
-for await (const event of iter) {
+for await (const event of watcher) {
   console.log(">>>> event", event);
   // { kind: "create", paths: [ "/foo.txt" ] }
 }