From ae74c4d932879b517df15bba34773e5f72abe4e2 Mon Sep 17 00:00:00 2001 From: Mick Dekkers Date: Sun, 12 Nov 2017 01:18:06 +0100 Subject: [PATCH] [execa] update to v0.8, refactor definitions - Update execa to v0.8 - Add JSDoc documentation for everything - Fix being unable to pass boolean to `shell` option due to intersection type issues - Restructure definitions file based on chroma-js typings to expose function return types --- types/execa/index.d.ts | 298 ++++++++++++++++++++++++++++++++++------- 1 file changed, 249 insertions(+), 49 deletions(-) diff --git a/types/execa/index.d.ts b/types/execa/index.d.ts index 84c6939798..ff665a8e9f 100644 --- a/types/execa/index.d.ts +++ b/types/execa/index.d.ts @@ -1,63 +1,263 @@ -// Type definitions for execa 0.7 +// Type definitions for execa 0.8 // Project: https://github.com/sindresorhus/execa#readme // Definitions by: Douglas Duteil // BendingBender +// Mick Dekkers // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped // TypeScript Version: 2.3 /// -import { ChildProcess, ExecOptions, SpawnOptions, SpawnSyncOptions } from "child_process"; +import { ChildProcess } from 'child_process'; import { Stream } from 'stream'; -type StdIOOption = 'pipe' | 'ipc' | 'ignore' | number | Stream | undefined | null; - -interface ExecaOptions { - input: string | Buffer | Stream; - preferLocal: boolean; - stripEof: boolean; - extendEnv: boolean; - argv0: string; - localDir: string; - reject: boolean; - cleanup: boolean; - stdin: StdIOOption; - stdout: StdIOOption; - stderr: StdIOOption; -} - -type Options = SpawnOptions & ExecaOptions & ExecOptions; -type SyncOptions = SpawnSyncOptions & ExecaOptions & ExecOptions; - -interface ExecaReturns { - cmd: string; - code: number; - failed: boolean; - killed: boolean; - signal: string | null; - stderr: string; - stdout: string; - timedOut: boolean; -} - -type ExecaError = Error & ExecaReturns; - -interface ExecaChildPromise { - catch(onrejected?: ((reason: ExecaError) => TResult | PromiseLike) | null): Promise; -} -type ExecaChildProcess = ChildProcess & ExecaChildPromise & Promise; - -declare function execa(file: string, options?: Partial): ExecaChildProcess; -declare function execa(file: string, args?: string[], options?: Partial): ExecaChildProcess; +/** + * A better `child_process` + */ declare namespace execa { - function stdout(file: string, options?: Partial): Promise; - function stdout(file: string, args?: string[], options?: Partial): Promise; - function stderr(file: string, options?: Partial): Promise; - function stderr(file: string, args?: string[], options?: Partial): Promise; - function shell(command: string, options?: Partial): ExecaChildProcess; - function sync(file: string, options?: Partial): ExecaReturns; - function sync(file: string, args?: string[], options?: Partial): ExecaReturns; - function shellSync(command: string, options?: Partial): ExecaReturns; + interface ExecaStatic { + /** + * Execute a file. + * + * Think of this as a mix of `child_process.execFile` and `child_process.spawn`. + * @returns a `child_process` instance which is enhanced to also be a `Promise` for a result `Object` with `stdout` and `stderr` properties. + */ + (file: string, args?: string[], options?: Options): ExecaChildProcess; + (file: string, options?: Options): ExecaChildProcess; + + /** + * Execute a file. + * + * Think of this as a mix of `child_process.execFile` and `child_process.spawn`. + * @returns a `child_process` instance which is enhanced to also be a `Promise` for `stdout`. + */ + stdout(file: string, args?: string[], options?: Options): Promise; + stdout(file: string, options?: Options): Promise; + + /** + * Execute a file. + * + * Think of this as a mix of `child_process.execFile` and `child_process.spawn`. + * @returns a `child_process` instance which is enhanced to also be a `Promise` for `stderr`. + */ + stderr(file: string, args?: string[], options?: Options): Promise; + stderr(file: string, options?: Options): Promise; + + /** + * Execute a command through the system shell. + * + * Prefer `execa()` whenever possible, as it's both faster and safer. + * @returns a `child_process` instance which is enhanced to also be a `Promise` for a result `Object` with `stdout` and `stderr` properties. + */ + shell(command: string, options?: Options): ExecaChildProcess; + + /** + * Execute a file synchronously. + * + * Think of this as a mix of `child_process.execFile` and `child_process.spawn`. + * @returns the same result object as `child_process.spawnSync`. + * @throws an `Error` if the command fails. + */ + sync(file: string, args?: string[], options?: SyncOptions): ExecaReturns; + sync(file: string, options?: SyncOptions): ExecaReturns; + + /** + * Execute a command synchronously through the system shell. + * + * @returns the same result object as `child_process.spawnSync`. + * @throws an `Error` if the command fails. + */ + shellSync(command: string, options?: Options): ExecaReturns; + } + + type StdIOOption = 'pipe' | 'ipc' | 'ignore' | Stream | number | null | undefined; + + interface CommonOptions { + /** + * Current working directory of the child process. + * @default `process.cwd()` + */ + cwd?: string; + /** + * Environment key-value pairs. + * Extends automatically from `process.env`. + * Set `extendEnv` to `false` if you don't want this. + * @default `process.env` + */ + env?: NodeJS.ProcessEnv; + /** + * Set to `false` if you don't want to extend the environment variables when providing the `env` property. + * @default `true` + */ + extendEnv?: boolean; + /** + * Explicitly set the value of `argv[0]` sent to the child process. + * This will be set to `command` or `file` if not specified. + */ + argv0?: string; + /** + * The `stdio` option is used to configure the pipes that are established between the parent and child process. + * By default, the child's stdin, stdout, and stderr are redirected to corresponding `subprocess.stdin`, `subprocess.stdout`, and `subprocess.stderr` streams on the `ChildProcess` object. + * @default `'pipe'` + * + * @see https://nodejs.org/api/child_process.html#child_process_options_stdio + */ + stdio?: 'pipe' | 'ignore' | 'inherit' | StdIOOption[]; + /** + * Prepare child to run independently of its parent process. + * Specific behavior depends on the platform. + * @see https://nodejs.org/api/child_process.html#child_process_options_detached + */ + detached?: boolean; + /** + * Sets the user identity of the process. + */ + uid?: number; + /** + * Sets the group identity of the process. + */ + gid?: number; + /** + * If `true`, runs `command` inside of a shell. + * Uses `/bin/sh` on UNIX and `cmd.exe` on Windows. + * A different shell can be specified as a string. + * The shell should understand the `-c` switch on UNIX or `/d /s /c` on Windows. + * @default `false` + */ + shell?: boolean | string; + /** + * If `true`, no quoting or escaping of arguments is done on Windows. + * Ignored on other platforms. + * This is set to `true` automatically when `shell` is specified. + * @default `false` + */ + windowsVerbatimArguments?: boolean; + /** + * Strip EOF (last newline) from the output. + * @default `true` + * @see https://github.com/sindresorhus/strip-eof + */ + stripEof?: boolean; + /** + * Prefer locally installed binaries when looking for a binary to execute. + * If you `$ npm install foo`, you can then `execa('foo')`. + * @default `true` + */ + preferLocal?: boolean; + /** + * Preferred path to find locally installed binaries in (use with `preferLocal`). + * @default `process.cwd()` + */ + localDir?: string; + /** + * Setting this to `false` resolves the promise with the error instead of rejecting it. + * @default `true` + */ + reject?: boolean; + /** + * Keep track of the spawned process and `kill` it when the parent process exits. + * @default `true` + */ + cleanup?: boolean; + /** + * Specify the character encoding used to decode the `stdout` and `stderr` output. + * @default `utf8` + */ + encoding?: string; + /** + * If `timeout` is greater than `0`, the parent will send the signal identified by the `killSignal` property (the default is `SIGTERM`) if the child runs longer than `timeout` milliseconds. + * @default `0` + */ + timeout?: number; + /** + * Largest amount of data in bytes allowed on `stdout` or `stderr`. + * @default `10000000` (10MB) + */ + maxBuffer?: number; + /** + * Signal value to be used when the spawned process will be killed. + * @default `SIGTERM` + */ + killSignal?: string | number; + /** + * Used to configure the stdin pipe that is established between the parent and child process. + * @default `'pipe'` + * @see https://nodejs.org/api/child_process.html#child_process_options_stdio + */ + stdin?: StdIOOption; + /** + * Used to configure the stdout pipe that is established between the parent and child process. + * @default `'pipe'` + * @see https://nodejs.org/api/child_process.html#child_process_options_stdio + */ + stdout?: StdIOOption; + /** + * Used to configure the stderr pipe that is established between the parent and child process. + * @default `'pipe'` + * @see https://nodejs.org/api/child_process.html#child_process_options_stdio + */ + stderr?: StdIOOption; + } + + interface Options extends CommonOptions { + /** + * Write some input to the `stdin` of your binary. + */ + input?: string | Buffer | Stream; + } + + interface SyncOptions extends CommonOptions { + /** + * Write some input to the `stdin` of your binary. + * Streams are not allowed when using the synchronous methods. + */ + input?: string | Buffer; + } + + interface ExecaReturns { + /** + * The command that was run. + */ + cmd: string; + /** + * The exit code of the process that was run. + */ + code: number; + /** + * Whether the process failed to run. + */ + failed: boolean; + /** + * Whether the process was killed. + */ + killed: boolean; + /** + * The signal that was used to terminate the process. + */ + signal: string | null; + /** + * The output of the process on stderr. + */ + stderr: string; + /** + * The output of the process on stdout. + */ + stdout: string; + /** + * Whether the process timed out. + */ + timedOut: boolean; + } + + type ExecaError = Error & ExecaReturns; + + interface ExecaChildPromise { + catch(onrejected?: ((reason: ExecaError) => TResult | PromiseLike) | null): Promise; + } + + type ExecaChildProcess = ChildProcess & ExecaChildPromise & Promise; } +declare var execa: execa.ExecaStatic; + export = execa;