🦪 zx-extra

zx with some extras

Requirements

• Node.js >= 16.0.0
• Bun >= 1.0.12

Install

# npm
npm i zx-extra

# yarn
yarn add zx-extra

Usage

Inherits zx, so all original methods are available. Follow the upstream docs for details.

Extras

striked text marks APIs that was merged into zx core.

ip

Resolves the current IP address via node-ip.

import {ip} from 'zx-extra'

ip.address() // 1.2.3.4

semver

Semantic versioning API provided by node-semver.

import {semver} from 'zx-extra'

semver.gte('1.0.1', '1.0.0')

ver

Asserts the version of the specified package or binary against the semver range.

import {ver} from 'zx-extra'

ver('ip')           // '1.1.8'
ver('git')          // '2.37.0'
ver('git', '>=2')   // '2.37.0'
ver('git', '>=5')   // Error: git@2.37.0 does not satisfy >=5

tcping

Checks the network availability of the specified gateway via is-reachable.

import {tcping} from 'zx-extra'

await tcping('example.com:443') // true
await tcping('unknown:1234')    // false

tempy

deprecated, use tmpfile and tmpdir instead: zx#803

Creates temp dirs and files.

import {tempy} from 'zx-extra'

temporaryFile()       // '/private/var/folders/p0/p7xckky93s30rshd51gs4pdc0000gn/T/1b7e9277860eb90b94aad816d4f66f8e'
temporaryDirectory()  // '/private/var/folders/p0/p7xckky93s30rshd51gs4pdc0000gn/T/1b7e9277860eb90b94aad816d4f66f8e'

copy

Provides globby-boosted copying API.

import {copy} from 'zx-extra'

await copy({
  from:       'src/**/*.js',
  to:         'dist/',
  baseFrom,   // process.cwd()
  baseTo,     // process.cwd(),
  debug,      // () => {}
  ignoreFiles // undefined
})

INI

Provides INI API.

import {INI} from 'zx-extra'

const ini = `[database]
user = dbuser
password = dbpassword
`
  const parsed = INI.parse(ini)
  parsed.database.user //  'dbuser'
  INI.stringify(parsed, {whitespace: true}) //  ini

SSRI

Exposes SSRI API

import {SSRI} from 'zx-extra'

const integrity = 'sha512-9KhgCRIx/AmzC8xqYJTZRrnO8OW2Pxyl2DIMZSBOr0oDvtEFyht3xpp71j/r/pAe1DM+JI/A+line3jUBgzQ7A==?foo'
// Parsing and serializing
const parsed = SSRI.parse(integrity)
SSRI.stringify(parsed) // === integrity (works on non-Integrity objects)
parsed.toString() // === integrity

ctx

async_hooks-driven scope isolator. Creates a separate zx-context for the specified function.

import {ctx} from 'zx/experimental'

const _$ = $
ctx(async ($) => {
  await sleep(10)
  cd('/foo')
  // $.cwd refers to /foo
  // _$.cwd === $.cwd
})

ctx(async ($) => {
  await sleep(20)
  // _$.cwd refers to /foo
  // but _$.cwd !== $.cwd
})

const ref = $.bind(null)
ctx(($) => {
  ref === $ // true
}, ref)

$.preferLocal

Landed as zx#798

In npm run scripts you can execute locally installed binaries by name. This enables the same for zx.

$`terser input.js --compress ecma=2015,computed_props=false`

Note, that yarn and npm modify env.$PATH value, so some */node_modules/.bin binaries are available for invocation. To disable this side-effect, append smth like PATH=$(env -i bash -c 'echo $PATH') to the command.

$.raw

Evaluates target cmd as is without shq.

const cmd = 'echo foo'
const msg = 'bar'
const output = (await $.raw`${cmd} ${msg}`).toString().trim()
// $ echo foo bar

$.verbose

Since zx@8.0.0

Set to false by default.

$.trim

Applies .trim() to ProcessOutput string representation. Set true by default.

$.opt

Landed as zx#733

Returns $ with the specified preset. Aliased for $.o.

const $$ = $.opt({verbose: false, spawn: customSpawn})

await $$`foo 'bar'`

createHook

Helper to create chainable extras.

const quiet = createHook({ verbose: false }, 'quiet')
const timeout = createHook(
  null,
  'timeout',
  (p, t, signal) => {
    if (!t) return p
    let timer = setTimeout(() => p.kill(signal), t)

    return Object.assign(
      p.finally(() => clearTimeout(timer)),
      p
    )
  },
  true
)

const p = $`sleep 9999`
await quiet(timeout(100, 'SIGKILL')(p))
await $`sleep 9999`.quiet().timeout(100, 'SIGKILL')
await quiet(timeout(100, 'SIGKILL')`sleep 9999`)

$.silent

merged as bf88f50

Sets verbose = false for a single invocation.

await $.silent`echo foo`
// <no output in console>

$.fs / global.fs

merged as d8b6b87
Refers to fs-extra instead of standard Node.js fs module.

await fs.copy('/tmp/myfile', '/tmp/mynewfile')

global.argv

merged as d8b6b87
Represents parsed with minimist script arguments

// zx-extra test.mjs --foo=bar
argv
{ _: [ 'test.mjs' ], foo: 'bar' }

License

MIT