Audit repl externs for Node 24 + Haxe 4 (#261)

* Audit repl externs for Node 24 and Haxe 4.

Add Recoverable, deprecated builtinModules, and default writer; extend REPLServer from readline.Interface with Node 24.2 setupHistory options; refresh comments and copyright years.

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

* Polish repl writer options typing and doc links.

Expose util.inspect-compatible options on Repl.writer and tighten
Node 24 API documentation references on Repl/REPLServer.

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

---------

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

Author: kevinresol

src/js/node/Repl.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,24 +25,50 @@ package js.node;
 import haxe.DynamicAccess;
 import js.lib.Error;
 import js.lib.Symbol;
+import js.node.Util.InspectOptions;
 import js.node.repl.REPLServer;
 import js.node.stream.Readable.IReadable;
 import js.node.stream.Writable.IWritable;
 
 /**
-	The `repl` module provides a Read-Eval-Print-Loop (REPL) implementation that is available both as a standalone
+	The `node:repl` module provides a Read-Eval-Print-Loop (REPL) implementation that is available both as a standalone
 	program or includible in other applications.
 
+	Related types: `js.node.repl.REPLServer`, `js.node.repl.Recoverable`.
+
 	@see https://nodejs.org/docs/latest-v24.x/api/repl.html
 **/
 @:jsRequire("repl")
 extern class Repl {
 	/**
 		The `repl.start()` method creates and starts a `repl.REPLServer` instance.
+
+		If `options` is a string, then it specifies the input prompt.
+
+		@see https://nodejs.org/docs/latest-v24.x/api/repl.html#replstartoptions
 	**/
 	@:overload(function(prompt:String):REPLServer {})
 	static function start(?options:ReplOptions):REPLServer;
 
+	/**
+		Default function used to format each command's output before writing to `output`.
+		A wrapper for `util.inspect()`; may be overridden by a custom `writer` option.
+		Inspect defaults are available via `writer.options`.
+
+		@see https://nodejs.org/docs/latest-v24.x/api/repl.html#customizing-repl-output
+	**/
+	static final writer:ReplWriter;
+
+	/**
+		A list of the names of some Node.js modules, e.g. `'http'`.
+
+		Deprecated since: v24.0.0. Use `js.node.Module.builtinModules` instead.
+
+		@see https://nodejs.org/docs/latest-v24.x/api/repl.html#replbuiltinmodules
+	**/
+	@:deprecated("Use js.node.Module.builtinModules instead")
+	static var builtinModules(default, null):Array<String>;
+
 	/**
 		Evaluates expressions in sloppy mode.
 	**/
@@ -56,7 +82,7 @@ extern class Repl {
 }
 
 /**
-	Options object used by `Repl.start`.
+	Options object used by `Repl.start` / `new REPLServer`.
 
 	@see https://nodejs.org/docs/latest-v24.x/api/repl.html#replstartoptions
 **/
@@ -78,40 +104,46 @@ typedef ReplOptions = {
 
 	/**
 		If `true`, specifies that the `output` should be treated as a TTY terminal.
+		Default: checking the value of the `isTTY` property on the `output` stream upon instantiation.
 	**/
 	@:optional var terminal:Bool;
 
 	/**
 		The function to be used when evaluating each given line of input.
 		Default: an async wrapper for the JavaScript `eval()` function.
 
+		An `eval` function can error with `repl.Recoverable` to indicate the input was incomplete
+		and prompt for additional lines.
+
 		// TODO(section-5): replace DynamicAccess<Dynamic>/Dynamic result with a typed REPL context model
 	**/
 	@:optional var eval:(code:String, context:DynamicAccess<Dynamic>, file:String, cb:(error:Null<Error>, ?result:Dynamic) -> Void) -> Void;
 
 	/**
 		If `true`, specifies that the default `writer` function should include ANSI color styling to REPL output.
+		If a custom `writer` is provided then this has no effect.
+		Default: checking color support on the `output` stream if the REPL instance's `terminal` value is `true`.
 	**/
 	@:optional var useColors:Bool;
 
 	/**
-		If `true`, specifies that the default evaluation function will use the JavaScript `global` as the context.
+		If `true`, specifies that the default evaluation function will use the JavaScript `global` as the context
+		as opposed to creating a new separate context for the REPL instance.
+		The node CLI REPL sets this value to `true`. Default: `false`.
 	**/
 	@:optional var useGlobal:Bool;
 
 	/**
 		If `true`, specifies that the default writer will not output the return value of a command if it evaluates to
-		`undefined`.
+		`undefined`. Default: `false`.
 	**/
 	@:optional var ignoreUndefined:Bool;
 
 	/**
 		The function to invoke to format the output of each command before writing to `output`.
-		Default: `util.inspect()`.
-
-		// TODO(section-5): type writer as (value:Dynamic) -> String
+		Default: `util.inspect()` / `repl.writer`.
 	**/
-	@:optional var writer:Dynamic->Dynamic;
+	@:optional var writer:(obj:Dynamic) -> String;
 
 	/**
 		An optional function used for custom Tab auto completion.
@@ -127,12 +159,33 @@ typedef ReplOptions = {
 
 	/**
 		Stop evaluating the current piece of code when `SIGINT` is received, i.e. `Ctrl+C` is pressed.
-		This cannot be used together with a custom `eval` function.
+		This cannot be used together with a custom `eval` function. Default: `false`.
 	**/
 	@:optional var breakEvalOnSigint:Bool;
 
 	/**
-		If `true`, show preview of the results when inputting. Default depends on Node version / terminal.
+		Defines if the REPL prints autocomplete and output previews.
+		Default: `true` with the default eval function and `false` when a custom eval function is used.
+		If `terminal` is falsy, there are no previews and this value has no effect.
 	**/
 	@:optional var preview:Bool;
 }
+
+/**
+	Default REPL writer: callable formatter with `util.inspect`-compatible `options`.
+**/
+@:callable
+abstract ReplWriter((obj:Dynamic) -> String) from((obj:Dynamic) -> String) to((obj:Dynamic) -> String) {
+	/**
+		Inspection options used by the default writer.
+	**/
+	public var options(get, set):InspectOptions;
+
+	inline function get_options():InspectOptions
+		return Reflect.field(this, "options");
+
+	inline function set_options(value:InspectOptions):InspectOptions {
+		Reflect.setField(this, "options", value);
+		return value;
+	}
+}

src/js/node/repl/REPLServer.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,51 +23,97 @@
 package js.node.repl;
 
 import haxe.DynamicAccess;
+import haxe.extern.EitherType;
 import js.lib.Error;
-import js.node.events.EventEmitter;
+import js.node.Repl.ReplOptions;
+import js.node.events.EventEmitter.Event;
+import js.node.readline.Interface;
+import js.node.stream.Readable.IReadable;
+import js.node.stream.Writable.IWritable;
 
 /**
-	Enumeration of events emitted by the `REPLServer` objects.
+	Enumeration of events emitted by `REPLServer` objects.
 **/
 enum abstract REPLServerEvent<T:haxe.Constraints.Function>(Event<T>) to Event<T> {
 	/**
 		The `'exit'` event is emitted when the REPL is exited either by receiving the `.exit` command as input,
-		the user pressing `<ctrl>-C` twice to signal `SIGINT`, or by pressing `<ctrl>-D` to signal 'end' on the input stream.
+		the user pressing Ctrl+C twice to signal `SIGINT`, or by pressing Ctrl+D to signal `'end'` on the input stream.
+
+		@see https://nodejs.org/docs/latest-v24.x/api/repl.html#event-exit
 	**/
-	var Exit:REPLServerEvent<Void->Void> = "exit";
+	var Exit:REPLServerEvent<() -> Void> = "exit";
 
 	/**
 		The `'reset'` event is emitted when the REPL's context is reset.
+		This occurs whenever the `.clear` command is received as input unless the REPL is using the default evaluator
+		and the `REPLServer` instance was created with the `useGlobal` option set to `true`.
 
 		// TODO(section-5): type context beyond DynamicAccess<Dynamic>
+
+		@see https://nodejs.org/docs/latest-v24.x/api/repl.html#event-reset
 	**/
 	var Reset:REPLServerEvent<(context:DynamicAccess<Dynamic>) -> Void> = "reset";
 }
 
 /**
-	Instances of `repl.REPLServer` are created using the `repl.start()` method and should not be created directly using
-	the JavaScript `new` keyword.
+	Instances of `repl.REPLServer` are created using `repl.start()` or directly with `new REPLServer(options)`.
+
+	Extends `readline.Interface`.
 
 	@see https://nodejs.org/docs/latest-v24.x/api/repl.html#class-replserver
 **/
 @:jsRequire("repl", "REPLServer")
-extern class REPLServer extends EventEmitter<REPLServer> {
+extern class REPLServer extends Interface {
+	/**
+		Creates a new `REPLServer` instance. Prefer `Repl.start()` in most cases.
+	**/
+	function new(?options:ReplOptions);
+
 	/**
-		It is possible to expose a variable to the REPL explicitly by assigning it to the `context` object associated
-		with each `REPLServer`.
+		The `vm` / REPL context object provided to the `eval` function.
 
 		// TODO(section-5): type context beyond DynamicAccess<Dynamic>
 	**/
 	var context(default, null):DynamicAccess<Dynamic>;
 
+	/**
+		The `Readable` stream from which REPL input will be read.
+	**/
+	var input(default, null):IReadable;
+
+	/**
+		The `Writable` stream to which REPL output will be written.
+	**/
+	var output(default, null):IWritable;
+
+	/**
+		Deprecated alias for `input`. Deprecated since: v14.3.0.
+	**/
+	@:deprecated("Use input instead")
+	var inputStream(default, null):IReadable;
+
+	/**
+		Deprecated alias for `output`. Deprecated since: v14.3.0.
+	**/
+	@:deprecated("Use output instead")
+	var outputStream(default, null):IWritable;
+
+	/**
+		Commands registered via `defineCommand()`.
+	**/
+	var commands(default, null):DynamicAccess<EitherType<REPLCommand, (rest:String) -> Void>>;
+
 	/**
 		The `replServer.defineCommand()` method is used to add new `.`-prefixed commands to the REPL instance.
 	**/
 	@:overload(function(keyword:String, cmd:(rest:String) -> Void):Void {})
-	function defineCommand(keyword:String, cmd:REPLServerOptions):Void;
+	function defineCommand(keyword:String, cmd:REPLCommand):Void;
 
 	/**
-		The `replServer.displayPrompt()` method readies the REPL instance for input from the user.
+		The `replServer.displayPrompt()` method readies the REPL instance for input from the user,
+		printing the configured `prompt` to a new line in `output` and resuming `input`.
+
+		When multi-line input is being entered, a pipe `'|'` is printed rather than the prompt.
 	**/
 	function displayPrompt(?preserveCursor:Bool):Void;
 
@@ -78,21 +124,57 @@ extern class REPLServer extends EventEmitter<REPLServer> {
 
 	/**
 		Initializes a history log file for the REPL instance.
+
+		When `historyConfig` is a string, it is the path to the history file.
+		Since Node.js v24.2.0, an options object may be passed instead.
 	**/
+	@:overload(function(historyConfig:REPLServerHistoryOptions, ?callback:(err:Null<Error>, repl:Null<REPLServer>) -> Void):Void {})
 	function setupHistory(historyPath:String, callback:(err:Null<Error>, repl:Null<REPLServer>) -> Void):Void;
 }
 
+/**
+	Object form of `replServer.setupHistory` (Node.js v24.2.0+).
+
+	@see https://nodejs.org/docs/latest-v24.x/api/repl.html#replserversetuphistoryhistoryconfig-callback
+**/
+typedef REPLServerHistoryOptions = {
+	/**
+		The path to the history file.
+	**/
+	@:optional var filePath:String;
+
+	/**
+		Maximum number of history lines retained. Set to `0` to disable history.
+		Only applies when `terminal` is `true`. Default: `30`.
+	**/
+	@:optional var size:Int;
+
+	/**
+		If `true`, when a new input line duplicates an older one, the older line is removed. Default: `false`.
+	**/
+	@:optional var removeHistoryDuplicates:Bool;
+
+	/**
+		Called when history writes are ready or upon error.
+		May be used instead of the `callback` argument to `setupHistory`.
+	**/
+	@:optional var onHistoryFileLoaded:(err:Null<Error>, repl:Null<REPLServer>) -> Void;
+}
+
 /**
 	Options object used by `REPLServer.defineCommand`.
 **/
-typedef REPLServerOptions = {
+typedef REPLCommand = {
 	/**
 		Help text to be displayed when `.help` is entered.
 	**/
 	@:optional var help:String;
 
 	/**
-		The function to execute.
+		The function to execute, optionally accepting a single string argument.
 	**/
 	var action:(rest:String) -> Void;
 }
+
+/** @deprecated Use `REPLCommand` instead. **/
+typedef REPLServerOptions = REPLCommand;

src/js/node/repl/Recoverable.hx

@@ -0,0 +1,43 @@
+/*
+ * 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"),
+ * to deal in the Software without restriction, including without limitation
+ * the rights to use, copy, modify, merge, publish, distribute, sublicense,
+ * and/or sell copies of the Software, and to permit persons to whom the
+ * Software is furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+ * DEALINGS IN THE SOFTWARE.
+ */
+
+package js.node.repl;
+
+import js.lib.Error;
+
+/**
+	Indicates a recoverable error that a `REPLServer` can use to support multi-line input.
+
+	Pass an instance to the custom `eval` callback to request additional lines when input is incomplete
+	(e.g. unclosed braces).
+
+	@see https://nodejs.org/docs/latest-v24.x/api/repl.html#recoverable-errors
+**/
+@:jsRequire("repl", "Recoverable")
+extern class Recoverable extends Error {
+	/**
+		The underlying error that triggered the recoverable state.
+	**/
+	var err:Error;
+
+	function new(err:Error);
+}