tinyexec: Minimal Node.js Process Execution

Common errors

• Error [ERR_REQUIRE_ESM]: require() of ES Module ... tinyexec/dist/index.js not supported. Instead change the require of index.js in ... to a dynamic import() which is available in all CommonJS modules.

  cause Attempting to import `tinyexec` using a CommonJS `require()` statement in a Node.js environment where tinyexec is treated as an ES Module.
  fix Refactor your code to use ES Module `import` syntax: `import { x } from 'tinyexec';`. Ensure your project's `package.json` includes `"type": "module"` or that your file has a `.mjs` extension.

• Error: Command failed with exit code 1

  cause This error occurs when `throwOnError: true` is set in the options, and the executed process exits with a non-zero status code, indicating a failure.
  fix Inspect the `stderr` output (e.g., `error.stderr`) for clues about why the command failed. If a non-zero exit code should not throw an error, set `throwOnError: false` in the options object.

• TypeError: proc.pipe is not a function

  cause Attempting to call `.pipe()` on the `Output` result object after `await x(...)` has resolved, rather than on the live `Promise` returned by `x`.
  fix Chain the `.pipe()` call directly onto the `x()` invocation before awaiting: `const proc1 = x('ls', ['-l']); const proc2 = proc1.pipe('grep', ['.js']); const result = await proc2;`

Warnings

• breaking tinyexec migrated to an ESM-only build starting with version 1.0.0. CommonJS `require()` statements are no longer supported.
  Fix: Migrate your project to use ECMAScript Modules (ESM) by setting `"type": "module"` in your `package.json` or by using `.mjs` file extensions. Update all `require('tinyexec')` calls to `import { x } from 'tinyexec';`.
• breaking The default behavior for `throwOnError` has changed across minor versions. In v0.3.0, `tinyexec` started throwing on non-zero exit codes by default. However, as of recent versions (including 1.x), it *does not* throw by default.
  Fix: To ensure consistent error handling, always explicitly set the `throwOnError` option in your calls to `x` or `xSync` (e.g., `{ throwOnError: true }` to throw on non-zero exit codes, or `{ throwOnError: false }` to always return the result object).
• gotcha Output from `stdout` and `stderr` streams does not automatically trim trailing newlines. The exact raw output is returned.
  Fix: If trimmed output is desired, explicitly clean the string: `result.stdout.replace(/\r?\n$/, '')`.
• gotcha tinyexec requires Node.js version 18 or higher due to its ESM-only nature and usage of modern Node.js features.
  Fix: Ensure your Node.js runtime environment is version 18 or newer. Update Node.js using your preferred package manager (e.g., `nvm install 18` or `nvm use 18`).
• gotcha When attempting to pass commands as a single shell-like string (e.g., `await x('echo "Hello, World!"')`), `tinyexec` expects the command and arguments to be split. It does not invoke a shell by default.
  Fix: Split the command string into a command and an array of arguments, e.g., `await x('echo', ['Hello, World!'])`. For parsing complex shell syntax, consider using `args-tokenizer`: `const [cmd, ...args] = tokenizeArgs(commandString); await x(cmd, args);`

Install

• npm install tinyexec npm
• yarn add tinyexec yarn
• pnpm add tinyexec pnpm

Imports

• x
  wrong:

  const x = require('tinyexec');

  correct:

  import { x } from 'tinyexec';

  The primary asynchronous process execution function. tinyexec is ESM-only since v1.0.0.
• xSync
  wrong:

  const { xSync } = require('tinyexec');

  correct:

  import { xSync } from 'tinyexec';

  Synchronous (blocking) process execution function, introduced in v1.1.0. tinyexec is ESM-only since v1.0.0.
• Output

  import type { Output } from 'tinyexec';

  TypeScript type definition for the result object returned by `x` and `xSync`, containing `stdout`, `stderr`, `exitCode`, etc.

Quickstart

Demonstrates asynchronous (`x`) and synchronous (`xSync`) command execution, including options, piping, and async iteration over output lines. It also shows optional use of `args-tokenizer` for command string parsing.

import { x, xSync } from 'tinyexec';
import { tokenizeArgs } from 'args-tokenizer'; // Optional, for parsing string commands

async function runExample() {
  console.log('--- Async Example (x) ---');
  try {
    const result = await x('ls', ['-l', '.'], {
      timeout: 5000, // Process will be killed after 5 seconds
      throwOnError: true, // Throws an error if exitCode is non-zero
      env: { ...process.env, MY_CUSTOM_VAR: 'hello' } // Pass custom environment variables
    });
    console.log('stdout:', result.stdout.trim());
    console.log('stderr:', result.stderr.trim());
    console.log('exitCode:', result.exitCode);
  } catch (error) {
    console.error('Async process failed:', error);
  }

  console.log('\n--- Async Iteration Example ---');
  const proc = x('node', ['-e', 'console.log("Line 1"); await new Promise(r => setTimeout(r, 10)); console.log("Line 2");']);
  console.log('Output lines:');
  for await (const line of proc) {
    console.log(`- ${line.trim()}`);
  }

  console.log('\n--- Sync Example (xSync) ---');
  try {
    const syncResult = xSync('node', ['-e', 'console.log("Hello from sync"); process.exit(0);']);
    console.log('sync stdout:', syncResult.stdout.trim());
  } catch (error) {
    console.error('Sync process failed:', error);
  }

  console.log('\n--- Piping Example ---');
  // Using args-tokenizer for a more realistic command string parsing example
  const commandString = 'grep .mjs';
  const [grepCommand, ...grepArgs] = tokenizeArgs(commandString);

  const proc1 = x('ls', ['.']);
  const proc2 = proc1.pipe(grepCommand, grepArgs);
  const pipedResult = await proc2;
  console.log('Piped .mjs files:', pipedResult.stdout.trim());
}

runExample();