teen_process 3.0.6 → 4.0.1

package/build/lib/subprocess.d.ts

@@ -1,79 +1,124 @@
+import { EventEmitter } from 'node:events';
+import type { SubProcessOptions, StartDetector } from './types';
 /**
- * @template {SubProcessOptions} TSubProcessOptions
+ * 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> extends EventEmitter<any> {
-    /**
-     * @param {string} cmd
-     * @param {string[]} [args=[]]
-     * @param {TSubProcessOptions} [opts]
-     */
+export declare class SubProcess<TSubProcessOptions extends SubProcessOptions = SubProcessOptions> extends EventEmitter {
+    private proc;
+    private args;
+    private cmd;
+    private opts;
+    private expectingExit;
+    private readonly rep;
     constructor(cmd: string, args?: string[], opts?: TSubProcessOptions);
-    /**
-     * @callback StartDetector
-     * @param {TSubProcessOptions extends TIsBufferOpts ? Buffer : string} stdout
-     * @param {TSubProcessOptions extends TIsBufferOpts ? Buffer : string} [stderr]
-     * @returns {any}
-     */
-    /** @type {import('child_process').ChildProcess | null} */
-    proc: import("child_process").ChildProcess | null;
-    /** @type {string[]} */
-    args: string[];
-    /**
-     * @type {string}
-     */
-    cmd: string;
-    /**
-     * @type {SubProcessOptions}
-    */
-    opts: SubProcessOptions;
-    /**
-     * @type {boolean}
-     */
-    expectingExit: boolean;
-    /**
-     * @type {string}
-     */
-    rep: string;
     get isRunning(): boolean;
     /**
+     * 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();
      *
-     * @param {string} streamName
-     * @param {Iterable<string>|string} lines
+     * // 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);
+     * ```
      */
-    emitLines(streamName: string, lines: Iterable<string> | string): void;
+    start(startDetector?: StartDetector<TSubProcessOptions> | number | boolean | null, timeoutMs?: number | boolean | null, detach?: boolean): Promise<void>;
     /**
-     * spawn the subprocess and return control whenever we deem that it has fully
-     * "started"
+     * 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
      *
-     * @param {StartDetector|number?} startDetector
-     * @param {number?} timeoutMs
-     * @param {boolean} detach
-     * @returns {Promise<void>}
+     * @example
+     * ```typescript
+     * // Graceful stop with SIGTERM
+     * await proc.stop();
+     *
+     * // Force kill with SIGKILL
+     * await proc.stop('SIGKILL');
+     *
+     * // Custom timeout
+     * await proc.stop('SIGTERM', 5000);
+     * ```
      */
-    start(startDetector?: ((stdout: TSubProcessOptions extends TIsBufferOpts ? Buffer : string, stderr?: (TSubProcessOptions extends TIsBufferOpts ? Buffer<ArrayBufferLike> : string) | undefined) => any) | (number | null), timeoutMs?: number | null, detach?: boolean): Promise<void>;
+    stop(signal?: NodeJS.Signals, timeout?: number): Promise<void>;
     /**
-     * @deprecated This method is deprecated and will be removed
+     * 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]);
+     * ```
      */
-    handleLastLines(): void;
+    join(allowedExitCodes?: number[]): Promise<number | null>;
     /**
+     * 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.
      *
-     * @param {NodeJS.Signals} signal
-     * @param {number} timeout
-     * @returns {Promise<void>}
+     * @throws {Error} When process was not created with 'detached' option
      */
-    stop(signal?: NodeJS.Signals, timeout?: number): Promise<void>;
-    join(allowedExitCodes?: number[]): Promise<any>;
     detachProcess(): void;
-    get pid(): number | null | undefined;
+    get pid(): number | null;
+    private emitLines;
 }
-export default SubProcess;
-export type SubProcessCustomOptions = {
-    isBuffer?: boolean | undefined;
-    encoding?: string | undefined;
-};
-export type SubProcessOptions = SubProcessCustomOptions & import("child_process").SpawnOptionsWithoutStdio;
-export type TIsBufferOpts = {
-    isBuffer: true;
-};
-import { EventEmitter } from 'events';
 //# sourceMappingURL=subprocess.d.ts.map

package/build/lib/subprocess.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"subprocess.d.ts","sourceRoot":"","sources":["../../lib/subprocess.js"],"names":[],"mappings":"AAQA;;GAEG;AACH,wBAFiC,kBAAkB,SAArC,iBAAkB;IA+B9B;;;;OAIG;IACH,iBAJW,MAAM,SACN,MAAM,EAAE,SACR,kBAAkB,EAgB5B;IA/CD;;;;;OAKG;IAEH,0DAA0D;IAC1D,MADW,OAAO,eAAe,EAAE,YAAY,GAAG,IAAI,CACjD;IACL,uBAAuB;IACvB,MADW,MAAM,EAAE,CACd;IACL;;OAEG;IACH,KAFU,MAAM,CAEZ;IACJ;;MAEE;IACF,MAFU,iBAAiB,CAEtB;IACL;;OAEG;IACH,eAFU,OAAO,CAEH;IACd;;OAEG;IACH,KAFU,MAAM,CAEZ;IAuBJ,yBAGC;IAED;;;;OAIG;IACH,sBAHW,MAAM,SACN,QAAQ,CAAC,MAAM,CAAC,GAAC,MAAM,QAYjC;IAED;;;;;;;;OAQG;IACH,sBALW,UAzEA,kBAAkB,SAAS,aAAa,GAAG,MAAM,GAAG,MAAM,yGAExD,GAAG,KAuES,MAAM,OAAC,CAAA,cACrB,MAAM,OAAC,WACP,OAAO,GACL,OAAO,CAAC,IAAI,CAAC,CAiKzB;IAED;;OAEG;IACH,wBAGC;IAED;;;;;OAKG;IACH,cAJW,MAAM,CAAC,OAAO,YACd,MAAM,GACJ,OAAO,CAAC,IAAI,CAAC,CAgBzB;IAED,gDAcC;IAKD,sBAQC;IAED,qCAEC;CACF;;;;;;gCAWY,uBAAuB,GAAG,OAAO,eAAe,EAAE,wBAAwB;4BAC1E;IAAC,QAAQ,EAAE,IAAI,CAAA;CAAC;6BAtUA,QAAQ"}
+{"version":3,"file":"subprocess.d.ts","sourceRoot":"","sources":["../../lib/subprocess.ts"],"names":[],"mappings":"AAEA,OAAO,EAAC,YAAY,EAAC,MAAM,aAAa,CAAC;AAOzC,OAAO,KAAK,EACR,iBAAiB,EACjB,aAAa,EAGhB,MAAM,SAAS,CAAC;AAEjB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,qBAAa,UAAU,CACrB,kBAAkB,SAAS,iBAAiB,GAAG,iBAAiB,CAChE,SAAQ,YAAY;IACpB,OAAO,CAAC,IAAI,CAAsB;IAClC,OAAO,CAAC,IAAI,CAAW;IACvB,OAAO,CAAC,GAAG,CAAS;IACpB,OAAO,CAAC,IAAI,CAAqB;IACjC,OAAO,CAAC,aAAa,CAAU;IAC/B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;gBAEjB,GAAG,EAAE,MAAM,EAAE,IAAI,GAAE,MAAM,EAAO,EAAE,IAAI,CAAC,EAAE,kBAAkB;IAwBvE,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACG,KAAK,CACT,aAAa,GAAE,aAAa,CAAC,kBAAkB,CAAC,GAAG,MAAM,GAAG,OAAO,GAAG,IAAW,EACjF,SAAS,GAAE,MAAM,GAAG,OAAO,GAAG,IAAW,EACzC,MAAM,GAAE,OAAe,GACtB,OAAO,CAAC,IAAI,CAAC;IAuIhB;;;;;;;;;;;;;;;;;;;OAmBG;IACG,IAAI,CAAC,MAAM,GAAE,MAAM,CAAC,OAAmB,EAAE,OAAO,SAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAc9E;;;;;;;;;;;;;;;;OAgBG;IACG,IAAI,CAAC,gBAAgB,GAAE,MAAM,EAAQ,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAgBpE;;;;;;;OAOG;IACH,aAAa,IAAI,IAAI;IASrB,IAAI,GAAG,IAAI,MAAM,GAAG,IAAI,CAEvB;IAED,OAAO,CAAC,SAAS;CAWlB"}

package/build/lib/subprocess.js

@@ -4,115 +4,121 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SubProcess = void 0;
-const child_process_1 = require("child_process");
-const events_1 = require("events");
+const node_child_process_1 = require("node:child_process");
+const node_events_1 = require("node:events");
 const bluebird_1 = __importDefault(require("bluebird"));
 const shell_quote_1 = require("shell-quote");
 const lodash_1 = __importDefault(require("lodash"));
 const helpers_1 = require("./helpers");
 const node_readline_1 = require("node:readline");
 /**
- * @template {SubProcessOptions} TSubProcessOptions
+ * 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();
+ * ```
  */
-class SubProcess extends events_1.EventEmitter {
-    /**
-     * @callback StartDetector
-     * @param {TSubProcessOptions extends TIsBufferOpts ? Buffer : string} stdout
-     * @param {TSubProcessOptions extends TIsBufferOpts ? Buffer : string} [stderr]
-     * @returns {any}
-     */
-    /** @type {import('child_process').ChildProcess | null} */
+class SubProcess extends node_events_1.EventEmitter {
     proc;
-    /** @type {string[]} */
     args;
-    /**
-     * @type {string}
-     */
     cmd;
-    /**
-     * @type {SubProcessOptions}
-    */
     opts;
-    /**
-     * @type {boolean}
-     */
     expectingExit;
-    /**
-     * @type {string}
-     */
     rep;
-    /**
-     * @param {string} cmd
-     * @param {string[]} [args=[]]
-     * @param {TSubProcessOptions} [opts]
-     */
     constructor(cmd, args = [], opts) {
         super();
-        if (!cmd)
-            throw new Error('Command is required'); // eslint-disable-line curly
-        if (!lodash_1.default.isString(cmd))
-            throw new Error('Command must be a string'); // eslint-disable-line curly
-        if (!lodash_1.default.isArray(args))
-            throw new Error('Args must be an array'); // eslint-disable-line curly
+        if (!cmd) {
+            throw new Error('Command is required');
+        }
+        if (!lodash_1.default.isString(cmd)) {
+            throw new Error('Command must be a string');
+        }
+        if (!lodash_1.default.isArray(args)) {
+            throw new Error('Args must be an array');
+        }
         this.cmd = cmd;
         this.args = args;
         this.proc = null;
         this.opts = opts ?? {};
         this.expectingExit = false;
-        // get a quoted representation of the command for error strings
         this.rep = (0, shell_quote_1.quote)([cmd, ...args]);
     }
     get isRunning() {
-        // presence of `proc` means we have connected and started
         return !!this.proc;
     }
     /**
+     * Starts the subprocess and waits for it to be ready.
      *
-     * @param {string} streamName
-     * @param {Iterable<string>|string} lines
-     */
-    emitLines(streamName, lines) {
-        const doEmit = (/** @type {string} */ line) => this.emit('stream-line', `[${streamName.toUpperCase()}] ${line}`);
-        if (lodash_1.default.isString(lines)) {
-            doEmit(lines);
-        }
-        else {
-            for (const line of lines) {
-                doEmit(line);
-            }
-        }
-    }
-    /**
-     * spawn the subprocess and return control whenever we deem that it has fully
-     * "started"
+     * @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();
      *
-     * @param {StartDetector|number?} startDetector
-     * @param {number?} timeoutMs
-     * @param {boolean} detach
-     * @returns {Promise<void>}
+     * // 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 = null, timeoutMs = null, detach = false) {
         let startDelay = 10;
-        const genericStartDetector = /** @type {StartDetector} */ (function genericStartDetector(stdout, stderr) {
-            return stdout || stderr;
-        });
-        // the default start detector simply returns true when we get any output
+        const genericStartDetector = (stdout, stderr) => stdout || stderr;
+        let detector = null;
         if (startDetector === null) {
-            startDetector = genericStartDetector;
+            detector = genericStartDetector;
         }
-        // if the user passes a number, then we simply delay a certain amount of
-        // time before returning control, rather than waiting for a condition
         if (lodash_1.default.isNumber(startDetector)) {
             startDelay = startDetector;
-            startDetector = null;
+            detector = null;
+        }
+        else if (lodash_1.default.isFunction(startDetector)) {
+            detector = startDetector;
         }
-        // if the user passes in a boolean as one of the arguments, use it for `detach`
         if (lodash_1.default.isBoolean(startDetector) && startDetector) {
             if (!this.opts.detached) {
                 throw new Error(`Unable to detach process that is not started with 'detached' option`);
             }
             detach = true;
-            startDetector = genericStartDetector;
+            detector = genericStartDetector;
         }
         else if (lodash_1.default.isBoolean(timeoutMs) && timeoutMs) {
             if (!this.opts.detached) {
@@ -121,49 +127,35 @@ class SubProcess extends events_1.EventEmitter {
             detach = true;
             timeoutMs = null;
         }
-        // return a promise so we can wrap the async behavior
         return await new bluebird_1.default((resolve, reject) => {
-            // actually spawn the subproc
-            this.proc = (0, child_process_1.spawn)(this.cmd, this.args, this.opts);
-            // this function handles output that we collect from the subproc
-            /**
-             * @param { {
-             * stdout: TSubProcessOptions extends TIsBufferOpts ? Buffer : string,
-             * stderr: TSubProcessOptions extends TIsBufferOpts ? Buffer : string
-             * } } streams
-             */
+            this.proc = (0, node_child_process_1.spawn)(this.cmd, this.args, this.opts);
             const handleOutput = (streams) => {
                 const { stdout, stderr } = streams;
-                // if we have a startDetector, run it on the output so we can resolve/
-                // reject and move on from start
                 try {
-                    if (lodash_1.default.isFunction(startDetector) && startDetector(stdout, stderr)) {
-                        startDetector = null;
+                    if (detector && detector(stdout, stderr)) {
+                        detector = null;
                         resolve();
                     }
                 }
                 catch (e) {
                     reject(e);
                 }
-                // emit the actual output for whomever's listening
                 this.emit('output', stdout, stderr);
             };
-            // if we get an error spawning the proc, reject and clean up the proc
-            this.proc.on('error', /** @param {NodeJS.ErrnoException} err */ async (err) => {
+            this.proc.on('error', async (err) => {
                 this.proc?.removeAllListeners('exit');
                 this.proc?.kill('SIGINT');
-                if (err.code === 'ENOENT') {
-                    err = await (0, helpers_1.formatEnoent)(err, this.cmd, this.opts?.cwd?.toString());
+                let error = err;
+                if (error.code === 'ENOENT') {
+                    error = await (0, helpers_1.formatEnoent)(error, this.cmd, this.opts?.cwd?.toString());
                 }
-                reject(err);
+                reject(error);
                 this.proc?.unref();
                 this.proc = null;
             });
-            const handleStreamLines = (/** @type {string} */ streamName, /** @type {import('stream').Readable} */ input) => {
+            const handleStreamLines = (streamName, input) => {
                 const rl = (0, node_readline_1.createInterface)({ input });
                 rl.on('line', (line) => {
-                    // This event is a legacy one
-                    // It always produces a single-item array
                     if (this.listenerCount(`lines-${streamName}`)) {
                         this.emit(`lines-${streamName}`, [line]);
                     }
@@ -177,51 +169,34 @@ class SubProcess extends events_1.EventEmitter {
             const encoding = this.opts.encoding || 'utf8';
             if (this.proc.stdout) {
                 this.proc.stdout.on('data', (chunk) => handleOutput({
-                    stdout: isBuffer ? chunk : chunk.toString(encoding),
-                    // @ts-ignore This is OK
-                    stderr: isBuffer ? Buffer.alloc(0) : '',
+                    stdout: (isBuffer ? chunk : chunk.toString(encoding)),
+                    stderr: (isBuffer ? Buffer.alloc(0) : ''),
                 }));
                 handleStreamLines('stdout', this.proc.stdout);
             }
             if (this.proc.stderr) {
                 this.proc.stderr.on('data', (chunk) => handleOutput({
-                    // @ts-ignore This is OK
-                    stdout: isBuffer ? Buffer.alloc(0) : '',
-                    stderr: isBuffer ? chunk : chunk.toString(encoding)
+                    stdout: (isBuffer ? Buffer.alloc(0) : ''),
+                    stderr: (isBuffer ? chunk : chunk.toString(encoding)),
                 }));
                 handleStreamLines('stderr', this.proc.stderr);
             }
-            // when the proc exits, we might still have a buffer of lines we were
-            // waiting on more chunks to complete. Go ahead and emit those, then
-            // re-emit the exit so a listener can handle the possibly-unexpected exit
             this.proc.on('exit', (code, signal) => {
                 this.emit('exit', code, signal);
-                // in addition to the bare exit event, also emit one of three other
-                // events that contain more helpful information:
-                // 'stop': we stopped this
-                // 'die': the process ended out of our control with a non-zero exit
-                // 'end': the process ended out of our control with a zero exit
                 let event = this.expectingExit ? 'stop' : 'die';
                 if (!this.expectingExit && code === 0) {
                     event = 'end';
                 }
                 this.emit(event, code, signal);
-                // finally clean up the proc and make sure to reset our exit
-                // expectations
                 this.proc = null;
                 this.expectingExit = false;
             });
-            // if the user hasn't given us a startDetector, instead just resolve
-            // when startDelay ms have passed
-            if (!startDetector) {
-                setTimeout(() => { resolve(); }, startDelay);
+            if (!detector) {
+                setTimeout(() => resolve(), startDelay);
             }
-            // if the user has given us a timeout, start the clock for rejecting
-            // the promise if we take too long to start
             if (lodash_1.default.isNumber(timeoutMs)) {
                 setTimeout(() => {
-                    reject(new Error(`The process did not start within ${timeoutMs}ms ` +
-                        `(cmd: '${this.rep}')`));
+                    reject(new Error(`The process did not start within ${timeoutMs}ms (cmd: '${this.rep}')`));
                 }, timeoutMs);
             }
         }).finally(() => {
@@ -231,40 +206,62 @@ class SubProcess extends events_1.EventEmitter {
         });
     }
     /**
-     * @deprecated This method is deprecated and will be removed
-     */
-    handleLastLines() {
-        // TODO: THis is a noop left for backward compatibility.
-        // TODO: Remove it after the major version bump
-    }
-    /**
+     * 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');
      *
-     * @param {NodeJS.Signals} signal
-     * @param {number} timeout
-     * @returns {Promise<void>}
+     * // Custom timeout
+     * await proc.stop('SIGTERM', 5000);
+     * ```
      */
     async stop(signal = 'SIGTERM', timeout = 10000) {
         if (!this.isRunning) {
             throw new Error(`Can't stop process; it's not currently running (cmd: '${this.rep}')`);
         }
         return await new bluebird_1.default((resolve, reject) => {
-            this.proc?.on('close', resolve);
+            this.proc?.on('close', () => resolve());
             this.expectingExit = true;
             this.proc?.kill(signal);
-            // this timeout needs unref() or node will wait for the timeout to fire before
-            // exiting the process.
             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 = [0]) {
         if (!this.isRunning) {
             throw new Error(`Cannot join process; it is not currently running (cmd: '${this.rep}')`);
         }
         return await new bluebird_1.default((resolve, reject) => {
             this.proc?.on('exit', (code) => {
-                if (code !== null && allowedExitCodes.indexOf(code) === -1) {
+                if (code !== null && !allowedExitCodes.includes(code)) {
                     reject(new Error(`Process ended with exitcode ${code} (cmd: '${this.rep}')`));
                 }
                 else {
@@ -273,12 +270,16 @@ class SubProcess extends events_1.EventEmitter {
             });
         });
     }
-    /*
-     * This will only work if the process is created with the `detached` option
+    /**
+     * 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() {
         if (!this.opts.detached) {
-            // this means that there is a misconfiguration in the calling code
             throw new Error(`Unable to detach process that is not started with 'detached' option`);
         }
         if (this.proc) {
@@ -286,18 +287,19 @@ class SubProcess extends events_1.EventEmitter {
         }
     }
     get pid() {
-        return this.proc ? this.proc.pid : null;
+        return this.proc?.pid ?? null;
+    }
+    emitLines(streamName, lines) {
+        const doEmit = (line) => this.emit('stream-line', `[${streamName.toUpperCase()}] ${line}`);
+        if (lodash_1.default.isString(lines)) {
+            doEmit(lines);
+        }
+        else {
+            for (const line of lines) {
+                doEmit(line);
+            }
+        }
     }
 }
 exports.SubProcess = SubProcess;
-exports.default = SubProcess;
-/**
- * @typedef {Object} SubProcessCustomOptions
- * @property {boolean} [isBuffer]
- * @property {string} [encoding]
- */
-/**
- * @typedef {SubProcessCustomOptions & import('child_process').SpawnOptionsWithoutStdio} SubProcessOptions
- * @typedef {{isBuffer: true}} TIsBufferOpts
- */
 //# sourceMappingURL=subprocess.js.map