8.3.0 – Pipes of Steel

A few weeks ago zx took a part in OSS Library Night 🎉
Many thanks to the organizers and contributors who have boosted the project with their pull requests!

Today we are releasing the zx with a huge bunch of new features and improvements.

Features

API

• Implemented [Symbol.asyncIterator] API for ProcessPromise #984 #998 #1000
  Now you can iterate over the process output using for await loop from any point of the process execution.

const process = $`sleep 0.1; echo Chunk1; sleep 0.1; echo Chunk2; sleep 0.2; echo Chunk3; sleep 0.1; echo Chunk4;`
const chunks = []

await new Promise((resolve) => setTimeout(resolve, 250))
for await (const chunk of process) {
  chunks.push(chunk)
}

chunks.length //  4
chunks[0]     // 'Chunk1'
chunks[3]     // 'Chunk4'

• zx version is available via JS API #986

import { version } from 'zx'
const [major] = (version || '').split('.').map(Number)
if (major < 6)
  throw new Error('zx >= 6 is required')

Pipes

• Enabled stream picking for pipe() #1023

const p = $`echo foo >&2; echo bar`
const o1 = (await p.pipe.stderr`cat`).toString()
const o2 = (await p.pipe.stdout`cat`).toString()

assert.equal(o1, 'foo\n')  // <- piped from stderr
assert.equal(o2, 'bar\n')  // <- stdout

• Added signal handling on piping #992

const ac = new AbortController()
const { signal } = ac
const p = $({ signal, nothrow: true })`echo test`.pipe`sleep 999`
setTimeout(() => ac.abort(), 50)

try {
  await p
} catch ({ message }) {
  message // The operation was aborted
}

• Added direct piping to file shortcut #1001

// before
await $`echo "Hello, stdout!"`.pipe(fs.createWriteStream('/tmp/output.txt'))

// after
await $`echo "Hello, stdout!"`.pipe('/tmp/output.txt')

CLI

• Provided $.defaults setting via ZX_-prefixed environment variables #988 #998

ZX_VERBOSE=true ZX_SHELL='/bin/bash' zx script.mjs

• Introduced --env option to load dotenvs 1022 #1030

zx --env=/path/to/some.env script

• Landed installation registry customization #994

zx --install --registry=https://registry.yarnpkg.com script.mjs

• Added --prefer-local option #1015

Fixes

• Fixed temp assets clutter on process.exit() #993 #997
• Handle tslib-generated string templates #966
• Disabled spinner on CI and in quiet mode #1008 #1009 #1017
• Added missing ZX_SHELL env handling #1024

Docs

• Contribution guide updated #983
• Documentation is now built from the main branch #985
• Finally synced with the current API #1025 #1026

Chores

• Added autotest generation for 3rd party libs export #987 #990 #1007 #1021
• Added some jsr.io pre-publish tests #989 #991
• Optimized package.json on publishing #1005 #1006
• Attached .node_version to improve contributors devx #1012
• Built-in chalk updated to v5.4.1 #1019

Merry Christmas! 🎄🎅🎁