teen_process 3.0.6 → 4.0.1

package/lib/exec.ts

@@ -0,0 +1,158 @@
+import {spawn} from 'node:child_process';
+import {quote} from 'shell-quote';
+import B from 'bluebird';
+import _ from 'lodash';
+import {formatEnoent} from './helpers';
+import {CircularBuffer, MAX_BUFFER_SIZE} from './circular-buffer';
+import type {
+    TeenProcessExecOptions,
+    ExecResult,
+    BufferProp,
+    TeenProcessExecError,
+    StreamName
+} from './types';
+
+
+/**
+ * Spawns a child process and collects its output.
+ *
+ * This is a promisified version of Node's spawn that collects stdout and stderr,
+ * handles timeouts, and provides error context.
+ *
+ * @template T - The options type extending TeenProcessExecOptions
+ * @param cmd - The command to execute
+ * @param args - Array of arguments to pass to the command (default: [])
+ * @param originalOpts - Execution options including timeout, encoding, environment, etc.
+ * @returns Promise resolving to an object with stdout, stderr, and exit code
+ *
+ * @throws {TeenProcessExecError} When the process exits with non-zero code or times out
+ *
+ * @example
+ * ```typescript
+ * // Simple execution
+ * const {stdout, stderr, code} = await exec('ls', ['-la']);
+ *
+ * // With timeout and custom encoding
+ * const result = await exec('long-running-cmd', [], {
+ *   timeout: 5000,
+ *   encoding: 'utf8',
+ *   cwd: '/custom/path'
+ * });
+ *
+ * // Return output as Buffer
+ * const {stdout} = await exec('cat', ['image.png'], {isBuffer: true});
+ * ```
+ */
+export async function exec<T extends TeenProcessExecOptions = TeenProcessExecOptions>(
+  cmd: string,
+  args: string[] = [],
+  originalOpts: T = {} as T,
+): Promise<ExecResult<BufferProp<T>>> {
+  // get a quoted representation of the command for error strings
+  const rep = quote([cmd, ...args]);
+
+  const defaults: TeenProcessExecOptions = {
+    timeout: undefined,
+    encoding: 'utf8',
+    killSignal: 'SIGTERM',
+    cwd: undefined,
+    env: process.env,
+    ignoreOutput: false,
+    stdio: 'inherit',
+    isBuffer: false,
+    shell: undefined,
+    logger: undefined,
+    maxStdoutBufferSize: MAX_BUFFER_SIZE,
+    maxStderrBufferSize: MAX_BUFFER_SIZE,
+  };
+
+  const opts = _.defaults({}, originalOpts, defaults) as T;
+  const isBuffer = Boolean(opts.isBuffer);
+
+  return await new B<ExecResult<BufferProp<T>>>((resolve, reject) => {
+    const proc = spawn(cmd, args, {cwd: opts.cwd, env: opts.env, shell: opts.shell});
+    const stdoutBuffer = new CircularBuffer(opts.maxStdoutBufferSize);
+    const stderrBuffer = new CircularBuffer(opts.maxStderrBufferSize);
+    let timer: NodeJS.Timeout | null = null;
+
+    proc.on('error', async (err: NodeJS.ErrnoException) => {
+      let error = err;
+      if (error.code === 'ENOENT') {
+        error = await formatEnoent(error, cmd, opts.cwd?.toString());
+      }
+      reject(error);
+    });
+
+    if (proc.stdin) {
+      proc.stdin.on('error', (err: NodeJS.ErrnoException) => {
+        reject(new Error(`Standard input '${err.syscall}' error: ${err.stack}`));
+      });
+    }
+
+    const handleStream = (streamType: StreamName, buffer: CircularBuffer) => {
+      const stream = proc[streamType];
+      if (!stream) {
+        return;
+      }
+
+      stream.on('error', (err: NodeJS.ErrnoException) => {
+        reject(new Error(`${_.capitalize(streamType)} '${err.syscall}' error: ${err.stack}`));
+      });
+
+      if (opts.ignoreOutput) {
+        // https://github.com/nodejs/node/issues/4236
+        stream.on('data', () => {});
+        return;
+      }
+
+      stream.on('data', (chunk: Buffer) => {
+        buffer.add(chunk);
+        if (opts.logger?.debug && _.isFunction(opts.logger.debug)) {
+          opts.logger.debug(chunk.toString());
+        }
+      });
+    };
+
+    handleStream('stdout', stdoutBuffer);
+    handleStream('stderr', stderrBuffer);
+
+    function getStdio<U extends boolean>(
+      wantBuffer: U,
+    ): U extends true ? {stdout: Buffer; stderr: Buffer} : {stdout: string; stderr: string} {
+      const stdout = wantBuffer ? stdoutBuffer.value() : stdoutBuffer.value().toString(opts.encoding);
+      const stderr = wantBuffer ? stderrBuffer.value() : stderrBuffer.value().toString(opts.encoding);
+      return {stdout, stderr} as U extends true
+        ? {stdout: Buffer; stderr: Buffer}
+        : {stdout: string; stderr: string};
+    }
+
+    proc.on('close', (code: number | null) => {
+      if (timer) {
+        clearTimeout(timer);
+      }
+      const {stdout, stderr} = getStdio(isBuffer);
+      if (code === 0) {
+        resolve({stdout, stderr, code} as ExecResult<BufferProp<T>>);
+      } else {
+        const err = Object.assign(new Error(`Command '${rep}' exited with code ${code}`), {
+          stdout,
+          stderr,
+          code,
+        }) as TeenProcessExecError;
+        reject(err);
+      }
+    });
+
+    if (opts.timeout) {
+      timer = setTimeout(() => {
+        const {stdout, stderr} = getStdio(isBuffer);
+        const err = Object.assign(
+          new Error(`Command '${rep}' timed out after ${opts.timeout}ms`),
+          {stdout, stderr, code: null},
+        ) as TeenProcessExecError;
+        reject(err);
+        proc.kill(opts.killSignal ?? 'SIGTERM');
+      }, opts.timeout);
+    }
+  });
+}

package/lib/helpers.ts

@@ -0,0 +1,44 @@
+import path from 'node:path';
+import fs from 'node:fs/promises';
+
+/**
+ * Enhances ENOENT errors from spawn with descriptive messages.
+ *
+ * This is an internal helper that mutates the error object to provide context about:
+ * - Invalid working directory paths
+ * - Missing executables in PATH
+ *
+ * @param error - The original ENOENT error from spawn
+ * @param cmd - The command that was attempted to execute
+ * @param cwd - The working directory used (if any)
+ * @returns The same error object with an enhanced message
+ *
+ * @internal
+ */
+export async function formatEnoent(
+  error: NodeJS.ErrnoException,
+  cmd: string,
+  cwd?: string,
+): Promise<NodeJS.ErrnoException> {
+  if (cwd) {
+    try {
+      const stat = await fs.stat(cwd);
+      if (!stat.isDirectory()) {
+        error.message = `The working directory '${cwd}' of '${cmd}' is not a valid folder path`;
+        return error;
+      }
+    } catch (e) {
+      const err = e as NodeJS.ErrnoException;
+      if (err.code === 'ENOENT') {
+        error.message = `The working directory '${cwd}' of '${cmd}' does not exist`;
+        return error;
+      }
+    }
+  }
+
+  const curDir = path.resolve(cwd ?? process.cwd());
+  const pathMsg = process.env.PATH ?? 'which is not defined for the process';
+  error.message = `'${cmd}' executable is not found neither in the process working folder (${curDir}) ` +
+    `nor in any folders specified in the PATH environment variable (${pathMsg})`;
+  return error;
+}

package/lib/index.ts

@@ -0,0 +1,8 @@
+export {spawn} from 'node:child_process';
+export {SubProcess} from './subprocess';
+export {exec} from './exec';
+export type {
+  TeenProcessExecOptions,
+  ExecResult,
+  SubProcessOptions
+} from './types';

package/lib/subprocess.ts

@@ -0,0 +1,353 @@
+import {spawn} from 'node:child_process';
+import type {ChildProcess} from 'node:child_process';
+import {EventEmitter} from 'node:events';
+import B from 'bluebird';
+import {quote} from 'shell-quote';
+import _ from 'lodash';
+import {formatEnoent} from './helpers';
+import {createInterface} from 'node:readline';
+import type {Readable} from 'node:stream';
+import type {
+    SubProcessOptions,
+    StartDetector,
+    TIsBufferOpts,
+    StreamName
+} from './types';
+
+/**
+ * A wrapper around Node's spawn that provides event-driven process management.
+ *
+ * Extends EventEmitter to provide real-time output streaming and lifecycle events.
+ *
+ * @template TSubProcessOptions - Options type extending SubProcessOptions
+ *
+ * @fires SubProcess#output - Emitted when stdout or stderr receives data
+ * @fires SubProcess#line-stdout - Emitted for each line of stdout
+ * @fires SubProcess#line-stderr - Emitted for each line of stderr
+ * @fires SubProcess#lines-stdout - Legacy event emitting stdout lines (deprecated)
+ * @fires SubProcess#lines-stderr - Legacy event emitting stderr lines (deprecated)
+ * @fires SubProcess#stream-line - Emitted for combined stdout/stderr lines
+ * @fires SubProcess#exit - Emitted when process exits
+ * @fires SubProcess#stop - Emitted when process is stopped intentionally
+ * @fires SubProcess#die - Emitted when process dies unexpectedly with non-zero code
+ * @fires SubProcess#end - Emitted when process ends normally with code 0
+ *
+ * @example
+ * ```typescript
+ * const proc = new SubProcess('tail', ['-f', 'logfile.txt']);
+ *
+ * proc.on('output', (stdout, stderr) => {
+ *   console.log('Output:', stdout);
+ * });
+ *
+ * proc.on('line-stdout', (line) => {
+ *   console.log('Line:', line);
+ * });
+ *
+ * await proc.start();
+ * // ... later
+ * await proc.stop();
+ * ```
+ */
+export class SubProcess<
+  TSubProcessOptions extends SubProcessOptions = SubProcessOptions,
+> extends EventEmitter {
+  private proc: ChildProcess | null;
+  private args: string[];
+  private cmd: string;
+  private opts: TSubProcessOptions;
+  private expectingExit: boolean;
+  private readonly rep: string;
+
+  constructor(cmd: string, args: string[] = [], opts?: TSubProcessOptions) {
+    super();
+
+    if (!cmd) {
+      throw new Error('Command is required');
+    }
+
+    if (!_.isString(cmd)) {
+      throw new Error('Command must be a string');
+    }
+
+    if (!_.isArray(args)) {
+      throw new Error('Args must be an array');
+    }
+
+    this.cmd = cmd;
+    this.args = args;
+    this.proc = null;
+    this.opts = opts ?? ({} as TSubProcessOptions);
+    this.expectingExit = false;
+
+    this.rep = quote([cmd, ...args]);
+  }
+
+  get isRunning(): boolean {
+    return !!this.proc;
+  }
+
+  /**
+   * Starts the subprocess and waits for it to be ready.
+   *
+   * @param startDetector - Function to detect when process is ready, number for delay in ms,
+   *                        boolean true to detach immediately, or null for default behavior
+   * @param timeoutMs - Maximum time to wait for process to start (in ms), or boolean true to detach
+   * @param detach - Whether to detach the process (requires 'detached' option)
+   *
+   * @throws {Error} When process fails to start or times out
+   *
+   * @example
+   * ```typescript
+   * // Wait for any output
+   * await proc.start();
+   *
+   * // Wait 100ms then continue
+   * await proc.start(100);
+   *
+   * // Wait for specific output
+   * await proc.start((stdout) => stdout.includes('Server ready'));
+   *
+   * // With timeout
+   * await proc.start(null, 5000);
+   * ```
+   */
+  async start(
+    startDetector: StartDetector<TSubProcessOptions> | number | boolean | null = null,
+    timeoutMs: number | boolean | null = null,
+    detach: boolean = false,
+  ): Promise<void> {
+    let startDelay = 10;
+
+    const genericStartDetector: StartDetector<TSubProcessOptions> = (stdout, stderr) => stdout || stderr;
+    let detector: StartDetector<TSubProcessOptions> | null = null;
+
+    if (startDetector === null) {
+      detector = genericStartDetector;
+    }
+
+    if (_.isNumber(startDetector)) {
+      startDelay = startDetector;
+      detector = null;
+    } else if (_.isFunction(startDetector)) {
+      detector = startDetector;
+    }
+
+    if (_.isBoolean(startDetector) && startDetector) {
+      if (!this.opts.detached) {
+        throw new Error(`Unable to detach process that is not started with 'detached' option`);
+      }
+      detach = true;
+      detector = genericStartDetector;
+    } else if (_.isBoolean(timeoutMs) && timeoutMs) {
+      if (!this.opts.detached) {
+        throw new Error(`Unable to detach process that is not started with 'detached' option`);
+      }
+      detach = true;
+      timeoutMs = null;
+    }
+
+    return await new B<void>((resolve, reject) => {
+      this.proc = spawn(this.cmd, this.args, this.opts);
+
+      const handleOutput = (streams: {
+        stdout: TSubProcessOptions extends TIsBufferOpts ? Buffer : string;
+        stderr: TSubProcessOptions extends TIsBufferOpts ? Buffer : string;
+      }) => {
+        const {stdout, stderr} = streams;
+
+        try {
+          if (detector && detector(stdout, stderr)) {
+            detector = null;
+            resolve();
+          }
+        } catch (e) {
+          reject(e as Error);
+        }
+
+        this.emit('output', stdout, stderr);
+      };
+
+      this.proc.on('error', async (err: NodeJS.ErrnoException) => {
+        this.proc?.removeAllListeners('exit');
+        this.proc?.kill('SIGINT');
+
+        let error = err;
+        if (error.code === 'ENOENT') {
+          error = await formatEnoent(error, this.cmd, this.opts?.cwd?.toString());
+        }
+        reject(error);
+
+        this.proc?.unref();
+        this.proc = null;
+      });
+
+      const handleStreamLines = (streamName: StreamName, input: Readable) => {
+        const rl = createInterface({input});
+        rl.on('line', (line) => {
+          if (this.listenerCount(`lines-${streamName}`)) {
+            this.emit(`lines-${streamName}`, [line]);
+          }
+          this.emit(`line-${streamName}`, line);
+          if (this.listenerCount('stream-line')) {
+            this.emitLines(streamName, line);
+          }
+        });
+      };
+
+      const isBuffer = Boolean(this.opts.isBuffer);
+      const encoding = this.opts.encoding || 'utf8';
+
+      if (this.proc.stdout) {
+        this.proc.stdout.on('data', (chunk: Buffer) =>
+          handleOutput({
+            stdout: (isBuffer ? chunk : chunk.toString(encoding)) as TSubProcessOptions extends TIsBufferOpts
+              ? Buffer
+              : string,
+            stderr: (isBuffer ? Buffer.alloc(0) : '') as TSubProcessOptions extends TIsBufferOpts ? Buffer : string,
+          }),
+        );
+        handleStreamLines('stdout', this.proc.stdout);
+      }
+
+      if (this.proc.stderr) {
+        this.proc.stderr.on('data', (chunk: Buffer) =>
+          handleOutput({
+            stdout: (isBuffer ? Buffer.alloc(0) : '') as TSubProcessOptions extends TIsBufferOpts ? Buffer : string,
+            stderr: (isBuffer ? chunk : chunk.toString(encoding)) as TSubProcessOptions extends TIsBufferOpts
+              ? Buffer
+              : string,
+          }),
+        );
+        handleStreamLines('stderr', this.proc.stderr);
+      }
+
+      this.proc.on('exit', (code: number | null, signal: NodeJS.Signals | null) => {
+        this.emit('exit', code, signal);
+
+        let event: 'stop' | 'die' | 'end' = this.expectingExit ? 'stop' : 'die';
+        if (!this.expectingExit && code === 0) {
+          event = 'end';
+        }
+        this.emit(event, code, signal);
+
+        this.proc = null;
+        this.expectingExit = false;
+      });
+
+      if (!detector) {
+        setTimeout(() => resolve(), startDelay);
+      }
+
+      if (_.isNumber(timeoutMs)) {
+        setTimeout(() => {
+          reject(new Error(`The process did not start within ${timeoutMs}ms (cmd: '${this.rep}')`));
+        }, timeoutMs);
+      }
+    }).finally(() => {
+      if (detach && this.proc) {
+        this.proc.unref();
+      }
+    });
+  }
+
+  /**
+   * Stops the running subprocess by sending a signal.
+   *
+   * @param signal - Signal to send to the process (default: 'SIGTERM')
+   * @param timeout - Maximum time to wait for process to exit in ms (default: 10000)
+   *
+   * @throws {Error} When process is not running or doesn't exit within timeout
+   *
+   * @example
+   * ```typescript
+   * // Graceful stop with SIGTERM
+   * await proc.stop();
+   *
+   * // Force kill with SIGKILL
+   * await proc.stop('SIGKILL');
+   *
+   * // Custom timeout
+   * await proc.stop('SIGTERM', 5000);
+   * ```
+   */
+  async stop(signal: NodeJS.Signals = 'SIGTERM', timeout = 10000): Promise<void> {
+    if (!this.isRunning) {
+      throw new Error(`Can't stop process; it's not currently running (cmd: '${this.rep}')`);
+    }
+    return await new B<void>((resolve, reject) => {
+      this.proc?.on('close', () => resolve());
+      this.expectingExit = true;
+      this.proc?.kill(signal);
+      setTimeout(() => {
+        reject(new Error(`Process didn't end after ${timeout}ms (cmd: '${this.rep}')`));
+      }, timeout).unref();
+    });
+  }
+
+  /**
+   * Waits for the process to exit and validates its exit code.
+   *
+   * @param allowedExitCodes - Array of acceptable exit codes (default: [0])
+   * @returns Promise resolving to the exit code
+   *
+   * @throws {Error} When process is not running or exits with disallowed code
+   *
+   * @example
+   * ```typescript
+   * // Wait for successful exit (code 0)
+   * const code = await proc.join();
+   *
+   * // Allow multiple exit codes
+   * const code = await proc.join([0, 1, 2]);
+   * ```
+   */
+  async join(allowedExitCodes: number[] = [0]): Promise<number | null> {
+    if (!this.isRunning) {
+      throw new Error(`Cannot join process; it is not currently running (cmd: '${this.rep}')`);
+    }
+
+    return await new B<number | null>((resolve, reject) => {
+      this.proc?.on('exit', (code: number | null) => {
+        if (code !== null && !allowedExitCodes.includes(code)) {
+          reject(new Error(`Process ended with exitcode ${code} (cmd: '${this.rep}')`));
+        } else {
+          resolve(code);
+        }
+      });
+    });
+  }
+
+  /**
+   * Detaches the process so it continues running independently.
+   *
+   * The process must have been created with the 'detached' option.
+   * Once detached, the process will not be killed when the parent exits.
+   *
+   * @throws {Error} When process was not created with 'detached' option
+   */
+  detachProcess(): void {
+    if (!this.opts.detached) {
+      throw new Error(`Unable to detach process that is not started with 'detached' option`);
+    }
+    if (this.proc) {
+      this.proc.unref();
+    }
+  }
+
+  get pid(): number | null {
+    return this.proc?.pid ?? null;
+  }
+
+  private emitLines(streamName: StreamName, lines: Iterable<string> | string): void {
+    const doEmit = (line: string) => this.emit('stream-line', `[${streamName.toUpperCase()}] ${line}`);
+
+    if (_.isString(lines)) {
+      doEmit(lines);
+    } else {
+      for (const line of lines) {
+        doEmit(line);
+      }
+    }
+  }
+}

package/lib/types.ts

@@ -0,0 +1,95 @@
+import type {SpawnOptions, SpawnOptionsWithoutStdio} from 'node:child_process';
+
+/**
+ * Minimal logger interface used by teen_process for debug output.
+ */
+export type TeenProcessLogger = {
+  /** Called for each debug message emitted by exec/SubProcess. */
+  debug: (...args: any[]) => void;
+};
+
+/**
+ * Extra options supported by teen_process on top of Node's SpawnOptions.
+ */
+export interface TeenProcessProps {
+  /** Ignore and discard all child stdout/stderr (reduces memory use). */
+  ignoreOutput?: boolean;
+  /** When true, exec/SubProcess emits Buffers; otherwise strings (default). */
+  isBuffer?: boolean;
+  /** Optional logger for streaming debug output. */
+  logger?: TeenProcessLogger;
+  /** Maximum bytes retained in the stdout circular buffer. */
+  maxStdoutBufferSize?: number;
+  /** Maximum bytes retained in the stderr circular buffer. */
+  maxStderrBufferSize?: number;
+  /** Encoding used when returning string output (default: 'utf8'). */
+  encoding?: BufferEncoding;
+}
+
+/** Options accepted by exec (SpawnOptions + teen_process props). */
+export type TeenProcessExecOptions = SpawnOptions & TeenProcessProps;
+
+/** exec result when isBuffer is false/undefined (string output). */
+export type TeenProcessExecStringResult = {
+  stdout: string;
+  stderr: string;
+  code: number | null;
+};
+
+/** exec result when isBuffer is true (Buffer output). */
+export type TeenProcessExecBufferResult = {
+  stdout: Buffer;
+  stderr: Buffer;
+  code: number | null;
+};
+
+/** Additional properties attached to exec errors. */
+export type TeenProcessExecErrorProps = {
+  stdout: string;
+  stderr: string;
+  code: number | null;
+};
+
+/** Error thrown by exec on non-zero exit or timeout. */
+export type TeenProcessExecError = Error & TeenProcessExecErrorProps;
+
+/**
+ * Extracts the isBuffer property from options, normalizing undefined/false to false.
+ */
+export type BufferProp<T extends {isBuffer?: boolean}> = T['isBuffer'] extends true ? true : false;
+
+/**
+ * Resolves to the correct exec result shape based on buffer mode.
+ * Defaults to string output when isBuffer is false/undefined.
+ */
+export type ExecResult<T extends boolean> = T extends true
+  ? TeenProcessExecBufferResult
+  : TeenProcessExecStringResult;
+
+/** Supported stdio stream names. */
+export type StreamName = 'stdout' | 'stderr';
+
+/** Additional SubProcess-only options. */
+export type SubProcessCustomOptions = {
+  /** When true, SubProcess emits Buffers instead of strings. */
+  isBuffer?: boolean;
+  /** Encoding used when isBuffer is false. */
+  encoding?: BufferEncoding;
+};
+
+/** Options accepted by SubProcess (extends spawn options). */
+export type SubProcessOptions = SubProcessCustomOptions & SpawnOptionsWithoutStdio;
+
+/** Helper type representing SubProcess buffer mode. */
+export type TIsBufferOpts = {
+  isBuffer: true;
+};
+
+/**
+ * Function that detects when a subprocess has started.
+ * Receives stdout/stderr as Buffer when isBuffer is true, otherwise strings.
+ */
+export type StartDetector<T extends SubProcessOptions> = (
+  stdout: T extends TIsBufferOpts ? Buffer : string,
+  stderr?: T extends TIsBufferOpts ? Buffer : string,
+) => unknown;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "teen_process",
-  "version": "3.0.6",
+  "version": "4.0.1",
   "description": "A grown up version of Node's spawn/exec",
   "keywords": [
     "child_process",
@@ -20,15 +20,15 @@
   },
   "license": "Apache-2.0",
   "author": "Appium Contributors",
-  "main": "index.js",
+  "main": "build/lib/index.js",
+  "types": "build/lib/index.d.ts",
   "bin": {},
   "directories": {
     "lib": "lib"
   },
   "files": [
-    "index.js",
-    "lib",
-    "build/lib"
+    "build",
+    "lib"
   ],
   "scripts": {
     "build": "tsc -b",

package/index.js

@@ -1 +0,0 @@
-module.exports = require('./build/lib');