feat: Start warning on each use of a deprecated API

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) {

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,
@@ -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,25 +231,29 @@ 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();
 }
 
 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));
   }
 }
 
 function writeAllSync(w, arr) {
+  internals.warnOnDeprecatedApi("Deno.writeAllSync()", (new Error()).stack);
   let nwritten = 0;
   while (nwritten < arr.length) {
     nwritten += w.writeSync(TypedArrayPrototypeSubarray(arr, nwritten));

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 });
   }

runtime/js/40_http.js

@@ -1,12 +1,13 @@
 // 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();
 
 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);
 }

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,

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,

runtime/js/99_main.js

@@ -8,7 +8,9 @@ const ops = core.ops;
 const {
   ArrayPrototypeFilter,
   ArrayPrototypeIncludes,
+  ArrayPrototypeJoin,
   ArrayPrototypeMap,
+  ArrayPrototypeShift,
   DateNow,
   Error,
   ErrorPrototype,
@@ -23,6 +25,8 @@ const {
   ObjectValues,
   PromisePrototypeThen,
   PromiseResolve,
+  SafeSet,
+  StringPrototypeSplit,
   Symbol,
   SymbolIterator,
   TypeError,
@@ -89,6 +93,61 @@ ObjectDefineProperties(Symbol, {
 let windowIsClosing = false;
 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) {
+    // 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();
+  }
+
+  ALREADY_WARNED_DEPRECATED.add(apiName + stack);
+  console.log(
+    "%cWarning",
+    "color: yellow; font-weight: bold;",
+  );
+  console.log(
+    `%c\u251c Use of deprecated API "${apiName}".`,
+    "color: yellow;",
+  );
+  console.log("%c\u2502", "color: yellow;");
+  console.log(
+    "%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() {
   if (!windowIsClosing) {
     windowIsClosing = true;
@@ -432,7 +491,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,