feat: print warning on use of deprecated API

internal/mod.ts

@@ -0,0 +1,9 @@
+// Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
+
+/**
+ * Internal utilities for the public API of the Deno Standard Library.
+ *
+ * Note: for internal use only.
+ *
+ * @module
+ */

internal/testdata/test.ts

@@ -0,0 +1,16 @@
+// Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
+import { warnDeprecatedApi } from "../warn_deprecated_api.ts";
+
+function fn() {
+  warnDeprecatedApi({
+    name: "fn()",
+    stack: new Error().stack!,
+    version: "1.0.0",
+    message: "Use `y` instead.",
+  });
+  console.log("Hello, world!");
+}
+
+for (let i = 0; i < 2; i++) {
+  fn();
+}

internal/warn_deprecated_api.ts

@@ -0,0 +1,47 @@
+// Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
+// This module is browser compatible.
+
+// deno-lint-ignore no-explicit-any
+const { Deno } = globalThis as any;
+
+const ALREADY_WARNED_DEPRECATED = new Set<string>();
+
+interface WarnDeprecatedApiConfig {
+  /** The name of the deprecated API. */
+  name: string;
+  /** The stack trace of the deprecated API. */
+  stack: string;
+  /** The version in which the API will be removed. */
+  version: string;
+  /** An optional message to print. */
+  message?: string;
+}
+
+/**
+ * Prints a warning message to the console for the given deprecated API.
+ *
+ * These warnings can be disabled by setting `NO_DEPRECATION_WARNINGS=1`
+ * in the current process.
+ */
+export function warnDeprecatedApi(config: WarnDeprecatedApiConfig) {
+  const variable = "NO_DEPRECATION_WARNINGS";
+  if (
+    Deno?.permissions.querySync({ name: "env", variable }).state ===
+      "granted" && Deno?.env.get(variable) === "1"
+  ) return;
+
+  // Remove the prepending "Error\n" from the stack output.
+  const stack = config.stack.slice(6);
+  const key = config.name + stack;
+
+  if (ALREADY_WARNED_DEPRECATED.has(key)) return;
+  ALREADY_WARNED_DEPRECATED.add(key);
+
+  console.log(
+    "%cWarning",
+    "color: yellow;",
+    `Use of deprecated API \`${config.name}\`. This API will be removed in ${config.version} of the Deno Standard Library.`,
+    config.message ?? "",
+    "\n" + stack,
+  );
+}

streams/read_all.ts

@@ -6,6 +6,7 @@ import {
   readAllSync as _readAllSync,
 } from "../io/read_all.ts";
 import type { Reader, ReaderSync } from "../io/types.ts";
+import { warnDeprecatedApi } from "../internal/warn_deprecated_api.ts";
 
 /**
  * Read {@linkcode Reader} `r` until EOF (`null`) and resolve to the content as
@@ -33,6 +34,12 @@ import type { Reader, ReaderSync } from "../io/types.ts";
  * @deprecated (will be removed in 0.214.0) Import from {@link https://deno.land/std/io/read_all.ts} instead.
  */
 export async function readAll(r: Reader): Promise<Uint8Array> {
+  warnDeprecatedApi({
+    name: "readAll()",
+    stack: new Error().stack!,
+    version: "0.214.0",
+    message: "Import from `https://deno.land/std/io/read_all.ts` instead.",
+  });
   return await _readAll(r);
 }
 
@@ -62,5 +69,11 @@ export async function readAll(r: Reader): Promise<Uint8Array> {
  * @deprecated (will be removed in 0.214.0) Import from {@link https://deno.land/std/io/read_all.ts} instead.
  */
 export function readAllSync(r: ReaderSync): Uint8Array {
+  warnDeprecatedApi({
+    name: "readAllSync()",
+    stack: new Error().stack!,
+    version: "0.214.0",
+    message: "Import from `https://deno.land/std/io/read_all.ts` instead.",
+  });
   return _readAllSync(r);
 }