[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

@@ -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

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

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,