9cb5f5b78671d9cbee4f511e0b339d337a2d529589deca650ddab027dcefcc7b5cd4923c92d44ad45a829f0c1f820f44fd4af597096e553c8028f07d0bbb22 19 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438
  1. /**
  2. * The `node:repl` module provides a Read-Eval-Print-Loop (REPL) implementation
  3. * that is available both as a standalone program or includible in other
  4. * applications. It can be accessed using:
  5. *
  6. * ```js
  7. * import repl from 'node:repl';
  8. * ```
  9. * @see [source](https://github.com/nodejs/node/blob/v24.x/lib/repl.js)
  10. */
  11. declare module "repl" {
  12. import { AsyncCompleter, Completer, Interface } from "node:readline";
  13. import { Context } from "node:vm";
  14. import { InspectOptions } from "node:util";
  15. interface ReplOptions {
  16. /**
  17. * The input prompt to display.
  18. * @default "> "
  19. */
  20. prompt?: string | undefined;
  21. /**
  22. * The `Readable` stream from which REPL input will be read.
  23. * @default process.stdin
  24. */
  25. input?: NodeJS.ReadableStream | undefined;
  26. /**
  27. * The `Writable` stream to which REPL output will be written.
  28. * @default process.stdout
  29. */
  30. output?: NodeJS.WritableStream | undefined;
  31. /**
  32. * If `true`, specifies that the output should be treated as a TTY terminal, and have
  33. * ANSI/VT100 escape codes written to it.
  34. * Default: checking the value of the `isTTY` property on the output stream upon
  35. * instantiation.
  36. */
  37. terminal?: boolean | undefined;
  38. /**
  39. * The function to be used when evaluating each given line of input.
  40. * **Default:** an async wrapper for the JavaScript `eval()` function. An `eval` function can
  41. * error with `repl.Recoverable` to indicate the input was incomplete and prompt for
  42. * additional lines. See the [custom evaluation functions](https://nodejs.org/dist/latest-v24.x/docs/api/repl.html#custom-evaluation-functions)
  43. * section for more details.
  44. */
  45. eval?: REPLEval | undefined;
  46. /**
  47. * Defines if the repl prints output previews or not.
  48. * @default `true` Always `false` in case `terminal` is falsy.
  49. */
  50. preview?: boolean | undefined;
  51. /**
  52. * If `true`, specifies that the default `writer` function should include ANSI color
  53. * styling to REPL output. If a custom `writer` function is provided then this has no
  54. * effect.
  55. * @default the REPL instance's `terminal` value
  56. */
  57. useColors?: boolean | undefined;
  58. /**
  59. * If `true`, specifies that the default evaluation function will use the JavaScript
  60. * `global` as the context as opposed to creating a new separate context for the REPL
  61. * instance. The node CLI REPL sets this value to `true`.
  62. * @default false
  63. */
  64. useGlobal?: boolean | undefined;
  65. /**
  66. * If `true`, specifies that the default writer will not output the return value of a
  67. * command if it evaluates to `undefined`.
  68. * @default false
  69. */
  70. ignoreUndefined?: boolean | undefined;
  71. /**
  72. * The function to invoke to format the output of each command before writing to `output`.
  73. * @default a wrapper for `util.inspect`
  74. *
  75. * @see https://nodejs.org/dist/latest-v24.x/docs/api/repl.html#repl_customizing_repl_output
  76. */
  77. writer?: REPLWriter | undefined;
  78. /**
  79. * An optional function used for custom Tab auto completion.
  80. *
  81. * @see https://nodejs.org/dist/latest-v24.x/docs/api/readline.html#readline_use_of_the_completer_function
  82. */
  83. completer?: Completer | AsyncCompleter | undefined;
  84. /**
  85. * A flag that specifies whether the default evaluator executes all JavaScript commands in
  86. * strict mode or default (sloppy) mode.
  87. * Accepted values are:
  88. * - `repl.REPL_MODE_SLOPPY` - evaluates expressions in sloppy mode.
  89. * - `repl.REPL_MODE_STRICT` - evaluates expressions in strict mode. This is equivalent to
  90. * prefacing every repl statement with `'use strict'`.
  91. */
  92. replMode?: typeof REPL_MODE_SLOPPY | typeof REPL_MODE_STRICT | undefined;
  93. /**
  94. * Stop evaluating the current piece of code when `SIGINT` is received, i.e. `Ctrl+C` is
  95. * pressed. This cannot be used together with a custom `eval` function.
  96. * @default false
  97. */
  98. breakEvalOnSigint?: boolean | undefined;
  99. }
  100. type REPLEval = (
  101. this: REPLServer,
  102. evalCmd: string,
  103. context: Context,
  104. file: string,
  105. cb: (err: Error | null, result: any) => void,
  106. ) => void;
  107. type REPLWriter = (this: REPLServer, obj: any) => string;
  108. /**
  109. * This is the default "writer" value, if none is passed in the REPL options,
  110. * and it can be overridden by custom print functions.
  111. */
  112. const writer: REPLWriter & {
  113. options: InspectOptions;
  114. };
  115. type REPLCommandAction = (this: REPLServer, text: string) => void;
  116. interface REPLCommand {
  117. /**
  118. * Help text to be displayed when `.help` is entered.
  119. */
  120. help?: string | undefined;
  121. /**
  122. * The function to execute, optionally accepting a single string argument.
  123. */
  124. action: REPLCommandAction;
  125. }
  126. interface REPLServerSetupHistoryOptions {
  127. filePath?: string | undefined;
  128. size?: number | undefined;
  129. removeHistoryDuplicates?: boolean | undefined;
  130. onHistoryFileLoaded?: ((err: Error | null, repl: REPLServer) => void) | undefined;
  131. }
  132. /**
  133. * Instances of `repl.REPLServer` are created using the {@link start} method
  134. * or directly using the JavaScript `new` keyword.
  135. *
  136. * ```js
  137. * import repl from 'node:repl';
  138. *
  139. * const options = { useColors: true };
  140. *
  141. * const firstInstance = repl.start(options);
  142. * const secondInstance = new repl.REPLServer(options);
  143. * ```
  144. * @since v0.1.91
  145. */
  146. class REPLServer extends Interface {
  147. /**
  148. * The `vm.Context` provided to the `eval` function to be used for JavaScript
  149. * evaluation.
  150. */
  151. readonly context: Context;
  152. /**
  153. * @deprecated since v14.3.0 - Use `input` instead.
  154. */
  155. readonly inputStream: NodeJS.ReadableStream;
  156. /**
  157. * @deprecated since v14.3.0 - Use `output` instead.
  158. */
  159. readonly outputStream: NodeJS.WritableStream;
  160. /**
  161. * The `Readable` stream from which REPL input will be read.
  162. */
  163. readonly input: NodeJS.ReadableStream;
  164. /**
  165. * The `Writable` stream to which REPL output will be written.
  166. */
  167. readonly output: NodeJS.WritableStream;
  168. /**
  169. * The commands registered via `replServer.defineCommand()`.
  170. */
  171. readonly commands: NodeJS.ReadOnlyDict<REPLCommand>;
  172. /**
  173. * A value indicating whether the REPL is currently in "editor mode".
  174. *
  175. * @see https://nodejs.org/dist/latest-v24.x/docs/api/repl.html#repl_commands_and_special_keys
  176. */
  177. readonly editorMode: boolean;
  178. /**
  179. * A value indicating whether the `_` variable has been assigned.
  180. *
  181. * @see https://nodejs.org/dist/latest-v24.x/docs/api/repl.html#repl_assignment_of_the_underscore_variable
  182. */
  183. readonly underscoreAssigned: boolean;
  184. /**
  185. * The last evaluation result from the REPL (assigned to the `_` variable inside of the REPL).
  186. *
  187. * @see https://nodejs.org/dist/latest-v24.x/docs/api/repl.html#repl_assignment_of_the_underscore_variable
  188. */
  189. readonly last: any;
  190. /**
  191. * A value indicating whether the `_error` variable has been assigned.
  192. *
  193. * @since v9.8.0
  194. * @see https://nodejs.org/dist/latest-v24.x/docs/api/repl.html#repl_assignment_of_the_underscore_variable
  195. */
  196. readonly underscoreErrAssigned: boolean;
  197. /**
  198. * The last error raised inside the REPL (assigned to the `_error` variable inside of the REPL).
  199. *
  200. * @since v9.8.0
  201. * @see https://nodejs.org/dist/latest-v24.x/docs/api/repl.html#repl_assignment_of_the_underscore_variable
  202. */
  203. readonly lastError: any;
  204. /**
  205. * Specified in the REPL options, this is the function to be used when evaluating each
  206. * given line of input. If not specified in the REPL options, this is an async wrapper
  207. * for the JavaScript `eval()` function.
  208. */
  209. readonly eval: REPLEval;
  210. /**
  211. * Specified in the REPL options, this is a value indicating whether the default
  212. * `writer` function should include ANSI color styling to REPL output.
  213. */
  214. readonly useColors: boolean;
  215. /**
  216. * Specified in the REPL options, this is a value indicating whether the default `eval`
  217. * function will use the JavaScript `global` as the context as opposed to creating a new
  218. * separate context for the REPL instance.
  219. */
  220. readonly useGlobal: boolean;
  221. /**
  222. * Specified in the REPL options, this is a value indicating whether the default `writer`
  223. * function should output the result of a command if it evaluates to `undefined`.
  224. */
  225. readonly ignoreUndefined: boolean;
  226. /**
  227. * Specified in the REPL options, this is the function to invoke to format the output of
  228. * each command before writing to `outputStream`. If not specified in the REPL options,
  229. * this will be a wrapper for `util.inspect`.
  230. */
  231. readonly writer: REPLWriter;
  232. /**
  233. * Specified in the REPL options, this is the function to use for custom Tab auto-completion.
  234. */
  235. readonly completer: Completer | AsyncCompleter;
  236. /**
  237. * Specified in the REPL options, this is a flag that specifies whether the default `eval`
  238. * function should execute all JavaScript commands in strict mode or default (sloppy) mode.
  239. * Possible values are:
  240. * - `repl.REPL_MODE_SLOPPY` - evaluates expressions in sloppy mode.
  241. * - `repl.REPL_MODE_STRICT` - evaluates expressions in strict mode. This is equivalent to
  242. * prefacing every repl statement with `'use strict'`.
  243. */
  244. readonly replMode: typeof REPL_MODE_SLOPPY | typeof REPL_MODE_STRICT;
  245. /**
  246. * NOTE: According to the documentation:
  247. *
  248. * > Instances of `repl.REPLServer` are created using the `repl.start()` method and
  249. * > _should not_ be created directly using the JavaScript `new` keyword.
  250. *
  251. * `REPLServer` cannot be subclassed due to implementation specifics in NodeJS.
  252. *
  253. * @see https://nodejs.org/dist/latest-v24.x/docs/api/repl.html#repl_class_replserver
  254. */
  255. private constructor();
  256. /**
  257. * The `replServer.defineCommand()` method is used to add new `.`\-prefixed commands
  258. * to the REPL instance. Such commands are invoked by typing a `.` followed by the `keyword`. The `cmd` is either a `Function` or an `Object` with the following
  259. * properties:
  260. *
  261. * The following example shows two new commands added to the REPL instance:
  262. *
  263. * ```js
  264. * import repl from 'node:repl';
  265. *
  266. * const replServer = repl.start({ prompt: '> ' });
  267. * replServer.defineCommand('sayhello', {
  268. * help: 'Say hello',
  269. * action(name) {
  270. * this.clearBufferedCommand();
  271. * console.log(`Hello, ${name}!`);
  272. * this.displayPrompt();
  273. * },
  274. * });
  275. * replServer.defineCommand('saybye', function saybye() {
  276. * console.log('Goodbye!');
  277. * this.close();
  278. * });
  279. * ```
  280. *
  281. * The new commands can then be used from within the REPL instance:
  282. *
  283. * ```console
  284. * > .sayhello Node.js User
  285. * Hello, Node.js User!
  286. * > .saybye
  287. * Goodbye!
  288. * ```
  289. * @since v0.3.0
  290. * @param keyword The command keyword (_without_ a leading `.` character).
  291. * @param cmd The function to invoke when the command is processed.
  292. */
  293. defineCommand(keyword: string, cmd: REPLCommandAction | REPLCommand): void;
  294. /**
  295. * The `replServer.displayPrompt()` method readies the REPL instance for input
  296. * from the user, printing the configured `prompt` to a new line in the `output` and resuming the `input` to accept new input.
  297. *
  298. * When multi-line input is being entered, a pipe `'|'` is printed rather than the
  299. * 'prompt'.
  300. *
  301. * When `preserveCursor` is `true`, the cursor placement will not be reset to `0`.
  302. *
  303. * The `replServer.displayPrompt` method is primarily intended to be called from
  304. * within the action function for commands registered using the `replServer.defineCommand()` method.
  305. * @since v0.1.91
  306. */
  307. displayPrompt(preserveCursor?: boolean): void;
  308. /**
  309. * The `replServer.clearBufferedCommand()` method clears any command that has been
  310. * buffered but not yet executed. This method is primarily intended to be
  311. * called from within the action function for commands registered using the `replServer.defineCommand()` method.
  312. * @since v9.0.0
  313. */
  314. clearBufferedCommand(): void;
  315. /**
  316. * Initializes a history log file for the REPL instance. When executing the
  317. * Node.js binary and using the command-line REPL, a history file is initialized
  318. * by default. However, this is not the case when creating a REPL
  319. * programmatically. Use this method to initialize a history log file when working
  320. * with REPL instances programmatically.
  321. * @since v11.10.0
  322. * @param historyPath the path to the history file
  323. * @param callback called when history writes are ready or upon error
  324. */
  325. setupHistory(historyPath: string, callback: (err: Error | null, repl: this) => void): void;
  326. setupHistory(
  327. historyConfig?: REPLServerSetupHistoryOptions,
  328. callback?: (err: Error | null, repl: this) => void,
  329. ): void;
  330. /**
  331. * events.EventEmitter
  332. * 1. close - inherited from `readline.Interface`
  333. * 2. line - inherited from `readline.Interface`
  334. * 3. pause - inherited from `readline.Interface`
  335. * 4. resume - inherited from `readline.Interface`
  336. * 5. SIGCONT - inherited from `readline.Interface`
  337. * 6. SIGINT - inherited from `readline.Interface`
  338. * 7. SIGTSTP - inherited from `readline.Interface`
  339. * 8. exit
  340. * 9. reset
  341. */
  342. addListener(event: string, listener: (...args: any[]) => void): this;
  343. addListener(event: "close", listener: () => void): this;
  344. addListener(event: "line", listener: (input: string) => void): this;
  345. addListener(event: "pause", listener: () => void): this;
  346. addListener(event: "resume", listener: () => void): this;
  347. addListener(event: "SIGCONT", listener: () => void): this;
  348. addListener(event: "SIGINT", listener: () => void): this;
  349. addListener(event: "SIGTSTP", listener: () => void): this;
  350. addListener(event: "exit", listener: () => void): this;
  351. addListener(event: "reset", listener: (context: Context) => void): this;
  352. emit(event: string | symbol, ...args: any[]): boolean;
  353. emit(event: "close"): boolean;
  354. emit(event: "line", input: string): boolean;
  355. emit(event: "pause"): boolean;
  356. emit(event: "resume"): boolean;
  357. emit(event: "SIGCONT"): boolean;
  358. emit(event: "SIGINT"): boolean;
  359. emit(event: "SIGTSTP"): boolean;
  360. emit(event: "exit"): boolean;
  361. emit(event: "reset", context: Context): boolean;
  362. on(event: string, listener: (...args: any[]) => void): this;
  363. on(event: "close", listener: () => void): this;
  364. on(event: "line", listener: (input: string) => void): this;
  365. on(event: "pause", listener: () => void): this;
  366. on(event: "resume", listener: () => void): this;
  367. on(event: "SIGCONT", listener: () => void): this;
  368. on(event: "SIGINT", listener: () => void): this;
  369. on(event: "SIGTSTP", listener: () => void): this;
  370. on(event: "exit", listener: () => void): this;
  371. on(event: "reset", listener: (context: Context) => void): this;
  372. once(event: string, listener: (...args: any[]) => void): this;
  373. once(event: "close", listener: () => void): this;
  374. once(event: "line", listener: (input: string) => void): this;
  375. once(event: "pause", listener: () => void): this;
  376. once(event: "resume", listener: () => void): this;
  377. once(event: "SIGCONT", listener: () => void): this;
  378. once(event: "SIGINT", listener: () => void): this;
  379. once(event: "SIGTSTP", listener: () => void): this;
  380. once(event: "exit", listener: () => void): this;
  381. once(event: "reset", listener: (context: Context) => void): this;
  382. prependListener(event: string, listener: (...args: any[]) => void): this;
  383. prependListener(event: "close", listener: () => void): this;
  384. prependListener(event: "line", listener: (input: string) => void): this;
  385. prependListener(event: "pause", listener: () => void): this;
  386. prependListener(event: "resume", listener: () => void): this;
  387. prependListener(event: "SIGCONT", listener: () => void): this;
  388. prependListener(event: "SIGINT", listener: () => void): this;
  389. prependListener(event: "SIGTSTP", listener: () => void): this;
  390. prependListener(event: "exit", listener: () => void): this;
  391. prependListener(event: "reset", listener: (context: Context) => void): this;
  392. prependOnceListener(event: string, listener: (...args: any[]) => void): this;
  393. prependOnceListener(event: "close", listener: () => void): this;
  394. prependOnceListener(event: "line", listener: (input: string) => void): this;
  395. prependOnceListener(event: "pause", listener: () => void): this;
  396. prependOnceListener(event: "resume", listener: () => void): this;
  397. prependOnceListener(event: "SIGCONT", listener: () => void): this;
  398. prependOnceListener(event: "SIGINT", listener: () => void): this;
  399. prependOnceListener(event: "SIGTSTP", listener: () => void): this;
  400. prependOnceListener(event: "exit", listener: () => void): this;
  401. prependOnceListener(event: "reset", listener: (context: Context) => void): this;
  402. }
  403. /**
  404. * A flag passed in the REPL options. Evaluates expressions in sloppy mode.
  405. */
  406. const REPL_MODE_SLOPPY: unique symbol;
  407. /**
  408. * A flag passed in the REPL options. Evaluates expressions in strict mode.
  409. * This is equivalent to prefacing every repl statement with `'use strict'`.
  410. */
  411. const REPL_MODE_STRICT: unique symbol;
  412. /**
  413. * The `repl.start()` method creates and starts a {@link REPLServer} instance.
  414. *
  415. * If `options` is a string, then it specifies the input prompt:
  416. *
  417. * ```js
  418. * import repl from 'node:repl';
  419. *
  420. * // a Unix style prompt
  421. * repl.start('$ ');
  422. * ```
  423. * @since v0.1.91
  424. */
  425. function start(options?: string | ReplOptions): REPLServer;
  426. /**
  427. * Indicates a recoverable error that a `REPLServer` can use to support multi-line input.
  428. *
  429. * @see https://nodejs.org/dist/latest-v24.x/docs/api/repl.html#repl_recoverable_errors
  430. */
  431. class Recoverable extends SyntaxError {
  432. err: Error;
  433. constructor(err: Error);
  434. }
  435. }
  436. declare module "node:repl" {
  437. export * from "repl";
  438. }