tinyspawn

tinyspawn is a minimalistic child_process wrapper with following features:

• Small (~80 LOC, 835 bytes).
• Focus on performance.
• Zero dependencies.
• Meaningful errors.
• Easy to extend.
• Fully typed.

Install

$ npm install tinyspawn --save

Usage

Getting started

The child_process in Node.js is great, but I always found the API confusing and hard to remember.

That's why I created tinyspawn. It's recommended to bind it to $:

const $ = require('tinyspawn')

The first argument is the command (with arguments) to be executed:

const { stdout } = await $(`node -e 'console.log("hello world")'`)
console.log(stdout) // => 'hello world'

The second argument is any of the spawn#options:

const { stdout } = $(`node -e 'console.log("hello world")'`, {
  shell: true
})

Passing dynamic values safely

The string form above splits the command on whitespace, so any interpolated value that contains a space becomes multiple arguments:

const file = 'a.txt b.txt'
await $(`cat ${file}`) // spawns: cat "a.txt" "b.txt"  ⚠️ two arguments

When a value comes from an untrusted or dynamic source, this is argument injection (see Security). Pass those values using the array form, where the second argument is an array of arguments and each item is passed verbatim, spaces and all:

await $('cat', [file]) // spawns: cat "a.txt b.txt"  ✅ one argument

You can pass a list of values the same way:

const files = ['a.txt', 'b.txt']
await $('cat', files) // spawns: cat "a.txt" "b.txt"

When you execute a command, it returns a ChildProcess instance:

const {
  exitCode,
  killed,
  pid,
  signalCode,
  spawnargs,
  spawnfile,
  stderr,
  stdin,
  stdout,
} = await $('date')

Piping streams

Since tinyspawn returns a ChildProcess instance, you can use it for interacting with other Node.js streams:

const subprocess = $('echo 1234567890')
subprocess.stdout.pipe(process.stdout) // => 1234567890

/* You can also continue interacting with it as a promise */

const { stdout } = await subprocess
console.log(stdout) // => 1234567890

or stdin:

const { Readable } = require('node:stream')

const subprocess = $('cat')
Readable.from('hello world').pipe(subprocess.stdin)
const { stdout } = await subprocess

console.log(stdout) // 'hello world'

JSON parsing

A CLI program commonly supports a way to return a JSON that makes it easy to connect with other programs.

tinyspawn has been designed to be easy to work with CLI programs, making it possible to call $.json or pass { json: true } as an option:

const { stdout } = await $.json(`curl https://geolocation.microlink.io`)

Extending behavior

Although you can pass spawn#options as a second argument, sometimes defining something as default behavior is convenient.

tinyspawn exports the method $.extend to create a tinyspawn with spawn#options defaults set:

const $ = require('tinyspawn').extend({
  timeout: 5000,
  killSignal: 'SIGKILL'
})

Meaningful errors

When working with CLI programs and something wrong happens, it's crucial to present the error as readable as possible.

tinyspawn prints meaningful errors to help you understa dn what happened:

const subprocess = $('node', ['child.js'], {
  timeout: 500,
  killSignal: 'SIGKILL'
})

console.log(await subprocess.catch(error => error))
// Error [ChildProcessError]: The command spawned as:

//   `node child.js`

// exited with:

//   `{ signal: 'null', code: 1 }`

// with the following trace:

//     at createChildProcessError (/Users/kikobeats/Projects/microlink/tinyspawn/src/index.js:20:17)
//     at ChildProcess.<anonymous> (/Users/kikobeats/Projects/microlink/tinyspawn/src/index.js:63:18)
//     at ChildProcess.emit (node:events:531:35)
//     at ChildProcess._handle.onexit (node:internal/child_process:294:12) {
//   command: 'node child.js',
//   connected: false,
//   signalCode: null,
//   exitCode: 1,
//   killed: false,
//   spawnfile: 'node',
//   spawnargs: [ 'node', 'child.js' ],
//   pid: 63467,
//   stdout: '',
//   stderr: 'node:internal/modules/cjs/loader:1148\n' +
//     '  throw err;\n' +
//     '  ^\n' +
//     '\n' +
//     "Error: Cannot find module '/Users/kikobeats/Projects/microlink/tinyspawn/child.js'\n" +
//     '    at Module._resolveFilename (node:internal/modules/cjs/loader:1145:15)\n' +
//     '    at Module._load (node:internal/modules/cjs/loader:986:27)\n' +
//     '    at Function.executeUserEntryPoint [as runMain] (node:internal/modules/run_main:174:12)\n' +
//     '    at node:internal/main/run_main_module:28:49 {\n' +
//     "  code: 'MODULE_NOT_FOUND',\n" +
//     '  requireStack: []\n' +
//     '}\n' +
//     '\n' +
//     'Node.js v20.15.1'
// }

The ChildProcess instance properties are also available as part of the error:

const { stdout: node } = await $('which node')

const error = await $(`${node} -e 'require("notfound")'`).catch(error => error)

const {
  signalCode,
  exitCode,
  killed,
  spawnfile,
  spawnargs,
  pid,
  stdin,
  stdout,
  stderr,
} = error

Security

tinyspawn never spawns a shell by default, so shell metacharacters (;, `, $(), |) are inert and classic shell injection is not possible.

There is still one thing to keep in mind: the string form $('cmd arg1 arg2') splits on whitespace, so interpolating an untrusted value that contains a space turns it into several arguments. Depending on the wrapped binary, extra arguments can change behavior (read/write other files, follow redirects, run helper programs). This is CWE-88: argument injection.

The rule is simple:

• Static commands you write yourself → the string form is fine.
• Any value from an untrusted or dynamic source → use the array form $(cmd, [value]), which keeps each value as a single, opaque argument.

Never interpolate untrusted input into the string form.

Related

• tinyrun – CLI for executing multiple commands in parallel with minimal footprint (~2KB).

License

tinyspawn microlink.io, released under the MIT License.
Authored and maintained by Kiko Beats with help from contributors.

microlink.io · GitHub microlink.io · X @microlinkhq