From 21969fa8f57f698cdc59c2ef655068ff59fbb9b6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bartek=20Iwa=C5=84czuk?= <biwanczuk@gmail.com>
Date: Sun, 14 Jan 2024 23:48:45 +0100
Subject: [PATCH 01/12] feat: Start warning on each use of a deprecated API

---
 ext/io/12_io.js            |  7 ++++++-
 runtime/js/13_buffer.js    |  4 +++-
 runtime/js/40_fs_events.js |  6 +++++-
 runtime/js/40_http.js      |  3 ++-
 runtime/js/40_process.js   |  1 +
 runtime/js/90_deno_ns.js   |  7 +++++--
 runtime/js/99_main.js      | 23 ++++++++++++++++++++++-
 7 files changed, 44 insertions(+), 7 deletions(-)

diff --git a/ext/io/12_io.js b/ext/io/12_io.js
index d9b91a9470163..ef27747a17e31 100644
--- a/ext/io/12_io.js
+++ b/ext/io/12_io.js
@@ -4,7 +4,7 @@
 // Documentation liberally lifted from them too.
 // Thank you! We love Go! <3
 
-import { core, primordials } from "ext:core/mod.js";
+import { core, internals, primordials } from "ext:core/mod.js";
 const {
   op_stdin_set_raw,
 } = core.ensureFastOps(true);
@@ -39,6 +39,7 @@ async function copy(
   dst,
   options,
 ) {
+  internals.warnOnDeprecatedApi("Deno.copy()", (new Error()).stack);
   let n = 0;
   const bufSize = options?.bufSize ?? DEFAULT_BUFFER_SIZE;
   const b = new Uint8Array(bufSize);
@@ -64,6 +65,7 @@ async function* iter(
   r,
   options,
 ) {
+  internals.warnOnDeprecatedApi("Deno.iter()", (new Error()).stack);
   const bufSize = options?.bufSize ?? DEFAULT_BUFFER_SIZE;
   const b = new Uint8Array(bufSize);
   while (true) {
@@ -80,6 +82,7 @@ function* iterSync(
   r,
   options,
 ) {
+  internals.warnOnDeprecatedApi("Deno.iterSync()", (new Error()).stack);
   const bufSize = options?.bufSize ?? DEFAULT_BUFFER_SIZE;
   const b = new Uint8Array(bufSize);
   while (true) {
@@ -115,6 +118,7 @@ function write(rid, data) {
 const READ_PER_ITER = 64 * 1024; // 64kb
 
 async function readAll(r) {
+  internals.warnOnDeprecatedApi("Deno.readAll()", (new Error()).stack);
   const buffers = [];
 
   while (true) {
@@ -131,6 +135,7 @@ async function readAll(r) {
 }
 
 function readAllSync(r) {
+  internals.warnOnDeprecatedApi("Deno.readAllSync()", (new Error()).stack);
   const buffers = [];
 
   while (true) {
diff --git a/runtime/js/13_buffer.js b/runtime/js/13_buffer.js
index 36d979e75aade..53635fdb3cb7c 100644
--- a/runtime/js/13_buffer.js
+++ b/runtime/js/13_buffer.js
@@ -4,7 +4,7 @@
 // Copyright 2009 The Go Authors. All rights reserved. BSD license.
 // https://github.com/golang/go/blob/master/LICENSE
 
-import { primordials } from "ext:core/mod.js";
+import { internals, primordials } from "ext:core/mod.js";
 const {
   ArrayBufferPrototypeGetByteLength,
   TypedArrayPrototypeSubarray,
@@ -242,6 +242,7 @@ function readAllSync(r) {
 }
 
 async function writeAll(w, arr) {
+  internals.warnOnDeprecatedApi("Deno.writeAll()", (new Error()).stack);
   let nwritten = 0;
   while (nwritten < arr.length) {
     nwritten += await w.write(TypedArrayPrototypeSubarray(arr, nwritten));
@@ -249,6 +250,7 @@ async function writeAll(w, arr) {
 }
 
 function writeAllSync(w, arr) {
+  internals.warnOnDeprecatedApi("Deno.writeAllSync()", (new Error()).stack);
   let nwritten = 0;
   while (nwritten < arr.length) {
     nwritten += w.writeSync(TypedArrayPrototypeSubarray(arr, nwritten));
diff --git a/runtime/js/40_fs_events.js b/runtime/js/40_fs_events.js
index 13cacc36be394..4e11af62844c3 100644
--- a/runtime/js/40_fs_events.js
+++ b/runtime/js/40_fs_events.js
@@ -1,6 +1,6 @@
 // Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
 
-import { core, primordials } from "ext:core/mod.js";
+import { core, internals, primordials } from "ext:core/mod.js";
 const {
   BadResourcePrototype,
   InterruptedPrototype,
@@ -49,6 +49,10 @@ 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);
     return PromiseResolve({ value, done: true });
   }
diff --git a/runtime/js/40_http.js b/runtime/js/40_http.js
index d38caa55dbb07..b44be86b06b1a 100644
--- a/runtime/js/40_http.js
+++ b/runtime/js/40_http.js
@@ -1,5 +1,5 @@
 // Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
-import { core } from "ext:core/mod.js";
+import { core, internals } from "ext:core/mod.js";
 const {
   op_http_start,
 } = core.ensureFastOps();
@@ -7,6 +7,7 @@ const {
 import { HttpConn } from "ext:deno_http/01_http.js";
 
 function serveHttp(conn) {
+  internals.warnOnDeprecatedApi("Deno.serveHttp()", (new Error()).stack);
   const rid = op_http_start(conn.rid);
   return new HttpConn(rid, conn.remoteAddr, conn.localAddr);
 }
diff --git a/runtime/js/40_process.js b/runtime/js/40_process.js
index c90f38664d68c..9fbd5150cc379 100644
--- a/runtime/js/40_process.js
+++ b/runtime/js/40_process.js
@@ -140,6 +140,7 @@ function run({
       ...new SafeArrayIterator(ArrayPrototypeSlice(cmd, 1)),
     ];
   }
+  internals.warnOnDeprecatedApi("Deno.run()", (new Error()).stack);
   const res = opRun({
     cmd: ArrayPrototypeMap(cmd, String),
     cwd,
diff --git a/runtime/js/90_deno_ns.js b/runtime/js/90_deno_ns.js
index e196fd1040e99..ea427f0f327f3 100644
--- a/runtime/js/90_deno_ns.js
+++ b/runtime/js/90_deno_ns.js
@@ -1,6 +1,6 @@
 // Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
 
-import { core } from "ext:core/mod.js";
+import { core, internals } from "ext:core/mod.js";
 const {
   op_net_listen_udp,
   op_net_listen_unixpacket,
@@ -31,7 +31,10 @@ import * as kv from "ext:deno_kv/01_db.ts";
 import * as cron from "ext:deno_cron/01_cron.ts";
 
 const denoNs = {
-  metrics: core.metrics,
+  metrics: () => {
+    internals.warnOnDeprecatedApi("Deno.metrics()", (new Error()).stack);
+    return core.metrics();
+  },
   Process: process.Process,
   run: process.run,
   isatty: tty.isatty,
diff --git a/runtime/js/99_main.js b/runtime/js/99_main.js
index 6c5ca3b590490..2eae2d586d8d9 100644
--- a/runtime/js/99_main.js
+++ b/runtime/js/99_main.js
@@ -24,6 +24,7 @@ const {
   PromisePrototypeThen,
   PromiseResolve,
   Symbol,
+  SafeSet,
   SymbolIterator,
   TypeError,
 } = primordials;
@@ -89,6 +90,26 @@ ObjectDefineProperties(Symbol, {
 let windowIsClosing = false;
 let globalThis_;
 
+const ALREADY_WARNED_DEPRECATED = new SafeSet();
+
+function warnOnDeprecatedApi(apiName, stack) {
+  const stackLines = stack.split("\n");
+  stackLines.shift();
+  const stackString = stackLines.join("\n");
+
+  if (ALREADY_WARNED_DEPRECATED.has(apiName + stackString)) {
+    return;
+  }
+
+  ALREADY_WARNED_DEPRECATED.add(apiName + stackString);
+  console.log(
+    "%cWarning %cUse of deprecated API `" + apiName +
+      "`. This API will be removed in Deno 2.\n" + stackString,
+    "color: yellow; font-weight: bold;",
+    "color: yellow;",
+  );
+}
+
 function windowClose() {
   if (!windowIsClosing) {
     windowIsClosing = true;
@@ -432,7 +453,7 @@ function exposeUnstableFeaturesForWindowOrWorkerGlobalScope(options) {
 // FIXME(bartlomieju): temporarily add whole `Deno.core` to
 // `Deno[Deno.internal]` namespace. It should be removed and only necessary
 // methods should be left there.
-ObjectAssign(internals, { core });
+ObjectAssign(internals, { core, warnOnDeprecatedApi });
 const internalSymbol = Symbol("Deno.internal");
 const finalDenoNs = {
   internal: internalSymbol,

From 4332d9f78f9ca4d0a0c040df2702882df4cce8e6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bartek=20Iwa=C5=84czuk?= <biwanczuk@gmail.com>
Date: Sun, 14 Jan 2024 23:59:53 +0100
Subject: [PATCH 02/12] lint

---
 runtime/js/99_main.js | 11 +++++++----
 1 file changed, 7 insertions(+), 4 deletions(-)

diff --git a/runtime/js/99_main.js b/runtime/js/99_main.js
index 2eae2d586d8d9..0b0d462a96a6e 100644
--- a/runtime/js/99_main.js
+++ b/runtime/js/99_main.js
@@ -8,7 +8,9 @@ const ops = core.ops;
 const {
   ArrayPrototypeFilter,
   ArrayPrototypeIncludes,
+  ArrayPrototypeJoin,
   ArrayPrototypeMap,
+  ArrayPrototypeShift,
   DateNow,
   Error,
   ErrorPrototype,
@@ -23,8 +25,9 @@ const {
   ObjectValues,
   PromisePrototypeThen,
   PromiseResolve,
-  Symbol,
   SafeSet,
+  StringPrototypeSplit,
+  Symbol,
   SymbolIterator,
   TypeError,
 } = primordials;
@@ -93,9 +96,9 @@ let globalThis_;
 const ALREADY_WARNED_DEPRECATED = new SafeSet();
 
 function warnOnDeprecatedApi(apiName, stack) {
-  const stackLines = stack.split("\n");
-  stackLines.shift();
-  const stackString = stackLines.join("\n");
+  const stackLines = StringPrototypeSplit(stack, "\n");
+  ArrayPrototypeShift(stackLines);
+  const stackString = ArrayPrototypeJoin(stackLines, "\n");
 
   if (ALREADY_WARNED_DEPRECATED.has(apiName + stackString)) {
     return;

From 663da9d3ed6cfa6a996b44b528d09d046571fb7c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bartek=20Iwa=C5=84czuk?= <biwanczuk@gmail.com>
Date: Mon, 15 Jan 2024 00:02:33 +0100
Subject: [PATCH 03/12] change where deprecation happens

---
 ext/io/12_io.js         | 2 --
 runtime/js/13_buffer.js | 3 +++
 2 files changed, 3 insertions(+), 2 deletions(-)

diff --git a/ext/io/12_io.js b/ext/io/12_io.js
index ef27747a17e31..2b3423b2a68ec 100644
--- a/ext/io/12_io.js
+++ b/ext/io/12_io.js
@@ -118,7 +118,6 @@ function write(rid, data) {
 const READ_PER_ITER = 64 * 1024; // 64kb
 
 async function readAll(r) {
-  internals.warnOnDeprecatedApi("Deno.readAll()", (new Error()).stack);
   const buffers = [];
 
   while (true) {
@@ -135,7 +134,6 @@ async function readAll(r) {
 }
 
 function readAllSync(r) {
-  internals.warnOnDeprecatedApi("Deno.readAllSync()", (new Error()).stack);
   const buffers = [];
 
   while (true) {
diff --git a/runtime/js/13_buffer.js b/runtime/js/13_buffer.js
index 53635fdb3cb7c..f6561c9aa98a8 100644
--- a/runtime/js/13_buffer.js
+++ b/runtime/js/13_buffer.js
@@ -45,6 +45,7 @@ class Buffer {
   #off = 0; // read at buf[off], write at buf[buf.byteLength]
 
   constructor(ab) {
+    internals.warnOnDeprecatedApi("new Deno.Buffer()", (new Error()).stack);
     if (ab == null) {
       this.#buf = new Uint8Array(0);
       return;
@@ -230,12 +231,14 @@ class Buffer {
 }
 
 async function readAll(r) {
+  internals.warnOnDeprecatedApi("Deno.readAll()", (new Error()).stack);
   const buf = new Buffer();
   await buf.readFrom(r);
   return buf.bytes();
 }
 
 function readAllSync(r) {
+  internals.warnOnDeprecatedApi("Deno.readAllSync()", (new Error()).stack);
   const buf = new Buffer();
   buf.readFromSync(r);
   return buf.bytes();

From e4d9f12bb9495165f08aaf9c07a3e0b04b4aad31 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bartek=20Iwa=C5=84czuk?= <biwanczuk@gmail.com>
Date: Mon, 15 Jan 2024 03:44:12 +0100
Subject: [PATCH 04/12] improve the warning

---
 runtime/js/99_main.js | 14 ++++++++++++--
 1 file changed, 12 insertions(+), 2 deletions(-)

diff --git a/runtime/js/99_main.js b/runtime/js/99_main.js
index 0b0d462a96a6e..18cedaef37c5e 100644
--- a/runtime/js/99_main.js
+++ b/runtime/js/99_main.js
@@ -106,11 +106,21 @@ function warnOnDeprecatedApi(apiName, stack) {
 
   ALREADY_WARNED_DEPRECATED.add(apiName + stackString);
   console.log(
-    "%cWarning %cUse of deprecated API `" + apiName +
-      "`. This API will be removed in Deno 2.\n" + stackString,
+    `%cWarning %cUse of deprecated API "${apiName}".`,
     "color: yellow; font-weight: bold;",
     "color: yellow;",
   );
+  console.log();
+  console.log(
+    "%cThis API will be removed in Deno 2.0. Make sure to upgrade to a stable API before then.",
+    "color: yellow;",
+  );
+  // TODO(bartlomieju): add API suggestion to what to migrate to
+  console.log();
+  console.log(
+    "%cThis API was called from:\n" + stackString + "\n",
+    "color: yellow;",
+  );
 }
 
 function windowClose() {

From 7a8e0c809c19c075b92d1b48671c30ebf7c212d0 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bartek=20Iwa=C5=84czuk?= <biwanczuk@gmail.com>
Date: Mon, 15 Jan 2024 14:25:08 +0100
Subject: [PATCH 05/12] improve message further

---
 runtime/js/99_main.js | 18 +++++++++++++++++-
 1 file changed, 17 insertions(+), 1 deletion(-)

diff --git a/runtime/js/99_main.js b/runtime/js/99_main.js
index 18cedaef37c5e..877046d3ba846 100644
--- a/runtime/js/99_main.js
+++ b/runtime/js/99_main.js
@@ -98,6 +98,22 @@ const ALREADY_WARNED_DEPRECATED = new SafeSet();
 function warnOnDeprecatedApi(apiName, stack) {
   const stackLines = StringPrototypeSplit(stack, "\n");
   ArrayPrototypeShift(stackLines);
+  while (true) {
+    // Filter out internal frames at the top of the stack - they are not useful
+    // to the user.
+    if (stackLines[0].includes("(ext:") || stackLines[0].includes("(node:")) {
+      stackLines.shift();
+    } else {
+      break;
+    }
+  }
+  // Now remove the last frame if it's coming from "ext:core" - this is most likely
+  // event loop tick or promise handler calling a user function - again not
+  // useful to the user.
+  if (stackLines[stackLines.length - 1].includes("(ext:core/")) {
+    stackLines.pop();
+  }
+
   const stackString = ArrayPrototypeJoin(stackLines, "\n");
 
   if (ALREADY_WARNED_DEPRECATED.has(apiName + stackString)) {
@@ -118,7 +134,7 @@ function warnOnDeprecatedApi(apiName, stack) {
   // TODO(bartlomieju): add API suggestion to what to migrate to
   console.log();
   console.log(
-    "%cThis API was called from:\n" + stackString + "\n",
+    "%cStack trace:\n" + stackString + "\n",
     "color: yellow;",
   );
 }

From f4d7b93d58df53576eda684224b75e2a71a7d184 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bartek=20Iwa=C5=84czuk?= <biwanczuk@gmail.com>
Date: Mon, 15 Jan 2024 17:14:18 +0100
Subject: [PATCH 06/12] make storage more efficient, eye-candy

---
 runtime/js/99_main.js | 37 +++++++++++++++++++++++--------------
 1 file changed, 23 insertions(+), 14 deletions(-)

diff --git a/runtime/js/99_main.js b/runtime/js/99_main.js
index 877046d3ba846..b4605225245bd 100644
--- a/runtime/js/99_main.js
+++ b/runtime/js/99_main.js
@@ -96,6 +96,12 @@ let globalThis_;
 const ALREADY_WARNED_DEPRECATED = new SafeSet();
 
 function warnOnDeprecatedApi(apiName, stack) {
+  if (ALREADY_WARNED_DEPRECATED.has(apiName + stack)) {
+    return;
+  }
+
+  // If we haven't warned yet, let's do some processing of the stack trace
+  // to make it more useful.
   const stackLines = StringPrototypeSplit(stack, "\n");
   ArrayPrototypeShift(stackLines);
   while (true) {
@@ -114,29 +120,32 @@ function warnOnDeprecatedApi(apiName, stack) {
     stackLines.pop();
   }
 
-  const stackString = ArrayPrototypeJoin(stackLines, "\n");
-
-  if (ALREADY_WARNED_DEPRECATED.has(apiName + stackString)) {
-    return;
-  }
-
-  ALREADY_WARNED_DEPRECATED.add(apiName + stackString);
+  ALREADY_WARNED_DEPRECATED.add(apiName + stack);
   console.log(
-    `%cWarning %cUse of deprecated API "${apiName}".`,
+    "%cWarning",
     "color: yellow; font-weight: bold;",
-    "color: yellow;",
   );
-  console.log();
   console.log(
-    "%cThis API will be removed in Deno 2.0. Make sure to upgrade to a stable API before then.",
+    `%c\u251c Use of deprecated API "${apiName}".`,
     "color: yellow;",
   );
-  // TODO(bartlomieju): add API suggestion to what to migrate to
-  console.log();
+  console.log("%c\u2502", "color: yellow;");
   console.log(
-    "%cStack trace:\n" + stackString + "\n",
+    "%c\u251c This API will be removed in Deno 2.0. Make sure to upgrade to a stable API before then.",
     "color: yellow;",
   );
+  // TODO(bartlomieju): add API suggestion to what to migrate to
+  console.log("%c\u2502", "color: yellow;");
+  console.log("%c\u2514 Stack trace:", "color: yellow;");
+  for (let i = 0; i < stackLines.length; i++) {
+    console.log(
+      `%c  ${i == stackLines.length - 1 ? "\u2514" : "\u251c"}\u2500 ${
+        stackLines[i].trim()
+      }`,
+      "color: yellow;",
+    );
+  }
+  console.log();
 }
 
 function windowClose() {

From 482b64ab234e02a1693bbdce82c12c9857911fac Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bartek=20Iwa=C5=84czuk?= <biwanczuk@gmail.com>
Date: Sun, 21 Jan 2024 22:08:28 +0100
Subject: [PATCH 07/12] lint

---
 runtime/js/99_main.js | 1 -
 1 file changed, 1 deletion(-)

diff --git a/runtime/js/99_main.js b/runtime/js/99_main.js
index 9a1322f00b93d..54a4406b2e2e0 100644
--- a/runtime/js/99_main.js
+++ b/runtime/js/99_main.js
@@ -8,7 +8,6 @@ const ops = core.ops;
 const {
   ArrayPrototypeFilter,
   ArrayPrototypeIncludes,
-  ArrayPrototypeJoin,
   ArrayPrototypeMap,
   ArrayPrototypePop,
   ArrayPrototypeShift,

From cf1876298bd6cd380d105807f01f30f41c1be250 Mon Sep 17 00:00:00 2001
From: Asher Gomez <ashersaupingomez@gmail.com>
Date: Wed, 24 Jan 2024 09:04:47 +1100
Subject: [PATCH 08/12] tweaks

---
 cli/tsc/dts/lib.deno.ns.d.ts | 4 ++--
 ext/io/12_io.js              | 7 +++++--
 2 files changed, 7 insertions(+), 4 deletions(-)

diff --git a/cli/tsc/dts/lib.deno.ns.d.ts b/cli/tsc/dts/lib.deno.ns.d.ts
index f17f9088dc58e..37e76445622e5 100644
--- a/cli/tsc/dts/lib.deno.ns.d.ts
+++ b/cli/tsc/dts/lib.deno.ns.d.ts
@@ -1801,8 +1801,8 @@ declare namespace Deno {
    * an error occurs. It resolves to the number of bytes copied or rejects with
    * the first error encountered while copying.
    *
-   * @deprecated Use {@linkcode ReadableStream.pipeTo} instead.
-   * {@linkcode Deno.copy} will be removed in v2.0.0.
+   * @deprecated Use {@linkcode https://deno.land/std/io/copy.ts?s=copy | copy}
+   * instead. {@linkcode Deno.copy} will be removed in v2.0.0.
    *
    * @category I/O
    *
diff --git a/ext/io/12_io.js b/ext/io/12_io.js
index 2b3423b2a68ec..89c4488b9d75f 100644
--- a/ext/io/12_io.js
+++ b/ext/io/12_io.js
@@ -3,7 +3,6 @@
 // Interfaces 100% copied from Go.
 // Documentation liberally lifted from them too.
 // Thank you! We love Go! <3
-
 import { core, internals, primordials } from "ext:core/mod.js";
 const {
   op_stdin_set_raw,
@@ -39,7 +38,11 @@ async function copy(
   dst,
   options,
 ) {
-  internals.warnOnDeprecatedApi("Deno.copy()", (new Error()).stack);
+  internals.warnOnDeprecatedApi(
+    "Deno.copy()",
+    new Error().stack,
+    "Use `copy()` from `https://deno.land/std/io/copy.ts` instead.",
+  );
   let n = 0;
   const bufSize = options?.bufSize ?? DEFAULT_BUFFER_SIZE;
   const b = new Uint8Array(bufSize);

From 1f0c66e7295fd471170e8c8bc89501643fd5772f Mon Sep 17 00:00:00 2001
From: Asher Gomez <ashersaupingomez@gmail.com>
Date: Wed, 24 Jan 2024 09:23:37 +1100
Subject: [PATCH 09/12] further work

---
 cli/tsc/dts/lib.deno.ns.d.ts | 34 +++++++++++++++++-----------------
 ext/io/12_io.js              | 12 ++++++++++--
 runtime/js/13_buffer.js      | 30 +++++++++++++++++++++++++-----
 runtime/js/40_fs_events.js   |  2 +-
 runtime/js/99_main.js        | 10 ++++++----
 5 files changed, 59 insertions(+), 29 deletions(-)

diff --git a/cli/tsc/dts/lib.deno.ns.d.ts b/cli/tsc/dts/lib.deno.ns.d.ts
index 37e76445622e5..30804ca3eeabd 100644
--- a/cli/tsc/dts/lib.deno.ns.d.ts
+++ b/cli/tsc/dts/lib.deno.ns.d.ts
@@ -1819,8 +1819,8 @@ declare namespace Deno {
   /**
    * Turns a Reader, `r`, into an async iterator.
    *
-   * @deprecated Use {@linkcode ReadableStream} instead. {@linkcode Deno.iter}
-   * will be removed in v2.0.0.
+   * @deprecated Use {@linkcode ReadableStreamDefaultReader} instead.
+   * {@linkcode Deno.iter} will be removed in v2.0.0.
    *
    * @category I/O
    */
@@ -1832,7 +1832,7 @@ declare namespace Deno {
   /**
    * Turns a ReaderSync, `r`, into an iterator.
    *
-   * @deprecated Use {@linkcode ReadableStream} instead.
+   * @deprecated Use {@linkcode ReadableStreamDefaultReader} instead.
    * {@linkcode Deno.iterSync} will be removed in v2.0.0.
    *
    * @category I/O
@@ -2699,9 +2699,9 @@ declare namespace Deno {
   /**
    * A variable-sized buffer of bytes with `read()` and `write()` methods.
    *
-   * @deprecated Use the
-   * [Web Streams API]{@link https://developer.mozilla.org/en-US/docs/Web/API/Streams_API}
-   * instead. {@linkcode Deno.Buffer} will be removed in v2.0.0.
+   * @deprecated Use
+   * {@linkcode https://deno.land/std/io/buffer.ts?s=Buffer | Buffer} instead.
+   * {@linkcode Deno.Buffer} will be removed in v2.0.0.
    *
    * @category I/O
    */
@@ -2775,8 +2775,8 @@ declare namespace Deno {
    * Read Reader `r` until EOF (`null`) and resolve to the content as
    * Uint8Array`.
    *
-   * @deprecated Use {@linkcode ReadableStream} and
-   * [`toArrayBuffer()`](https://deno.land/std/streams/to_array_buffer.ts?s=toArrayBuffer)
+   * @deprecated Use
+   * {@linkcode https://deno.land/std@/io/read_all.ts?s=readAll | readAll}
    * instead. {@linkcode Deno.readAll} will be removed in v2.0.0.
    *
    * @category I/O
@@ -2787,8 +2787,8 @@ declare namespace Deno {
    * Synchronously reads Reader `r` until EOF (`null`) and returns the content
    * as `Uint8Array`.
    *
-   * @deprecated Use {@linkcode ReadableStream} and
-   * [`toArrayBuffer()`](https://deno.land/std/streams/to_array_buffer.ts?s=toArrayBuffer)
+   * @deprecated Use
+   * {@linkcode https://deno.land/std@/io/read_all.ts?s=readAllSync | readAllSync}
    * instead. {@linkcode Deno.readAllSync} will be removed in v2.0.0.
    *
    * @category I/O
@@ -2798,9 +2798,9 @@ declare namespace Deno {
   /**
    * Write all the content of the array buffer (`arr`) to the writer (`w`).
    *
-   * @deprecated Use {@linkcode WritableStream}, {@linkcode ReadableStream.from}
-   * and {@linkcode ReadableStream.pipeTo} instead. {@linkcode Deno.writeAll}
-   * will be removed in v2.0.0.
+   * @deprecated Use
+   * {@linkcode https://deno.land/std/io/write_all.ts?s=writeAll | writeAll}
+   * instead. {@linkcode Deno.writeAll} will be removed in v2.0.0.
    *
    * @category I/O
    */
@@ -2810,9 +2810,9 @@ declare namespace Deno {
    * Synchronously write all the content of the array buffer (`arr`) to the
    * writer (`w`).
    *
-   * @deprecated Use {@linkcode WritableStream}, {@linkcode ReadableStream.from}
-   * and {@linkcode ReadableStream.pipeTo} instead.
-   * {@linkcode Deno.writeAllSync} will be removed in v2.0.0.
+   * @deprecated Use
+   * {@linkcode https://deno.land/std/io/write_all.ts?s=writeAllSync | writeAllSync}
+   * instead. {@linkcode Deno.writeAllSync} will be removed in v2.0.0.
    *
    * @category I/O
    */
@@ -3882,7 +3882,7 @@ declare namespace Deno {
     /**
      * Stops watching the file system and closes the watcher resource.
      *
-     * @deprecated Will be removed in v2.0.0.
+     * @deprecated {@linkcode Deno.FsWatcher.return} will be removed in v2.0.0.
      */
     return?(value?: any): Promise<IteratorResult<FsEvent>>;
     [Symbol.asyncIterator](): AsyncIterableIterator<FsEvent>;
diff --git a/ext/io/12_io.js b/ext/io/12_io.js
index 89c4488b9d75f..33d358bfb60a2 100644
--- a/ext/io/12_io.js
+++ b/ext/io/12_io.js
@@ -68,7 +68,11 @@ async function* iter(
   r,
   options,
 ) {
-  internals.warnOnDeprecatedApi("Deno.iter()", (new Error()).stack);
+  internals.warnOnDeprecatedApi(
+    "Deno.iter()",
+    new Error().stack,
+    "Use `ReadableStreamDefaultReader` instead.",
+  );
   const bufSize = options?.bufSize ?? DEFAULT_BUFFER_SIZE;
   const b = new Uint8Array(bufSize);
   while (true) {
@@ -85,7 +89,11 @@ function* iterSync(
   r,
   options,
 ) {
-  internals.warnOnDeprecatedApi("Deno.iterSync()", (new Error()).stack);
+  internals.warnOnDeprecatedApi(
+    "Deno.iterSync()",
+    new Error().stack,
+    "Use `ReadableStreamDefaultReader` instead.",
+  );
   const bufSize = options?.bufSize ?? DEFAULT_BUFFER_SIZE;
   const b = new Uint8Array(bufSize);
   while (true) {
diff --git a/runtime/js/13_buffer.js b/runtime/js/13_buffer.js
index f6561c9aa98a8..cac1a66944b61 100644
--- a/runtime/js/13_buffer.js
+++ b/runtime/js/13_buffer.js
@@ -45,7 +45,11 @@ class Buffer {
   #off = 0; // read at buf[off], write at buf[buf.byteLength]
 
   constructor(ab) {
-    internals.warnOnDeprecatedApi("new Deno.Buffer()", (new Error()).stack);
+    internals.warnOnDeprecatedApi(
+      "new Deno.Buffer()",
+      new Error().stack,
+      "Use `Buffer` from `https://deno.land/std/io/buffer.ts` instead.",
+    );
     if (ab == null) {
       this.#buf = new Uint8Array(0);
       return;
@@ -231,21 +235,33 @@ class Buffer {
 }
 
 async function readAll(r) {
-  internals.warnOnDeprecatedApi("Deno.readAll()", (new Error()).stack);
+  internals.warnOnDeprecatedApi(
+    "Deno.readAll()",
+    new Error().stack,
+    "Use `readAll()` from `https://deno.land/std/io/read_all.ts` instead.",
+  );
   const buf = new Buffer();
   await buf.readFrom(r);
   return buf.bytes();
 }
 
 function readAllSync(r) {
-  internals.warnOnDeprecatedApi("Deno.readAllSync()", (new Error()).stack);
+  internals.warnOnDeprecatedApi(
+    "Deno.readAllSync()",
+    new Error().stack,
+    "Use `readAllSync()` from `https://deno.land/std/io/read_all.ts` instead.",
+  );
   const buf = new Buffer();
   buf.readFromSync(r);
   return buf.bytes();
 }
 
 async function writeAll(w, arr) {
-  internals.warnOnDeprecatedApi("Deno.writeAll()", (new Error()).stack);
+  internals.warnOnDeprecatedApi(
+    "Deno.writeAll()",
+    new Error().stack,
+    "Use `writeAll()` from `https://deno.land/std/io/write_all.ts` instead.",
+  );
   let nwritten = 0;
   while (nwritten < arr.length) {
     nwritten += await w.write(TypedArrayPrototypeSubarray(arr, nwritten));
@@ -253,7 +269,11 @@ async function writeAll(w, arr) {
 }
 
 function writeAllSync(w, arr) {
-  internals.warnOnDeprecatedApi("Deno.writeAllSync()", (new Error()).stack);
+  internals.warnOnDeprecatedApi(
+    "Deno.writeAllSync()",
+    new Error().stack,
+    "Use `writeAllSync()` from `https://deno.land/std/io/write_all.ts` instead.",
+  );
   let nwritten = 0;
   while (nwritten < arr.length) {
     nwritten += w.writeSync(TypedArrayPrototypeSubarray(arr, nwritten));
diff --git a/runtime/js/40_fs_events.js b/runtime/js/40_fs_events.js
index 4e11af62844c3..0bc61433532b4 100644
--- a/runtime/js/40_fs_events.js
+++ b/runtime/js/40_fs_events.js
@@ -51,7 +51,7 @@ class FsWatcher {
   return(value) {
     internals.warnOnDeprecatedApi(
       "Deno.FsWatcher.return()",
-      (new Error()).stack,
+      new Error().stack,
     );
     core.close(this.rid);
     return PromiseResolve({ value, done: true });
diff --git a/runtime/js/99_main.js b/runtime/js/99_main.js
index 54a4406b2e2e0..6eac215516a6a 100644
--- a/runtime/js/99_main.js
+++ b/runtime/js/99_main.js
@@ -153,10 +153,12 @@ function warnOnDeprecatedApi(apiName, stack, suggestion) {
     "color: yellow;",
   );
   console.error("%c\u2502", "color: yellow;");
-  console.error(
-    `%c\u251c Suggestion: ${suggestion}`,
-    "color: yellow;",
-  );
+  if (suggestion) {
+    console.error(
+      `%c\u251c Suggestion: ${suggestion}`,
+      "color: yellow;",
+    );
+  }
   if (isFromRemoteDependency) {
     console.error("%c\u2502", "color: yellow;");
     console.error(

From 12e9ae2a1f3b7de74b7209bd7b81bf67149d1b79 Mon Sep 17 00:00:00 2001
From: Asher Gomez <ashersaupingomez@gmail.com>
Date: Wed, 24 Jan 2024 09:24:57 +1100
Subject: [PATCH 10/12] tweak

---
 runtime/js/90_deno_ns.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/runtime/js/90_deno_ns.js b/runtime/js/90_deno_ns.js
index 814f097271bba..84a745a14cfdf 100644
--- a/runtime/js/90_deno_ns.js
+++ b/runtime/js/90_deno_ns.js
@@ -33,7 +33,7 @@ import * as webgpuSurface from "ext:deno_webgpu/02_surface.js";
 
 const denoNs = {
   metrics: () => {
-    internals.warnOnDeprecatedApi("Deno.metrics()", (new Error()).stack);
+    internals.warnOnDeprecatedApi("Deno.metrics()", new Error().stack);
     return core.metrics();
   },
   Process: process.Process,

From 9c0f9771010a64411bbc12c83b1b4134ae5784ee Mon Sep 17 00:00:00 2001
From: Asher Gomez <ashersaupingomez@gmail.com>
Date: Wed, 24 Jan 2024 09:27:38 +1100
Subject: [PATCH 11/12] fix

---
 cli/tsc/dts/lib.deno.ns.d.ts | 4 ++--
 runtime/js/40_http.js        | 1 +
 2 files changed, 3 insertions(+), 2 deletions(-)

diff --git a/cli/tsc/dts/lib.deno.ns.d.ts b/cli/tsc/dts/lib.deno.ns.d.ts
index a893aa3669a0a..d37bcc076f634 100644
--- a/cli/tsc/dts/lib.deno.ns.d.ts
+++ b/cli/tsc/dts/lib.deno.ns.d.ts
@@ -2782,7 +2782,7 @@ declare namespace Deno {
    * Uint8Array`.
    *
    * @deprecated Use
-   * {@linkcode https://deno.land/std@/io/read_all.ts?s=readAll | readAll}
+   * {@linkcode https://deno.land/std/io/read_all.ts?s=readAll | readAll}
    * instead. {@linkcode Deno.readAll} will be removed in v2.0.0.
    *
    * @category I/O
@@ -2794,7 +2794,7 @@ declare namespace Deno {
    * as `Uint8Array`.
    *
    * @deprecated Use
-   * {@linkcode https://deno.land/std@/io/read_all.ts?s=readAllSync | readAllSync}
+   * {@linkcode https://deno.land/std/io/read_all.ts?s=readAllSync | readAllSync}
    * instead. {@linkcode Deno.readAllSync} will be removed in v2.0.0.
    *
    * @category I/O
diff --git a/runtime/js/40_http.js b/runtime/js/40_http.js
index 19b552934a51c..fcabf237bc0f0 100644
--- a/runtime/js/40_http.js
+++ b/runtime/js/40_http.js
@@ -11,6 +11,7 @@ function serveHttp(conn) {
     "Deno.serveHttp()",
     new Error().stack,
     "Use `Deno.serve()` instead.",
+  );
   const rid = op_http_start(conn.rid);
   return new HttpConn(rid, conn.remoteAddr, conn.localAddr);
 }

From 22126e9095b62398fe1724f36282be7cce3c4961 Mon Sep 17 00:00:00 2001
From: Asher Gomez <ashersaupingomez@gmail.com>
Date: Wed, 24 Jan 2024 11:43:31 +1100
Subject: [PATCH 12/12] revert

---
 cli/tsc/dts/lib.deno.ns.d.ts | 4 ++--
 ext/io/12_io.js              | 4 ++--
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/cli/tsc/dts/lib.deno.ns.d.ts b/cli/tsc/dts/lib.deno.ns.d.ts
index d37bcc076f634..a002237cf30a1 100644
--- a/cli/tsc/dts/lib.deno.ns.d.ts
+++ b/cli/tsc/dts/lib.deno.ns.d.ts
@@ -1818,7 +1818,7 @@ declare namespace Deno {
   /**
    * Turns a Reader, `r`, into an async iterator.
    *
-   * @deprecated Use {@linkcode ReadableStreamDefaultReader} instead.
+   * @deprecated Use {@linkcode ReadableStream} instead.
    * {@linkcode Deno.iter} will be removed in v2.0.0.
    *
    * @category I/O
@@ -1831,7 +1831,7 @@ declare namespace Deno {
   /**
    * Turns a ReaderSync, `r`, into an iterator.
    *
-   * @deprecated Use {@linkcode ReadableStreamDefaultReader} instead.
+   * @deprecated Use {@linkcode ReadableStream} instead.
    * {@linkcode Deno.iterSync} will be removed in v2.0.0.
    *
    * @category I/O
diff --git a/ext/io/12_io.js b/ext/io/12_io.js
index 33d358bfb60a2..f228fd70e9723 100644
--- a/ext/io/12_io.js
+++ b/ext/io/12_io.js
@@ -71,7 +71,7 @@ async function* iter(
   internals.warnOnDeprecatedApi(
     "Deno.iter()",
     new Error().stack,
-    "Use `ReadableStreamDefaultReader` instead.",
+    "Use `ReadableStream` instead.",
   );
   const bufSize = options?.bufSize ?? DEFAULT_BUFFER_SIZE;
   const b = new Uint8Array(bufSize);
@@ -92,7 +92,7 @@ function* iterSync(
   internals.warnOnDeprecatedApi(
     "Deno.iterSync()",
     new Error().stack,
-    "Use `ReadableStreamDefaultReader` instead.",
+    "Use `ReadableStream` instead.",
   );
   const bufSize = options?.bufSize ?? DEFAULT_BUFFER_SIZE;
   const b = new Uint8Array(bufSize);