Skip to content

Commit

Permalink
lib: add JSDoc typings for child_process
Browse files Browse the repository at this point in the history
Added JSDoc typings for the `child_process` lib module.

PR-URL: #38222
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Michael Dawson <midawson@redhat.com>
  • Loading branch information
VoltrexKeyva authored and richardlau committed Jul 20, 2021
1 parent 04032fa commit 2bc2a23
Showing 1 changed file with 161 additions and 3 deletions.
164 changes: 161 additions & 3 deletions lib/child_process.js
Original file line number Diff line number Diff line change
Expand Up @@ -74,6 +74,28 @@ const {

const MAX_BUFFER = 1024 * 1024;

/**
* Spawns a new Node.js process + fork.
* @param {string} modulePath
* @param {string[]} [args]
* @param {{
* cwd?: string;
* detached?: boolean;
* env?: Object;
* execPath?: string;
* execArgv?: string[];
* gid?: number;
* serialization?: string;
* signal?: AbortSignal;
* killSignal?: string | number;
* silent?: boolean;
* stdio?: Array | string;
* uid?: number;
* windowsVerbatimArguments?: boolean;
* timeout?: number;
* }} [options]
* @returns {ChildProcess}
*/
function fork(modulePath /* , args, options */) {
validateString(modulePath, 'modulePath');

Expand Down Expand Up @@ -161,7 +183,29 @@ function normalizeExecArgs(command, options, callback) {
};
}


/**
* Spawns a shell executing the given command.
* @param {string} command
* @param {{
* cmd?: string;
* env?: Object;
* encoding?: string;
* shell?: string;
* signal?: AbortSignal;
* timeout?: number;
* maxBuffer?: number;
* killSignal?: string | number;
* uid?: number;
* gid?: number;
* windowsHide?: boolean;
* }} [options]
* @param {(
* error?: Error,
* stdout?: string | Buffer,
* stderr?: string | Buffer
* ) => any} [callback]
* @returns {ChildProcess}
*/
function exec(command, options, callback) {
const opts = normalizeExecArgs(command, options, callback);
return module.exports.execFile(opts.file,
Expand Down Expand Up @@ -197,6 +241,31 @@ ObjectDefineProperty(exec, promisify.custom, {
value: customPromiseExecFunction(exec)
});

/**
* Spawns the specified file as a shell.
* @param {string} file
* @param {string[]} [args]
* @param {{
* cwd?: string;
* env?: Object;
* encoding?: string;
* timeout?: number;
* maxBuffer?: number;
* killSignal?: string | number;
* uid?: number;
* gid?: number;
* windowsHide?: boolean;
* windowsVerbatimArguments?: boolean;
* shell?: boolean | string;
* signal?: AbortSignal;
* }} [options]
* @param {(
* error?: Error,
* stdout?: string | Buffer,
* stderr?: string | Buffer
* ) => any} [callback]
* @returns {ChildProcess}
*/
function execFile(file /* , args, options, callback */) {
let args = [];
let callback;
Expand Down Expand Up @@ -567,6 +636,28 @@ function normalizeSpawnArguments(file, args, options) {
}


/**
* Spawns a new process using the given `file`.
* @param {string} file
* @param {string[]} [args]
* @param {{
* cwd?: string;
* env?: Object;
* argv0?: string;
* stdio?: Array | string;
* detached?: boolean;
* uid?: number;
* gid?: number;
* serialization?: string;
* shell?: boolean | string;
* windowsVerbatimArguments?: boolean;
* windowsHide?: boolean;
* signal?: AbortSignal;
* timeout?: number;
* killSignal?: string | number;
* }} [options]
* @returns {ChildProcess}
*/
function spawn(file, args, options) {
const child = new ChildProcess();

Expand All @@ -577,6 +668,36 @@ function spawn(file, args, options) {
return child;
}

/**
* Spawns a new process synchronously using the given `file`.
* @param {string} file
* @param {string[]} [args]
* @param {{
* cwd?: string;
* input?: string | Buffer | TypedArray | DataView;
* argv0?: string;
* stdio?: string | Array;
* env?: Object;
* uid?: number;
* gid?: number;
* timeout?: number;
* killSignal?: string | number;
* maxBuffer?: number;
* encoding?: string;
* shell?: boolean | string;
* windowsVerbatimArguments?: boolean;
* windowsHide?: boolean;
* }} [options]
* @returns {{
* pid: number;
* output: Array;
* stdout: Buffer | string;
* stderr: Buffer | string;
* status: number | null;
* signal: string | null;
* error: Error;
* }}
*/
function spawnSync(file, args, options) {
options = {
maxBuffer: MAX_BUFFER,
Expand Down Expand Up @@ -643,7 +764,26 @@ function checkExecSyncError(ret, args, cmd) {
return err;
}


/**
* Spawns a file as a shell synchronously.
* @param {string} command
* @param {string[]} [args]
* @param {{
* cwd?: string;
* input?: string | Buffer | TypedArray | DataView;
* stdio?: string | Array;
* env?: Object;
* uid?: number;
* gid?: number;
* timeout?: number;
* killSignal?: string | number;
* maxBuffer?: number;
* encoding?: string;
* windowsHide?: boolean;
* shell?: boolean | string;
* }} [options]
* @returns {Buffer | string}
*/
function execFileSync(command, args, options) {
options = normalizeSpawnArguments(command, args, options);

Expand All @@ -661,7 +801,25 @@ function execFileSync(command, args, options) {
return ret.stdout;
}


/**
* Spawns a shell executing the given `command` synchronously.
* @param {string} command
* @param {{
* cwd?: string;
* input?: string | Buffer | TypedArray | DataView;
* stdio?: string | Array;
* env?: Object;
* shell?: string;
* uid?: number;
* gid?: number;
* timeout?: number;
* killSignal?: string | number;
* maxBuffer?: number;
* encoding?: string;
* windowsHide?: boolean;
* }} [options]
* @returns {Buffer | string}
*/
function execSync(command, options) {
const opts = normalizeExecArgs(command, options, null);
const inheritStderr = !opts.options.stdio;
Expand Down

0 comments on commit 2bc2a23

Please sign in to comment.