tessl/npm-zx

A tool for writing better scripts by bridging JavaScript and shell commands with cross-platform wrappers around child_process

Overview

Eval results

Files

Shell Execution

Name: tessl/npm-zx
Author: tessl

Core shell command execution with the $ function, configuration options, and command composition capabilities.

Capabilities

Dollar Function ($)

The main shell execution function that serves as both a template literal function and configuration object.

/**
 * Execute shell commands using template literals
 * @param pieces - Template string parts
 * @param args - Interpolated arguments (automatically escaped)
 * @returns ProcessPromise for async execution or ProcessOutput for sync
 */
interface Shell<S = false, R = S extends true ? ProcessOutput : ProcessPromise> {
  (pieces: TemplateStringsArray, ...args: any[]): R;
  <O extends Partial<Options>>(opts: O): Shell;
  sync: Shell<true>;
}

type $ = Shell & Options;
declare const $: $;

Basic Usage:

import { $ } from "zx";

// Execute commands
const result = await $`echo "Hello World"`;
console.log(result.stdout); // "Hello World\n"

// With interpolated arguments (automatically escaped)
const dir = "my folder";
await $`mkdir ${dir}`; // Safe even with spaces/special chars

// Sync execution
const output = $.sync`pwd`;
console.log(output.stdout);

Configuration Options

Configure shell behavior by calling $ as a function with options.

interface Options {
  /** Working directory for command execution */
  cwd?: string;
  /** Environment variables */
  env?: NodeJS.ProcessEnv;
  /** Shell to use (true for default, string for specific shell) */
  shell?: string | true;
  /** Standard I/O configuration */
  stdio?: StdioOptions;
  /** Enable verbose output */
  verbose?: boolean;
  /** Suppress output */
  quiet?: boolean;
  /** Don't throw on non-zero exit codes */
  nothrow?: boolean;
  /** Command timeout */
  timeout?: Duration;
  /** Timeout signal */
  timeoutSignal?: NodeJS.Signals;
  /** Kill signal */
  killSignal?: NodeJS.Signals;
  /** Command prefix */
  prefix?: string;
  /** Command postfix */
  postfix?: string;
  /** Run as detached process */
  detached?: boolean;
  /** Prefer local binaries */
  preferLocal?: boolean | string | string[];
  /** Synchronous execution */
  sync?: boolean;
  /** Input for command */
  input?: string | Buffer | Readable | ProcessOutput | ProcessPromise;
  /** Abort signal */
  signal?: AbortSignal;
  /** Abort controller */
  ac?: AbortController;
}

Configuration Examples:

// Quiet execution
const result = await $({ quiet: true })`git status`;

// Custom working directory
const files = await $({ cwd: '/tmp' })`ls -la`;

// With timeout
const output = await $({ timeout: '5s' })`long-running-command`;

// Multiple options
const result = await $({
  quiet: true,
  nothrow: true,
  cwd: '/project',
  env: { NODE_ENV: 'production' }
})`npm test`;

Directory Management

Navigate and manage working directories within scripts.

/**
 * Change current working directory
 * @param dir - Directory path or ProcessOutput containing path
 */
function cd(dir: string | ProcessOutput): void;

/**
 * Control directory synchronization behavior
 * @param flag - Whether to sync process.cwd() with internal state
 */
function syncProcessCwd(flag?: boolean): void;

/**
 * Execute callback with temporary configuration
 * @param callback - Function to execute with current $ configuration
 * @returns Result of callback execution
 */
function within<R>(callback: () => R): R;

Usage:

import { $, cd, within } from "zx";

// Change directory
cd('/tmp');
await $`pwd`; // Shows /tmp

// Temporary configuration
const result = await within(() => {
   $.verbose = false;
   return $`echo "quiet"`;
});

Default Configuration

Access and modify default options for all shell executions.

/**
 * Default options applied to all $ calls
 */
declare const defaults: Options;

/**
 * Resolve configuration defaults with environment variables
 * @param defs - Default options
 * @param prefix - Environment variable prefix
 * @param env - Environment variables to read from
 * @param allowed - Set of allowed option keys
 * @returns Resolved options
 */
function resolveDefaults(
  defs?: Options,
  prefix?: string,
  env?: NodeJS.ProcessEnv,
  allowed?: Set<string>
): Options;

Usage:

import { $, defaults } from "zx";

// Modify global defaults
defaults.verbose = false;
defaults.shell = '/bin/bash';

// All subsequent $ calls use these defaults
await $`echo "uses defaults"`;

Process Control

Kill processes and manage process lifecycle.

/**
 * Kill a process by PID
 * @param pid - Process ID to kill
 * @param signal - Signal to send (default: SIGTERM)
 */
function kill(pid: number, signal?: NodeJS.Signals): Promise<void>;

Usage:

import { $, kill } from "zx";

const proc = $`sleep 100`;
const pid = proc.pid;

if (pid) {
  await kill(pid, 'SIGKILL');
}

Types

type Duration = string | number;

type StdioOptions = 'pipe' | 'ignore' | 'inherit' | Array<'pipe' | 'ignore' | 'inherit' | Stream | number | null | undefined>;

interface TemplateStringsArray extends ReadonlyArray<string> {
  readonly raw: ReadonlyArray<string>;
}

Install with Tessl CLI