Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

typings: add JSDoc typings for child_process #38222

Closed
wants to merge 1 commit into from
Closed

typings: add JSDoc typings for child_process #38222

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
165 changes: 161 additions & 4 deletions lib/child_process.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -87,6 +87,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 @@ -174,7 +196,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 @@ -205,6 +249,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 @@ -597,7 +666,28 @@ function abortChildProcess(child, killSignal) {
}
}


/**
* 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) {
options = normalizeSpawnArguments(file, args, options);
validateTimeout(options.timeout);
Expand Down Expand Up @@ -646,6 +736,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 @@ -712,7 +832,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 @@ -731,7 +870,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