Audit child_process externs for Node 24 and Haxe 4 (#248)

* Audit child_process externs for Node 24 and Haxe 4.

Align IPC typing with Process, expose Symbol.dispose, fork detached, and
narrow shell/windowsHide off fork; refresh docs and copyright through 2026.

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

* Fix ChildProcess.dispose to call Symbol.dispose.

@:native("Symbol.dispose") compiled to a string-key lookup; use extern
inline + Syntax.code so callers emit this[Symbol.dispose]().

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

---------

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

Author: kevinresol

src/js/node/ChildProcess.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"),
@@ -66,21 +66,6 @@ private typedef ChildProcessCommonOptions = {
 	**/
 	@:optional var gid:Int;
 
-	/**
-		Shell to execute the command with.
-		Default: `'/bin/sh'` on UNIX, `'cmd.exe'` on Windows.
-
-		The shell should understand the `-c` switch on UNIX or `/s /c` on Windows.
-		On Windows, command line parsing should be compatible with `cmd.exe`.
-	**/
-	@:optional var shell:EitherType<Bool, String>;
-
-	/**
-		Hide the subprocess console window that would normally be created on Windows.
-		Default: `false`.
-	**/
-	@:optional var windowsHide:Bool;
-
 	/**
 		No quoting or escaping of arguments is done on Windows.
 		Ignored on Unix. Default: `false`.
@@ -120,13 +105,20 @@ private typedef ChildProcessSpawnOptionsBase = {
 		Possible values are `'json'` and `'advanced'`. Default: `'json'`.
 	**/
 	@:optional var serialization:ChildProcessSerialization;
-}
 
-/**
-	Options for the `spawn` method.
-**/
-typedef ChildProcessSpawnOptions = {
-	> ChildProcessSpawnOptionsBase,
+	/**
+		If `true`, runs `command` inside a shell.
+		Uses `'/bin/sh'` on Unix and `process.env.ComSpec` on Windows.
+		A different shell can be specified as a string.
+		Default: `false` (no shell).
+	**/
+	@:optional var shell:EitherType<Bool, String>;
+
+	/**
+		Hide the subprocess console window that would normally be created on Windows.
+		Default: `false`.
+	**/
+	@:optional var windowsHide:Bool;
 
 	/**
 		The child will be a process group leader / can keep running after parent exits.
@@ -140,14 +132,26 @@ typedef ChildProcessSpawnOptions = {
 	@:optional var argv0:String;
 }
 
+/**
+	Options for the `spawn` method.
+**/
+typedef ChildProcessSpawnOptions = {
+	> ChildProcessSpawnOptionsBase,
+}
+
 /**
 	Options for the `spawnSync` method.
 **/
 typedef ChildProcessSpawnSyncOptions = {
 	> ChildProcessSpawnOptionsBase,
 	> ChildProcessExecOptionsBase,
 
-	@:optional var input:EitherType<String, Buffer>;
+	/**
+		The value passed as stdin to the spawned process.
+		Supplying this value overrides `stdio[0]`.
+		Accepts a string or `ArrayBufferView` (Buffer, TypedArray, or DataView).
+	**/
+	@:optional var input:EitherType<String, js.lib.ArrayBufferView>;
 }
 
 /**
@@ -165,6 +169,7 @@ typedef ChildProcessSpawnSyncOptions = {
 	 As a shorthand, the stdio argument may also be one of the following strings:
 		ignore - ['ignore', 'ignore', 'ignore']
 		pipe - ['pipe', 'pipe', 'pipe']
+		overlapped - ['overlapped', 'overlapped', 'overlapped']
 		inherit - [process.stdin, process.stdout, process.stderr] or [0,1,2]
 **/
 typedef ChildProcessSpawnOptionsStdio = EitherType<ChildProcessSpawnOptionsStdioSimple, ChildProcessSpawnOptionsStdioFull>;
@@ -246,6 +251,22 @@ private typedef ChildProcessExecOptionsBase = {
 		Default: `1024 * 1024`
 	**/
 	@:optional var maxBuffer:Int;
+
+	/**
+		If `true`, runs the command inside a shell.
+		Uses `'/bin/sh'` on Unix and `process.env.ComSpec` on Windows.
+		A different shell can be specified as a string.
+
+		For `exec`, a shell is always used (default `'/bin/sh'` / `ComSpec`).
+		For `execFile`, default is `false` (no shell).
+	**/
+	@:optional var shell:EitherType<Bool, String>;
+
+	/**
+		Hide the subprocess console window that would normally be created on Windows.
+		Default: `false`.
+	**/
+	@:optional var windowsHide:Bool;
 }
 
 /**
@@ -294,6 +315,12 @@ typedef ChildProcessForkOptions = {
 		Specify the kind of serialization used for sending messages between processes.
 	**/
 	@:optional var serialization:ChildProcessSerialization;
+
+	/**
+		Prepare the child to run independently of its parent process.
+		Platform-specific; see Node.js `options.detached` docs.
+	**/
+	@:optional var detached:Bool;
 }
 
 /**
@@ -360,7 +387,7 @@ typedef ChildProcessSpawnSyncResult = {
 	/**
 		The error object if the child process failed or timed out
 	**/
-	var error:Error;
+	var error:Null<Error>;
 }
 
 /**
@@ -373,19 +400,25 @@ extern class ChildProcess {
 	/**
 		Launches a new process with the given `command`, with command line arguments in `args`.
 		If omitted, `args` defaults to an empty `Array`.
+
+		@see https://nodejs.org/docs/latest-v24.x/api/child_process.html#child_processspawncommand-args-options
 	**/
 	@:overload(function(command:String, ?options:ChildProcessSpawnOptions):ChildProcessObject {})
 	@:overload(function(command:String, args:Array<String>, ?options:ChildProcessSpawnOptions):ChildProcessObject {})
 	static function spawn(command:String, ?args:Array<String>):ChildProcessObject;
 
 	/**
 		Runs a command in a shell and buffers the output.
+
+		@see https://nodejs.org/docs/latest-v24.x/api/child_process.html#child_processexeccommand-options-callback
 	**/
-	@:overload(function(command:String, options:ChildProcessExecOptions, callback:ChildProcessExecCallback):ChildProcessObject {})
-	static function exec(command:String, callback:ChildProcessExecCallback):ChildProcessObject;
+	@:overload(function(command:String, options:ChildProcessExecOptions, ?callback:ChildProcessExecCallback):ChildProcessObject {})
+	static function exec(command:String, ?callback:ChildProcessExecCallback):ChildProcessObject;
 
 	/**
 		Similar to `exec` except it does not execute a subshell but rather the specified file directly.
+
+		@see https://nodejs.org/docs/latest-v24.x/api/child_process.html#child_processexecfilefile-args-options-callback
 	**/
 	@:overload(function(file:String, args:Array<String>, options:ChildProcessExecFileOptions, ?callback:ChildProcessExecCallback):ChildProcessObject {})
 	@:overload(function(file:String, options:ChildProcessExecFileOptions, ?callback:ChildProcessExecCallback):ChildProcessObject {})
@@ -394,28 +427,36 @@ extern class ChildProcess {
 
 	/**
 		Special case of `spawn` for spawning Node.js processes with an IPC channel.
+
+		@see https://nodejs.org/docs/latest-v24.x/api/child_process.html#child_processforkmodulepath-args-options
 	**/
 	@:overload(function(modulePath:EitherType<String, URL>, args:Array<String>, options:ChildProcessForkOptions):ChildProcessObject {})
 	@:overload(function(modulePath:EitherType<String, URL>, options:ChildProcessForkOptions):ChildProcessObject {})
 	static function fork(modulePath:EitherType<String, URL>, ?args:Array<String>):ChildProcessObject;
 
 	/**
 		Synchronous version of `spawn`.
+
+		@see https://nodejs.org/docs/latest-v24.x/api/child_process.html#child_processspawnsynccommand-args-options
 	**/
 	@:overload(function(command:String, args:Array<String>, ?options:ChildProcessSpawnSyncOptions):ChildProcessSpawnSyncResult {})
 	static function spawnSync(command:String, ?options:ChildProcessSpawnSyncOptions):ChildProcessSpawnSyncResult;
 
 	/**
 		Synchronous version of `execFile`.
 		If the process times out, or has a non-zero exit code, this method will throw.
+
+		@see https://nodejs.org/docs/latest-v24.x/api/child_process.html#child_processexecfilesyncfile-args-options
 	**/
-	@:overload(function(command:String, ?options:ChildProcessSpawnSyncOptions):EitherType<String, Buffer> {})
-	@:overload(function(command:String, args:Array<String>, ?options:ChildProcessSpawnSyncOptions):EitherType<String, Buffer> {})
-	static function execFileSync(command:String, ?args:Array<String>):EitherType<String, Buffer>;
+	@:overload(function(file:String, ?options:ChildProcessSpawnSyncOptions):EitherType<String, Buffer> {})
+	@:overload(function(file:String, args:Array<String>, ?options:ChildProcessSpawnSyncOptions):EitherType<String, Buffer> {})
+	static function execFileSync(file:String, ?args:Array<String>):EitherType<String, Buffer>;
 
 	/**
 		Synchronous version of `exec`.
 		If the process times out, or has a non-zero exit code, this method will throw.
+
+		@see https://nodejs.org/docs/latest-v24.x/api/child_process.html#child_processexecsynccommand-options
 	**/
 	static function execSync(command:String, ?options:ChildProcessSpawnSyncOptions):EitherType<String, Buffer>;
 }

src/js/node/child_process/ChildProcess.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"),
@@ -88,15 +88,13 @@ enum abstract ChildProcessEvent<T:haxe.Constraints.Function>(Event<T>) to Event<
 	var Disconnect:ChildProcessEvent<Void->Void> = "disconnect";
 
 	/**
-		Messages send by `send` are obtained using the message event.
+		Messages sent by `send` are obtained using the `'message'` event.
 
 		Listener arguments:
 			message - a parsed JSON object or primitive value
-			sendHandle - a Socket or Server object
-
-		// TODO(section-5): tighten message/sendHandle typing beyond Dynamic once IPC handle unions are modeled
+			sendHandle - a `net.Socket`, `net.Server`, or `dgram.Socket` when one was sent
 	**/
-	var Message:ChildProcessEvent<Dynamic->Dynamic->Void> = "message";
+	var Message:ChildProcessEvent<(message:Dynamic, sendHandle:Null<ChildProcessSendHandle>) -> Void> = "message";
 
 	/**
 		The `'spawn'` event is emitted once the child process has spawned successfully.
@@ -201,10 +199,11 @@ extern class ChildProcess extends EventEmitter<ChildProcess> {
 
 	/**
 		While the IPC channel established by `fork` is open, this is a reference to that channel.
-		Otherwise `null`.
+		Otherwise `null` / `undefined`.
+
+		@see https://nodejs.org/docs/latest-v24.x/api/child_process.html#subprocesschannel
 	**/
-	// TODO(section-5): type IPC channel pipe more precisely than Null<Dynamic>
-	var channel(default, null):Null<Dynamic>;
+	var channel(default, null):Null<ChildProcessChannel>;
 
 	/**
 		Send a signal to the child process.
@@ -213,35 +212,52 @@ extern class ChildProcess extends EventEmitter<ChildProcess> {
 		See signal(7) for a list of available signals.
 
 		Returns `true` if `kill()` succeeded, else `false`.
+
+		@see https://nodejs.org/docs/latest-v24.x/api/child_process.html#subprocesskillsignal
 	**/
 	function kill(?signal:EitherType<String, Int>):Bool;
 
 	/**
-		When using `fork` you can write to the child using `send`
-		and messages are received by a `'message'` event on the child.
+		Calls `kill('SIGTERM')`. Available as `subprocess[Symbol.dispose]()`
+		(stable since Node.js 24.2).
+
+		@see https://nodejs.org/docs/latest-v24.x/api/child_process.html#subprocesssymboldispose
+	**/
+	extern inline function dispose():Void
+		js.Syntax.code("{0}[Symbol.dispose]()", this);
+
+	/**
+		When using `fork`, write to the child using `send`;
+		messages are received via the `'message'` event on the child.
 
-		// TODO(section-5): replace Dynamic message/sendHandle with structured IPC types
+		@see https://nodejs.org/docs/latest-v24.x/api/child_process.html#subprocesssendmessage-sendhandle-options-callback
 	**/
-	@:overload(function(message:Dynamic, sendHandle:Dynamic, options:ChildProcessSendOptions, ?callback:Null<Error>->Void):Bool {})
-	@:overload(function(message:Dynamic, sendHandle:Dynamic, ?callback:Null<Error>->Void):Bool {})
+	@:overload(function(message:Dynamic, sendHandle:ChildProcessSendHandle, options:ChildProcessSendOptions, ?callback:Null<Error>->Void):Bool {})
+	@:overload(function(message:Dynamic, sendHandle:ChildProcessSendHandle, ?callback:Null<Error>->Void):Bool {})
 	function send(message:Dynamic, ?callback:Null<Error>->Void):Bool;
 
 	/**
 		Close the IPC channel between parent and child, allowing the child to exit gracefully once there are no other
 		connections keeping it alive.
+
+		@see https://nodejs.org/docs/latest-v24.x/api/child_process.html#subprocessdisconnect
 	**/
 	function disconnect():Void;
 
 	/**
 		By default, the parent will wait for the detached child to exit.
 		To prevent the parent from waiting for a given child, use the `unref` method.
+
+		@see https://nodejs.org/docs/latest-v24.x/api/child_process.html#subprocessunref
 	**/
 	function unref():Void;
 
 	/**
-		Opposite of `unref()`. Calls reference the child from the parent's event loop so that
+		Opposite of `unref()`. References the child from the parent's event loop so that
 		the parent will wait for the child to exit before exiting itself
 		(unless there are other references keeping the parent alive).
+
+		@see https://nodejs.org/docs/latest-v24.x/api/child_process.html#subprocessref
 	**/
 	function ref():Void;
 }