This commit is contained in:
2024-11-28 23:08:17 +01:00
parent 8895fde030
commit 0dda8e760c
16116 changed files with 2866428 additions and 71 deletions

21
node_modules/start-server-and-test/LICENSE generated vendored Normal file
View File

@@ -0,0 +1,21 @@
MIT License
Copyright (c) 2022 bahmutov
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

399
node_modules/start-server-and-test/README.md generated vendored Normal file
View File

@@ -0,0 +1,399 @@
# start-server-and-test
> Starts server, waits for URL, then runs test command; when the tests end, shuts down server
[![NPM][npm-icon] ][npm-url]
[![Build status][ci-image] ][ci-url]
[![semantic-release][semantic-image] ][semantic-url]
[![js-standard-style][standard-image]][standard-url]
[![renovate-app badge][renovate-badge]][renovate-app]
## Install
Requires [Node](https://nodejs.org/en/) version 16 or above.
```sh
npm install --save-dev start-server-and-test
```
## Upgrade
### v1 to v2
If you are using just the port number, and the resolved URL `localhost:xxxx` no longer works, use the explicit `http://localhost:xxxx` instead
```
# v1
$ npx start-test 3000
# v2
$ npx start-test http://localhost:3000
```
## Use
This command is meant to be used with NPM script commands. If you have a "start server", and "test" script names for example, you can start the server, wait for a url to respond, then run tests. When the test process exits, the server is shut down.
```json
{
"scripts": {
"start-server": "npm start",
"test": "mocha e2e-spec.js",
"ci": "start-server-and-test start-server http://localhost:8080 test"
}
}
```
To execute all tests simply run `npm run ci`.
### Commands
In addition to using NPM script names, you can pass entire commands (surround them with quotes so it is still a single string) that will be executed "as is". For example, to start globally installed `http-server` before running and recording [Cypress.io](https://www.cypress.io) tests you can use
```shell
# run http-server, then when port 8000 responds run Cypress tests
start-server-and-test 'http-server -c-1 --silent' 8000 './node_modules/.bin/cypress run --record'
```
Because `npm` scripts execute with `./node_modules/.bin` in the `$PATH`, you can mix global and locally installed tools when using commands inside `package.json` file. For example, if you want to run a single spec file:
```json
{
"scripts": {
"ci": "start-server-and-test 'http-server -c-1 --silent' 8080 'cypress run --spec cypress/integration/location.spec.js'"
}
}
```
Or you can move `http-server` part into its own `start` script, which is used by default and have the equivalent JSON
```json
{
"scripts": {
"start": "http-server -c-1 --silent",
"ci": "start-server-and-test 8080 'cypress run --spec cypress/integration/location.spec.js'"
}
}
```
Here is another example that uses Mocha
```json
{
"scripts": {
"ci": "start-server-and-test 'http-server -c-1 --silent' 8080 'mocha e2e-spec.js'"
}
}
```
### Alias
You can use either `start-server-and-test`, `server-test` or `start-test` commands in your scripts.
You can use `:` in front of port number like `server-test :8080`, so all these are equivalent
```
start-server-and-test start http://127.0.0.1:8080 test
server-test start http://127.0.0.1:8080 test
server-test http://127.0.0.1:8080 test
server-test 127.0.0.1:8080 test
start-test :8080 test
start-test 8080 test
start-test 8080
```
**Tip:** I highly recommend you specify the full url instead of the port, see the `localhost vs 0.0.0.0 vs 127.0.0.1` section later in this README.
### Options
If you use convention and name your scripts "start" and "test" you can simply provide URL
```json
{
"scripts": {
"start": "npm start",
"test": "mocha e2e-spec.js",
"ci": "start-server-and-test http://localhost:8080"
}
}
```
You can also shorten local url to just port, the code below is equivalent to checking `http://127.0.0.1:8080`.
```json
{
"scripts": {
"start": "npm start",
"test": "mocha e2e-spec.js",
"ci": "server-test 8080"
}
}
```
You can provide first start command, port (or url) and implicit `test` command
```json
{
"scripts": {
"start-it": "npm start",
"test": "mocha e2e-spec.js",
"ci": "server-test start-it 8080"
}
}
```
You can provide port number and custom test command, in that case `npm start` is assumed to start the server.
```json
{
"scripts": {
"start": "npm start",
"test-it": "mocha e2e-spec.js",
"ci": "server-test :9000 test-it"
}
}
```
You can provide multiple resources to wait on, separated by a pipe `|`. _(be sure to wrap in quotes)_
```json
{
"scripts": {
"start": "npm start",
"test-it": "mocha e2e-spec.js",
"ci": "server-test \"8080|http://foo.com\""
}
}
```
or for multiple ports simply: `server-test '8000|9000' test`.
If you want to start the server, wait for it to respond, and then run multiple test commands (and stop the server after they finish), you should be able to use `&&` to separate the test commands:
```json
{
"scripts": {
"start": "npm start",
"test:unit": "mocha test.js",
"test:e2e": "mocha e2e.js",
"ci": "start-test 9000 'npm run test:unit && npm run test:e2e'"
}
}
```
The above script `ci` after the `127.0.0.1:9000` responds executes the `npm run test:unit` command. Then when it finishes it runs `npm run test:e2e`. If the first or second command fails, the `ci` script fails. Of course, your mileage on Windows might vary.
#### expected
The server might respond, but require authorization, returning an error HTTP code by default. You can still know that the server is responding by using `--expect` argument (or its alias `--expected`):
```
$ start-test --expect 403 start :9000 test:e2e
```
See `demo-expect-403` NPM script.
Default expected value is 200.
## `npx` and `yarn`
If you have [npx](https://www.npmjs.com/package/npx) available, you can execute locally installed tools from the shell. For example, if the `package.json` has the following local tools:
```json
{
"devDependencies": {
"cypress": "3.2.0",
"http-server": "0.11.1",
"start-server-and-test": "1.9.0"
}
}
```
Then you can execute tests simply:
```text
$ npx start-test 'http-server -c-1 .' 8080 'cypress run'
starting server using command "http-server -c-1 ."
and when url "http://127.0.0.1:8080" is responding
running tests using command "cypress run"
Starting up http-server, serving .
...
```
Similarly, you can use [yarn](https://yarnpkg.com/en/) to call locally installed tools
```text
$ yarn start-test 'http-server -c-1 .' 8080 'cypress run'
yarn run v1.13.0
$ /private/tmp/test-t/node_modules/.bin/start-test 'http-server -c-1 .' 8080 'cypress run'
starting server using command "http-server -c-1 ."
and when url "http://127.0.0.1:8080" is responding
running tests using command "cypress run"
Starting up http-server, serving .
...
```
## localhost vs 0.0.0.0 vs 127.0.0.1
The latest versions of Node and some web servers listen on host `0.0.0.0` which _no longer means localhost_. Thus if you specify _just the port number_, like `:3000`, this package will try `http://127.0.0.1:3000` to ping the server. A good practice is to specify the full URL you would like to ping.
```
# same as "http://127.0.0.1:3000"
start-server start 3000 test
# better
start-server start http://127.0.0.1:3000 test
# or
start-server start http://0.0.0.0:3000 test
# of course, if your server is listening on localhost
# you can still set the URL
start-server start http://localhost:3000 test
```
If you specify just `localhost` or `127.0.0.1` or `0.0.0.0`, it automatically pings `http://...` URL.
```
start-test localhost:3000
# is the same as
start-test http://localhost:3000
```
## Note for yarn users
By default, npm is used to run scripts, however you can specify that yarn is used as follows:
```json
"scripts": {
"start-server": "yarn start",
"test": "mocha e2e-spec.js",
"ci": "start-server-and-test 'yarn start-server' http://localhost:8080 'yarn test'"
}
```
## Note for webpack-dev-server users
Also applies to **Vite** users!
If you are using [webpack-dev-server](https://www.npmjs.com/package/webpack-dev-server) (directly or via `angular/cli` or other boilerplates) then the server does not respond to HEAD requests from `start-server-and-test`. You can check if the server responds to the HEAD requests by starting the server and pinging it from another terminal using `curl`
```
# from the first terminal start the server
$ npm start
# from the second terminal call the server with HEAD request
$ curl --head http://localhost:3000
```
If the server responds with 404, then it does not handle the HEAD requests. You have two solutions:
### Use HTTP GET requests
You can force the `start-server-and-test` to ping the server using GET requests using the `http-get://` prefix:
```
start-server-and-test http-get://localhost:8080
```
### Ping a specific resource
As an alternative to using GET method to request the root page, you can try pinging a specific resource, see the discussion in the [issue #4](https://github.com/bahmutov/start-server-and-test/issues/4).
```
# maybe the server responds to HEAD requests to the HTML page
start-server-and-test http://localhost:3000/index.html
# or maybe the server responds to HEAD requests to JS resource
start-server-and-test http://localhost:8080/app.js
```
### Explanation
You can watch the explanation in the video [Debug a Problem in start-server-and-test](https://youtu.be/rxyZOxYCsAk).
Under the hood this module uses [wait-on](https://github.com/jeffbski/wait-on) to ping the server. Wait-on uses `HEAD` by default, but `webpack-dev-server` does not respond to `HEAD` only to `GET` requests. Thus you need to use `http-get://` URL format to force `wait-on` to use `GET` probe or ask for a particular resource.
### Debugging
To see diagnostic messages, run with environment variable `DEBUG=start-server-and-test`
```
$ DEBUG=start-server-and-test npm run test
start-server-and-test parsing CLI arguments: [ 'dev', '3000', 'subtask' ] +0ms
start-server-and-test parsed args: { services: [ { start: 'npm run dev', url: [Array] } ], test: 'npm run subtask' }
...
making HTTP(S) head request to url:http://127.0.0.1:3000 ...
HTTP(S) error for http://127.0.0.1:3000 Error: Request failed with status code 404
```
### Disable HTTPS certificate checks
To disable HTTPS checks for `wait-on`, run with environment variable `START_SERVER_AND_TEST_INSECURE=1`.
### Timeout
This utility will wait for maximum of 5 minutes while checking for the server to respond (default). Setting an environment variable `WAIT_ON_TIMEOUT=600000` (milliseconds) sets the timeout for example to 10 minutes.
### Interval
This utility will check for a server response every two seconds (default). Setting an environment variable `WAIT_ON_INTERVAL=600000` (milliseconds) sets the interval for example to 10 minutes.
### Starting two servers
Sometimes you need to start one API server and one webserver in order to test the application. Use the syntax:
```
start-test <first command> <first resource> <second command> <second resource> <test command>
```
For example if API runs at port 3000 and server runs at port 8080:
```json
{
"scripts": {
"test": "node src/test",
"start:api": "node src/api",
"start:server": "node src/server",
"test:all": "start-test start:api 3000 start:server 8080 test"
}
}
```
In the above example you would run `npm run test:all` to start the API first, then when it responds, start the server, and when the server is responding, it would run the tests. After the tests finish, it will shut down both servers. See the repo [start-two-servers-example](https://github.com/bahmutov/start-two-servers-example) for full example
## Note for Apollo Server users
When passing a simple GET request to Apollo Server it will respond with a 405 error. To get around this problem you need to pass a valid GraphQL query into the query parameter. Passing in a basic schema introspection query will work to determine the presence of an Apollo Server. You can configure your npm script like so:
```json
{
"scripts": {
"ci": "start-server-and-test start 'http-get://localhost:4000/graphql?query={ __schema { queryType { name } } }' test"
}
}
```
### Small print
Author: Gleb Bahmutov &lt;gleb.bahmutov@gmail.com&gt; &copy; 2017
* [@bahmutov](https://twitter.com/bahmutov)
* [glebbahmutov.com](https://glebbahmutov.com)
* [blog](https://glebbahmutov.com/blog)
License: MIT - do anything with the code, but don't blame me if it does not work.
Support: if you find any problems with this module, email / tweet /
[open issue](https://github.com/bahmutov/start-server-and-test/issues) on Github
## MIT License
See [LICENSE](./LICENSE)
[npm-icon]: https://nodei.co/npm/start-server-and-test.svg?downloads=true
[npm-url]: https://npmjs.org/package/start-server-and-test
[ci-image]: https://github.com/bahmutov/start-server-and-test/workflows/ci/badge.svg?branch=master
[ci-url]: https://github.com/bahmutov/start-server-and-test/actions
[semantic-image]: https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg
[semantic-url]: https://github.com/semantic-release/semantic-release
[standard-image]: https://img.shields.io/badge/code%20style-standard-brightgreen.svg
[standard-url]: http://standardjs.com/
[renovate-badge]: https://img.shields.io/badge/renovate-app-blue.svg
[renovate-app]: https://renovateapp.com/

View File

@@ -0,0 +1,564 @@
/// <reference types="node"/>
import {ChildProcess} from 'child_process';
import {Stream, Readable as ReadableStream} from 'stream';
declare namespace execa {
type StdioOption =
| 'pipe'
| 'ipc'
| 'ignore'
| 'inherit'
| Stream
| number
| undefined;
interface CommonOptions<EncodingType> {
/**
Kill the spawned process when the parent process exits unless either:
- the spawned process is [`detached`](https://nodejs.org/api/child_process.html#child_process_options_detached)
- the parent process is terminated abruptly, for example, with `SIGKILL` as opposed to `SIGTERM` or a normal exit
@default true
*/
readonly cleanup?: boolean;
/**
Prefer locally installed binaries when looking for a binary to execute.
If you `$ npm install foo`, you can then `execa('foo')`.
@default false
*/
readonly preferLocal?: boolean;
/**
Preferred path to find locally installed binaries in (use with `preferLocal`).
@default process.cwd()
*/
readonly localDir?: string;
/**
Path to the Node.js executable to use in child processes.
This can be either an absolute path or a path relative to the `cwd` option.
Requires `preferLocal` to be `true`.
For example, this can be used together with [`get-node`](https://github.com/ehmicky/get-node) to run a specific Node.js version in a child process.
@default process.execPath
*/
readonly execPath?: string;
/**
Buffer the output from the spawned process. When set to `false`, you must read the output of `stdout` and `stderr` (or `all` if the `all` option is `true`). Otherwise the returned promise will not be resolved/rejected.
If the spawned process fails, `error.stdout`, `error.stderr`, and `error.all` will contain the buffered data.
@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 stdin?: StdioOption;
/**
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;
/**
Setting this to `false` resolves the promise with the error instead of rejecting it.
@default true
*/
readonly reject?: boolean;
/**
Add an `.all` property on the promise and the resolved value. The property contains the output of the process with `stdout` and `stderr` interleaved.
@default false
*/
readonly all?: boolean;
/**
Strip the final [newline character](https://en.wikipedia.org/wiki/Newline) from the output.
@default true
*/
readonly stripFinalNewline?: boolean;
/**
Set to `false` if you don't want to extend the environment variables when providing the `env` property.
@default true
*/
readonly extendEnv?: boolean;
/**
Current working directory of the child process.
@default process.cwd()
*/
readonly cwd?: string;
/**
Environment key-value pairs. Extends automatically from `process.env`. Set `extendEnv` to `false` if you don't want this.
@default process.env
*/
readonly env?: NodeJS.ProcessEnv;
/**
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;
/**
Child's [stdio](https://nodejs.org/api/child_process.html#child_process_options_stdio) configuration.
@default 'pipe'
*/
readonly stdio?: 'pipe' | 'ignore' | 'inherit' | readonly StdioOption[];
/**
Specify the kind of serialization used for sending messages between processes when using the `stdio: 'ipc'` option or `execa.node()`:
- `json`: Uses `JSON.stringify()` and `JSON.parse()`.
- `advanced`: Uses [`v8.serialize()`](https://nodejs.org/api/v8.html#v8_v8_serialize_value)
Requires Node.js `13.2.0` or later.
[More info.](https://nodejs.org/api/child_process.html#child_process_advanced_serialization)
@default 'json'
*/
readonly serialization?: 'json' | 'advanced';
/**
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 false
*/
readonly detached?: boolean;
/**
Sets the user identity of the process.
*/
readonly uid?: number;
/**
Sets the group identity of the process.
*/
readonly 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.
We recommend against using this option since it is:
- not cross-platform, encouraging shell-specific syntax.
- slower, because of the additional shell interpretation.
- unsafe, potentially allowing command injection.
@default false
*/
readonly shell?: boolean | string;
/**
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 'utf8'
*/
readonly encoding?: EncodingType;
/**
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;
/**
Largest amount of data in bytes allowed on `stdout` or `stderr`. Default: 100 MB.
@default 100_000_000
*/
readonly maxBuffer?: number;
/**
Signal value to be used when the spawned process will be killed.
@default 'SIGTERM'
*/
readonly killSignal?: string | number;
/**
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;
/**
On Windows, do not create a new console window. Please note this also prevents `CTRL-C` [from working](https://github.com/nodejs/node/issues/29837) on Windows.
@default true
*/
readonly windowsHide?: boolean;
}
interface Options<EncodingType = string> extends CommonOptions<EncodingType> {
/**
Write some input to the `stdin` of your binary.
*/
readonly input?: string | Buffer | ReadableStream;
}
interface SyncOptions<EncodingType = string> extends CommonOptions<EncodingType> {
/**
Write some input to the `stdin` of your binary.
*/
readonly input?: string | Buffer;
}
interface NodeOptions<EncodingType = string> extends Options<EncodingType> {
/**
The Node.js executable to use.
@default process.execPath
*/
readonly nodePath?: string;
/**
List of [CLI options](https://nodejs.org/api/cli.html#cli_options) passed to the Node.js executable.
@default process.execArgv
*/
readonly nodeOptions?: string[];
}
interface ExecaReturnBase<StdoutStderrType> {
/**
The file and arguments that were run, for logging purposes.
This is not escaped and should not be executed directly as a process, including using `execa()` or `execa.command()`.
*/
command: string;
/**
Same as `command` but escaped.
This is meant to be copy and pasted into a shell, for debugging purposes.
Since the escaping is fairly basic, this should not be executed directly as a process, including using `execa()` or `execa.command()`.
*/
escapedCommand: string;
/**
The numeric exit code of the process that was run.
*/
exitCode: number;
/**
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;
/**
Whether the process timed out.
*/
timedOut: boolean;
/**
Whether the process was killed.
*/
killed: boolean;
/**
The name of the signal that was used to terminate the process. For example, `SIGFPE`.
If a signal terminated the process, this property is defined and included in the error message. Otherwise it is `undefined`.
*/
signal?: string;
/**
A human-friendly description of the signal that was used to terminate the process. For example, `Floating point arithmetic error`.
If a signal terminated the process, this property is defined and included in the error message. Otherwise it is `undefined`. It is also `undefined` when the signal is very uncommon which should seldomly happen.
*/
signalDescription?: string;
}
interface ExecaSyncReturnValue<StdoutErrorType = string>
extends ExecaReturnBase<StdoutErrorType> {
}
/**
Result of a child process execution. On success this is a plain object. On failure this is also an `Error` instance.
The child process fails when:
- its exit code is not `0`
- it was killed with a signal
- timing out
- being canceled
- there's not enough memory or there are already too many child processes
*/
interface ExecaReturnValue<StdoutErrorType = string>
extends ExecaSyncReturnValue<StdoutErrorType> {
/**
The output of the process with `stdout` and `stderr` interleaved.
This is `undefined` if either:
- the `all` option is `false` (default value)
- `execa.sync()` was used
*/
all?: StdoutErrorType;
/**
Whether the process was canceled.
*/
isCanceled: boolean;
}
interface ExecaSyncError<StdoutErrorType = string>
extends Error,
ExecaReturnBase<StdoutErrorType> {
/**
Error message when the child process failed to run. In addition to the underlying error message, it also contains some information related to why the child process errored.
The child process stderr then stdout are appended to the end, separated with newlines and not interleaved.
*/
message: string;
/**
This is the same as the `message` property except it does not include the child process stdout/stderr.
*/
shortMessage: string;
/**
Original error message. This is the same as the `message` property except it includes neither the child process stdout/stderr nor some additional information added by Execa.
This is `undefined` unless the child process exited due to an `error` event or a timeout.
*/
originalMessage?: string;
}
interface ExecaError<StdoutErrorType = string>
extends ExecaSyncError<StdoutErrorType> {
/**
The output of the process with `stdout` and `stderr` interleaved.
This is `undefined` if either:
- the `all` option is `false` (default value)
- `execa.sync()` was used
*/
all?: StdoutErrorType;
/**
Whether the process was canceled.
*/
isCanceled: boolean;
}
interface KillOptions {
/**
Milliseconds to wait for the child process to terminate before sending `SIGKILL`.
Can be disabled with `false`.
@default 5000
*/
forceKillAfterTimeout?: number | false;
}
interface ExecaChildPromise<StdoutErrorType> {
/**
Stream combining/interleaving [`stdout`](https://nodejs.org/api/child_process.html#child_process_subprocess_stdout) and [`stderr`](https://nodejs.org/api/child_process.html#child_process_subprocess_stderr).
This is `undefined` if either:
- the `all` option is `false` (the default value)
- both `stdout` and `stderr` options are set to [`'inherit'`, `'ipc'`, `Stream` or `integer`](https://nodejs.org/dist/latest-v6.x/docs/api/child_process.html#child_process_options_stdio)
*/
all?: ReadableStream;
catch<ResultType = never>(
onRejected?: (reason: ExecaError<StdoutErrorType>) => ResultType | PromiseLike<ResultType>
): Promise<ExecaReturnValue<StdoutErrorType> | ResultType>;
/**
Same as the original [`child_process#kill()`](https://nodejs.org/api/child_process.html#child_process_subprocess_kill_signal), except if `signal` is `SIGTERM` (the default value) and the child process is not terminated after 5 seconds, force it by sending `SIGKILL`.
*/
kill(signal?: string, options?: KillOptions): void;
/**
Similar to [`childProcess.kill()`](https://nodejs.org/api/child_process.html#child_process_subprocess_kill_signal). This is preferred when cancelling the child process execution as the error is more descriptive and [`childProcessResult.isCanceled`](#iscanceled) is set to `true`.
*/
cancel(): void;
}
type ExecaChildProcess<StdoutErrorType = string> = ChildProcess &
ExecaChildPromise<StdoutErrorType> &
Promise<ExecaReturnValue<StdoutErrorType>>;
}
declare const execa: {
/**
Execute a file.
Think of this as a mix of `child_process.execFile` and `child_process.spawn`.
@param file - The program/script to execute.
@param arguments - Arguments to pass to `file` on execution.
@returns A [`child_process` instance](https://nodejs.org/api/child_process.html#child_process_class_childprocess), which is enhanced to also be a `Promise` for a result `Object` with `stdout` and `stderr` properties.
@example
```
import execa = require('execa');
(async () => {
const {stdout} = await execa('echo', ['unicorns']);
console.log(stdout);
//=> 'unicorns'
// Cancelling a spawned process
const subprocess = execa('node');
setTimeout(() => {
subprocess.cancel()
}, 1000);
try {
await subprocess;
} catch (error) {
console.log(subprocess.killed); // true
console.log(error.isCanceled); // true
}
})();
// Pipe the child process stdout to the current stdout
execa('echo', ['unicorns']).stdout.pipe(process.stdout);
```
*/
(
file: string,
arguments?: readonly string[],
options?: execa.Options
): execa.ExecaChildProcess;
(
file: string,
arguments?: readonly string[],
options?: execa.Options<null>
): execa.ExecaChildProcess<Buffer>;
(file: string, options?: execa.Options): execa.ExecaChildProcess;
(file: string, options?: execa.Options<null>): execa.ExecaChildProcess<
Buffer
>;
/**
Execute a file synchronously.
This method throws an `Error` if the command fails.
@param file - The program/script to execute.
@param arguments - Arguments to pass to `file` on execution.
@returns A result `Object` with `stdout` and `stderr` properties.
*/
sync(
file: string,
arguments?: readonly string[],
options?: execa.SyncOptions
): execa.ExecaSyncReturnValue;
sync(
file: string,
arguments?: readonly string[],
options?: execa.SyncOptions<null>
): execa.ExecaSyncReturnValue<Buffer>;
sync(file: string, options?: execa.SyncOptions): execa.ExecaSyncReturnValue;
sync(
file: string,
options?: execa.SyncOptions<null>
): execa.ExecaSyncReturnValue<Buffer>;
/**
Same as `execa()` except both file and arguments are specified in a single `command` string. For example, `execa('echo', ['unicorns'])` is the same as `execa.command('echo unicorns')`.
If the file or an argument contains spaces, they must be escaped with backslashes. This matters especially if `command` is not a constant but a variable, for example with `__dirname` or `process.cwd()`. Except for spaces, no escaping/quoting is needed.
The `shell` option must be used if the `command` uses shell-specific features (for example, `&&` or `||`), as opposed to being a simple `file` followed by its `arguments`.
@param command - The program/script to execute and its arguments.
@returns A [`child_process` instance](https://nodejs.org/api/child_process.html#child_process_class_childprocess), which is enhanced to also be a `Promise` for a result `Object` with `stdout` and `stderr` properties.
@example
```
import execa = require('execa');
(async () => {
const {stdout} = await execa.command('echo unicorns');
console.log(stdout);
//=> 'unicorns'
})();
```
*/
command(command: string, options?: execa.Options): execa.ExecaChildProcess;
command(command: string, options?: execa.Options<null>): execa.ExecaChildProcess<Buffer>;
/**
Same as `execa.command()` but synchronous.
@param command - The program/script to execute and its arguments.
@returns A result `Object` with `stdout` and `stderr` properties.
*/
commandSync(command: string, options?: execa.SyncOptions): execa.ExecaSyncReturnValue;
commandSync(command: string, options?: execa.SyncOptions<null>): execa.ExecaSyncReturnValue<Buffer>;
/**
Execute a Node.js script as a child process.
Same as `execa('node', [scriptPath, ...arguments], options)` except (like [`child_process#fork()`](https://nodejs.org/api/child_process.html#child_process_child_process_fork_modulepath_args_options)):
- the current Node version and options are used. This can be overridden using the `nodePath` and `nodeArguments` options.
- the `shell` option cannot be used
- an extra channel [`ipc`](https://nodejs.org/api/child_process.html#child_process_options_stdio) is passed to [`stdio`](#stdio)
@param scriptPath - Node.js script to execute.
@param arguments - Arguments to pass to `scriptPath` on execution.
@returns A [`child_process` instance](https://nodejs.org/api/child_process.html#child_process_class_childprocess), which is enhanced to also be a `Promise` for a result `Object` with `stdout` and `stderr` properties.
*/
node(
scriptPath: string,
arguments?: readonly string[],
options?: execa.NodeOptions
): execa.ExecaChildProcess;
node(
scriptPath: string,
arguments?: readonly string[],
options?: execa.Options<null>
): execa.ExecaChildProcess<Buffer>;
node(scriptPath: string, options?: execa.Options): execa.ExecaChildProcess;
node(scriptPath: string, options?: execa.Options<null>): execa.ExecaChildProcess<Buffer>;
};
export = execa;

View File

@@ -0,0 +1,268 @@
'use strict';
const path = require('path');
const childProcess = require('child_process');
const crossSpawn = require('cross-spawn');
const stripFinalNewline = require('strip-final-newline');
const npmRunPath = require('npm-run-path');
const onetime = require('onetime');
const makeError = require('./lib/error');
const normalizeStdio = require('./lib/stdio');
const {spawnedKill, spawnedCancel, setupTimeout, validateTimeout, setExitHandler} = require('./lib/kill');
const {handleInput, getSpawnedResult, makeAllStream, validateInputSync} = require('./lib/stream');
const {mergePromise, getSpawnedPromise} = require('./lib/promise');
const {joinCommand, parseCommand, getEscapedCommand} = require('./lib/command');
const DEFAULT_MAX_BUFFER = 1000 * 1000 * 100;
const getEnv = ({env: envOption, extendEnv, preferLocal, localDir, execPath}) => {
const env = extendEnv ? {...process.env, ...envOption} : envOption;
if (preferLocal) {
return npmRunPath.env({env, cwd: localDir, execPath});
}
return env;
};
const handleArguments = (file, args, options = {}) => {
const parsed = crossSpawn._parse(file, args, options);
file = parsed.command;
args = parsed.args;
options = parsed.options;
options = {
maxBuffer: DEFAULT_MAX_BUFFER,
buffer: true,
stripFinalNewline: true,
extendEnv: true,
preferLocal: false,
localDir: options.cwd || process.cwd(),
execPath: process.execPath,
encoding: 'utf8',
reject: true,
cleanup: true,
all: false,
windowsHide: true,
...options
};
options.env = getEnv(options);
options.stdio = normalizeStdio(options);
if (process.platform === 'win32' && path.basename(file, '.exe') === 'cmd') {
// #116
args.unshift('/q');
}
return {file, args, options, parsed};
};
const handleOutput = (options, value, error) => {
if (typeof value !== 'string' && !Buffer.isBuffer(value)) {
// When `execa.sync()` errors, we normalize it to '' to mimic `execa()`
return error === undefined ? undefined : '';
}
if (options.stripFinalNewline) {
return stripFinalNewline(value);
}
return value;
};
const execa = (file, args, options) => {
const parsed = handleArguments(file, args, options);
const command = joinCommand(file, args);
const escapedCommand = getEscapedCommand(file, args);
validateTimeout(parsed.options);
let spawned;
try {
spawned = childProcess.spawn(parsed.file, parsed.args, parsed.options);
} catch (error) {
// Ensure the returned error is always both a promise and a child process
const dummySpawned = new childProcess.ChildProcess();
const errorPromise = Promise.reject(makeError({
error,
stdout: '',
stderr: '',
all: '',
command,
escapedCommand,
parsed,
timedOut: false,
isCanceled: false,
killed: false
}));
return mergePromise(dummySpawned, errorPromise);
}
const spawnedPromise = getSpawnedPromise(spawned);
const timedPromise = setupTimeout(spawned, parsed.options, spawnedPromise);
const processDone = setExitHandler(spawned, parsed.options, timedPromise);
const context = {isCanceled: false};
spawned.kill = spawnedKill.bind(null, spawned.kill.bind(spawned));
spawned.cancel = spawnedCancel.bind(null, spawned, context);
const handlePromise = async () => {
const [{error, exitCode, signal, timedOut}, stdoutResult, stderrResult, allResult] = await getSpawnedResult(spawned, parsed.options, processDone);
const stdout = handleOutput(parsed.options, stdoutResult);
const stderr = handleOutput(parsed.options, stderrResult);
const all = handleOutput(parsed.options, allResult);
if (error || exitCode !== 0 || signal !== null) {
const returnedError = makeError({
error,
exitCode,
signal,
stdout,
stderr,
all,
command,
escapedCommand,
parsed,
timedOut,
isCanceled: context.isCanceled,
killed: spawned.killed
});
if (!parsed.options.reject) {
return returnedError;
}
throw returnedError;
}
return {
command,
escapedCommand,
exitCode: 0,
stdout,
stderr,
all,
failed: false,
timedOut: false,
isCanceled: false,
killed: false
};
};
const handlePromiseOnce = onetime(handlePromise);
handleInput(spawned, parsed.options.input);
spawned.all = makeAllStream(spawned, parsed.options);
return mergePromise(spawned, handlePromiseOnce);
};
module.exports = execa;
module.exports.sync = (file, args, options) => {
const parsed = handleArguments(file, args, options);
const command = joinCommand(file, args);
const escapedCommand = getEscapedCommand(file, args);
validateInputSync(parsed.options);
let result;
try {
result = childProcess.spawnSync(parsed.file, parsed.args, parsed.options);
} catch (error) {
throw makeError({
error,
stdout: '',
stderr: '',
all: '',
command,
escapedCommand,
parsed,
timedOut: false,
isCanceled: false,
killed: false
});
}
const stdout = handleOutput(parsed.options, result.stdout, result.error);
const stderr = handleOutput(parsed.options, result.stderr, result.error);
if (result.error || result.status !== 0 || result.signal !== null) {
const error = makeError({
stdout,
stderr,
error: result.error,
signal: result.signal,
exitCode: result.status,
command,
escapedCommand,
parsed,
timedOut: result.error && result.error.code === 'ETIMEDOUT',
isCanceled: false,
killed: result.signal !== null
});
if (!parsed.options.reject) {
return error;
}
throw error;
}
return {
command,
escapedCommand,
exitCode: 0,
stdout,
stderr,
failed: false,
timedOut: false,
isCanceled: false,
killed: false
};
};
module.exports.command = (command, options) => {
const [file, ...args] = parseCommand(command);
return execa(file, args, options);
};
module.exports.commandSync = (command, options) => {
const [file, ...args] = parseCommand(command);
return execa.sync(file, args, options);
};
module.exports.node = (scriptPath, args, options = {}) => {
if (args && !Array.isArray(args) && typeof args === 'object') {
options = args;
args = [];
}
const stdio = normalizeStdio.node(options);
const defaultExecArgv = process.execArgv.filter(arg => !arg.startsWith('--inspect'));
const {
nodePath = process.execPath,
nodeOptions = defaultExecArgv
} = options;
return execa(
nodePath,
[
...nodeOptions,
scriptPath,
...(Array.isArray(args) ? args : [])
],
{
...options,
stdin: undefined,
stdout: undefined,
stderr: undefined,
stdio,
shell: false
}
);
};

View File

@@ -0,0 +1,52 @@
'use strict';
const normalizeArgs = (file, args = []) => {
if (!Array.isArray(args)) {
return [file];
}
return [file, ...args];
};
const NO_ESCAPE_REGEXP = /^[\w.-]+$/;
const DOUBLE_QUOTES_REGEXP = /"/g;
const escapeArg = arg => {
if (typeof arg !== 'string' || NO_ESCAPE_REGEXP.test(arg)) {
return arg;
}
return `"${arg.replace(DOUBLE_QUOTES_REGEXP, '\\"')}"`;
};
const joinCommand = (file, args) => {
return normalizeArgs(file, args).join(' ');
};
const getEscapedCommand = (file, args) => {
return normalizeArgs(file, args).map(arg => escapeArg(arg)).join(' ');
};
const SPACES_REGEXP = / +/g;
// Handle `execa.command()`
const parseCommand = command => {
const tokens = [];
for (const token of command.trim().split(SPACES_REGEXP)) {
// Allow spaces to be escaped by a backslash if not meant as a delimiter
const previousToken = tokens[tokens.length - 1];
if (previousToken && previousToken.endsWith('\\')) {
// Merge previous token with current one
tokens[tokens.length - 1] = `${previousToken.slice(0, -1)} ${token}`;
} else {
tokens.push(token);
}
}
return tokens;
};
module.exports = {
joinCommand,
getEscapedCommand,
parseCommand
};

View File

@@ -0,0 +1,88 @@
'use strict';
const {signalsByName} = require('human-signals');
const getErrorPrefix = ({timedOut, timeout, errorCode, signal, signalDescription, exitCode, isCanceled}) => {
if (timedOut) {
return `timed out after ${timeout} milliseconds`;
}
if (isCanceled) {
return 'was canceled';
}
if (errorCode !== undefined) {
return `failed with ${errorCode}`;
}
if (signal !== undefined) {
return `was killed with ${signal} (${signalDescription})`;
}
if (exitCode !== undefined) {
return `failed with exit code ${exitCode}`;
}
return 'failed';
};
const makeError = ({
stdout,
stderr,
all,
error,
signal,
exitCode,
command,
escapedCommand,
timedOut,
isCanceled,
killed,
parsed: {options: {timeout}}
}) => {
// `signal` and `exitCode` emitted on `spawned.on('exit')` event can be `null`.
// We normalize them to `undefined`
exitCode = exitCode === null ? undefined : exitCode;
signal = signal === null ? undefined : signal;
const signalDescription = signal === undefined ? undefined : signalsByName[signal].description;
const errorCode = error && error.code;
const prefix = getErrorPrefix({timedOut, timeout, errorCode, signal, signalDescription, exitCode, isCanceled});
const execaMessage = `Command ${prefix}: ${command}`;
const isError = Object.prototype.toString.call(error) === '[object Error]';
const shortMessage = isError ? `${execaMessage}\n${error.message}` : execaMessage;
const message = [shortMessage, stderr, stdout].filter(Boolean).join('\n');
if (isError) {
error.originalMessage = error.message;
error.message = message;
} else {
error = new Error(message);
}
error.shortMessage = shortMessage;
error.command = command;
error.escapedCommand = escapedCommand;
error.exitCode = exitCode;
error.signal = signal;
error.signalDescription = signalDescription;
error.stdout = stdout;
error.stderr = stderr;
if (all !== undefined) {
error.all = all;
}
if ('bufferedData' in error) {
delete error.bufferedData;
}
error.failed = true;
error.timedOut = Boolean(timedOut);
error.isCanceled = isCanceled;
error.killed = killed && !timedOut;
return error;
};
module.exports = makeError;

View File

@@ -0,0 +1,115 @@
'use strict';
const os = require('os');
const onExit = require('signal-exit');
const DEFAULT_FORCE_KILL_TIMEOUT = 1000 * 5;
// Monkey-patches `childProcess.kill()` to add `forceKillAfterTimeout` behavior
const spawnedKill = (kill, signal = 'SIGTERM', options = {}) => {
const killResult = kill(signal);
setKillTimeout(kill, signal, options, killResult);
return killResult;
};
const setKillTimeout = (kill, signal, options, killResult) => {
if (!shouldForceKill(signal, options, killResult)) {
return;
}
const timeout = getForceKillAfterTimeout(options);
const t = setTimeout(() => {
kill('SIGKILL');
}, timeout);
// Guarded because there's no `.unref()` when `execa` is used in the renderer
// process in Electron. This cannot be tested since we don't run tests in
// Electron.
// istanbul ignore else
if (t.unref) {
t.unref();
}
};
const shouldForceKill = (signal, {forceKillAfterTimeout}, killResult) => {
return isSigterm(signal) && forceKillAfterTimeout !== false && killResult;
};
const isSigterm = signal => {
return signal === os.constants.signals.SIGTERM ||
(typeof signal === 'string' && signal.toUpperCase() === 'SIGTERM');
};
const getForceKillAfterTimeout = ({forceKillAfterTimeout = true}) => {
if (forceKillAfterTimeout === true) {
return DEFAULT_FORCE_KILL_TIMEOUT;
}
if (!Number.isFinite(forceKillAfterTimeout) || forceKillAfterTimeout < 0) {
throw new TypeError(`Expected the \`forceKillAfterTimeout\` option to be a non-negative integer, got \`${forceKillAfterTimeout}\` (${typeof forceKillAfterTimeout})`);
}
return forceKillAfterTimeout;
};
// `childProcess.cancel()`
const spawnedCancel = (spawned, context) => {
const killResult = spawned.kill();
if (killResult) {
context.isCanceled = true;
}
};
const timeoutKill = (spawned, signal, reject) => {
spawned.kill(signal);
reject(Object.assign(new Error('Timed out'), {timedOut: true, signal}));
};
// `timeout` option handling
const setupTimeout = (spawned, {timeout, killSignal = 'SIGTERM'}, spawnedPromise) => {
if (timeout === 0 || timeout === undefined) {
return spawnedPromise;
}
let timeoutId;
const timeoutPromise = new Promise((resolve, reject) => {
timeoutId = setTimeout(() => {
timeoutKill(spawned, killSignal, reject);
}, timeout);
});
const safeSpawnedPromise = spawnedPromise.finally(() => {
clearTimeout(timeoutId);
});
return Promise.race([timeoutPromise, safeSpawnedPromise]);
};
const validateTimeout = ({timeout}) => {
if (timeout !== undefined && (!Number.isFinite(timeout) || timeout < 0)) {
throw new TypeError(`Expected the \`timeout\` option to be a non-negative integer, got \`${timeout}\` (${typeof timeout})`);
}
};
// `cleanup` option handling
const setExitHandler = async (spawned, {cleanup, detached}, timedPromise) => {
if (!cleanup || detached) {
return timedPromise;
}
const removeExitHandler = onExit(() => {
spawned.kill();
});
return timedPromise.finally(() => {
removeExitHandler();
});
};
module.exports = {
spawnedKill,
spawnedCancel,
setupTimeout,
validateTimeout,
setExitHandler
};

View File

@@ -0,0 +1,46 @@
'use strict';
const nativePromisePrototype = (async () => {})().constructor.prototype;
const descriptors = ['then', 'catch', 'finally'].map(property => [
property,
Reflect.getOwnPropertyDescriptor(nativePromisePrototype, property)
]);
// The return value is a mixin of `childProcess` and `Promise`
const mergePromise = (spawned, promise) => {
for (const [property, descriptor] of descriptors) {
// Starting the main `promise` is deferred to avoid consuming streams
const value = typeof promise === 'function' ?
(...args) => Reflect.apply(descriptor.value, promise(), args) :
descriptor.value.bind(promise);
Reflect.defineProperty(spawned, property, {...descriptor, value});
}
return spawned;
};
// Use promises instead of `child_process` events
const getSpawnedPromise = spawned => {
return new Promise((resolve, reject) => {
spawned.on('exit', (exitCode, signal) => {
resolve({exitCode, signal});
});
spawned.on('error', error => {
reject(error);
});
if (spawned.stdin) {
spawned.stdin.on('error', error => {
reject(error);
});
}
});
};
module.exports = {
mergePromise,
getSpawnedPromise
};

View File

@@ -0,0 +1,52 @@
'use strict';
const aliases = ['stdin', 'stdout', 'stderr'];
const hasAlias = options => aliases.some(alias => options[alias] !== undefined);
const normalizeStdio = options => {
if (!options) {
return;
}
const {stdio} = options;
if (stdio === undefined) {
return aliases.map(alias => options[alias]);
}
if (hasAlias(options)) {
throw new Error(`It's not possible to provide \`stdio\` in combination with one of ${aliases.map(alias => `\`${alias}\``).join(', ')}`);
}
if (typeof stdio === 'string') {
return stdio;
}
if (!Array.isArray(stdio)) {
throw new TypeError(`Expected \`stdio\` to be of type \`string\` or \`Array\`, got \`${typeof stdio}\``);
}
const length = Math.max(stdio.length, aliases.length);
return Array.from({length}, (value, index) => stdio[index]);
};
module.exports = normalizeStdio;
// `ipc` is pushed unless it is already present
module.exports.node = options => {
const stdio = normalizeStdio(options);
if (stdio === 'ipc') {
return 'ipc';
}
if (stdio === undefined || typeof stdio === 'string') {
return [stdio, stdio, stdio, 'ipc'];
}
if (stdio.includes('ipc')) {
return stdio;
}
return [...stdio, 'ipc'];
};

View File

@@ -0,0 +1,97 @@
'use strict';
const isStream = require('is-stream');
const getStream = require('get-stream');
const mergeStream = require('merge-stream');
// `input` option
const handleInput = (spawned, input) => {
// Checking for stdin is workaround for https://github.com/nodejs/node/issues/26852
// @todo remove `|| spawned.stdin === undefined` once we drop support for Node.js <=12.2.0
if (input === undefined || spawned.stdin === undefined) {
return;
}
if (isStream(input)) {
input.pipe(spawned.stdin);
} else {
spawned.stdin.end(input);
}
};
// `all` interleaves `stdout` and `stderr`
const makeAllStream = (spawned, {all}) => {
if (!all || (!spawned.stdout && !spawned.stderr)) {
return;
}
const mixed = mergeStream();
if (spawned.stdout) {
mixed.add(spawned.stdout);
}
if (spawned.stderr) {
mixed.add(spawned.stderr);
}
return mixed;
};
// On failure, `result.stdout|stderr|all` should contain the currently buffered stream
const getBufferedData = async (stream, streamPromise) => {
if (!stream) {
return;
}
stream.destroy();
try {
return await streamPromise;
} catch (error) {
return error.bufferedData;
}
};
const getStreamPromise = (stream, {encoding, buffer, maxBuffer}) => {
if (!stream || !buffer) {
return;
}
if (encoding) {
return getStream(stream, {encoding, maxBuffer});
}
return getStream.buffer(stream, {maxBuffer});
};
// Retrieve result of child process: exit code, signal, error, streams (stdout/stderr/all)
const getSpawnedResult = async ({stdout, stderr, all}, {encoding, buffer, maxBuffer}, processDone) => {
const stdoutPromise = getStreamPromise(stdout, {encoding, buffer, maxBuffer});
const stderrPromise = getStreamPromise(stderr, {encoding, buffer, maxBuffer});
const allPromise = getStreamPromise(all, {encoding, buffer, maxBuffer: maxBuffer * 2});
try {
return await Promise.all([processDone, stdoutPromise, stderrPromise, allPromise]);
} catch (error) {
return Promise.all([
{error, signal: error.signal, timedOut: error.timedOut},
getBufferedData(stdout, stdoutPromise),
getBufferedData(stderr, stderrPromise),
getBufferedData(all, allPromise)
]);
}
};
const validateInputSync = ({input}) => {
if (isStream(input)) {
throw new TypeError('The `input` option cannot be a stream in sync mode');
}
};
module.exports = {
handleInput,
makeAllStream,
getSpawnedResult,
validateInputSync
};

View File

@@ -0,0 +1,9 @@
MIT License
Copyright (c) Sindre Sorhus <sindresorhus@gmail.com> (https://sindresorhus.com)
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

View File

@@ -0,0 +1,74 @@
{
"name": "execa",
"version": "5.1.1",
"description": "Process execution for humans",
"license": "MIT",
"repository": "sindresorhus/execa",
"funding": "https://github.com/sindresorhus/execa?sponsor=1",
"author": {
"name": "Sindre Sorhus",
"email": "sindresorhus@gmail.com",
"url": "https://sindresorhus.com"
},
"engines": {
"node": ">=10"
},
"scripts": {
"test": "xo && nyc ava && tsd"
},
"files": [
"index.js",
"index.d.ts",
"lib"
],
"keywords": [
"exec",
"child",
"process",
"execute",
"fork",
"execfile",
"spawn",
"file",
"shell",
"bin",
"binary",
"binaries",
"npm",
"path",
"local"
],
"dependencies": {
"cross-spawn": "^7.0.3",
"get-stream": "^6.0.0",
"human-signals": "^2.1.0",
"is-stream": "^2.0.0",
"merge-stream": "^2.0.0",
"npm-run-path": "^4.0.1",
"onetime": "^5.1.2",
"signal-exit": "^3.0.3",
"strip-final-newline": "^2.0.0"
},
"devDependencies": {
"@types/node": "^14.14.10",
"ava": "^2.4.0",
"get-node": "^11.0.1",
"is-running": "^2.1.0",
"nyc": "^15.1.0",
"p-event": "^4.2.0",
"tempfile": "^3.0.0",
"tsd": "^0.13.1",
"xo": "^0.35.0"
},
"nyc": {
"reporter": [
"text",
"lcov"
],
"exclude": [
"**/fixtures/**",
"**/test.js",
"**/test/**"
]
}
}

View File

@@ -0,0 +1,663 @@
<img src="media/logo.svg" width="400">
<br>
[![Coverage Status](https://codecov.io/gh/sindresorhus/execa/branch/main/graph/badge.svg)](https://codecov.io/gh/sindresorhus/execa)
> Process execution for humans
## Why
This package improves [`child_process`](https://nodejs.org/api/child_process.html) methods with:
- Promise interface.
- [Strips the final newline](#stripfinalnewline) from the output so you don't have to do `stdout.trim()`.
- Supports [shebang](https://en.wikipedia.org/wiki/Shebang_(Unix)) binaries cross-platform.
- [Improved Windows support.](https://github.com/IndigoUnited/node-cross-spawn#why)
- Higher max buffer. 100 MB instead of 200 KB.
- [Executes locally installed binaries by name.](#preferlocal)
- [Cleans up spawned processes when the parent process dies.](#cleanup)
- [Get interleaved output](#all) from `stdout` and `stderr` similar to what is printed on the terminal. [*(Async only)*](#execasyncfile-arguments-options)
- [Can specify file and arguments as a single string without a shell](#execacommandcommand-options)
- More descriptive errors.
## Install
```
$ npm install execa
```
## Usage
```js
const execa = require('execa');
(async () => {
const {stdout} = await execa('echo', ['unicorns']);
console.log(stdout);
//=> 'unicorns'
})();
```
### Pipe the child process stdout to the parent
```js
const execa = require('execa');
execa('echo', ['unicorns']).stdout.pipe(process.stdout);
```
### Handling Errors
```js
const execa = require('execa');
(async () => {
// Catching an error
try {
await execa('unknown', ['command']);
} catch (error) {
console.log(error);
/*
{
message: 'Command failed with ENOENT: unknown command spawn unknown ENOENT',
errno: -2,
code: 'ENOENT',
syscall: 'spawn unknown',
path: 'unknown',
spawnargs: ['command'],
originalMessage: 'spawn unknown ENOENT',
shortMessage: 'Command failed with ENOENT: unknown command spawn unknown ENOENT',
command: 'unknown command',
escapedCommand: 'unknown command',
stdout: '',
stderr: '',
all: '',
failed: true,
timedOut: false,
isCanceled: false,
killed: false
}
*/
}
})();
```
### Cancelling a spawned process
```js
const execa = require('execa');
(async () => {
const subprocess = execa('node');
setTimeout(() => {
subprocess.cancel();
}, 1000);
try {
await subprocess;
} catch (error) {
console.log(subprocess.killed); // true
console.log(error.isCanceled); // true
}
})()
```
### Catching an error with the sync method
```js
try {
execa.sync('unknown', ['command']);
} catch (error) {
console.log(error);
/*
{
message: 'Command failed with ENOENT: unknown command spawnSync unknown ENOENT',
errno: -2,
code: 'ENOENT',
syscall: 'spawnSync unknown',
path: 'unknown',
spawnargs: ['command'],
originalMessage: 'spawnSync unknown ENOENT',
shortMessage: 'Command failed with ENOENT: unknown command spawnSync unknown ENOENT',
command: 'unknown command',
escapedCommand: 'unknown command',
stdout: '',
stderr: '',
all: '',
failed: true,
timedOut: false,
isCanceled: false,
killed: false
}
*/
}
```
### Kill a process
Using SIGTERM, and after 2 seconds, kill it with SIGKILL.
```js
const subprocess = execa('node');
setTimeout(() => {
subprocess.kill('SIGTERM', {
forceKillAfterTimeout: 2000
});
}, 1000);
```
## API
### execa(file, arguments, options?)
Execute a file. Think of this as a mix of [`child_process.execFile()`](https://nodejs.org/api/child_process.html#child_process_child_process_execfile_file_args_options_callback) and [`child_process.spawn()`](https://nodejs.org/api/child_process.html#child_process_child_process_spawn_command_args_options).
No escaping/quoting is needed.
Unless the [`shell`](#shell) option is used, no shell interpreter (Bash, `cmd.exe`, etc.) is used, so shell features such as variables substitution (`echo $PATH`) are not allowed.
Returns a [`child_process` instance](https://nodejs.org/api/child_process.html#child_process_class_childprocess) which:
- is also a `Promise` resolving or rejecting with a [`childProcessResult`](#childProcessResult).
- exposes the following additional methods and properties.
#### kill(signal?, options?)
Same as the original [`child_process#kill()`](https://nodejs.org/api/child_process.html#child_process_subprocess_kill_signal) except: if `signal` is `SIGTERM` (the default value) and the child process is not terminated after 5 seconds, force it by sending `SIGKILL`.
##### options.forceKillAfterTimeout
Type: `number | false`\
Default: `5000`
Milliseconds to wait for the child process to terminate before sending `SIGKILL`.
Can be disabled with `false`.
#### cancel()
Similar to [`childProcess.kill()`](https://nodejs.org/api/child_process.html#child_process_subprocess_kill_signal). This is preferred when cancelling the child process execution as the error is more descriptive and [`childProcessResult.isCanceled`](#iscanceled) is set to `true`.
#### all
Type: `ReadableStream | undefined`
Stream combining/interleaving [`stdout`](https://nodejs.org/api/child_process.html#child_process_subprocess_stdout) and [`stderr`](https://nodejs.org/api/child_process.html#child_process_subprocess_stderr).
This is `undefined` if either:
- the [`all` option](#all-2) is `false` (the default value)
- both [`stdout`](#stdout-1) and [`stderr`](#stderr-1) options are set to [`'inherit'`, `'ipc'`, `Stream` or `integer`](https://nodejs.org/dist/latest-v6.x/docs/api/child_process.html#child_process_options_stdio)
### execa.sync(file, arguments?, options?)
Execute a file synchronously.
Returns or throws a [`childProcessResult`](#childProcessResult).
### execa.command(command, options?)
Same as [`execa()`](#execafile-arguments-options) except both file and arguments are specified in a single `command` string. For example, `execa('echo', ['unicorns'])` is the same as `execa.command('echo unicorns')`.
If the file or an argument contains spaces, they must be escaped with backslashes. This matters especially if `command` is not a constant but a variable, for example with `__dirname` or `process.cwd()`. Except for spaces, no escaping/quoting is needed.
The [`shell` option](#shell) must be used if the `command` uses shell-specific features (for example, `&&` or `||`), as opposed to being a simple `file` followed by its `arguments`.
### execa.commandSync(command, options?)
Same as [`execa.command()`](#execacommand-command-options) but synchronous.
Returns or throws a [`childProcessResult`](#childProcessResult).
### execa.node(scriptPath, arguments?, options?)
Execute a Node.js script as a child process.
Same as `execa('node', [scriptPath, ...arguments], options)` except (like [`child_process#fork()`](https://nodejs.org/api/child_process.html#child_process_child_process_fork_modulepath_args_options)):
- the current Node version and options are used. This can be overridden using the [`nodePath`](#nodepath-for-node-only) and [`nodeOptions`](#nodeoptions-for-node-only) options.
- the [`shell`](#shell) option cannot be used
- an extra channel [`ipc`](https://nodejs.org/api/child_process.html#child_process_options_stdio) is passed to [`stdio`](#stdio)
### childProcessResult
Type: `object`
Result of a child process execution. On success this is a plain object. On failure this is also an `Error` instance.
The child process [fails](#failed) when:
- its [exit code](#exitcode) is not `0`
- it was [killed](#killed) with a [signal](#signal)
- [timing out](#timedout)
- [being canceled](#iscanceled)
- there's not enough memory or there are already too many child processes
#### command
Type: `string`
The file and arguments that were run, for logging purposes.
This is not escaped and should not be executed directly as a process, including using [`execa()`](#execafile-arguments-options) or [`execa.command()`](#execacommandcommand-options).
#### escapedCommand
Type: `string`
Same as [`command`](#command) but escaped.
This is meant to be copy and pasted into a shell, for debugging purposes.
Since the escaping is fairly basic, this should not be executed directly as a process, including using [`execa()`](#execafile-arguments-options) or [`execa.command()`](#execacommandcommand-options).
#### exitCode
Type: `number`
The numeric exit code of the process that was run.
#### stdout
Type: `string | Buffer`
The output of the process on stdout.
#### stderr
Type: `string | Buffer`
The output of the process on stderr.
#### all
Type: `string | Buffer | undefined`
The output of the process with `stdout` and `stderr` interleaved.
This is `undefined` if either:
- the [`all` option](#all-2) is `false` (the default value)
- `execa.sync()` was used
#### failed
Type: `boolean`
Whether the process failed to run.
#### timedOut
Type: `boolean`
Whether the process timed out.
#### isCanceled
Type: `boolean`
Whether the process was canceled.
#### killed
Type: `boolean`
Whether the process was killed.
#### signal
Type: `string | undefined`
The name of the signal that was used to terminate the process. For example, `SIGFPE`.
If a signal terminated the process, this property is defined and included in the error message. Otherwise it is `undefined`.
#### signalDescription
Type: `string | undefined`
A human-friendly description of the signal that was used to terminate the process. For example, `Floating point arithmetic error`.
If a signal terminated the process, this property is defined and included in the error message. Otherwise it is `undefined`. It is also `undefined` when the signal is very uncommon which should seldomly happen.
#### message
Type: `string`
Error message when the child process failed to run. In addition to the [underlying error message](#originalMessage), it also contains some information related to why the child process errored.
The child process [stderr](#stderr) then [stdout](#stdout) are appended to the end, separated with newlines and not interleaved.
#### shortMessage
Type: `string`
This is the same as the [`message` property](#message) except it does not include the child process stdout/stderr.
#### originalMessage
Type: `string | undefined`
Original error message. This is the same as the `message` property except it includes neither the child process stdout/stderr nor some additional information added by Execa.
This is `undefined` unless the child process exited due to an `error` event or a timeout.
### options
Type: `object`
#### cleanup
Type: `boolean`\
Default: `true`
Kill the spawned process when the parent process exits unless either:
- the spawned process is [`detached`](https://nodejs.org/api/child_process.html#child_process_options_detached)
- the parent process is terminated abruptly, for example, with `SIGKILL` as opposed to `SIGTERM` or a normal exit
#### preferLocal
Type: `boolean`\
Default: `false`
Prefer locally installed binaries when looking for a binary to execute.\
If you `$ npm install foo`, you can then `execa('foo')`.
#### localDir
Type: `string`\
Default: `process.cwd()`
Preferred path to find locally installed binaries in (use with `preferLocal`).
#### execPath
Type: `string`\
Default: `process.execPath` (Current Node.js executable)
Path to the Node.js executable to use in child processes.
This can be either an absolute path or a path relative to the [`cwd` option](#cwd).
Requires [`preferLocal`](#preferlocal) to be `true`.
For example, this can be used together with [`get-node`](https://github.com/ehmicky/get-node) to run a specific Node.js version in a child process.
#### buffer
Type: `boolean`\
Default: `true`
Buffer the output from the spawned process. When set to `false`, you must read the output of [`stdout`](#stdout-1) and [`stderr`](#stderr-1) (or [`all`](#all) if the [`all`](#all-2) option is `true`). Otherwise the returned promise will not be resolved/rejected.
If the spawned process fails, [`error.stdout`](#stdout), [`error.stderr`](#stderr), and [`error.all`](#all) will contain the buffered data.
#### input
Type: `string | Buffer | stream.Readable`
Write some input to the `stdin` of your binary.\
Streams are not allowed when using the synchronous methods.
#### stdin
Type: `string | number | Stream | undefined`\
Default: `pipe`
Same options as [`stdio`](https://nodejs.org/dist/latest-v6.x/docs/api/child_process.html#child_process_options_stdio).
#### stdout
Type: `string | number | Stream | undefined`\
Default: `pipe`
Same options as [`stdio`](https://nodejs.org/dist/latest-v6.x/docs/api/child_process.html#child_process_options_stdio).
#### stderr
Type: `string | number | Stream | undefined`\
Default: `pipe`
Same options as [`stdio`](https://nodejs.org/dist/latest-v6.x/docs/api/child_process.html#child_process_options_stdio).
#### all
Type: `boolean`\
Default: `false`
Add an `.all` property on the [promise](#all) and the [resolved value](#all-1). The property contains the output of the process with `stdout` and `stderr` interleaved.
#### reject
Type: `boolean`\
Default: `true`
Setting this to `false` resolves the promise with the error instead of rejecting it.
#### stripFinalNewline
Type: `boolean`\
Default: `true`
Strip the final [newline character](https://en.wikipedia.org/wiki/Newline) from the output.
#### extendEnv
Type: `boolean`\
Default: `true`
Set to `false` if you don't want to extend the environment variables when providing the `env` property.
---
Execa also accepts the below options which are the same as the options for [`child_process#spawn()`](https://nodejs.org/api/child_process.html#child_process_child_process_spawn_command_args_options)/[`child_process#exec()`](https://nodejs.org/api/child_process.html#child_process_child_process_exec_command_options_callback)
#### cwd
Type: `string`\
Default: `process.cwd()`
Current working directory of the child process.
#### env
Type: `object`\
Default: `process.env`
Environment key-value pairs. Extends automatically from `process.env`. Set [`extendEnv`](#extendenv) to `false` if you don't want this.
#### argv0
Type: `string`
Explicitly set the value of `argv[0]` sent to the child process. This will be set to `file` if not specified.
#### stdio
Type: `string | string[]`\
Default: `pipe`
Child's [stdio](https://nodejs.org/api/child_process.html#child_process_options_stdio) configuration.
#### serialization
Type: `string`\
Default: `'json'`
Specify the kind of serialization used for sending messages between processes when using the [`stdio: 'ipc'`](#stdio) option or [`execa.node()`](#execanodescriptpath-arguments-options):
- `json`: Uses `JSON.stringify()` and `JSON.parse()`.
- `advanced`: Uses [`v8.serialize()`](https://nodejs.org/api/v8.html#v8_v8_serialize_value)
Requires Node.js `13.2.0` or later.
[More info.](https://nodejs.org/api/child_process.html#child_process_advanced_serialization)
#### detached
Type: `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).
#### uid
Type: `number`
Sets the user identity of the process.
#### gid
Type: `number`
Sets the group identity of the process.
#### shell
Type: `boolean | string`\
Default: `false`
If `true`, runs `file` 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.
We recommend against using this option since it is:
- not cross-platform, encouraging shell-specific syntax.
- slower, because of the additional shell interpretation.
- unsafe, potentially allowing command injection.
#### encoding
Type: `string | null`\
Default: `utf8`
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.
#### timeout
Type: `number`\
Default: `0`
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.
#### maxBuffer
Type: `number`\
Default: `100_000_000` (100 MB)
Largest amount of data in bytes allowed on `stdout` or `stderr`.
#### killSignal
Type: `string | number`\
Default: `SIGTERM`
Signal value to be used when the spawned process will be killed.
#### windowsVerbatimArguments
Type: `boolean`\
Default: `false`
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`.
#### windowsHide
Type: `boolean`\
Default: `true`
On Windows, do not create a new console window. Please note this also prevents `CTRL-C` [from working](https://github.com/nodejs/node/issues/29837) on Windows.
#### nodePath *(For `.node()` only)*
Type: `string`\
Default: [`process.execPath`](https://nodejs.org/api/process.html#process_process_execpath)
Node.js executable used to create the child process.
#### nodeOptions *(For `.node()` only)*
Type: `string[]`\
Default: [`process.execArgv`](https://nodejs.org/api/process.html#process_process_execargv)
List of [CLI options](https://nodejs.org/api/cli.html#cli_options) passed to the Node.js executable.
## Tips
### Retry on error
Gracefully handle failures by using automatic retries and exponential backoff with the [`p-retry`](https://github.com/sindresorhus/p-retry) package:
```js
const pRetry = require('p-retry');
const run = async () => {
const results = await execa('curl', ['-sSL', 'https://sindresorhus.com/unicorn']);
return results;
};
(async () => {
console.log(await pRetry(run, {retries: 5}));
})();
```
### Save and pipe output from a child process
Let's say you want to show the output of a child process in real-time while also saving it to a variable.
```js
const execa = require('execa');
const subprocess = execa('echo', ['foo']);
subprocess.stdout.pipe(process.stdout);
(async () => {
const {stdout} = await subprocess;
console.log('child output:', stdout);
})();
```
### Redirect output to a file
```js
const execa = require('execa');
const subprocess = execa('echo', ['foo'])
subprocess.stdout.pipe(fs.createWriteStream('stdout.txt'))
```
### Redirect input from a file
```js
const execa = require('execa');
const subprocess = execa('cat')
fs.createReadStream('stdin.txt').pipe(subprocess.stdin)
```
### Execute the current package's binary
```js
const {getBinPathSync} = require('get-bin-path');
const binPath = getBinPathSync();
const subprocess = execa(binPath);
```
`execa` can be combined with [`get-bin-path`](https://github.com/ehmicky/get-bin-path) to test the current package's binary. As opposed to hard-coding the path to the binary, this validates that the `package.json` `bin` field is correctly set up.
## Related
- [gulp-execa](https://github.com/ehmicky/gulp-execa) - Gulp plugin for `execa`
- [nvexeca](https://github.com/ehmicky/nvexeca) - Run `execa` using any Node.js version
- [sudo-prompt](https://github.com/jorangreef/sudo-prompt) - Run commands with elevated privileges.
## Maintainers
- [Sindre Sorhus](https://github.com/sindresorhus)
- [@ehmicky](https://github.com/ehmicky)
---
<div align="center">
<b>
<a href="https://tidelift.com/subscription/pkg/npm-execa?utm_source=npm-execa&utm_medium=referral&utm_campaign=readme">Get professional support for this package with a Tidelift subscription</a>
</b>
<br>
<sub>
Tidelift helps make open source sustainable for maintainers while giving companies<br>assurances about security, maintenance, and licensing for their dependencies.
</sub>
</div>

View File

@@ -0,0 +1,52 @@
'use strict';
const {PassThrough: PassThroughStream} = require('stream');
module.exports = options => {
options = {...options};
const {array} = options;
let {encoding} = options;
const isBuffer = encoding === 'buffer';
let objectMode = false;
if (array) {
objectMode = !(encoding || isBuffer);
} else {
encoding = encoding || 'utf8';
}
if (isBuffer) {
encoding = null;
}
const stream = new PassThroughStream({objectMode});
if (encoding) {
stream.setEncoding(encoding);
}
let length = 0;
const chunks = [];
stream.on('data', chunk => {
chunks.push(chunk);
if (objectMode) {
length = chunks.length;
} else {
length += chunk.length;
}
});
stream.getBufferedValue = () => {
if (array) {
return chunks;
}
return isBuffer ? Buffer.concat(chunks, length) : chunks.join('');
};
stream.getBufferedLength = () => length;
return stream;
};

View File

@@ -0,0 +1,105 @@
/// <reference types="node"/>
import {Stream} from 'stream';
declare class MaxBufferErrorClass extends Error {
readonly name: 'MaxBufferError';
constructor();
}
declare namespace getStream {
interface Options {
/**
Maximum length of the returned string. If it exceeds this value before the stream ends, the promise will be rejected with a `MaxBufferError` error.
@default Infinity
*/
readonly maxBuffer?: number;
}
interface OptionsWithEncoding<EncodingType = BufferEncoding> extends Options {
/**
[Encoding](https://nodejs.org/api/buffer.html#buffer_buffer) of the incoming stream.
@default 'utf8'
*/
readonly encoding?: EncodingType;
}
type MaxBufferError = MaxBufferErrorClass;
}
declare const getStream: {
/**
Get the `stream` as a string.
@returns A promise that resolves when the end event fires on the stream, indicating that there is no more data to be read. The stream is switched to flowing mode.
@example
```
import * as fs from 'fs';
import getStream = require('get-stream');
(async () => {
const stream = fs.createReadStream('unicorn.txt');
console.log(await getStream(stream));
// ,,))))))));,
// __)))))))))))))),
// \|/ -\(((((''''((((((((.
// -*-==//////(('' . `)))))),
// /|\ ))| o ;-. '((((( ,(,
// ( `| / ) ;))))' ,_))^;(~
// | | | ,))((((_ _____------~~~-. %,;(;(>';'~
// o_); ; )))(((` ~---~ `:: \ %%~~)(v;(`('~
// ; ''''```` `: `:::|\,__,%% );`'; ~
// | _ ) / `:|`----' `-'
// ______/\/~ | / /
// /~;;.____/;;' / ___--,-( `;;;/
// / // _;______;'------~~~~~ /;;/\ /
// // | | / ; \;;,\
// (<_ | ; /',/-----' _>
// \_| ||_ //~;~~~~~~~~~
// `\_| (,~~
// \~\
// ~~
})();
```
*/
(stream: Stream, options?: getStream.OptionsWithEncoding): Promise<string>;
/**
Get the `stream` as a buffer.
It honors the `maxBuffer` option as above, but it refers to byte length rather than string length.
*/
buffer(
stream: Stream,
options?: getStream.Options
): Promise<Buffer>;
/**
Get the `stream` as an array of values.
It honors both the `maxBuffer` and `encoding` options. The behavior changes slightly based on the encoding chosen:
- When `encoding` is unset, it assumes an [object mode stream](https://nodesource.com/blog/understanding-object-streams/) and collects values emitted from `stream` unmodified. In this case `maxBuffer` refers to the number of items in the array (not the sum of their sizes).
- When `encoding` is set to `buffer`, it collects an array of buffers. `maxBuffer` refers to the summed byte lengths of every buffer in the array.
- When `encoding` is set to anything else, it collects an array of strings. `maxBuffer` refers to the summed character lengths of every string in the array.
*/
array<StreamObjectModeType>(
stream: Stream,
options?: getStream.Options
): Promise<StreamObjectModeType[]>;
array(
stream: Stream,
options: getStream.OptionsWithEncoding<'buffer'>
): Promise<Buffer[]>;
array(
stream: Stream,
options: getStream.OptionsWithEncoding<BufferEncoding>
): Promise<string[]>;
MaxBufferError: typeof MaxBufferErrorClass;
};
export = getStream;

View File

@@ -0,0 +1,61 @@
'use strict';
const {constants: BufferConstants} = require('buffer');
const stream = require('stream');
const {promisify} = require('util');
const bufferStream = require('./buffer-stream');
const streamPipelinePromisified = promisify(stream.pipeline);
class MaxBufferError extends Error {
constructor() {
super('maxBuffer exceeded');
this.name = 'MaxBufferError';
}
}
async function getStream(inputStream, options) {
if (!inputStream) {
throw new Error('Expected a stream');
}
options = {
maxBuffer: Infinity,
...options
};
const {maxBuffer} = options;
const stream = bufferStream(options);
await new Promise((resolve, reject) => {
const rejectPromise = error => {
// Don't retrieve an oversized buffer.
if (error && stream.getBufferedLength() <= BufferConstants.MAX_LENGTH) {
error.bufferedData = stream.getBufferedValue();
}
reject(error);
};
(async () => {
try {
await streamPipelinePromisified(inputStream, stream);
resolve();
} catch (error) {
rejectPromise(error);
}
})();
stream.on('data', () => {
if (stream.getBufferedLength() > maxBuffer) {
rejectPromise(new MaxBufferError());
}
});
});
return stream.getBufferedValue();
}
module.exports = getStream;
module.exports.buffer = (stream, options) => getStream(stream, {...options, encoding: 'buffer'});
module.exports.array = (stream, options) => getStream(stream, {...options, array: true});
module.exports.MaxBufferError = MaxBufferError;

View File

@@ -0,0 +1,9 @@
MIT License
Copyright (c) Sindre Sorhus <sindresorhus@gmail.com> (https://sindresorhus.com)
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

View File

@@ -0,0 +1,47 @@
{
"name": "get-stream",
"version": "6.0.1",
"description": "Get a stream as a string, buffer, or array",
"license": "MIT",
"repository": "sindresorhus/get-stream",
"funding": "https://github.com/sponsors/sindresorhus",
"author": {
"name": "Sindre Sorhus",
"email": "sindresorhus@gmail.com",
"url": "https://sindresorhus.com"
},
"engines": {
"node": ">=10"
},
"scripts": {
"test": "xo && ava && tsd"
},
"files": [
"index.js",
"index.d.ts",
"buffer-stream.js"
],
"keywords": [
"get",
"stream",
"promise",
"concat",
"string",
"text",
"buffer",
"read",
"data",
"consume",
"readable",
"readablestream",
"array",
"object"
],
"devDependencies": {
"@types/node": "^14.0.27",
"ava": "^2.4.0",
"into-stream": "^5.0.0",
"tsd": "^0.13.1",
"xo": "^0.24.0"
}
}

View File

@@ -0,0 +1,124 @@
# get-stream
> Get a stream as a string, buffer, or array
## Install
```
$ npm install get-stream
```
## Usage
```js
const fs = require('fs');
const getStream = require('get-stream');
(async () => {
const stream = fs.createReadStream('unicorn.txt');
console.log(await getStream(stream));
/*
,,))))))));,
__)))))))))))))),
\|/ -\(((((''''((((((((.
-*-==//////(('' . `)))))),
/|\ ))| o ;-. '((((( ,(,
( `| / ) ;))))' ,_))^;(~
| | | ,))((((_ _____------~~~-. %,;(;(>';'~
o_); ; )))(((` ~---~ `:: \ %%~~)(v;(`('~
; ''''```` `: `:::|\,__,%% );`'; ~
| _ ) / `:|`----' `-'
______/\/~ | / /
/~;;.____/;;' / ___--,-( `;;;/
/ // _;______;'------~~~~~ /;;/\ /
// | | / ; \;;,\
(<_ | ; /',/-----' _>
\_| ||_ //~;~~~~~~~~~
`\_| (,~~
\~\
~~
*/
})();
```
## API
The methods returns a promise that resolves when the `end` event fires on the stream, indicating that there is no more data to be read. The stream is switched to flowing mode.
### getStream(stream, options?)
Get the `stream` as a string.
#### options
Type: `object`
##### encoding
Type: `string`\
Default: `'utf8'`
[Encoding](https://nodejs.org/api/buffer.html#buffer_buffer) of the incoming stream.
##### maxBuffer
Type: `number`\
Default: `Infinity`
Maximum length of the returned string. If it exceeds this value before the stream ends, the promise will be rejected with a `getStream.MaxBufferError` error.
### getStream.buffer(stream, options?)
Get the `stream` as a buffer.
It honors the `maxBuffer` option as above, but it refers to byte length rather than string length.
### getStream.array(stream, options?)
Get the `stream` as an array of values.
It honors both the `maxBuffer` and `encoding` options. The behavior changes slightly based on the encoding chosen:
- When `encoding` is unset, it assumes an [object mode stream](https://nodesource.com/blog/understanding-object-streams/) and collects values emitted from `stream` unmodified. In this case `maxBuffer` refers to the number of items in the array (not the sum of their sizes).
- When `encoding` is set to `buffer`, it collects an array of buffers. `maxBuffer` refers to the summed byte lengths of every buffer in the array.
- When `encoding` is set to anything else, it collects an array of strings. `maxBuffer` refers to the summed character lengths of every string in the array.
## Errors
If the input stream emits an `error` event, the promise will be rejected with the error. The buffered data will be attached to the `bufferedData` property of the error.
```js
(async () => {
try {
await getStream(streamThatErrorsAtTheEnd('unicorn'));
} catch (error) {
console.log(error.bufferedData);
//=> 'unicorn'
}
})()
```
## FAQ
### How is this different from [`concat-stream`](https://github.com/maxogden/concat-stream)?
This module accepts a stream instead of being one and returns a promise instead of using a callback. The API is simpler and it only supports returning a string, buffer, or array. It doesn't have a fragile type inference. You explicitly choose what you want. And it doesn't depend on the huge `readable-stream` package.
## Related
- [get-stdin](https://github.com/sindresorhus/get-stdin) - Get stdin as a string or buffer
---
<div align="center">
<b>
<a href="https://tidelift.com/subscription/pkg/npm-get-stream?utm_source=npm-get-stream&utm_medium=referral&utm_campaign=readme">Get professional support for this package with a Tidelift subscription</a>
</b>
<br>
<sub>
Tidelift helps make open source sustainable for maintainers while giving companies<br>assurances about security, maintenance, and licensing for their dependencies.
</sub>
</div>

View File

@@ -0,0 +1,11 @@
# 2.1.0
## TypeScript types
- Add [TypeScript definitions](src/main.d.ts)
# 2.0.0
## Breaking changes
- Minimal supported Node.js version is now `10.17.0`

View File

@@ -0,0 +1,201 @@
Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
1. Definitions.
"License" shall mean the terms and conditions for use, reproduction,
and distribution as defined by Sections 1 through 9 of this document.
"Licensor" shall mean the copyright owner or entity authorized by
the copyright owner that is granting the License.
"Legal Entity" shall mean the union of the acting entity and all
other entities that control, are controlled by, or are under common
control with that entity. For the purposes of this definition,
"control" means (i) the power, direct or indirect, to cause the
direction or management of such entity, whether by contract or
otherwise, or (ii) ownership of fifty percent (50%) or more of the
outstanding shares, or (iii) beneficial ownership of such entity.
"You" (or "Your") shall mean an individual or Legal Entity
exercising permissions granted by this License.
"Source" form shall mean the preferred form for making modifications,
including but not limited to software source code, documentation
source, and configuration files.
"Object" form shall mean any form resulting from mechanical
transformation or translation of a Source form, including but
not limited to compiled object code, generated documentation,
and conversions to other media types.
"Work" shall mean the work of authorship, whether in Source or
Object form, made available under the License, as indicated by a
copyright notice that is included in or attached to the work
(an example is provided in the Appendix below).
"Derivative Works" shall mean any work, whether in Source or Object
form, that is based on (or derived from) the Work and for which the
editorial revisions, annotations, elaborations, or other modifications
represent, as a whole, an original work of authorship. For the purposes
of this License, Derivative Works shall not include works that remain
separable from, or merely link (or bind by name) to the interfaces of,
the Work and Derivative Works thereof.
"Contribution" shall mean any work of authorship, including
the original version of the Work and any modifications or additions
to that Work or Derivative Works thereof, that is intentionally
submitted to Licensor for inclusion in the Work by the copyright owner
or by an individual or Legal Entity authorized to submit on behalf of
the copyright owner. For the purposes of this definition, "submitted"
means any form of electronic, verbal, or written communication sent
to the Licensor or its representatives, including but not limited to
communication on electronic mailing lists, source code control systems,
and issue tracking systems that are managed by, or on behalf of, the
Licensor for the purpose of discussing and improving the Work, but
excluding communication that is conspicuously marked or otherwise
designated in writing by the copyright owner as "Not a Contribution."
"Contributor" shall mean Licensor and any individual or Legal Entity
on behalf of whom a Contribution has been received by Licensor and
subsequently incorporated within the Work.
2. Grant of Copyright License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
copyright license to reproduce, prepare Derivative Works of,
publicly display, publicly perform, sublicense, and distribute the
Work and such Derivative Works in Source or Object form.
3. Grant of Patent License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
(except as stated in this section) patent license to make, have made,
use, offer to sell, sell, import, and otherwise transfer the Work,
where such license applies only to those patent claims licensable
by such Contributor that are necessarily infringed by their
Contribution(s) alone or by combination of their Contribution(s)
with the Work to which such Contribution(s) was submitted. If You
institute patent litigation against any entity (including a
cross-claim or counterclaim in a lawsuit) alleging that the Work
or a Contribution incorporated within the Work constitutes direct
or contributory patent infringement, then any patent licenses
granted to You under this License for that Work shall terminate
as of the date such litigation is filed.
4. Redistribution. You may reproduce and distribute copies of the
Work or Derivative Works thereof in any medium, with or without
modifications, and in Source or Object form, provided that You
meet the following conditions:
(a) You must give any other recipients of the Work or
Derivative Works a copy of this License; and
(b) You must cause any modified files to carry prominent notices
stating that You changed the files; and
(c) You must retain, in the Source form of any Derivative Works
that You distribute, all copyright, patent, trademark, and
attribution notices from the Source form of the Work,
excluding those notices that do not pertain to any part of
the Derivative Works; and
(d) If the Work includes a "NOTICE" text file as part of its
distribution, then any Derivative Works that You distribute must
include a readable copy of the attribution notices contained
within such NOTICE file, excluding those notices that do not
pertain to any part of the Derivative Works, in at least one
of the following places: within a NOTICE text file distributed
as part of the Derivative Works; within the Source form or
documentation, if provided along with the Derivative Works; or,
within a display generated by the Derivative Works, if and
wherever such third-party notices normally appear. The contents
of the NOTICE file are for informational purposes only and
do not modify the License. You may add Your own attribution
notices within Derivative Works that You distribute, alongside
or as an addendum to the NOTICE text from the Work, provided
that such additional attribution notices cannot be construed
as modifying the License.
You may add Your own copyright statement to Your modifications and
may provide additional or different license terms and conditions
for use, reproduction, or distribution of Your modifications, or
for any such Derivative Works as a whole, provided Your use,
reproduction, and distribution of the Work otherwise complies with
the conditions stated in this License.
5. Submission of Contributions. Unless You explicitly state otherwise,
any Contribution intentionally submitted for inclusion in the Work
by You to the Licensor shall be under the terms and conditions of
this License, without any additional terms or conditions.
Notwithstanding the above, nothing herein shall supersede or modify
the terms of any separate license agreement you may have executed
with Licensor regarding such Contributions.
6. Trademarks. This License does not grant permission to use the trade
names, trademarks, service marks, or product names of the Licensor,
except as required for reasonable and customary use in describing the
origin of the Work and reproducing the content of the NOTICE file.
7. Disclaimer of Warranty. Unless required by applicable law or
agreed to in writing, Licensor provides the Work (and each
Contributor provides its Contributions) on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
implied, including, without limitation, any warranties or conditions
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
PARTICULAR PURPOSE. You are solely responsible for determining the
appropriateness of using or redistributing the Work and assume any
risks associated with Your exercise of permissions under this License.
8. Limitation of Liability. In no event and under no legal theory,
whether in tort (including negligence), contract, or otherwise,
unless required by applicable law (such as deliberate and grossly
negligent acts) or agreed to in writing, shall any Contributor be
liable to You for damages, including any direct, indirect, special,
incidental, or consequential damages of any character arising as a
result of this License or out of the use or inability to use the
Work (including but not limited to damages for loss of goodwill,
work stoppage, computer failure or malfunction, or any and all
other commercial damages or losses), even if such Contributor
has been advised of the possibility of such damages.
9. Accepting Warranty or Additional Liability. While redistributing
the Work or Derivative Works thereof, You may choose to offer,
and charge a fee for, acceptance of support, warranty, indemnity,
or other liability obligations and/or rights consistent with this
License. However, in accepting such obligations, You may act only
on Your own behalf and on Your sole responsibility, not on behalf
of any other Contributor, and only if You agree to indemnify,
defend, and hold each Contributor harmless for any liability
incurred by, or claims asserted against, such Contributor by reason
of your accepting any such warranty or additional liability.
END OF TERMS AND CONDITIONS
APPENDIX: How to apply the Apache License to your work.
To apply the Apache License to your work, attach the following
boilerplate notice, with the fields enclosed by brackets "[]"
replaced with your own identifying information. (Don't include
the brackets!) The text should be enclosed in the appropriate
comment syntax for the file format. We also recommend that a
file or class name and description of purpose be included on the
same "printed page" as the copyright notice for easier
identification within third-party archives.
Copyright 2019 ehmicky <ehmicky@gmail.com>
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

View File

@@ -0,0 +1,165 @@
[![Codecov](https://img.shields.io/codecov/c/github/ehmicky/human-signals.svg?label=tested&logo=codecov)](https://codecov.io/gh/ehmicky/human-signals)
[![Travis](https://img.shields.io/badge/cross-platform-4cc61e.svg?logo=travis)](https://travis-ci.org/ehmicky/human-signals)
[![Node](https://img.shields.io/node/v/human-signals.svg?logo=node.js)](https://www.npmjs.com/package/human-signals)
[![Gitter](https://img.shields.io/gitter/room/ehmicky/human-signals.svg?logo=gitter)](https://gitter.im/ehmicky/human-signals)
[![Twitter](https://img.shields.io/badge/%E2%80%8B-twitter-4cc61e.svg?logo=twitter)](https://twitter.com/intent/follow?screen_name=ehmicky)
[![Medium](https://img.shields.io/badge/%E2%80%8B-medium-4cc61e.svg?logo=medium)](https://medium.com/@ehmicky)
Human-friendly process signals.
This is a map of known process signals with some information about each signal.
Unlike
[`os.constants.signals`](https://nodejs.org/api/os.html#os_signal_constants)
this includes:
- human-friendly [descriptions](#description)
- [default actions](#action), including whether they [can be prevented](#forced)
- whether the signal is [supported](#supported) by the current OS
# Example
```js
const { signalsByName, signalsByNumber } = require('human-signals')
console.log(signalsByName.SIGINT)
// {
// name: 'SIGINT',
// number: 2,
// description: 'User interruption with CTRL-C',
// supported: true,
// action: 'terminate',
// forced: false,
// standard: 'ansi'
// }
console.log(signalsByNumber[8])
// {
// name: 'SIGFPE',
// number: 8,
// description: 'Floating point arithmetic error',
// supported: true,
// action: 'core',
// forced: false,
// standard: 'ansi'
// }
```
# Install
```bash
npm install human-signals
```
# Usage
## signalsByName
_Type_: `object`
Object whose keys are signal [names](#name) and values are
[signal objects](#signal).
## signalsByNumber
_Type_: `object`
Object whose keys are signal [numbers](#number) and values are
[signal objects](#signal).
## signal
_Type_: `object`
Signal object with the following properties.
### name
_Type_: `string`
Standard name of the signal, for example `'SIGINT'`.
### number
_Type_: `number`
Code number of the signal, for example `2`. While most `number` are
cross-platform, some are different between different OS.
### description
_Type_: `string`
Human-friendly description for the signal, for example
`'User interruption with CTRL-C'`.
### supported
_Type_: `boolean`
Whether the current OS can handle this signal in Node.js using
[`process.on(name, handler)`](https://nodejs.org/api/process.html#process_signal_events).
The list of supported signals
[is OS-specific](https://github.com/ehmicky/cross-platform-node-guide/blob/master/docs/6_networking_ipc/signals.md#cross-platform-signals).
### action
_Type_: `string`\
_Enum_: `'terminate'`, `'core'`, `'ignore'`, `'pause'`, `'unpause'`
What is the default action for this signal when it is not handled.
### forced
_Type_: `boolean`
Whether the signal's default action cannot be prevented. This is `true` for
`SIGTERM`, `SIGKILL` and `SIGSTOP`.
### standard
_Type_: `string`\
_Enum_: `'ansi'`, `'posix'`, `'bsd'`, `'systemv'`, `'other'`
Which standard defined that signal.
# Support
If you found a bug or would like a new feature, _don't hesitate_ to
[submit an issue on GitHub](../../issues).
For other questions, feel free to
[chat with us on Gitter](https://gitter.im/ehmicky/human-signals).
Everyone is welcome regardless of personal background. We enforce a
[Code of conduct](CODE_OF_CONDUCT.md) in order to promote a positive and
inclusive environment.
# Contributing
This project was made with ❤️. The simplest way to give back is by starring and
sharing it online.
If the documentation is unclear or has a typo, please click on the page's `Edit`
button (pencil icon) and suggest a correction.
If you would like to help us fix a bug or add a new feature, please check our
[guidelines](CONTRIBUTING.md). Pull requests are welcome!
Thanks go to our wonderful contributors:
<!-- ALL-CONTRIBUTORS-LIST:START -->
<!-- prettier-ignore-start -->
<!-- markdownlint-disable -->
<table>
<tr>
<td align="center"><a href="https://twitter.com/ehmicky"><img src="https://avatars2.githubusercontent.com/u/8136211?v=4" width="100px;" alt=""/><br /><sub><b>ehmicky</b></sub></a><br /><a href="https://github.com/ehmicky/human-signals/commits?author=ehmicky" title="Code">💻</a> <a href="#design-ehmicky" title="Design">🎨</a> <a href="#ideas-ehmicky" title="Ideas, Planning, & Feedback">🤔</a> <a href="https://github.com/ehmicky/human-signals/commits?author=ehmicky" title="Documentation">📖</a></td>
<td align="center"><a href="http://www.electrovir.com"><img src="https://avatars0.githubusercontent.com/u/1205860?v=4" width="100px;" alt=""/><br /><sub><b>electrovir</b></sub></a><br /><a href="https://github.com/ehmicky/human-signals/commits?author=electrovir" title="Code">💻</a></td>
</tr>
</table>
<!-- markdownlint-enable -->
<!-- prettier-ignore-end -->
<!-- ALL-CONTRIBUTORS-LIST:END -->

View File

@@ -0,0 +1,273 @@
"use strict";Object.defineProperty(exports,"__esModule",{value:true});exports.SIGNALS=void 0;
const SIGNALS=[
{
name:"SIGHUP",
number:1,
action:"terminate",
description:"Terminal closed",
standard:"posix"},
{
name:"SIGINT",
number:2,
action:"terminate",
description:"User interruption with CTRL-C",
standard:"ansi"},
{
name:"SIGQUIT",
number:3,
action:"core",
description:"User interruption with CTRL-\\",
standard:"posix"},
{
name:"SIGILL",
number:4,
action:"core",
description:"Invalid machine instruction",
standard:"ansi"},
{
name:"SIGTRAP",
number:5,
action:"core",
description:"Debugger breakpoint",
standard:"posix"},
{
name:"SIGABRT",
number:6,
action:"core",
description:"Aborted",
standard:"ansi"},
{
name:"SIGIOT",
number:6,
action:"core",
description:"Aborted",
standard:"bsd"},
{
name:"SIGBUS",
number:7,
action:"core",
description:
"Bus error due to misaligned, non-existing address or paging error",
standard:"bsd"},
{
name:"SIGEMT",
number:7,
action:"terminate",
description:"Command should be emulated but is not implemented",
standard:"other"},
{
name:"SIGFPE",
number:8,
action:"core",
description:"Floating point arithmetic error",
standard:"ansi"},
{
name:"SIGKILL",
number:9,
action:"terminate",
description:"Forced termination",
standard:"posix",
forced:true},
{
name:"SIGUSR1",
number:10,
action:"terminate",
description:"Application-specific signal",
standard:"posix"},
{
name:"SIGSEGV",
number:11,
action:"core",
description:"Segmentation fault",
standard:"ansi"},
{
name:"SIGUSR2",
number:12,
action:"terminate",
description:"Application-specific signal",
standard:"posix"},
{
name:"SIGPIPE",
number:13,
action:"terminate",
description:"Broken pipe or socket",
standard:"posix"},
{
name:"SIGALRM",
number:14,
action:"terminate",
description:"Timeout or timer",
standard:"posix"},
{
name:"SIGTERM",
number:15,
action:"terminate",
description:"Termination",
standard:"ansi"},
{
name:"SIGSTKFLT",
number:16,
action:"terminate",
description:"Stack is empty or overflowed",
standard:"other"},
{
name:"SIGCHLD",
number:17,
action:"ignore",
description:"Child process terminated, paused or unpaused",
standard:"posix"},
{
name:"SIGCLD",
number:17,
action:"ignore",
description:"Child process terminated, paused or unpaused",
standard:"other"},
{
name:"SIGCONT",
number:18,
action:"unpause",
description:"Unpaused",
standard:"posix",
forced:true},
{
name:"SIGSTOP",
number:19,
action:"pause",
description:"Paused",
standard:"posix",
forced:true},
{
name:"SIGTSTP",
number:20,
action:"pause",
description:"Paused using CTRL-Z or \"suspend\"",
standard:"posix"},
{
name:"SIGTTIN",
number:21,
action:"pause",
description:"Background process cannot read terminal input",
standard:"posix"},
{
name:"SIGBREAK",
number:21,
action:"terminate",
description:"User interruption with CTRL-BREAK",
standard:"other"},
{
name:"SIGTTOU",
number:22,
action:"pause",
description:"Background process cannot write to terminal output",
standard:"posix"},
{
name:"SIGURG",
number:23,
action:"ignore",
description:"Socket received out-of-band data",
standard:"bsd"},
{
name:"SIGXCPU",
number:24,
action:"core",
description:"Process timed out",
standard:"bsd"},
{
name:"SIGXFSZ",
number:25,
action:"core",
description:"File too big",
standard:"bsd"},
{
name:"SIGVTALRM",
number:26,
action:"terminate",
description:"Timeout or timer",
standard:"bsd"},
{
name:"SIGPROF",
number:27,
action:"terminate",
description:"Timeout or timer",
standard:"bsd"},
{
name:"SIGWINCH",
number:28,
action:"ignore",
description:"Terminal window size changed",
standard:"bsd"},
{
name:"SIGIO",
number:29,
action:"terminate",
description:"I/O is available",
standard:"other"},
{
name:"SIGPOLL",
number:29,
action:"terminate",
description:"Watched event",
standard:"other"},
{
name:"SIGINFO",
number:29,
action:"ignore",
description:"Request for process information",
standard:"other"},
{
name:"SIGPWR",
number:30,
action:"terminate",
description:"Device running out of power",
standard:"systemv"},
{
name:"SIGSYS",
number:31,
action:"core",
description:"Invalid system call",
standard:"other"},
{
name:"SIGUNUSED",
number:31,
action:"terminate",
description:"Invalid system call",
standard:"other"}];exports.SIGNALS=SIGNALS;
//# sourceMappingURL=core.js.map

File diff suppressed because one or more lines are too long

View File

@@ -0,0 +1,52 @@
/**
* Object whose keys are signal names and values are signal objects.
*/
export declare const signalsByName: { [signalName: string]: Signal }
/**
* Object whose keys are signal numbers and values are signal objects.
*/
export declare const signalsByNumber: { [signalNumber: string]: Signal }
export declare type SignalAction =
| 'terminate'
| 'core'
| 'ignore'
| 'pause'
| 'unpause'
export declare type SignalStandard =
| 'ansi'
| 'posix'
| 'bsd'
| 'systemv'
| 'other'
export declare type Signal = {
/**
* Standard name of the signal, for example 'SIGINT'.
*/
name: string
/**
* Code number of the signal, for example 2. While most number are cross-platform, some are different between different OS.
*/
number: number
/**
* Human-friendly description for the signal, for example 'User interruption with CTRL-C'.
*/
description: string
/**
* Whether the current OS can handle this signal in Node.js using process.on(name, handler). The list of supported signals is OS-specific.
*/
supported: boolean
/**
* What is the default action for this signal when it is not handled.
*/
action: SignalAction
/**
* Whether the signal's default action cannot be prevented. This is true for SIGTERM, SIGKILL and SIGSTOP.
*/
forced: boolean
/**
* Which standard defined that signal.
*/
standard: SignalStandard
}

View File

@@ -0,0 +1,71 @@
"use strict";Object.defineProperty(exports,"__esModule",{value:true});exports.signalsByNumber=exports.signalsByName=void 0;var _os=require("os");
var _signals=require("./signals.js");
var _realtime=require("./realtime.js");
const getSignalsByName=function(){
const signals=(0,_signals.getSignals)();
return signals.reduce(getSignalByName,{});
};
const getSignalByName=function(
signalByNameMemo,
{name,number,description,supported,action,forced,standard})
{
return{
...signalByNameMemo,
[name]:{name,number,description,supported,action,forced,standard}};
};
const signalsByName=getSignalsByName();exports.signalsByName=signalsByName;
const getSignalsByNumber=function(){
const signals=(0,_signals.getSignals)();
const length=_realtime.SIGRTMAX+1;
const signalsA=Array.from({length},(value,number)=>
getSignalByNumber(number,signals));
return Object.assign({},...signalsA);
};
const getSignalByNumber=function(number,signals){
const signal=findSignalByNumber(number,signals);
if(signal===undefined){
return{};
}
const{name,description,supported,action,forced,standard}=signal;
return{
[number]:{
name,
number,
description,
supported,
action,
forced,
standard}};
};
const findSignalByNumber=function(number,signals){
const signal=signals.find(({name})=>_os.constants.signals[name]===number);
if(signal!==undefined){
return signal;
}
return signals.find(signalA=>signalA.number===number);
};
const signalsByNumber=getSignalsByNumber();exports.signalsByNumber=signalsByNumber;
//# sourceMappingURL=main.js.map

View File

@@ -0,0 +1 @@
{"version":3,"sources":["../../src/main.js"],"names":["getSignalsByName","signals","reduce","getSignalByName","signalByNameMemo","name","number","description","supported","action","forced","standard","signalsByName","getSignalsByNumber","length","SIGRTMAX","signalsA","Array","from","value","getSignalByNumber","Object","assign","signal","findSignalByNumber","undefined","find","constants","signalA","signalsByNumber"],"mappings":"2HAAA;;AAEA;AACA;;;;AAIA,KAAMA,CAAAA,gBAAgB,CAAG,UAAW;AAClC,KAAMC,CAAAA,OAAO,CAAG,yBAAhB;AACA,MAAOA,CAAAA,OAAO,CAACC,MAAR,CAAeC,eAAf,CAAgC,EAAhC,CAAP;AACD,CAHD;;AAKA,KAAMA,CAAAA,eAAe,CAAG;AACtBC,gBADsB;AAEtB,CAAEC,IAAF,CAAQC,MAAR,CAAgBC,WAAhB,CAA6BC,SAA7B,CAAwCC,MAAxC,CAAgDC,MAAhD,CAAwDC,QAAxD,CAFsB;AAGtB;AACA,MAAO;AACL,GAAGP,gBADE;AAEL,CAACC,IAAD,EAAQ,CAAEA,IAAF,CAAQC,MAAR,CAAgBC,WAAhB,CAA6BC,SAA7B,CAAwCC,MAAxC,CAAgDC,MAAhD,CAAwDC,QAAxD,CAFH,CAAP;;AAID,CARD;;AAUO,KAAMC,CAAAA,aAAa,CAAGZ,gBAAgB,EAAtC,C;;;;;AAKP,KAAMa,CAAAA,kBAAkB,CAAG,UAAW;AACpC,KAAMZ,CAAAA,OAAO,CAAG,yBAAhB;AACA,KAAMa,CAAAA,MAAM,CAAGC,mBAAW,CAA1B;AACA,KAAMC,CAAAA,QAAQ,CAAGC,KAAK,CAACC,IAAN,CAAW,CAAEJ,MAAF,CAAX,CAAuB,CAACK,KAAD,CAAQb,MAAR;AACtCc,iBAAiB,CAACd,MAAD,CAASL,OAAT,CADF,CAAjB;;AAGA,MAAOoB,CAAAA,MAAM,CAACC,MAAP,CAAc,EAAd,CAAkB,GAAGN,QAArB,CAAP;AACD,CAPD;;AASA,KAAMI,CAAAA,iBAAiB,CAAG,SAASd,MAAT,CAAiBL,OAAjB,CAA0B;AAClD,KAAMsB,CAAAA,MAAM,CAAGC,kBAAkB,CAAClB,MAAD,CAASL,OAAT,CAAjC;;AAEA,GAAIsB,MAAM,GAAKE,SAAf,CAA0B;AACxB,MAAO,EAAP;AACD;;AAED,KAAM,CAAEpB,IAAF,CAAQE,WAAR,CAAqBC,SAArB,CAAgCC,MAAhC,CAAwCC,MAAxC,CAAgDC,QAAhD,EAA6DY,MAAnE;AACA,MAAO;AACL,CAACjB,MAAD,EAAU;AACRD,IADQ;AAERC,MAFQ;AAGRC,WAHQ;AAIRC,SAJQ;AAKRC,MALQ;AAMRC,MANQ;AAORC,QAPQ,CADL,CAAP;;;AAWD,CAnBD;;;;AAuBA,KAAMa,CAAAA,kBAAkB,CAAG,SAASlB,MAAT,CAAiBL,OAAjB,CAA0B;AACnD,KAAMsB,CAAAA,MAAM,CAAGtB,OAAO,CAACyB,IAAR,CAAa,CAAC,CAAErB,IAAF,CAAD,GAAcsB,cAAU1B,OAAV,CAAkBI,IAAlB,IAA4BC,MAAvD,CAAf;;AAEA,GAAIiB,MAAM,GAAKE,SAAf,CAA0B;AACxB,MAAOF,CAAAA,MAAP;AACD;;AAED,MAAOtB,CAAAA,OAAO,CAACyB,IAAR,CAAaE,OAAO,EAAIA,OAAO,CAACtB,MAAR,GAAmBA,MAA3C,CAAP;AACD,CARD;;AAUO,KAAMuB,CAAAA,eAAe,CAAGhB,kBAAkB,EAA1C,C","sourcesContent":["import { constants } from 'os'\n\nimport { getSignals } from './signals.js'\nimport { SIGRTMAX } from './realtime.js'\n\n// Retrieve `signalsByName`, an object mapping signal name to signal properties.\n// We make sure the object is sorted by `number`.\nconst getSignalsByName = function() {\n const signals = getSignals()\n return signals.reduce(getSignalByName, {})\n}\n\nconst getSignalByName = function(\n signalByNameMemo,\n { name, number, description, supported, action, forced, standard },\n) {\n return {\n ...signalByNameMemo,\n [name]: { name, number, description, supported, action, forced, standard },\n }\n}\n\nexport const signalsByName = getSignalsByName()\n\n// Retrieve `signalsByNumber`, an object mapping signal number to signal\n// properties.\n// We make sure the object is sorted by `number`.\nconst getSignalsByNumber = function() {\n const signals = getSignals()\n const length = SIGRTMAX + 1\n const signalsA = Array.from({ length }, (value, number) =>\n getSignalByNumber(number, signals),\n )\n return Object.assign({}, ...signalsA)\n}\n\nconst getSignalByNumber = function(number, signals) {\n const signal = findSignalByNumber(number, signals)\n\n if (signal === undefined) {\n return {}\n }\n\n const { name, description, supported, action, forced, standard } = signal\n return {\n [number]: {\n name,\n number,\n description,\n supported,\n action,\n forced,\n standard,\n },\n }\n}\n\n// Several signals might end up sharing the same number because of OS-specific\n// numbers, in which case those prevail.\nconst findSignalByNumber = function(number, signals) {\n const signal = signals.find(({ name }) => constants.signals[name] === number)\n\n if (signal !== undefined) {\n return signal\n }\n\n return signals.find(signalA => signalA.number === number)\n}\n\nexport const signalsByNumber = getSignalsByNumber()\n"],"file":"src/main.js"}

View File

@@ -0,0 +1,19 @@
"use strict";Object.defineProperty(exports,"__esModule",{value:true});exports.SIGRTMAX=exports.getRealtimeSignals=void 0;
const getRealtimeSignals=function(){
const length=SIGRTMAX-SIGRTMIN+1;
return Array.from({length},getRealtimeSignal);
};exports.getRealtimeSignals=getRealtimeSignals;
const getRealtimeSignal=function(value,index){
return{
name:`SIGRT${index+1}`,
number:SIGRTMIN+index,
action:"terminate",
description:"Application-specific signal (realtime)",
standard:"posix"};
};
const SIGRTMIN=34;
const SIGRTMAX=64;exports.SIGRTMAX=SIGRTMAX;
//# sourceMappingURL=realtime.js.map

View File

@@ -0,0 +1 @@
{"version":3,"sources":["../../src/realtime.js"],"names":["getRealtimeSignals","length","SIGRTMAX","SIGRTMIN","Array","from","getRealtimeSignal","value","index","name","number","action","description","standard"],"mappings":";AACO,KAAMA,CAAAA,kBAAkB,CAAG,UAAW;AAC3C,KAAMC,CAAAA,MAAM,CAAGC,QAAQ,CAAGC,QAAX,CAAsB,CAArC;AACA,MAAOC,CAAAA,KAAK,CAACC,IAAN,CAAW,CAAEJ,MAAF,CAAX,CAAuBK,iBAAvB,CAAP;AACD,CAHM,C;;AAKP,KAAMA,CAAAA,iBAAiB,CAAG,SAASC,KAAT,CAAgBC,KAAhB,CAAuB;AAC/C,MAAO;AACLC,IAAI,CAAG,QAAOD,KAAK,CAAG,CAAE,EADnB;AAELE,MAAM,CAAEP,QAAQ,CAAGK,KAFd;AAGLG,MAAM,CAAE,WAHH;AAILC,WAAW,CAAE,wCAJR;AAKLC,QAAQ,CAAE,OALL,CAAP;;AAOD,CARD;;AAUA,KAAMV,CAAAA,QAAQ,CAAG,EAAjB;AACO,KAAMD,CAAAA,QAAQ,CAAG,EAAjB,C","sourcesContent":["// List of realtime signals with information about them\nexport const getRealtimeSignals = function() {\n const length = SIGRTMAX - SIGRTMIN + 1\n return Array.from({ length }, getRealtimeSignal)\n}\n\nconst getRealtimeSignal = function(value, index) {\n return {\n name: `SIGRT${index + 1}`,\n number: SIGRTMIN + index,\n action: 'terminate',\n description: 'Application-specific signal (realtime)',\n standard: 'posix',\n }\n}\n\nconst SIGRTMIN = 34\nexport const SIGRTMAX = 64\n"],"file":"src/realtime.js"}

View File

@@ -0,0 +1,35 @@
"use strict";Object.defineProperty(exports,"__esModule",{value:true});exports.getSignals=void 0;var _os=require("os");
var _core=require("./core.js");
var _realtime=require("./realtime.js");
const getSignals=function(){
const realtimeSignals=(0,_realtime.getRealtimeSignals)();
const signals=[..._core.SIGNALS,...realtimeSignals].map(normalizeSignal);
return signals;
};exports.getSignals=getSignals;
const normalizeSignal=function({
name,
number:defaultNumber,
description,
action,
forced=false,
standard})
{
const{
signals:{[name]:constantSignal}}=
_os.constants;
const supported=constantSignal!==undefined;
const number=supported?constantSignal:defaultNumber;
return{name,number,description,supported,action,forced,standard};
};
//# sourceMappingURL=signals.js.map

View File

@@ -0,0 +1 @@
{"version":3,"sources":["../../src/signals.js"],"names":["getSignals","realtimeSignals","signals","SIGNALS","map","normalizeSignal","name","number","defaultNumber","description","action","forced","standard","constantSignal","constants","supported","undefined"],"mappings":"gGAAA;;AAEA;AACA;;;;AAIO,KAAMA,CAAAA,UAAU,CAAG,UAAW;AACnC,KAAMC,CAAAA,eAAe,CAAG,kCAAxB;AACA,KAAMC,CAAAA,OAAO,CAAG,CAAC,GAAGC,aAAJ,CAAa,GAAGF,eAAhB,EAAiCG,GAAjC,CAAqCC,eAArC,CAAhB;AACA,MAAOH,CAAAA,OAAP;AACD,CAJM,C;;;;;;;;AAYP,KAAMG,CAAAA,eAAe,CAAG,SAAS;AAC/BC,IAD+B;AAE/BC,MAAM,CAAEC,aAFuB;AAG/BC,WAH+B;AAI/BC,MAJ+B;AAK/BC,MAAM,CAAG,KALsB;AAM/BC,QAN+B,CAAT;AAOrB;AACD,KAAM;AACJV,OAAO,CAAE,CAAE,CAACI,IAAD,EAAQO,cAAV,CADL;AAEFC,aAFJ;AAGA,KAAMC,CAAAA,SAAS,CAAGF,cAAc,GAAKG,SAArC;AACA,KAAMT,CAAAA,MAAM,CAAGQ,SAAS,CAAGF,cAAH,CAAoBL,aAA5C;AACA,MAAO,CAAEF,IAAF,CAAQC,MAAR,CAAgBE,WAAhB,CAA6BM,SAA7B,CAAwCL,MAAxC,CAAgDC,MAAhD,CAAwDC,QAAxD,CAAP;AACD,CAdD","sourcesContent":["import { constants } from 'os'\n\nimport { SIGNALS } from './core.js'\nimport { getRealtimeSignals } from './realtime.js'\n\n// Retrieve list of know signals (including realtime) with information about\n// them\nexport const getSignals = function() {\n const realtimeSignals = getRealtimeSignals()\n const signals = [...SIGNALS, ...realtimeSignals].map(normalizeSignal)\n return signals\n}\n\n// Normalize signal:\n// - `number`: signal numbers are OS-specific. This is taken into account by\n// `os.constants.signals`. However we provide a default `number` since some\n// signals are not defined for some OS.\n// - `forced`: set default to `false`\n// - `supported`: set value\nconst normalizeSignal = function({\n name,\n number: defaultNumber,\n description,\n action,\n forced = false,\n standard,\n}) {\n const {\n signals: { [name]: constantSignal },\n } = constants\n const supported = constantSignal !== undefined\n const number = supported ? constantSignal : defaultNumber\n return { name, number, description, supported, action, forced, standard }\n}\n"],"file":"src/signals.js"}

View File

@@ -0,0 +1,64 @@
{
"name": "human-signals",
"version": "2.1.0",
"main": "build/src/main.js",
"files": [
"build/src",
"!~"
],
"scripts": {
"test": "gulp test"
},
"husky": {
"hooks": {
"pre-push": "gulp check --full"
}
},
"description": "Human-friendly process signals",
"keywords": [
"signal",
"signals",
"handlers",
"error-handling",
"errors",
"interrupts",
"sigterm",
"sigint",
"irq",
"process",
"exit",
"exit-code",
"status",
"operating-system",
"es6",
"javascript",
"linux",
"macos",
"windows",
"nodejs"
],
"license": "Apache-2.0",
"homepage": "https://git.io/JeluP",
"repository": "ehmicky/human-signals",
"bugs": {
"url": "https://github.com/ehmicky/human-signals/issues"
},
"author": "ehmicky <ehmicky@gmail.com> (https://github.com/ehmicky)",
"directories": {
"lib": "src",
"test": "test"
},
"types": "build/src/main.d.ts",
"dependencies": {},
"devDependencies": {
"@ehmicky/dev-tasks": "^0.31.9",
"ajv": "^6.12.0",
"ava": "^3.5.0",
"gulp": "^4.0.2",
"husky": "^4.2.3",
"test-each": "^2.0.0"
},
"engines": {
"node": ">=10.17.0"
}
}

159
node_modules/start-server-and-test/package.json generated vendored Normal file
View File

@@ -0,0 +1,159 @@
{
"name": "start-server-and-test",
"description": "Starts server, waits for URL, then runs test command; when the tests end, shuts down server",
"version": "2.0.8",
"author": "Gleb Bahmutov <gleb.bahmutov@gmail.com>",
"bugs": "https://github.com/bahmutov/start-server-and-test/issues",
"bin": {
"start-server-and-test": "src/bin/start.js",
"server-test": "src/bin/start.js",
"start-test": "src/bin/start.js"
},
"config": {
"pre-git": {
"commit-msg": "simple",
"pre-commit": [
"npm run deps",
"npm test",
"npm run ban"
],
"pre-push": [
"npm run unused-deps",
"npm run license",
"npm run ban -- --all",
"npm run size"
],
"post-commit": [],
"post-merge": []
}
},
"engines": {
"node": ">=16"
},
"files": [
"src/**/*.js",
"!src/**/*-spec.js"
],
"homepage": "https://github.com/bahmutov/start-server-and-test#readme",
"keywords": [
"ci",
"parallel",
"server",
"start",
"test",
"utility",
"wait"
],
"license": "MIT",
"main": "src/",
"private": false,
"publishConfig": {
"registry": "https://registry.npmjs.org/"
},
"repository": {
"type": "git",
"url": "https://github.com/bahmutov/start-server-and-test.git"
},
"scripts": {
"ban": "ban",
"deps": "deps-ok && dependency-check --no-dev .",
"issues": "git-issues",
"license": "license-checker --production --onlyunknown --csv",
"lint": "standard --verbose --fix 'src/**/*.js'",
"prelint": "npm run pretty",
"pretest": "npm run lint",
"pretty": "prettier-standard 'src/**/*.js'",
"size": "t=\"$(npm pack .)\"; wc -c \"${t}\"; tar tvf \"${t}\"; rm \"${t}\";",
"test": "npm run unit",
"unit": "mocha test/helper src/*-spec.js",
"unused-deps": "dependency-check --unused --no-dev .",
"semantic-release": "semantic-release",
"start": "node test/server.js",
"start-with-child": "node test/server-as-child.js",
"start-multiple": "node test/multiple-servers.js",
"start-https": "node test/https-server.js",
"start-fail": "node test/server-fail.js",
"start-304": "node test/server-304.js",
"start-403": "node test/server-403.js",
"start-cross-env": "cross-env FOO=bar node test/server.js",
"test2": "curl http://127.0.0.1:9000",
"test3": "curl http://127.0.0.1:9000 && curl http://127.0.0.1:9001",
"test4": "curl --insecure https://127.0.0.1:9000",
"message": "echo Hi there 👋",
"message2": "echo Hi there 2 👋",
"demo": "node src/bin/start.js http://127.0.0.1:9000 message",
"demo2": "node src/bin/start.js start http://127.0.0.1:9000 test2",
"demo3": "node src/bin/start.js start-with-child http://127.0.0.1:9000 test",
"demo4": "node src/bin/start.js 9000",
"demo5": "node src/bin/start.js start-with-child 9000",
"demo6": "node src/bin/start.js :9000",
"demo7": "node src/bin/start.js :9000 test2",
"demo8": "node src/bin/start.js start-multiple \":9000|:9001\" test3",
"demo9": "node src/bin/start.js start-https \"https://127.0.0.1:9000\" test4",
"demo10": "node src/bin/start.js start-fail http://127.0.0.1:9000 test",
"demo11": "node src/bin/start.js http-get://127.0.0.1:9000",
"demo12": "node src/bin/start.js start-304 9000 test2",
"demo-expect-403": "node src/bin/start.js --expect 403 start-403 9000 'echo Waited'",
"demo-interval": "WAIT_ON_INTERVAL=1000 node src/bin/start.js start http://127.0.0.1:9000 test2",
"demo-timeout": "WAIT_ON_TIMEOUT=10000 node src/bin/start.js start http://127.0.0.1:9000 test2",
"demo-cross-env": "node src/bin/start.js start-cross-env 9000",
"demo-commands": "node src/bin/start.js 'node test/server.js --port 8800' 8800 'node test/client --port 8800'",
"demo-multiple": "node src/bin/start.js 'node test/server --port 6000' 6000 'node test/server --port 6010' 6010 'curl http://127.0.0.1:6000 && curl http://127.0.0.1:6010'",
"demo-multiple-test-commands": "node src/bin/start.js 9000 'npm run message && npm run message2'",
"demo-json-server": "WAIT_ON_TIMEOUT=10000 DEBUG=start-server-and-test node src/bin/start.js 'json-server test/data.json' localhost:3000 'echo json-server working'",
"demo-ip6": "WAIT_ON_TIMEOUT=10000 DEBUG=start-server-and-test node src/bin/start.js 'node test/ip6.mjs' localhost:8000 'echo server with ::1 working'",
"demo-zero": "WAIT_ON_TIMEOUT=10000 node src/bin/start.js 'node test/zero.mjs' 8000 'echo server with 0.0.0.0 working'",
"demo-zero-127": "WAIT_ON_TIMEOUT=10000 node src/bin/start.js 'node test/zero.mjs' http://127.0.0.1:8000 'echo server with 0.0.0.0 working'",
"demo-zero-explicit": "node src/bin/start.js 'node test/zero.mjs' http://0.0.0.0:8000 'echo server with 0.0.0.0 working'"
},
"devDependencies": {
"@types/node": "^18.14.1",
"ban-sensitive-files": "1.9.7",
"chai": "4.2.0",
"cross-env": "7.0.2",
"dependency-check": "3.4.1",
"deps-ok": "1.4.1",
"dont-crack": "1.2.1",
"git-issues": "1.3.1",
"got": "9.6.0",
"json-server": "^0.17.1",
"license-checker": "24.1.0",
"minimist": "1.2.5",
"mocha": "7.1.1",
"pre-git": "3.17.1",
"prettier-standard": "8.0.1",
"semantic-release": "^17.1.1",
"simple-commit-message": "4.0.13",
"sinon": "9.0.2",
"sinon-chai": "3.5.0",
"snap-shot-it": "6.3.5",
"standard": "13.1.0"
},
"dependencies": {
"arg": "^5.0.2",
"bluebird": "3.7.2",
"check-more-types": "2.24.0",
"debug": "4.3.7",
"execa": "5.1.1",
"lazy-ass": "1.6.0",
"ps-tree": "1.2.0",
"wait-on": "8.0.1"
},
"release": {
"analyzeCommits": {
"preset": "angular",
"releaseRules": [
{
"type": "break",
"release": "major"
}
]
}
},
"standard": {
"globals": [
"sandbox",
"expect"
]
}
}

30
node_modules/start-server-and-test/src/bin/start.js generated vendored Executable file
View File

@@ -0,0 +1,30 @@
#!/usr/bin/env node
const debug = require('debug')('start-server-and-test')
const startAndTest = require('..').startAndTest
const utils = require('../utils')
const namedArguments = utils.getNamedArguments(process.argv.slice(2))
debug('named arguments: %o', namedArguments)
const args = utils.crossArguments(process.argv.slice(2))
debug('parsing CLI arguments: %o', args)
const parsed = utils.getArguments(args)
debug('parsed args: %o', parsed)
const { services, test } = parsed
if (!Array.isArray(services)) {
throw new Error(`Could not parse arguments %o, got %o`, args, parsed)
}
if (!namedArguments.expect) {
namedArguments.expect = 200
}
utils.printArguments({ services, test, namedArguments })
startAndTest({ services, test, namedArguments }).catch(e => {
console.error(e)
process.exit(1)
})

166
node_modules/start-server-and-test/src/index.js generated vendored Normal file
View File

@@ -0,0 +1,166 @@
// @ts-check
'use strict'
const la = require('lazy-ass')
const is = require('check-more-types')
const execa = require('execa')
const waitOn = require('wait-on')
const Promise = require('bluebird')
const psTree = require('ps-tree')
const debug = require('debug')('start-server-and-test')
/**
* Used for timeout (ms)
*/
const fiveMinutes = 5 * 60 * 1000
const twoSeconds = 2000
const waitOnTimeout = process.env.WAIT_ON_TIMEOUT
? Number(process.env.WAIT_ON_TIMEOUT)
: fiveMinutes
const waitOnInterval = process.env.WAIT_ON_INTERVAL
? Number(process.env.WAIT_ON_INTERVAL)
: twoSeconds
const isDebug = () =>
process.env.DEBUG && process.env.DEBUG.indexOf('start-server-and-test') !== -1
const isInsecure = () => process.env.START_SERVER_AND_TEST_INSECURE
function waitAndRun ({ start, url, runFn, namedArguments }) {
la(is.unemptyString(start), 'missing start script name', start)
la(is.fn(runFn), 'missing test script name', runFn)
la(
is.unemptyString(url) || is.unemptyArray(url),
'missing url to wait on',
url
)
const isSuccessfulHttpCode = status =>
(status >= 200 && status < 300) || status === 304
const validateStatus = namedArguments.expect
? status => status === namedArguments.expect
: isSuccessfulHttpCode
debug('starting server with command "%s", verbose mode?', start, isDebug())
const server = execa(start, {
shell: true,
stdio: ['ignore', 'inherit', 'inherit']
})
let serverStopped
function stopServer () {
debug('getting child processes')
if (!serverStopped) {
serverStopped = true
return Promise.fromNode(cb => psTree(server.pid, cb))
.then(children => {
debug('stopping child processes')
children.forEach(child => {
try {
process.kill(child.PID, 'SIGINT')
} catch (e) {
if (e.code === 'ESRCH') {
console.log(
`Child process ${child.PID} exited before trying to stop it`
)
} else {
throw e
}
}
})
})
.then(() => {
debug('stopping server')
server.kill()
})
}
}
const waited = new Promise((resolve, reject) => {
const onClose = () => {
reject(new Error('server closed unexpectedly'))
}
server.on('close', onClose)
debug('starting waitOn %s', url)
const options = {
resources: Array.isArray(url) ? url : [url],
interval: waitOnInterval,
window: 1000,
timeout: waitOnTimeout,
verbose: isDebug(),
strictSSL: !isInsecure(),
log: isDebug(),
headers: {
Accept: 'text/html, application/json, text/plain, */*'
},
validateStatus
}
debug('wait-on options %o', options)
waitOn(options, err => {
if (err) {
debug('error waiting for url', url)
debug(err.message)
return reject(err)
}
debug('waitOn finished successfully')
server.removeListener('close', onClose)
resolve()
})
})
return waited
.tapCatch(stopServer)
.then(runFn)
.finally(stopServer)
}
const runTheTests = testCommand => () => {
debug('running test script command: %s', testCommand)
return execa(testCommand, { shell: true, stdio: 'inherit' })
}
/**
* Starts a single service and runs tests or recursively
* runs a service, then goes to the next list, until it reaches 1 service and runs test.
*/
function startAndTest ({ services, test, namedArguments }) {
if (services.length === 0) {
throw new Error('Got zero services to start ...')
}
la(
is.number(namedArguments.expect),
'expected status should be a number',
namedArguments.expect
)
if (services.length === 1) {
const runTests = runTheTests(test)
debug('single service "%s" to run and test', services[0].start)
return waitAndRun({
start: services[0].start,
url: services[0].url,
namedArguments,
runFn: runTests
})
}
return waitAndRun({
start: services[0].start,
url: services[0].url,
namedArguments,
runFn: () => {
debug('previous service started, now going to the next one')
return startAndTest({ services: services.slice(1), test, namedArguments })
}
})
}
module.exports = {
startAndTest
}

277
node_modules/start-server-and-test/src/utils.js generated vendored Normal file
View File

@@ -0,0 +1,277 @@
const la = require('lazy-ass')
const is = require('check-more-types')
const { join } = require('path')
const { existsSync } = require('fs')
const arg = require('arg')
const debug = require('debug')('start-server-and-test')
const namedArguments = {
'--expect': Number
}
/**
* Returns new array of command line arguments
* where leading and trailing " and ' are indicating
* the beginning and end of an argument.
*/
const crossArguments = cliArguments => {
const args = arg(namedArguments, {
permissive: true,
argv: cliArguments
})
debug('initial parsed arguments %o', args)
// all other arguments
const cliArgs = args._
let concatModeChar = false
const indicationChars = ["'", '"', '`']
const combinedArgs = []
for (let i = 0; i < cliArgs.length; i++) {
let arg = cliArgs[i]
if (
!concatModeChar &&
indicationChars.some(char => cliArgs[i].startsWith(char))
) {
arg = arg.slice(1)
}
if (concatModeChar && cliArgs[i].endsWith(concatModeChar)) {
arg = arg.slice(0, -1)
}
if (concatModeChar && combinedArgs.length) {
combinedArgs[combinedArgs.length - 1] += ' ' + arg
} else {
combinedArgs.push(arg)
}
if (
!concatModeChar &&
indicationChars.some(char => cliArgs[i].startsWith(char))
) {
concatModeChar = cliArgs[i][0]
}
if (concatModeChar && cliArgs[i].endsWith(concatModeChar)) {
concatModeChar = false
}
}
return combinedArgs
}
const getNamedArguments = cliArgs => {
const args = arg(namedArguments, {
permissive: true,
argv: cliArgs
})
debug('initial parsed arguments %o', args)
return {
expect: args['--expect'],
// aliases
'--expected': '--expect'
}
}
/**
* Returns parsed command line arguments.
* If start command is NPM script name defined in the package.json
* file in the current working directory, returns 'npm run start' command.
*/
const getArguments = cliArgs => {
la(is.strings(cliArgs), 'expected list of strings', cliArgs)
const service = {
start: 'start',
url: undefined
}
const services = [service]
let test = 'test'
if (cliArgs.length === 1 && isUrlOrPort(cliArgs[0])) {
// passed just single url or port number, for example
// "start": "http://localhost:8080"
service.url = normalizeUrl(cliArgs[0])
} else if (cliArgs.length === 2) {
if (isUrlOrPort(cliArgs[0])) {
// passed port and custom test command
// like ":8080 test-ci"
service.url = normalizeUrl(cliArgs[0])
test = cliArgs[1]
}
if (isUrlOrPort(cliArgs[1])) {
// passed start command and url/port
// like "start-server 8080"
service.start = cliArgs[0]
service.url = normalizeUrl(cliArgs[1])
}
} else if (cliArgs.length === 5) {
service.start = cliArgs[0]
service.url = normalizeUrl(cliArgs[1])
const secondService = {
start: cliArgs[2],
url: normalizeUrl(cliArgs[3])
}
services.push(secondService)
test = cliArgs[4]
} else {
la(
cliArgs.length === 3,
'expected <NPM script name that starts server> <url or port> <NPM script name that runs tests>\n',
'example: start-test start 8080 test\n',
'see https://github.com/bahmutov/start-server-and-test#use\n'
)
service.start = cliArgs[0]
service.url = normalizeUrl(cliArgs[1])
test = cliArgs[2]
}
services.forEach(service => {
service.start = normalizeCommand(service.start)
})
test = normalizeCommand(test)
return {
services,
test
}
}
function normalizeCommand (command) {
return UTILS.isPackageScriptName(command) ? `npm run ${command}` : command
}
/**
* Returns true if the given string is a name of a script in the package.json file
* in the current working directory
*/
const isPackageScriptName = command => {
la(is.unemptyString(command), 'expected command name string', command)
const packageFilename = join(process.cwd(), 'package.json')
if (!existsSync(packageFilename)) {
return false
}
const packageJson = require(packageFilename)
if (!packageJson.scripts) {
return false
}
return Boolean(packageJson.scripts[command])
}
const isWaitOnUrl = s => /^https?-(?:get|head|options)/.test(s)
const isUrlOrPort = input => {
const str = is.string(input) ? input.split('|') : [input]
return str.every(s => {
if (is.url(s)) {
return s
}
// wait-on allows specifying HTTP verb to use instead of default HEAD
// and the format then is like "http-get://domain.com" to use GET
if (isWaitOnUrl(s)) {
return s
}
if (is.number(s)) {
return is.port(s)
}
if (!is.string(s)) {
return false
}
if (s[0] === ':') {
const withoutColon = s.substr(1)
return is.port(parseInt(withoutColon))
}
return is.port(parseInt(s))
})
}
/**
* Returns the host to ping if the user specified just the port.
* For a long time, the safest bet was "localhost", but now modern
* web servers seem to bind to "0.0.0.0", which means
* the "127.0.0.1" works better
*/
const getHost = () => '127.0.0.1'
const normalizeUrl = input => {
const str = is.string(input) ? input.split('|') : [input]
const defaultHost = getHost()
return str.map(s => {
if (is.url(s)) {
return s
}
if (is.number(s) && is.port(s)) {
return `http://${defaultHost}:${s}`
}
if (!is.string(s)) {
return s
}
if (
s.startsWith('localhost') ||
s.startsWith('127.0.0.1') ||
s.startsWith('0.0.0.0')
) {
return `http://${s}`
}
if (is.port(parseInt(s))) {
return `http://${defaultHost}:${s}`
}
if (s[0] === ':') {
return `http://${defaultHost}${s}`
}
// for anything else, return original argument
return s
})
}
function printArguments ({ services, test, namedArguments }) {
la(
is.number(namedArguments.expect),
'expected status code should be a number',
namedArguments.expect
)
services.forEach((service, k) => {
console.log('%d: starting server using command "%s"', k + 1, service.start)
console.log(
'and when url "%s" is responding with HTTP status code %d',
service.url,
namedArguments.expect
)
})
if (process.env.WAIT_ON_INTERVAL !== undefined) {
console.log('WAIT_ON_INTERVAL is set to', process.env.WAIT_ON_INTERVAL)
}
if (process.env.WAIT_ON_TIMEOUT !== undefined) {
console.log('WAIT_ON_TIMEOUT is set to', process.env.WAIT_ON_TIMEOUT)
}
console.log('running tests using command "%s"', test)
console.log('')
}
// placing functions into a common object
// makes them methods for easy stubbing
const UTILS = {
crossArguments,
getArguments,
getNamedArguments,
isPackageScriptName,
isUrlOrPort,
normalizeUrl,
printArguments
}
module.exports = UTILS