chore: Add more typedefs to the SubProcess class (#448)

Author: mykola-mokhnach

README.md

@@ -111,6 +111,21 @@ async function tailFileForABit () {
 
 Errors with start/stop are thrown in the calling context.
 
+### Options
+
+The instance constructor accepts same options that Node.js's
+[spawn](https://nodejs.org/api/child_process.html#child_processspawncommand-args-options)
+API plus some custom options:
+
+* `isBuffer` - If set to `true` then both stdout and stderr chunks are delivered
+  as buffers rather than strings to the following entities:
+  - `startDetector` argument
+  - `output` event
+* `encoding` - If provided then arguments of the `startDetector` argument and of the
+  `output` event will be encoded to strings using this given encoding, unless `isBuffer`
+  is set to `true`. If no explicit encoding is provided then `utf8` encoding is used by
+  default.
+
 ### Events
 
 You can listen to 8 events:
@@ -151,11 +166,9 @@ proc.on('output', (stdout, stderr) => {
   console.log(`stderr: ${stderr}`);
 });
 
-// lines-stderr is just the same
-proc.on('lines-stdout', lines => {
-  console.log(lines);
-  // ['foo', 'bar', 'baz']
-  // automatically handles rejoining lines across stream chunks
+// line-stderr is just the same
+proc.on('line-stdout', (line) => {
+  console.log(line);
 });
 
 // stream-line gives you one line at a time, with [STDOUT] or [STDERR]

lib/subprocess.js

@@ -1,46 +1,49 @@
 import { spawn } from 'child_process';
-import events from 'events';
-const { EventEmitter } = events;
+import { EventEmitter } from 'events';
 import B from 'bluebird';
 import { quote } from 'shell-quote';
 import _ from 'lodash';
 import { formatEnoent } from './helpers';
 import { createInterface } from 'node:readline';
 
-class SubProcess extends EventEmitter {
+/**
+ * @template {SubProcessOptions} TSubProcessOptions
+ */
+export class SubProcess extends EventEmitter {
+  /**
+   * @callback StartDetector
+   * @param {TSubProcessOptions extends TIsBufferOpts ? Buffer : string} stdout
+   * @param {TSubProcessOptions extends TIsBufferOpts ? Buffer : string} [stderr]
+   * @returns {any}
+   */
 
-  /** @type {import('child_process').ChildProcess?} */
+  /** @type {import('child_process').ChildProcess | null} */
   proc;
-
   /** @type {string[]} */
   args;
-
   /**
    * @type {string}
    */
   cmd;
-
   /**
-   * @type {any}
+   * @type {SubProcessOptions}
   */
   opts;
-
   /**
    * @type {boolean}
    */
   expectingExit;
-
   /**
    * @type {string}
    */
   rep;
 
   /**
    * @param {string} cmd
-   * @param {string[]} [args]
-   * @param {any} [opts]
+   * @param {string[]} [args=[]]
+   * @param {TSubProcessOptions} [opts]
    */
-  constructor (cmd, args = [], opts = {}) {
+  constructor (cmd, args = [], opts) {
     super();
     if (!cmd) throw new Error('Command is required'); // eslint-disable-line curly
     if (!_.isString(cmd)) throw new Error('Command must be a string'); // eslint-disable-line curly
@@ -49,7 +52,7 @@ class SubProcess extends EventEmitter {
     this.cmd = cmd;
     this.args = args;
     this.proc = null;
-    this.opts = opts;
+    this.opts = opts ?? {};
     this.expectingExit = false;
 
     // get a quoted representation of the command for error strings
@@ -128,8 +131,10 @@ class SubProcess extends EventEmitter {
 
       // this function handles output that we collect from the subproc
       /**
-       *
-       * @param { {stdout: string, stderr: string} } streams
+       * @param { {
+       * stdout: TSubProcessOptions extends TIsBufferOpts ? Buffer : string,
+       * stderr: TSubProcessOptions extends TIsBufferOpts ? Buffer : string
+       * } } streams
        */
       const handleOutput = (streams) => {
         const {stdout, stderr} = streams;
@@ -154,7 +159,7 @@ class SubProcess extends EventEmitter {
         this.proc?.kill('SIGINT');
 
         if (err.code === 'ENOENT') {
-          err = await formatEnoent(err, this.cmd, this.opts?.cwd);
+          err = await formatEnoent(err, this.cmd, this.opts?.cwd?.toString());
         }
         reject(err);
 
@@ -182,14 +187,22 @@ class SubProcess extends EventEmitter {
 
       if (this.proc.stdout) {
         this.proc.stdout.on('data', (chunk) =>
-          handleOutput({stdout: isBuffer ? chunk : chunk.toString(encoding), stderr: ''}),
+          handleOutput({
+            stdout: isBuffer ? chunk : chunk.toString(encoding),
+            // @ts-ignore This is OK
+            stderr: isBuffer ? Buffer.alloc(0) : '',
+          }),
         );
         handleStreamLines('stdout', this.proc.stdout);
       }
 
       if (this.proc.stderr) {
         this.proc.stderr.on('data', (chunk) =>
-          handleOutput({stdout: '', stderr: isBuffer ? chunk : chunk.toString(encoding)}),
+          handleOutput({
+            // @ts-ignore This is OK
+            stdout: isBuffer ? Buffer.alloc(0) : '',
+            stderr: isBuffer ? chunk : chunk.toString(encoding)
+          }),
         );
         handleStreamLines('stderr', this.proc.stderr);
       }
@@ -302,12 +315,15 @@ class SubProcess extends EventEmitter {
   }
 }
 
-export { SubProcess };
 export default SubProcess;
 
 /**
- * @callback StartDetector
- * @param {string} stdout
- * @param {string} [stderr]
- * @returns {any}
+ * @typedef {Object} SubProcessCustomOptions
+ * @property {boolean} [isBuffer]
+ * @property {string} [encoding]
+ */
+
+/**
+ * @typedef {SubProcessCustomOptions & import('child_process').SpawnOptionsWithoutStdio} SubProcessOptions
+ * @typedef {{isBuffer: true}} TIsBufferOpts
  */