spawncommand - npm Package Compare versions

Comparing version 2.0.1 to 2.1.0

build/index.js

@@ -1,41 +0,27 @@
-"use strict";
+const { spawn, fork: forkCp } = require('child_process');
+const { collect } = require('catchment');
 
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.default = spawn;
-exports.fork = fork;
-
-var _catchment = _interopRequireDefault(require("catchment"));
-
-var _child_process = require("child_process");
-
-function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
-
-// eslint-disable-line
-const pipe = (stream, catchment) => {
-  if (!stream) return catchment.end();
-  stream.pipe(catchment);
-};
-
-const getPromise = async (proc, {
-  promise: stdoutPromise
-}, {
-  promise: stderrPromise
-}) => {
-  const code = await new Promise((resolve, reject) => {
-    proc.on('error', reject);
-    proc.on('exit', code => {
-      resolve(code);
-    });
-  });
-  const [stdout, stderr] = await Promise.all([stdoutPromise, stderrPromise]);
+/**
+ * @returns {PromiseResult}
+ */
+const getPromise = async (proc) => {
+  const [code, stdout, stderr] = await Promise.all([
+    new Promise((resolve, reject) => {
+      proc.on('error', reject)
+        .on('exit', (code) => {
+          resolve(code)
+        })
+    }),
+    proc.stdout ? collect(proc.stdout) : undefined,
+    proc.stderr ? collect(proc.stderr) : undefined,
+  ])
   return {
     code,
     stdout,
-    stderr
-  };
-};
+    stderr,
+  }
+}
+
 /**
- * Spawns a new process using the `command` and returns an instance of a ChildProcess, extended to have a `promise` property which is resolved when the process exits. The resolved value is an object with stdout, stderr and code properties.
+ * Spawns a new process using the `command` and returns an instance of a ChildProcess, extended to have a `promise` property which is resolved when the process exits. The resolved value is an object with `stdout`, `stderr` and `code` properties.
  * @param {string} command The command to run.
@@ -45,35 +31,49 @@ * @param {string[]} [args] List of string arguments.
  */
+               function spawnCommand(command, args = [], options = {}) {
+  if (!command) throw new Error('Please specify a command to spawn.')
+  const proc = spawn(command, args, options)
 
+  const promise = getPromise(proc)
+  proc.promise = promise
+  proc.spawnCommand = proc.spawnargs.join(' ')
+  return proc
+}
 
-function spawn(command, args = [], options = {}) {
-  if (!command) throw new Error('Please specify a command to spawn');
-  const proc = (0, _child_process.spawn)(command, args, options);
-  const stdout = new _catchment.default();
-  const stderr = new _catchment.default();
-  pipe(proc.stdout, stdout);
-  pipe(proc.stderr, stderr);
-  const promise = getPromise(proc, stdout, stderr);
-  proc.promise = promise;
-  proc.spawnCommand = proc.spawnargs.join(' ');
-  return proc;
-}
 /**
- * Fork a process and assign a `promise` property to it, resolved on exit.
+ * Forks a process and assign a `promise` property to it, resolved with `stderr`, `stdout` and `code` properties on exit.
  * @param {string} mod The module to run in the child.
  * @param {string[]} [args] List of string arguments.
- * @param {ForkOptions} [options] Options used to fork.
+ * @param {ForkOptions} [options] Options to fork the process with.
  */
+       function fork(mod, args = [], options) {
+  if (!mod) throw new Error('Please specify a module to fork')
+  const proc = forkCp(mod, args, options)
 
+  const promise = getPromise(proc)
+  proc.promise = promise
+  proc.spawnCommand = proc.spawnargs.join(' ')
+  return proc
+}
 
-function fork(mod, args = [], options) {
-  if (!mod) throw new Error('Please specify a module to fork');
-  const proc = (0, _child_process.fork)(mod, args, options);
-  const stdout = new _catchment.default();
-  const stderr = new _catchment.default();
-  pipe(proc.stdout, stdout);
-  pipe(proc.stderr, stderr);
-  const promise = getPromise(proc, stdout, stderr);
-  proc.promise = promise;
-  proc.spawnCommand = proc.spawnargs.join(' ');
-  return proc;
-}
+/* documentary types/index.xml */
+/**
+ * @typedef {import('child_process').SpawnOptions} SpawnOptions
+ * @typedef {import('child_process').ForkOptions} ForkOptions
+ * @typedef {import('child_process').ChildProcess} ChildProcess
+ *
+ * @typedef {Object} PromiseResult
+ * @prop {string} stdout The accumulated result of the `stdout` stream.
+ * @prop {string} stderr The accumulated result of the `stderr` stream.
+ * @prop {number} code The code with which the process exited.
+ */
+
+/* documentary types/cp.xml */
+/**
+ * @typedef {ChildProcess} ChildProcessWithPromise A child process with an extra `promise` property.
+ * @prop {Promise.<PromiseResult>} promise A promise resolved when the process exits.
+ */
+
+
+module.exports = spawnCommand
+module.exports.fork = fork
+//# sourceMappingURL=index.js.map

CHANGELOG.md

@@ -1,7 +0,8 @@
-## 17 May 2018
+## 20 September 2018
 
-### 2.0.1
+### 2.1.0
 
-- [dependencies] move `babel-plugin-transform-rename-import` to dev dependencies.
-- [code] rename default export.
+- [feature] Correct JSDoc for the `ForkOptions` and `SpawnOptions`.
+- [doc] Compile with documentary.
+- [build] Build with [`alamode`](https://alamode.cc)
 
@@ -8,0 +9,0 @@ ## 15 May 2018

package.json

 {
   "name": "spawncommand",
-  "version": "2.0.1",
-  "description": "Spawn a child process with a promise property resolved on exit with stdout, stderr and code",
+  "version": "2.1.0",
+  "description": "Spawn or fork a child process with a promise property resolved on exit with stdout, stderr and code.",
   "main": "build",
@@ -10,7 +10,9 @@ "files": [
   "scripts": {
-    "t": "zoroaster --babel",
-    "build": "babel src --out-dir build",
-    "test": "zoroaster test/spec --babel",
-    "test-build": "BABEL_ENV=test-build zoroaster test/spec --babel",
-    "test-all": "yarn-s test test-build",
+    "t": "zoroaster -a",
+    "test": "yarn t test/spec",
+    "b": "alamode src -o build",
+    "build": "yarn-s d b doc",
+    "d": "doc src/index.js -g",
+    "doc": "NODE_DEBUG=doc doc documentary -o README.md",
+    "test-build": "ALAMODE_ENV=test-build yarn test",
     "example/spawncommand.js": "node example example/spawncommand",
@@ -26,7 +28,10 @@ "example/fork.js": "node example example/fork",
     "spawn",
+    "fork",
+    "async",
     "child_process",
+    "child process",
+    "ChildProcess",
     "promise",
     "stdout",
     "stderr",
-    "ChildProcess",
     "stdio"
@@ -41,14 +46,10 @@ ],
   "devDependencies": {
-    "@babel/cli": "7.0.0-beta.47",
-    "@babel/core": "7.0.0-beta.47",
-    "@babel/plugin-syntax-object-rest-spread": "7.0.0-beta.47",
-    "@babel/plugin-transform-modules-commonjs": "7.0.0-beta.47",
-    "@babel/register": "7.0.0-beta.47",
-    "babel-plugin-transform-rename-import": "2.2.0",
+    "alamode": "1.5.0",
+    "documentary": "1.18.0",
     "yarn-s": "1.1.0",
-    "zoroaster": "1.1.0"
+    "zoroaster": "3.4.1"
   },
   "dependencies": {
-    "catchment": "2.0.1"
+    "catchment": "3.1.1"
   }
 }

README.md

 # spawnCommand
 
-[![npm version](https://badge.fury.io/js/spawncommand.svg)](https://badge.fury.io/js/spawncommand)
+[![npm version](https://badge.fury.io/js/spawncommand.svg)](https://npmjs.org/package/spawncommand)
 
+_SpawnCommand_ will run the `spawn` or `fork` methods from the `child_process` module, and add a `promise` property to the returned process instance. The promise will be resolved on process exit with an object consisting of `code`, `stdout` and `stderr` properties.
+
 ```
@@ -9,28 +11,77 @@ yarn add -E spawncommand
 
-This package is a wrapper around `child_process.spawn` methods to set `.promise` property on the returned `ChildProcess` instances. The promise will be fulfilled on process exit with an object consisting of `code`, `stdout` and `stderr` properties, where:
+<p align="center"><a href="#table-of-contents"><img src=".documentary/section-breaks/0.svg?sanitize=true"></a></p>
 
-- `code` is the exit code
-- `stdout` is all data the process wrote to _stdout_
-- `stderr` is all data the process wrote to _stderr_
+## Table Of Contents
 
-The promise will be rejected if an error was encountered when trying to spawn the process.
+- [Table Of Contents](#table-of-contents)
+- [API](#api)
+  * [Types](#types)
+    * [`ChildProcessWithPromise`](#childprocesswithpromise)
+    * [`PromiseResult`](#promiseresult)
+  * [`spawn(module: string, args: string[], options?: SpawnOptions): ChildProcessWithPromise`](#spawnmodule-stringargs-stringoptions-spawnoptions-childprocesswithpromise)
+  * [`fork(module: string, args: string[], options?: ForkOptions): ChildProcessWithPromise`](#forkmodule-stringargs-stringoptions-forkoptions-childprocesswithpromise)
+- [Copyright](#copyright)
 
+<p align="center"><a href="#table-of-contents"><img src=".documentary/section-breaks/1.svg?sanitize=true"></a></p>
+
+## API
+
+_SpawnCommand_ can be used by importing the default `spawn` and named `fork` exports.
+
 ```js
-/* yarn example/spawncommand.js */
-import spawnCommand from 'spawncommand'
+import spawn, { fork } from 'spawncommand'
+```
 
+<p align="center"><a href="#table-of-contents"><img src=".documentary/section-breaks/2.svg?sanitize=true" width="15"></a></p>
+
+### Types
+
+The package's main type is _ChildProcessWithPromise_ which enriches the standard _ChildProcess_ with a `promise` property.
+
+[`import('child_process').ChildProcess`](https://nodejs.org/api/child_process.html#child_process_class_childprocess) __<a name="childprocess">`ChildProcess`</a>__
+
+`ChildProcess` __<a name="childprocesswithpromise">`ChildProcessWithPromise`</a>__: A child process with an extra `promise` property.
+
+|     Name     |                       Type                        |                Description                 | Default |
+| ------------ | ------------------------------------------------- | ------------------------------------------ | ------- |
+| __promise*__ | _Promise.&lt;[PromiseResult](#promiseresult)&gt;_ | A promise resolved when the process exits. | -       |
+
+__<a name="promiseresult">`PromiseResult`</a>__
+
+|    Name     |   Type   |                  Description                   | Default |
+| ----------- | -------- | ---------------------------------------------- | ------- |
+| __stdout*__ | _string_ | The accumulated result of the `stdout` stream. | -       |
+| __stderr*__ | _string_ | The accumulated result of the `stderr` stream. | -       |
+| __code*__   | _number_ | The code with which the process exited.        | -       |
+
+<p align="center"><a href="#table-of-contents"><img src=".documentary/section-breaks/3.svg?sanitize=true" width="15"></a></p>
+
+### `spawn(`<br/>&nbsp;&nbsp;`module: string,`<br/>&nbsp;&nbsp;`args: string[],`<br/>&nbsp;&nbsp;`options?: SpawnOptions,`<br/>`): ChildProcessWithPromise`
+
+Spawns a command and returns a _ChildProcess_ instance with the `promise` property resolved on exit. The promise will be rejected if an error was encountered when trying to spawn the process.
+
+`import('child_process').SpawnOptions` __<a name="spawnoptions">`SpawnOptions`</a>__
+
+```js
+import spawn from 'spawncommand'
+
 (async () => {
-  const { promise } = spawnCommand('echo', ['hello world'])
+  const { promise } = spawn('echo', ['hello world'])
   const { stderr, stdout, code } =  await promise
-
-  console.log(stderr) // undefined
-  console.log(stdout) // hello world\n
-  console.log(code) // 0
+  console.log(JSON.stringify({
+    stderr, stdout, code,
+  }, null, 2))
 })()
 ```
+```json5
+{
+  "stderr": "",
+  "stdout": "hello world\n",
+  "code": 0
+}
+```
 
-Because the returned object is a `ChildProcess`, all its properties can be accessed.
+The returned object is a `ChildProcess` and all of its properties can be accessed in the standard way.
 
 ```js
-/* yarn example/pipe.js */
 import spawnCommand from 'spawncommand'
@@ -45,30 +96,44 @@
 ```
+```
+hello world
+```
 
-## fork
+<p align="center"><a href="#table-of-contents"><img src=".documentary/section-breaks/4.svg?sanitize=true" width="15"></a></p>
 
-It is also possible to fork a Node.js process and execute a module in it.
+### `fork(`<br/>&nbsp;&nbsp;`module: string,`<br/>&nbsp;&nbsp;`args: string[],`<br/>&nbsp;&nbsp;`options?: ForkOptions,`<br/>`): ChildProcessWithPromise`
 
+Forks a Node.js module and adds a `promise` property to the returned _ChildProcess_.
+
+
+
 ```js
-/* yarn example/fork.js */
-import { resolve } from 'path'
 import { fork } from 'spawncommand'
 
-const MODULE_PATH = resolve(__dirname, 'example/spawn.js')
-
-;(async () => {
-  const { promise } = fork('example/spawn.js', [], {
+(async () => {
+  const { promise } = fork('example/index.js', ['example/spawn.js'], {
     stdio: 'pipe',
   })
   const { stdout } =  await promise
-  console.log(stdout) // same output as example/spawn.js
+  console.log(stdout)
 })()
 ```
+```json5
+{
+  "stderr": "",
+  "stdout": "hello world\n",
+  "code": 0
+}
+```
 
-Make sure to pass `pipe` option to be able to gather stderr and stdout streams (or an array for versions of Node.js when [this does not work][2]).
+The `pipe` option needs to be set in order to gather the output of the `stderr` and `stdout` streams (or an array for older versions of Node.js when [this does not work][2]).
 
----
+<p align="center"><a href="#table-of-contents"><img src=".documentary/section-breaks/5.svg?sanitize=true"></a></p>
 
-(c) [Art Deco Code][1] 2018
+## Copyright
 
+(c) [Art Deco][1] 2018
+
 [1]: https://artdeco.bz
 [2]: https://github.com/nodejs/node/pull/10866
+
+<p align="center"><a href="#table-of-contents"><img src=".documentary/section-breaks/-1.svg?sanitize=true"></a></p>

New alerts

Shell access

Supply chain risk

This module accesses the system shell. Accessing the system shell increases the risk of executing arbitrary code.

Found 1 instance in 1 package

Fixed alerts

Shell access

Supply chain risk

This module accesses the system shell. Accessing the system shell increases the risk of executing arbitrary code.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

15387

increased by107.2%

Dev dependency count

4

decreased by-50%

Number of package files

6

increased by20%

Lines of code

68

increased by1.49%

Number of lines in readme file

137

increased by87.67%

Dependency changes

• + Added@artdeco/clean-stack@1.0.0(transitive)

• + Addedcatchment@3.1.1(transitive)

• + Addederotic@2.0.1(transitive)

• - Removedcatchment@2.0.1(transitive)

• Updatedcatchment@3.1.1