@karinjs/node-pty/dist/index.d.ts

Fork pseudoterminals in Node.JS

//#region src/interfaces.d.ts
/**
 * Copyright (c) 2016, Daniel Imms (MIT License).
 * Copyright (c) 2018, Microsoft Corporation (MIT License).
 */
interface IProcessEnv {
  [key: string]: string | undefined;
}
interface IBasePtyForkOptions {
  name?: string;
  cols?: number;
  rows?: number;
  cwd?: string;
  env?: IProcessEnv;
  encoding?: string | null;
  handleFlowControl?: boolean;
  flowControlPause?: string;
  flowControlResume?: string;
}
interface IPtyForkOptions extends IBasePtyForkOptions {
  uid?: number;
  gid?: number;
}
interface IWindowsPtyForkOptions extends IBasePtyForkOptions {
  useConpty?: boolean;
  useConptyDll?: boolean;
  conptyInheritCursor?: boolean;
}
interface IPtyOpenOptions {
  cols?: number;
  rows?: number;
  encoding?: string | null;
}
//#endregion
//#region src/types.d.ts
/**
 * Copyright (c) 2017, Daniel Imms (MIT License).
 * Copyright (c) 2018, Microsoft Corporation (MIT License).
 */
type ArgvOrCommandLine = string[] | string;
interface IDisposable {
  dispose(): void;
}
/**
 * An interface representing a pseudoterminal, on Windows this is emulated via the winpty library.
 */
interface ITerminal {
  /**
   * The process ID of the outer process.
   */
  readonly pid: number;
  /**
   * The column size in characters.
   */
  readonly cols: number;
  /**
   * The row size in characters.
   */
  readonly rows: number;
  /**
   * The title of the active process.
   */
  readonly process: string;
  /**
   * (EXPERIMENTAL)
   * Whether to handle flow control. Useful to disable/re-enable flow control during runtime.
   * Use this for binary data that is likely to contain the `flowControlPause` string by accident.
   */
  handleFlowControl: boolean;
  /**
   * Adds an event listener for when a data event fires. This happens when data is returned from
   * the pty.
   * @returns an `IDisposable` to stop listening.
   */
  readonly onData: IEvent<string>;
  /**
   * Adds an event listener for when an exit event fires. This happens when the pty exits.
   * @returns an `IDisposable` to stop listening.
   */
  readonly onExit: IEvent<{
    exitCode: number;
    signal?: number;
  }>;
  /**
   * Resizes the dimensions of the pty.
   * @param columns The number of columns to use.
   * @param rows The number of rows to use.
   */
  resize(columns: number, rows: number): void;
  /**
  * Adds a listener to the data event, fired when data is returned from the pty.
  * @param event The name of the event.
  * @param listener The callback function.
  * @deprecated Use IPty.onData
  */
  on(event: 'data', listener: (data: string) => void): void;
  /**
   * Adds a listener to the exit event, fired when the pty exits.
   * @param event The name of the event.
   * @param listener The callback function, exitCode is the exit code of the process and signal is
   * the signal that triggered the exit. signal is not supported on Windows.
   * @deprecated Use IPty.onExit
   */
  on(event: 'exit', listener: (exitCode: number, signal?: number) => void): void;
  /**
   * Clears the pty's internal representation of its buffer. This is a no-op
   * unless on Windows/ConPTY. This is useful if the buffer is cleared on the
   * frontend in order to synchronize state with the backend to avoid ConPTY
   * possibly reprinting the screen.
   */
  clear(): void;
  /**
   * Writes data to the pty.
   * @param data The data to write.
   */
  write(data: string): void;
  /**
   * Kills the pty.
   * @param signal The signal to use, defaults to SIGHUP. This parameter is not supported on
   * Windows.
   * @throws Will throw when signal is used on Windows.
   */
  kill(signal?: string): void;
  /**
   * Pauses the pty for customizable flow control.
   */
  pause(): void;
  /**
   * Resumes the pty for customizable flow control.
   */
  resume(): void;
}
/**
 * An object that can be disposed via a dispose function.
 */
interface IDisposable {
  dispose(): void;
}
/**
 * An event that can be listened to.
 * @returns an `IDisposable` to stop listening.
 */
interface IEvent<T> {
  (listener: (e: T) => any): IDisposable;
}
//#endregion
//#region src/index.d.ts
/**
 * Forks a process as a pseudoterminal.
 * @param file The file to launch.
 * @param args The file's arguments as argv (string[]) or in a pre-escaped
 * CommandLine format (string). Note that the CommandLine option is only
 * available on Windows and is expected to be escaped properly.
 * @param options The options of the terminal.
 * @throws When the file passed to spawn with does not exists.
 * @see CommandLineToArgvW https://msdn.microsoft.com/en-us/library/windows/desktop/bb776391(v=vs.85).aspx
 * @see Parsing C++ Comamnd-Line Arguments https://msdn.microsoft.com/en-us/library/17w5ykft.aspx
 * @see GetCommandLine https://msdn.microsoft.com/en-us/library/windows/desktop/ms683156.aspx
 */
declare function spawn(file?: string, args?: ArgvOrCommandLine, opt?: IPtyForkOptions | IWindowsPtyForkOptions): ITerminal;
/** @deprecated */
declare function fork(file?: string, args?: ArgvOrCommandLine, opt?: IPtyForkOptions | IWindowsPtyForkOptions): ITerminal;
/** @deprecated */
declare function createTerminal(file?: string, args?: ArgvOrCommandLine, opt?: IPtyForkOptions | IWindowsPtyForkOptions): ITerminal;
declare function open(options: IPtyOpenOptions): ITerminal;
/**
 * Expose the native API when not Windows, note that this is not public API and
 * could be removed at any time.
 */
declare const native: any;
//#endregion
export { createTerminal, fork, native, open, spawn };