node_modules/node-pty/typings/node-pty.d.ts

   1 /**
   2  * Copyright (c) 2017, Daniel Imms (MIT License).
   3  * Copyright (c) 2018, Microsoft Corporation (MIT License).
   4  */
   5
   6 declare module 'node-pty' {
   7   /**
   8    * Forks a process as a pseudoterminal.
   9    * @param file The file to launch.
  10    * @param args The file's arguments as argv (string[]) or in a pre-escaped CommandLine format
  11    * (string). Note that the CommandLine option is only available on Windows and is expected to be
  12    * escaped properly.
  13    * @param options The options of the terminal.
  14    * @see CommandLineToArgvW https://msdn.microsoft.com/en-us/library/windows/desktop/bb776391(v=vs.85).aspx
  15    * @see Parsing C++ Comamnd-Line Arguments https://msdn.microsoft.com/en-us/library/17w5ykft.aspx
  16    * @see GetCommandLine https://msdn.microsoft.com/en-us/library/windows/desktop/ms683156.aspx
  17    */
  18   export function spawn(file: string, args: string[] | string, options: IPtyForkOptions | IWindowsPtyForkOptions): IPty;
  19
  20   export interface IBasePtyForkOptions {
  21
  22     /**
  23      * Name of the terminal to be set in environment ($TERM variable).
  24      */
  25     name?: string;
  26
  27     /**
  28      * Number of intial cols of the pty.
  29      */
  30     cols?: number;
  31
  32     /**
  33      * Number of initial rows of the pty.
  34      */
  35     rows?: number;
  36
  37     /**
  38      * Working directory to be set for the slave program.
  39      */
  40     cwd?: string;
  41
  42     /**
  43      * Environment to be set for the slave program.
  44      */
  45     env?: { [key: string]: string };
  46
  47     /**
  48      * String encoding of the underlying pty.
  49      * If set, incoming data will be decoded to strings and outgoing strings to bytes applying this encoding.
  50      * If unset, incoming data will be delivered as raw bytes (Buffer type).
  51      * By default 'utf8' is assumed, to unset it explicitly set it to `null`.
  52      */
  53     encoding?: string | null;
  54
  55     /**
  56      * (EXPERIMENTAL)
  57      * Whether to enable flow control handling (false by default). If enabled a message of `flowControlPause`
  58      * will pause the socket and thus blocking the slave program execution due to buffer back pressure.
  59      * A message of `flowControlResume` will resume the socket into flow mode.
  60      * For performance reasons only a single message as a whole will match (no message part matching).
  61      * If flow control is enabled the `flowControlPause` and `flowControlResume` messages are not forwarded to
  62      * the underlying pseudoterminal.
  63      */
  64     handleFlowControl?: boolean;
  65
  66     /**
  67      * (EXPERIMENTAL)
  68      * The string that should pause the pty when `handleFlowControl` is true. Default is XOFF ('\x13').
  69      */
  70     flowControlPause?: string;
  71
  72     /**
  73      * (EXPERIMENTAL)
  74      * The string that should resume the pty when `handleFlowControl` is true. Default is XON ('\x11').
  75      */
  76     flowControlResume?: string;
  77   }
  78
  79   export interface IPtyForkOptions extends IBasePtyForkOptions {
  80     /**
  81      * Security warning: use this option with great caution, as opened file descriptors
  82      * with higher privileges might leak to the slave program.
  83      */
  84     uid?: number;
  85     gid?: number;
  86   }
  87
  88   export interface IWindowsPtyForkOptions extends IBasePtyForkOptions {
  89     /**
  90      * Whether to use the ConPTY system on Windows. When this is not set, ConPTY will be used when
  91      * the Windows build number is >= 18309 (instead of winpty). Note that ConPTY is available from
  92      * build 17134 but is too unstable to enable by default.
  93      *
  94      * This setting does nothing on non-Windows.
  95      */
  96     useConpty?: boolean;
  97
  98     /**
  99      * Whether to use PSEUDOCONSOLE_INHERIT_CURSOR in conpty.
 100      * @see https://docs.microsoft.com/en-us/windows/console/createpseudoconsole
 101      */
 102     conptyInheritCursor?: boolean;
 103   }
 104
 105   /**
 106    * An interface representing a pseudoterminal, on Windows this is emulated via the winpty library.
 107    */
 108   export interface IPty {
 109     /**
 110      * The process ID of the outer process.
 111      */
 112     readonly pid: number;
 113
 114     /**
 115      * The column size in characters.
 116      */
 117     readonly cols: number;
 118
 119     /**
 120      * The row size in characters.
 121      */
 122     readonly rows: number;
 123
 124     /**
 125      * The title of the active process.
 126      */
 127     readonly process: string;
 128
 129     /**
 130      * (EXPERIMENTAL)
 131      * Whether to handle flow control. Useful to disable/re-enable flow control during runtime.
 132      * Use this for binary data that is likely to contain the `flowControlPause` string by accident.
 133      */
 134     handleFlowControl: boolean;
 135
 136     /**
 137      * Adds an event listener for when a data event fires. This happens when data is returned from
 138      * the pty.
 139      * @returns an `IDisposable` to stop listening.
 140      */
 141     readonly onData: IEvent<string>;
 142
 143     /**
 144      * Adds an event listener for when an exit event fires. This happens when the pty exits.
 145      * @returns an `IDisposable` to stop listening.
 146      */
 147     readonly onExit: IEvent<{ exitCode: number, signal?: number }>;
 148
 149     /**
 150      * Adds a listener to the data event, fired when data is returned from the pty.
 151      * @param event The name of the event.
 152      * @param listener The callback function.
 153      * @deprecated Use IPty.onData
 154      */
 155     on(event: 'data', listener: (data: string) => void): void;
 156
 157     /**
 158      * Adds a listener to the exit event, fired when the pty exits.
 159      * @param event The name of the event.
 160      * @param listener The callback function, exitCode is the exit code of the process and signal is
 161      * the signal that triggered the exit. signal is not supported on Windows.
 162      * @deprecated Use IPty.onExit
 163      */
 164     on(event: 'exit', listener: (exitCode: number, signal?: number) => void): void;
 165
 166     /**
 167      * Resizes the dimensions of the pty.
 168      * @param columns THe number of columns to use.
 169      * @param rows The number of rows to use.
 170      */
 171     resize(columns: number, rows: number): void;
 172
 173     /**
 174      * Writes data to the pty.
 175      * @param data The data to write.
 176      */
 177     write(data: string): void;
 178
 179     /**
 180      * Kills the pty.
 181      * @param signal The signal to use, defaults to SIGHUP. This parameter is not supported on
 182      * Windows.
 183      * @throws Will throw when signal is used on Windows.
 184      */
 185     kill(signal?: string): void;
 186   }
 187
 188   /**
 189    * An object that can be disposed via a dispose function.
 190    */
 191   export interface IDisposable {
 192     dispose(): void;
 193   }
 194
 195   /**
 196    * An event that can be listened to.
 197    * @returns an `IDisposable` to stop listening.
 198    */
 199   export interface IEvent<T> {
 200     (listener: (e: T) => any): IDisposable;
 201   }
 202 }