feat: JSON.stringify values with typeof 'object'

- `examples/echo` and `examples/echo-async` no longer need to do it
- Updated documentation in examples, tests and README

README.md

@@ -50,6 +50,7 @@ Options:
 - it can throw (rejected Promises will be treated the same way)
 - it is in control of `stdout` (`runex` only communicates over `stderr`), with one exception:
   - if you return a value it will be printed to `stdout` (so you don't have to, see goal)
+    if `typeof value === 'object` it will be `JSON.stringify`ed.
 
 Go check some [examples](https://github.com/karfau/runex/tree/master/examples).
 

examples/echo-async.js

@@ -10,20 +10,22 @@ const delay = async (ms = 100) => new Promise(resolve => {
 
 module.exports = {
   /**
-   * The **async** "Hello, world" of a `run` method, it uses `JSON.stringify`
-   * on all passed arguments, so it is more easy to see how many arguments have been passed.
-   * (This way it is more easy to parse the output with other shell tools like `jq`.)
+   * The **async** "Hello, world" of a `run` method,
+   * it returns all passed arguments as an Array after a short delay.
+   * (Runex prints the JSON to stdout by default.)
    *
-   * @returns {Promise<string>} The JSON is only provided after a short delay.
-   *          Rejects with with `Error.message` set to 'empty' if no arguments are passed.
+   * This way tests can check how many arguments have been passed.
+   *
+   * @returns {Promise<string[]>} The JSON is only provided after a short delay.
+   * @throws Rejects with with `Error.message` set to 'empty' if no arguments are passed.
    *
    * Usage:
-   * `npx runex examples/echo-async` // => []
+   * `npx runex examples/echo-async` // throws 'empty'
    * `npx runex examples/echo-async Hello world` // => ["Hello", "world"]
    * `npx runex examples/echo-async 'Hello, world'` // => ["Hello, world"]
    */
   run: async (...args) => delay().then(() => {
     if (args.length === 0) throw new Error('empty');
-    return JSON.stringify(args);
+    return args;
   })
 }

examples/echo.js

@@ -1,15 +1,15 @@
 module.exports = {
   /**
-   * The "Hello, world" of a `run` method, it uses `JSON.stringify`
-   * on all passed arguments, so it is more easy to see how many arguments have been passed.
-   * (This way it is more easy to parse the output with other shell tools like `jq`.)
+   * The "Hello, world" of a `run` method,
+   * it returns all passed arguments as an Array.
+   * (Runex prints the JSON to stdout by default.)
+   *
+   * This way tests can check how many arguments have been passed.
    *
    * Usage:
    * `npx runex examples/echo` // []
    * `npx runex examples/echo Hello world` // ["Hello", "world"]
    * `npx runex examples/echo 'Hello, world'` // ["Hello, world"]
    */
-  run: (...args) => {
-    console.log(JSON.stringify(args));
-  }
+  run: (...args) => args
 }

index.js

@@ -162,7 +162,9 @@ if (module === /** @type {NodeModule | typeof module} */(require.main)) {
   )
   run(runnable, p)
     .then(value => {
-      if (value !== undefined) console.log(value)
+      if (value !== undefined) console.log(
+        typeof value === 'object' ? JSON.stringify(value) : value
+      )
     })
 } else {
   module.exports = {

test/passing-arguments.js

@@ -3,9 +3,6 @@ import { test } from 'tap'
 import { assertStdout, command } from '../test.command'
 
 /**
- * The following assertions rely on the implementation of `../examples/echo:run`
- * to print the `JSON.stringify`ed arguments to stdout.
- *
  * Passing any argument via shell means they are all received as strings,
  * there is no conversion of arguments (other then type coercion done by JS runtime).
  *