🦪 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
Copy

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
Copy

semver

Semantic versioning API provided by node-semver.

import {semver} from 'zx-extra'

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

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
Copy

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
Copy

tempy

deprecated, use tmpfile and tmpdir instead: zx#803

Creates temp dirs and files.

import {tempy} from 'zx-extra'

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

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
})
Copy

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
Copy

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
Copy

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)
Copy

$.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`
Copy

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
Copy

$.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'`
Copy

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`)
Copy

$.silent

merged as bf88f50

Sets verbose = false for a single invocation.

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

$.fs / global.fs

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

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

global.argv

merged as d8b6b87
Represents parsed with minimist script arguments

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

License

MIT