Audit js.node inspector externs for Node 24 + Haxe 4. (#258)

Refresh copyrights to 2014-2026, add missing inspector console
methods, and modernize Session callback/event typing and docs.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: kevinresol

src/js/node/Inspector.hx

@@ -1,5 +1,5 @@
 /*
- * Copyright (C)2014-2020 Haxe Foundation
+ * Copyright (C)2014-2026 Haxe Foundation
  *
  * Permission is hereby granted, free of charge, to any person obtaining a
  * copy of this software and associated documentation files (the "Software"),
@@ -25,7 +25,9 @@ package js.node;
 import js.node.inspector.InspectorConsole;
 
 /**
-	The `inspector` module provides an API for interacting with the V8 inspector.
+	The `node:inspector` module provides an API for interacting with the V8 inspector.
+
+	Stability: 2 - Stable.
 
 	Related types live under `js.node.inspector` (`Session`, `Network`, `NetworkResources`, `DomStorage`).
 	Use those types directly (e.g. `js.node.inspector.Network.requestWillBeSent(...)`) — they map to
@@ -42,9 +44,12 @@ extern class Inspector {
 		If `wait` is `true`, will block until a client has connected to the inspect port
 		and flow control has been passed to the debugger client.
 
-		Returns a Disposable (`{ [Symbol.dispose](): void }`) that calls `inspector.close()`.
+		See the Node.js security warning regarding the `host` parameter (binding the inspector
+		to a public IP/port combination is insecure).
 
-		// TODO: model Web IDL `Disposable` / `Symbol.dispose` instead of `Dynamic`.
+		Returns a Disposable (`{ [Symbol.dispose](): void }`) that calls `inspector.close()`.
+		Typed as `Dynamic` because the returned object only exposes `Symbol.dispose` (no named
+		`dispose()` method) and hxnodejs does not yet model Web IDL `Disposable`.
 	**/
 	static function open(?port:Int, ?host:String, ?wait:Bool):Dynamic;
 

src/js/node/InspectorPromises.hx

@@ -1,5 +1,5 @@
 /*
- * Copyright (C)2014-2020 Haxe Foundation
+ * Copyright (C)2014-2026 Haxe Foundation
  *
  * Permission is hereby granted, free of charge, to any person obtaining a
  * copy of this software and associated documentation files (the "Software"),
@@ -23,16 +23,16 @@
 package js.node;
 
 import js.node.inspector.InspectorConsole;
-import js.node.inspector.promises.Session;
 
 /**
-	Promise-based `inspector` API (`inspector/promises`).
+	Promise-based `node:inspector` API (`inspector/promises`).
 
 	Stability: 1 - Experimental.
 
 	Module-level helpers match `Inspector`; use `js.node.inspector.promises.Session`
-	for a `Session` whose `post` returns a `Promise`. DevTools helpers live under
-	`js.node.inspector` (`Network`, `NetworkResources`, `DomStorage`).
+	for a `Session` whose `post` returns a `Promise`. DevTools helpers
+	(`Network`, `NetworkResources`, `DOMStorage`) are also exported from this module
+	in Node.js; prefer the typed externs under `js.node.inspector`.
 
 	@see https://nodejs.org/docs/latest-v24.x/api/inspector.html#promises-api
 **/
@@ -41,14 +41,18 @@ extern class InspectorPromises {
 	/**
 		Activate inspector on host and port.
 
-		Returns a Disposable (`{ [Symbol.dispose](): void }`) that calls `close()`.
+		See the Node.js security warning regarding the `host` parameter (binding the inspector
+		to a public IP/port combination is insecure).
 
-		// TODO: model Web IDL `Disposable` / `Symbol.dispose` instead of `Dynamic`.
+		Returns a Disposable (`{ [Symbol.dispose](): void }`) that calls `close()`.
+		Typed as `Dynamic` because the returned object only exposes `Symbol.dispose` (no named
+		`dispose()` method) and hxnodejs does not yet model Web IDL `Disposable`.
 	**/
 	static function open(?port:Int, ?host:String, ?wait:Bool):Dynamic;
 
 	/**
 		Attempts to close all remaining connections, blocking the event loop until all are closed.
+		Once all connections are closed, deactivates the inspector.
 	**/
 	static function close():Void;
 
@@ -58,12 +62,17 @@ extern class InspectorPromises {
 	static function url():Null<String>;
 
 	/**
-		Blocks until a client has sent `Runtime.runIfWaitingForDebugger`.
+		Blocks until a client (existing or connected later) has sent
+		`Runtime.runIfWaitingForDebugger` command.
+
+		An exception will be thrown if there is no active inspector.
 	**/
 	static function waitForDebugger():Void;
 
 	/**
 		An object to send messages to the remote inspector console.
+
+		The inspector console does not have API parity with Node.js console.
 	**/
 	static var console(default, null):InspectorConsole;
 }

src/js/node/inspector/DomStorage.hx

@@ -1,5 +1,5 @@
 /*
- * Copyright (C)2014-2020 Haxe Foundation
+ * Copyright (C)2014-2026 Haxe Foundation
  *
  * Permission is hereby granted, free of charge, to any person obtaining a
  * copy of this software and associated documentation files (the "Software"),
@@ -25,12 +25,14 @@ package js.node.inspector;
 /**
 	Helpers that broadcast Chrome DevTools Protocol `DOMStorage` events to connected frontends.
 
+	Stability: 1.1 - Active development.
+
 	Added in: v24.16.0 (Active LTS). Not available on Maintenance LTS 22.x.
 	Only available with the `--experimental-storage-inspection` flag enabled.
 
 	Haxe type is `DomStorage` (acronyms are not uppercased); the Node.js export name is `DOMStorage`.
 
-	@see https://nodejs.org/api/inspector.html#inspectordomstoragedomstorageitemadded
+	@see https://nodejs.org/docs/latest-v24.x/api/inspector.html#inspectordomstoragedomstorageitemadded
 **/
 @:jsRequire("inspector", "DOMStorage")
 extern class DomStorage {

src/js/node/inspector/InspectorConsole.hx

@@ -1,5 +1,5 @@
 /*
- * Copyright (C)2014-2020 Haxe Foundation
+ * Copyright (C)2014-2026 Haxe Foundation
  *
  * Permission is hereby granted, free of charge, to any person obtaining a
  * copy of this software and associated documentation files (the "Software"),
@@ -27,9 +27,10 @@ import haxe.extern.Rest;
 /**
 	Object used to send messages to the remote inspector console.
 
-	The inspector console does not have API parity with Node.js console.
+	Exposed by the V8 inspector console API; method signatures deliberately differ
+	from (and are more permissive than) the Node.js `console` API.
 
-	@see https://nodejs.org/api/inspector.html#inspectorconsole
+	@see https://nodejs.org/docs/latest-v24.x/api/inspector.html#inspectorconsole
 **/
 extern class InspectorConsole {
 	function debug(data:Rest<Dynamic>):Void;
@@ -51,6 +52,12 @@ extern class InspectorConsole {
 	function profile(?label:Dynamic):Void;
 	function profileEnd(?label:Dynamic):Void;
 	function time(?label:Dynamic):Void;
+	function timeEnd(?label:Dynamic):Void;
 	function timeLog(?label:Dynamic):Void;
 	function timeStamp(?label:Dynamic):Void;
+
+	/**
+		Creates a new inspector console context with the given name.
+	**/
+	function context(name:Dynamic):Void;
 }

src/js/node/inspector/Network.hx

@@ -1,5 +1,5 @@
 /*
- * Copyright (C)2014-2020 Haxe Foundation
+ * Copyright (C)2014-2026 Haxe Foundation
  *
  * Permission is hereby granted, free of charge, to any person obtaining a
  * copy of this software and associated documentation files (the "Software"),
@@ -27,11 +27,13 @@ import haxe.DynamicAccess;
 /**
 	Broadcast helpers for Chrome DevTools Protocol `Network.*` events.
 
+	Stability: 1.1 - Active development.
+
 	These APIs require the `--experimental-network-inspection` flag.
 
 	Usage: `Network.requestWillBeSent({ ... })` (maps to `inspector.Network` in Node.js).
 
-	@see https://nodejs.org/api/inspector.html#integration-with-devtools
+	@see https://nodejs.org/docs/latest-v24.x/api/inspector.html#integration-with-devtools
 **/
 @:jsRequire("inspector", "Network")
 extern class Network {
@@ -40,11 +42,15 @@ extern class Network {
 		`Network.streamResourceContent` command was not invoked for the given request yet.
 
 		Also enables `Network.getResponseBody` command to retrieve the response data.
+
+		Added in: v24.2.0.
 	**/
 	static function dataReceived(?params:NetworkDataReceivedParams):Void;
 
 	/**
 		Enables `Network.getRequestPostData` command to retrieve the request data.
+
+		Added in: v24.3.0.
 	**/
 	static function dataSent(?params:NetworkDataSentParams):Void;
 
@@ -123,14 +129,14 @@ typedef NetworkResponse = {
 /**
 	Pragmatic subset of CDP request initiator.
 
-	// TODO: model CDP `StackTrace` for `stack` instead of `Dynamic`.
+	`stack` remains `Any` pending a CDP `StackTrace` model in hxnodejs.
 **/
 typedef NetworkInitiator = {
 	var type:String;
 	@:optional var url:String;
 	@:optional var lineNumber:Float;
 	@:optional var columnNumber:Float;
-	@:optional var stack:Dynamic;
+	@:optional var stack:Any;
 }
 
 /**

src/js/node/inspector/NetworkResources.hx

@@ -1,5 +1,5 @@
 /*
- * Copyright (C)2014-2020 Haxe Foundation
+ * Copyright (C)2014-2026 Haxe Foundation
  *
  * Permission is hereby granted, free of charge, to any person obtaining a
  * copy of this software and associated documentation files (the "Software"),
@@ -26,11 +26,15 @@ package js.node.inspector;
 	Provides responses for `Network.loadNetworkResource` CDP requests
 	(e.g. source maps requested by a DevTools frontend).
 
+	Stability: 1.1 - Active development.
+
 	Requires the `--experimental-inspector-network-resource` flag.
 
 	Usage: `NetworkResources.put(url, data)` (maps to `inspector.NetworkResources` in Node.js).
 
-	@see https://nodejs.org/api/inspector.html#inspectornetworkresourcesput
+	Added in: v24.5.0.
+
+	@see https://nodejs.org/docs/latest-v24.x/api/inspector.html#inspectornetworkresourcesput
 **/
 @:jsRequire("inspector", "NetworkResources")
 extern class NetworkResources {

src/js/node/inspector/Session.hx

@@ -1,5 +1,5 @@
 /*
- * Copyright (C)2014-2020 Haxe Foundation
+ * Copyright (C)2014-2026 Haxe Foundation
  *
  * Permission is hereby granted, free of charge, to any person obtaining a
  * copy of this software and associated documentation files (the "Software"),
@@ -22,8 +22,8 @@
 
 package js.node.inspector;
 
-import js.node.events.EventEmitter;
 import js.lib.Error;
+import js.node.events.EventEmitter;
 
 /**
 	Enumeration of events emitted by `inspector.Session`.
@@ -35,22 +35,22 @@ enum abstract SessionEvent<T:haxe.Constraints.Function>(Event<T>) to Event<T> {
 	/**
 		Emitted when any notification from the V8 Inspector is received.
 	**/
-	var InspectorNotification:SessionEvent<InspectorNotificationMessage->Void> = "inspectorNotification";
+	var InspectorNotification:SessionEvent<(message:InspectorNotificationMessage) -> Void> = "inspectorNotification";
 
 	/**
 		Emitted when an inspector notification is received with method `Debugger.paused`.
 	**/
-	var DebuggerPaused:SessionEvent<InspectorNotificationMessage->Void> = "Debugger.paused";
+	var DebuggerPaused:SessionEvent<(message:InspectorNotificationMessage) -> Void> = "Debugger.paused";
 
 	/**
 		Emitted when an inspector notification is received with method `Debugger.resumed`.
 	**/
-	var DebuggerResumed:SessionEvent<InspectorNotificationMessage->Void> = "Debugger.resumed";
+	var DebuggerResumed:SessionEvent<(message:InspectorNotificationMessage) -> Void> = "Debugger.resumed";
 
 	/**
 		Emitted when an inspector notification is received with method `HeapProfiler.addHeapSnapshotChunk`.
 	**/
-	var HeapProfilerAddHeapSnapshotChunk:SessionEvent<InspectorNotificationMessage->Void> = "HeapProfiler.addHeapSnapshotChunk";
+	var HeapProfilerAddHeapSnapshotChunk:SessionEvent<(message:InspectorNotificationMessage) -> Void> = "HeapProfiler.addHeapSnapshotChunk";
 }
 
 /**
@@ -67,7 +67,10 @@ typedef InspectorNotificationMessage = {
 	The `inspector.Session` is used for dispatching messages to the V8 inspector
 	back-end and receiving message responses and notifications.
 
-	@see https://nodejs.org/api/inspector.html#class-inspectorsession
+	When using `Session`, objects outputted by the console API will not be released
+	unless `Runtime.DiscardConsoleEntries` is posted manually.
+
+	@see https://nodejs.org/docs/latest-v24.x/api/inspector.html#class-inspectorsession
 **/
 @:jsRequire("inspector", "Session")
 extern class Session extends EventEmitter<Session> {
@@ -105,6 +108,6 @@ extern class Session extends EventEmitter<Session> {
 		Protocol method names and parameter/result shapes follow the Chrome DevTools Protocol;
 		they are typed as `String` / `Dynamic` rather than enumerating the full CDP schema.
 	**/
-	@:overload(function(method:String, ?callback:Null<Error>->Dynamic->Void):Void {})
-	function post(method:String, ?params:Dynamic, ?callback:Null<Error>->Dynamic->Void):Void;
+	@:overload(function(method:String, ?callback:(error:Null<Error>, result:Dynamic) -> Void):Void {})
+	function post(method:String, ?params:Dynamic, ?callback:(error:Null<Error>, result:Dynamic) -> Void):Void;
 }

src/js/node/inspector/promises/Session.hx

@@ -1,5 +1,5 @@
 /*
- * Copyright (C)2014-2020 Haxe Foundation
+ * Copyright (C)2014-2026 Haxe Foundation
  *
  * Permission is hereby granted, free of charge, to any person obtaining a
  * copy of this software and associated documentation files (the "Software"),
@@ -22,8 +22,8 @@
 
 package js.node.inspector.promises;
 
-import js.node.events.EventEmitter;
 import js.lib.Promise;
+import js.node.events.EventEmitter;
 
 /**
 	Promise-based `inspector.Session` from `inspector/promises`.
@@ -33,7 +33,10 @@ import js.lib.Promise;
 	Emits the same notification events as callback `inspector.Session`;
 	use `js.node.inspector.SessionEvent` with `on` / `once` / `off`.
 
-	@see https://nodejs.org/api/inspector.html#promises-api
+	When using `Session`, objects outputted by the console API will not be released
+	unless `Runtime.DiscardConsoleEntries` is posted manually.
+
+	@see https://nodejs.org/docs/latest-v24.x/api/inspector.html#promises-api
 **/
 @:jsRequire("inspector/promises", "Session")
 extern class Session extends EventEmitter<Session> {
@@ -65,6 +68,9 @@ extern class Session extends EventEmitter<Session> {
 	/**
 		Posts a message to the inspector back-end and returns a Promise that resolves
 		with the message-specific result object.
+
+		Protocol method names and parameter/result shapes follow the Chrome DevTools Protocol;
+		they are typed as `String` / `Dynamic` rather than enumerating the full CDP schema.
 	**/
 	function post(method:String, ?params:Dynamic):Promise<Dynamic>;
 }