tinyspawn

tinyspawn

tinyspawn is a minimalistic child_process wrapper with following features:

• Small (~50 LOC, 600 bytes).
• Focus on performance.
• Zero dependencies.
• Meaningful errors.
• Easy to extend.

Install

$ npm install tinyspawn --save

Usage

Basic

It's recommended to bind tinyspawn to $:

const $ = require('tinyspawn')

After that, pass the command (with arguments) to be executed as first argument:

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

You can pass any spawn#options as second argument:

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

The output is a ChildProcess instance:

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

Piping

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

// It's a childProcess instance
const subprocess = $('echo 1234567890')
subprocess.stdout.pipe(process.stdout) // => 1234567890

// And it's a promise too
await subprocess

JSON parsing

tinyspawn has been designed to work with CLI commands that outputs json.

You can easily parse it calling $.json or passing { json: true } as option:

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

Extending

You can use $.extend to pass any spawn#options to be used by default:

const $ = require('tinyspawn').extend({ shell: true })

Errors

tinyspawn is oriented to print meanigful errors:

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

console.error(error)
// The command spawned as:

//   /Users/kikobeats/.n/bin/node -e 'require("notfound")'

// failed with code 1:

//   node:internal/modules/cjs/loader:1147
//     throw err;
//     ^

//   Error: Cannot find module 'notfound'
//   Require stack:
//   - /Users/kikobeats/Downloads/tinyspawn/[eval]
//       at Module._resolveFilename (node:internal/modules/cjs/loader:1144:15)
//       at Module._load (node:internal/modules/cjs/loader:985:27)
//       at Module.require (node:internal/modules/cjs/loader:1235:19)
//       at require (node:internal/modules/helpers:176:18)
//       at [eval]:1:1
//       at runScriptInThisContext (node:internal/vm:144:10)
//       at node:internal/process/execution:109:14
//       at [eval]-wrapper:6:24
//       at runScript (node:internal/process/execution:92:62)
//       at evalScript (node:internal/process/execution:123:10) {
//     code: 'MODULE_NOT_FOUND',
//     requireStack: [ '/Users/kikobeats/Downloads/tinyspawn/[eval]' ]
//   }

//   Node.js v20.10.0

The childProcess 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,
  stdin
} = error

License

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

kikobeats.com · GitHub Kiko Beats · Twitter @kikobeats

Changelog

1.1.1 (2023-12-12)

Bug Fixes

• buffer concat (1f048de)