diff --git a/index.d.ts b/index.d.ts index efab5e5e5..81ad662a9 100644 --- a/index.d.ts +++ b/index.d.ts @@ -2,305 +2,308 @@ import {ChildProcess} from 'child_process'; import {Stream, Readable as ReadableStream} from 'stream'; -export type StdioOption = - | 'pipe' - | 'ipc' - | 'ignore' - | 'inherit' - | Stream - | number - | null - | undefined; - -export interface CommonOptions { - /** - Current working directory of the child process. +declare namespace execa { + type StdioOption = + | 'pipe' + | 'ipc' + | 'ignore' + | 'inherit' + | Stream + | number + | null + | undefined; - @default process.cwd() - */ - readonly cwd?: string; + interface CommonOptions { + /** + Current working directory of the child process. - /** - Environment key-value pairs. Extends automatically from `process.env`. Set `extendEnv` to `false` if you don't want this. + @default process.cwd() + */ + readonly cwd?: string; - @default process.env - */ - readonly env?: NodeJS.ProcessEnv; + /** + Environment key-value pairs. Extends automatically from `process.env`. Set `extendEnv` to `false` if you don't want this. - /** - Set to `false` if you don't want to extend the environment variables when providing the `env` property. + @default process.env + */ + readonly env?: NodeJS.ProcessEnv; - @default true - */ - readonly extendEnv?: boolean; + /** + Set to `false` if you don't want to extend the environment variables when providing the `env` property. - /** - Explicitly set the value of `argv[0]` sent to the child process. This will be set to `command` or `file` if not specified. - */ - readonly argv0?: string; + @default true + */ + readonly extendEnv?: boolean; - /** - Child's [stdio](https://nodejs.org/api/child_process.html#child_process_options_stdio) configuration. + /** + Explicitly set the value of `argv[0]` sent to the child process. This will be set to `command` or `file` if not specified. + */ + readonly argv0?: string; - @default 'pipe' - */ - readonly stdio?: 'pipe' | 'ignore' | 'inherit' | ReadonlyArray; + /** + Child's [stdio](https://nodejs.org/api/child_process.html#child_process_options_stdio) configuration. - /** - Prepare child to run independently of its parent process. Specific behavior [depends on the platform](https://nodejs.org/api/child_process.html#child_process_options_detached). + @default 'pipe' + */ + readonly stdio?: 'pipe' | 'ignore' | 'inherit' | ReadonlyArray; - @default false - */ - readonly detached?: boolean; + /** + Prepare child to run independently of its parent process. Specific behavior [depends on the platform](https://nodejs.org/api/child_process.html#child_process_options_detached). - /** - Sets the user identity of the process. - */ - readonly uid?: number; + @default false + */ + readonly detached?: boolean; - /** - Sets the group identity of the process. - */ - readonly gid?: number; + /** + Sets the user identity of the process. + */ + readonly uid?: 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. + /** + Sets the group identity of the process. + */ + readonly gid?: number; - @default false - */ - readonly shell?: boolean | string; + /** + 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. - /** - Strip the final [newline character](https://en.wikipedia.org/wiki/Newline) from the output. + @default false + */ + readonly shell?: boolean | string; - @default true - */ - readonly stripFinalNewline?: boolean; + /** + Strip the final [newline character](https://en.wikipedia.org/wiki/Newline) from the output. - /** - Prefer locally installed binaries when looking for a binary to execute. + @default true + */ + readonly stripFinalNewline?: boolean; - If you `$ npm install foo`, you can then `execa('foo')`. + /** + Prefer locally installed binaries when looking for a binary to execute. - @default true - */ - readonly preferLocal?: boolean; + If you `$ npm install foo`, you can then `execa('foo')`. - /** - Preferred path to find locally installed binaries in (use with `preferLocal`). + @default true + */ + readonly preferLocal?: boolean; - @default process.cwd() - */ - readonly localDir?: string; + /** + Preferred path to find locally installed binaries in (use with `preferLocal`). - /** - Setting this to `false` resolves the promise with the error instead of rejecting it. + @default process.cwd() + */ + readonly localDir?: string; - @default true - */ - readonly reject?: boolean; + /** + Setting this to `false` resolves the promise with the error instead of rejecting it. - /** - Keep track of the spawned process and `kill` it when the parent process exits. + @default true + */ + readonly reject?: boolean; - @default true - */ - readonly cleanup?: boolean; + /** + Keep track of the spawned process and `kill` it when the parent process exits. - /** - Specify the character encoding used to decode the `stdout` and `stderr` output. If set to `null`, then `stdout` and `stderr` will be a `Buffer` instead of a string. + @default true + */ + readonly cleanup?: boolean; - @default 'utf8' - */ - readonly encoding?: EncodingType; + /** + Specify the character encoding used to decode the `stdout` and `stderr` output. If set to `null`, then `stdout` and `stderr` will be a `Buffer` instead of a 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 - */ - readonly timeout?: number; - - /** - Buffer the output from the spawned process. When buffering is disabled you must consume the output of the `stdout` and `stderr` streams because the promise will not be resolved/rejected until they have completed. + @default 'utf8' + */ + readonly encoding?: EncodingType; - @default true - */ - readonly buffer?: boolean; + /** + 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. - /** - Largest amount of data in bytes allowed on `stdout` or `stderr`. Default: 10MB. + @default 0 + */ + readonly timeout?: number; - @default 10000000 - */ - readonly maxBuffer?: number; + /** + Buffer the output from the spawned process. When buffering is disabled you must consume the output of the `stdout` and `stderr` streams because the promise will not be resolved/rejected until they have completed. - /** - Signal value to be used when the spawned process will be killed. - - @default 'SIGTERM' - */ - readonly killSignal?: string | number; - - /** - Same options as [`stdio`](https://nodejs.org/dist/latest-v6.x/docs/api/child_process.html#child_process_options_stdio). - - @default 'pipe' - */ - readonly stdin?: StdioOption; + @default true + */ + readonly buffer?: boolean; - /** - Same options as [`stdio`](https://nodejs.org/dist/latest-v6.x/docs/api/child_process.html#child_process_options_stdio). - - @default 'pipe' - */ - readonly stdout?: StdioOption; - - /** - Same options as [`stdio`](https://nodejs.org/dist/latest-v6.x/docs/api/child_process.html#child_process_options_stdio). - - @default 'pipe' - */ - readonly stderr?: StdioOption; - - /** - If `true`, no quoting or escaping of arguments is done on Windows. Ignored on other platforms. This is set to `true` automatically when the `shell` option is `true`. - - @default false - */ - readonly windowsVerbatimArguments?: boolean; -} - -export interface Options - extends CommonOptions { - /** - Write some input to the `stdin` of your binary. - */ - readonly input?: string | Buffer | ReadableStream; -} + /** + Largest amount of data in bytes allowed on `stdout` or `stderr`. Default: 10MB. -export interface SyncOptions - extends CommonOptions { - /** - Write some input to the `stdin` of your binary. - */ - readonly input?: string | Buffer; -} + @default 10000000 + */ + readonly maxBuffer?: number; -export interface ExecaReturnBase { - /** - The numeric exit code of the process that was run. - */ - exitCode: number; + /** + Signal value to be used when the spawned process will be killed. - /** - The textual exit code of the process that was run. - */ - exitCodeName: string; + @default 'SIGTERM' + */ + readonly killSignal?: string | number; - /** - The output of the process on stdout. - */ - stdout: StdoutStderrType; + /** + Same options as [`stdio`](https://nodejs.org/dist/latest-v6.x/docs/api/child_process.html#child_process_options_stdio). - /** - The output of the process on stderr. - */ - stderr: StdoutStderrType; + @default 'pipe' + */ + readonly stdin?: StdioOption; - /** - Whether the process failed to run. - */ - failed: boolean; + /** + Same options as [`stdio`](https://nodejs.org/dist/latest-v6.x/docs/api/child_process.html#child_process_options_stdio). - /** - The signal that was used to terminate the process. - */ - signal?: string; + @default 'pipe' + */ + readonly stdout?: StdioOption; - /** - The command that was run. - */ - command: string; + /** + Same options as [`stdio`](https://nodejs.org/dist/latest-v6.x/docs/api/child_process.html#child_process_options_stdio). - /** - Whether the process timed out. - */ - timedOut: boolean; + @default 'pipe' + */ + readonly stderr?: StdioOption; - /** - Whether the process was killed. - */ - killed: boolean; -} + /** + If `true`, no quoting or escaping of arguments is done on Windows. Ignored on other platforms. This is set to `true` automatically when the `shell` option is `true`. -export interface ExecaSyncReturnValue - extends ExecaReturnBase { - /** - The exit code of the process that was run. - */ - code: number; -} + @default false + */ + readonly windowsVerbatimArguments?: boolean; + } -export interface ExecaReturnValue - extends ExecaSyncReturnValue { - /** - The output of the process with `stdout` and `stderr` interleaved. - */ - all: StdoutErrorType; + interface Options extends CommonOptions { + /** + Write some input to the `stdin` of your binary. + */ + readonly input?: string | Buffer | ReadableStream; + } - /** - Whether the process was canceled. - */ - isCanceled: boolean; -} + interface SyncOptions + extends CommonOptions { + /** + Write some input to the `stdin` of your binary. + */ + readonly input?: string | Buffer; + } -export interface ExecaSyncError - extends Error, - ExecaReturnBase { - /** - The error message. - */ - message: string; + interface ExecaReturnBase { + /** + The numeric exit code of the process that was run. + */ + exitCode: number; + + /** + The textual exit code of the process that was run. + */ + exitCodeName: string; + + /** + The output of the process on stdout. + */ + stdout: StdoutStderrType; + + /** + The output of the process on stderr. + */ + stderr: StdoutStderrType; + + /** + Whether the process failed to run. + */ + failed: boolean; + + /** + The signal that was used to terminate the process. + */ + signal?: string; + + /** + The command that was run. + */ + command: string; + + /** + Whether the process timed out. + */ + timedOut: boolean; + + /** + Whether the process was killed. + */ + killed: boolean; + } - /** - The exit code (either numeric or textual) of the process that was run. - */ - code: number | string; -} + interface ExecaSyncReturnValue + extends ExecaReturnBase { + /** + The exit code of the process that was run. + */ + code: number; + } -export interface ExecaError - extends ExecaSyncError { - /** - The output of the process with `stdout` and `stderr` interleaved. - */ - all: StdoutErrorType; + interface ExecaReturnValue + extends ExecaSyncReturnValue { + /** + The output of the process with `stdout` and `stderr` interleaved. + */ + all: StdoutErrorType; + + /** + Whether the process was canceled. + */ + isCanceled: boolean; + } - /** - Whether the process was canceled. - */ - isCanceled: boolean; -} + interface ExecaSyncError + extends Error, + ExecaReturnBase { + /** + The error message. + */ + message: string; + + /** + The exit code (either numeric or textual) of the process that was run. + */ + code: number | string; + } -export interface ExecaChildPromise { - catch( - onRejected?: - | ((reason: ExecaError) => ResultType | PromiseLike) - | null - ): Promise | ResultType>; + interface ExecaError + extends ExecaSyncError { + /** + The output of the process with `stdout` and `stderr` interleaved. + */ + all: StdoutErrorType; + + /** + Whether the process was canceled. + */ + isCanceled: boolean; + } - /** - Cancel the subprocess. + interface ExecaChildPromise { + catch( + onRejected?: + | (( + reason: ExecaError + ) => ResultType | PromiseLike) + | null + ): Promise | ResultType>; + + /** + Cancel the subprocess. + + Causes the promise to reject an error with a `.isCanceled = true` property, provided the process gets canceled. The process will not be canceled if it has already exited. + */ + cancel(): void; + } - Causes the promise to reject an error with a `.isCanceled = true` property, provided the process gets canceled. The process will not be canceled if it has already exited. - */ - cancel(): void; + type ExecaChildProcess = ChildProcess & + ExecaChildPromise & + Promise>; } -export type ExecaChildProcess = ChildProcess & - ExecaChildPromise & - Promise>; - declare const execa: { /** Execute a file. @@ -338,15 +341,17 @@ declare const execa: { ( file: string, arguments?: ReadonlyArray, - options?: Options - ): ExecaChildProcess; + options?: execa.Options + ): execa.ExecaChildProcess; ( file: string, arguments?: ReadonlyArray, - options?: Options - ): ExecaChildProcess; - (file: string, options?: Options): ExecaChildProcess; - (file: string, options?: Options): ExecaChildProcess; + options?: execa.Options + ): execa.ExecaChildProcess; + (file: string, options?: execa.Options): execa.ExecaChildProcess; + (file: string, options?: execa.Options): execa.ExecaChildProcess< + Buffer + >; /** Same as `execa()`, but returns only `stdout`. @@ -358,15 +363,15 @@ declare const execa: { stdout( file: string, arguments?: ReadonlyArray, - options?: Options + options?: execa.Options ): Promise; stdout( file: string, arguments?: ReadonlyArray, - options?: Options + options?: execa.Options ): Promise; - stdout(file: string, options?: Options): Promise; - stdout(file: string, options?: Options): Promise; + stdout(file: string, options?: execa.Options): Promise; + stdout(file: string, options?: execa.Options): Promise; /** Same as `execa()`, but returns only `stderr`. @@ -378,15 +383,15 @@ declare const execa: { stderr( file: string, arguments?: ReadonlyArray, - options?: Options + options?: execa.Options ): Promise; stderr( file: string, arguments?: ReadonlyArray, - options?: Options + options?: execa.Options ): Promise; - stderr(file: string, options?: Options): Promise; - stderr(file: string, options?: Options): Promise; + stderr(file: string, options?: execa.Options): Promise; + stderr(file: string, options?: execa.Options): Promise; /** Execute a command through the system shell. @@ -427,8 +432,11 @@ declare const execa: { })(); ``` */ - shell(command: string, options?: Options): ExecaChildProcess; - shell(command: string, options?: Options): ExecaChildProcess; + shell(command: string, options?: execa.Options): execa.ExecaChildProcess; + shell( + command: string, + options?: execa.Options + ): execa.ExecaChildProcess; /** Execute a file synchronously. @@ -442,15 +450,18 @@ declare const execa: { sync( file: string, arguments?: ReadonlyArray, - options?: SyncOptions - ): ExecaSyncReturnValue; + options?: execa.SyncOptions + ): execa.ExecaSyncReturnValue; sync( file: string, arguments?: ReadonlyArray, - options?: SyncOptions - ): ExecaSyncReturnValue; - sync(file: string, options?: SyncOptions): ExecaSyncReturnValue; - sync(file: string, options?: SyncOptions): ExecaSyncReturnValue; + options?: execa.SyncOptions + ): execa.ExecaSyncReturnValue; + sync(file: string, options?: execa.SyncOptions): execa.ExecaSyncReturnValue; + sync( + file: string, + options?: execa.SyncOptions + ): execa.ExecaSyncReturnValue; /** Execute a command synchronously through the system shell. @@ -482,11 +493,14 @@ declare const execa: { } ``` */ - shellSync(command: string, options?: Options): ExecaSyncReturnValue; shellSync( command: string, - options?: Options - ): ExecaSyncReturnValue; + options?: execa.Options + ): execa.ExecaSyncReturnValue; + shellSync( + command: string, + options?: execa.Options + ): execa.ExecaSyncReturnValue; }; -export default execa; +export = execa; diff --git a/index.js b/index.js index 81d0c8022..92bfc6afc 100644 --- a/index.js +++ b/index.js @@ -375,7 +375,6 @@ const execa = (command, args, options) => { }; module.exports = execa; -module.exports.default = execa; // TODO: set `stderr: 'ignore'` when that option is implemented module.exports.stdout = async (...args) => { diff --git a/index.test-d.ts b/index.test-d.ts index 12d63e983..23c06591b 100644 --- a/index.test-d.ts +++ b/index.test-d.ts @@ -1,5 +1,6 @@ import {expectType, expectError} from 'tsd'; -import execa, { +import execa = require('.'); +import { ExecaReturnValue, ExecaChildProcess, ExecaError, diff --git a/package.json b/package.json index b478523f2..79eef9557 100644 --- a/package.json +++ b/package.json @@ -38,25 +38,25 @@ "local" ], "dependencies": { - "cross-spawn": "^6.0.0", - "get-stream": "^4.0.0", + "cross-spawn": "^6.0.5", + "get-stream": "^5.0.0", "is-stream": "^1.1.0", "merge-stream": "^1.0.1", - "npm-run-path": "^2.0.0", + "npm-run-path": "^3.0.0", "p-finally": "^1.0.0", - "signal-exit": "^3.0.0", + "signal-exit": "^3.0.2", "strip-final-newline": "^2.0.0" }, "devDependencies": { - "@types/node": "^11.11.4", - "ava": "^1.3.1", + "@types/node": "^11.12.2", + "ava": "^1.4.1", "cat-names": "^2.0.0", "coveralls": "^3.0.3", "delay": "^4.1.0", - "is-running": "^2.0.0", + "is-running": "^2.1.0", "nyc": "^13.3.0", "tempfile": "^2.0.0", - "tsd": "^0.7.0", + "tsd": "^0.7.1", "xo": "^0.24.0" }, "nyc": {