feat: deprecate `Deno.FsWatcher.rid` (#22074)

For removal in Deno v2. I've also updated the deprecation of
`Deno.FsWatcher.return()`, which, to be clear, I'm not in favour of
deprecating. I mention this in #15499. Either way, it's safe to merge
this PR, then decide against the deprecation.

2 files changed, 15 insertions, 8 deletions

diff --git a/cli/tsc/dts/lib.deno.ns.d.ts b/cli/tsc/dts/lib.deno.ns.d.ts
index 9ec90a2d6..743152442 100644
--- a/cli/tsc/dts/lib.deno.ns.d.ts
+++ b/cli/tsc/dts/lib.deno.ns.d.ts
@@ -4084,14 +4084,19 @@ declare namespace Deno {
    * @category File System
    */
   export interface FsWatcher extends AsyncIterable<FsEvent>, Disposable {
-    /** The resource id. */
+    /**
+     * The resource id.
+     *
+     * @deprecated Use {@linkcode Deno.FsWatcher} instance methods instead.
+     * {@linkcode Deno.FsWatcher.rid} will be removed in Deno 2.0.
+     */
     readonly rid: number;
     /** Stops watching the file system and closes the watcher resource. */
     close(): void;
     /**
      * Stops watching the file system and closes the watcher resource.
      *
-     * @deprecated {@linkcode Deno.FsWatcher.return} will be removed in v2.0.0.
+     * @deprecated {@linkcode Deno.FsWatcher.return} will be removed in Deno 2.0.
      */
     return?(value?: any): Promise<IteratorResult<FsEvent>>;
     [Symbol.asyncIterator](): AsyncIterableIterator<FsEvent>;
diff --git a/runtime/js/40_fs_events.js b/runtime/js/40_fs_events.js
index 0bc614335..4c7050b9f 100644
--- a/runtime/js/40_fs_events.js
+++ b/runtime/js/40_fs_events.js
@@ -27,12 +27,17 @@ class FsWatcher {
   }
 
   get rid() {
+    internals.warnOnDeprecatedApi(
+      "Deno.FsWatcher.rid",
+      new Error().stack,
+      "Use `Deno.FsWatcher` instance methods instead.",
+    );
     return this.#rid;
   }
 
   async next() {
     try {
-      const value = await op_fs_events_poll(this.rid);
+      const value = await op_fs_events_poll(this.#rid);
       return value ? { value, done: false } : { value: undefined, done: true };
     } catch (error) {
       if (ObjectPrototypeIsPrototypeOf(BadResourcePrototype, error)) {
@@ -49,11 +54,8 @@ class FsWatcher {
   // TODO(kt3k): This is deprecated. Will be removed in v2.0.
   // See https://github.com/denoland/deno/issues/10577 for details
   return(value) {
-    internals.warnOnDeprecatedApi(
-      "Deno.FsWatcher.return()",
-      new Error().stack,
-    );
-    core.close(this.rid);
+    internals.warnOnDeprecatedApi("Deno.FsWatcher.return()", new Error().stack);
+    core.close(this.#rid);
     return PromiseResolve({ value, done: true });
   }