From c10ce1caa15f438702861a06e42920f02cad106a Mon Sep 17 00:00:00 2001
From: filtered <176114999+webfiltered@users.noreply.github.com>
Date: Sat, 26 Apr 2025 02:16:01 +1000
Subject: [PATCH] [API] Add deprecated warning logging (#967)

Adds a global API to notify devs / users of deprecated features.

- Custom callbacks may be added
- By default, remembers message text and only sends each message once
- Sends to console.warn by default

```ts
// Add a custom notification when a warning is encountered
const warnMessage = (message: string, source?: object) => {
  addToast({ message, detail: object })
}
LiteGraph.onDeprecationWarning.push(warnMessage)
```

```ts
// Debugging flag. Repeats deprecation warnings every time they are reported.
// May impact performance.
LiteGraph.alwaysRepeatWarnings = true
```

Generate a warning
```ts
import { warnDeprecated } from "@/utils/feedback"

warnDeprecated(
  "[DEPRECATED] graph.oldFeature() will be removed from Litegraph. " +
  "Please use graph.newFeature() instead. https://helpful.site/faq",
  objectThatCausedThis
)
```
---
 src/LiteGraphGlobal.ts                    | 12 ++++++++++
 src/utils/feedback.ts                     | 27 +++++++++++++++++++++++
 test/__snapshots__/litegraph.test.ts.snap |  4 ++++
 3 files changed, 43 insertions(+)
 create mode 100644 src/utils/feedback.ts

diff --git a/src/LiteGraphGlobal.ts b/src/LiteGraphGlobal.ts
index 328e62a504..6e0be273b9 100644
--- a/src/LiteGraphGlobal.ts
+++ b/src/LiteGraphGlobal.ts
@@ -258,6 +258,18 @@ export class LiteGraphGlobal {
   /** Whether to scale context with the graph when zooming in.  Zooming out never makes context menus smaller. */
   context_menu_scaling = false
 
+  /**
+   * Debugging flag. Repeats deprecation warnings every time they are reported.
+   * May impact performance.
+   */
+  alwaysRepeatWarnings: boolean = false
+
+  /**
+   * Array of callbacks to execute when Litegraph first reports a deprecated API being used.
+   * @see alwaysRepeatWarnings By default, will not repeat identical messages.
+   */
+  onDeprecationWarning: ((message: string, source?: object) => void)[] = [console.warn]
+
   // TODO: Remove legacy accessors
   LGraph = LGraph
   LLink = LLink
diff --git a/src/utils/feedback.ts b/src/utils/feedback.ts
new file mode 100644
index 0000000000..72d2892d01
--- /dev/null
+++ b/src/utils/feedback.ts
@@ -0,0 +1,27 @@
+import { LiteGraph } from "@/litegraph"
+
+/** Guard against unbound allocation. */
+const UNIQUE_MESSAGE_LIMIT = 10_000
+const sentWarnings: Set<string> = new Set()
+
+/**
+ * Warns that a deprecated function has been used via the public
+ * {@link onDeprecationWarning} / {@link onEveryDeprecationWarning} callback arrays.
+ * @param message Plain-language detail about what has been deprecated. This **should not** include unique data; use {@link source}.
+ * @param source A reference object to include alongside the message, e.g. `this`.
+ */
+export function warnDeprecated(message: string, source?: object): void {
+  if (!LiteGraph.alwaysRepeatWarnings) {
+    // Do not repeat
+    if (sentWarnings.has(message)) return
+
+    // Hard limit of unique messages per session
+    if (sentWarnings.size > UNIQUE_MESSAGE_LIMIT) return
+
+    sentWarnings.add(message)
+  }
+
+  for (const callback of LiteGraph.onDeprecationWarning) {
+    callback(message, source)
+  }
+}
diff --git a/test/__snapshots__/litegraph.test.ts.snap b/test/__snapshots__/litegraph.test.ts.snap
index 1685582c36..177c6e896e 100644
--- a/test/__snapshots__/litegraph.test.ts.snap
+++ b/test/__snapshots__/litegraph.test.ts.snap
@@ -139,6 +139,7 @@ LiteGraphGlobal {
   "allow_multi_output_for_events": true,
   "allow_scripts": false,
   "alt_drag_do_clone_nodes": false,
+  "alwaysRepeatWarnings": false,
   "alwaysSnapToGrid": undefined,
   "auto_load_slot_types": false,
   "catch_exceptions": true,
@@ -158,6 +159,9 @@ LiteGraphGlobal {
   "node_box_coloured_when_on": false,
   "node_images_path": "",
   "node_types_by_file_extension": {},
+  "onDeprecationWarning": [
+    [Function],
+  ],
   "overlapBounding": [Function],
   "pointerevents_method": "pointer",
   "proxy": null,