# tinyexec 📟

> A minimal package for executing commands

This package was created to provide a minimal way of interacting with child
processes without having to manually deal with streams, piping, etc.

## Installing

```sh
$ npm i -S tinyexec
```

## Usage

A process can be spawned and awaited like so:

```ts
import {x} from 'tinyexec';

const result = await x('ls', ['-l']);

// result.stdout - the stdout as a string
// result.stderr - the stderr as a string
// result.exitCode - the process exit code as a number
```

By default, tinyexec does not throw on non‑zero exit codes. Check `result.exitCode` or pass `{throwOnError: true}`.

Output is returned exactly as produced; trailing newlines are not trimmed. If you need trimming, do it explicitly:

```ts
const clean = result.stdout.replace(/\r?\n$/, '');
```

You may also iterate over the lines of output via an async loop:

```ts
import {x} from 'tinyexec';

const proc = x('ls', ['-l']);

for await (const line of proc) {
  // line will be from stderr/stdout in the order you'd see it in a term
}
```

### Options

Options can be passed to have finer control over spawning of the process:

```ts
await x('ls', [], {
  timeout: 1000
});
```

The options object can have the following properties:

- `signal` - an `AbortSignal` to allow aborting of the execution
- `timeout` - time in milliseconds at which the process will be forcibly killed
- `persist` - if `true`, the process will continue after the host exits
- `stdin` - `string` or another `Result` that will be used as the input to the process
- `nodeOptions` - any valid options to node's underlying `spawn` function
- `throwOnError` - if true, non-zero exit codes will throw an error
- `nodePath` - if `false`, `node_modules/.bin` directories and the current node executable's directory will not be prepended to `PATH` (defaults to `true`)

### Passing a string to stdin

You can pass a string to `stdin`, which is useful for whitespace-sensitive values and for secrets that shouldn’t be exposed in shell history:

```ts
const result = await x('gh', ['auth', 'login', '--with-token'], {
  stdin: process.env.GITHUB_TOKEN
});

console.log(result.exitCode);
```

### Piping to another process

You can pipe a process to another via the `pipe` method:

```ts
const proc1 = x('ls', ['-l']);
const proc2 = proc1.pipe('grep', ['.js']);
const result = await proc2;

console.log(result.stdout);
```

`pipe` takes the same options as a regular execution. For example, you can
pass a timeout to the pipe call:

```ts
proc1.pipe('grep', ['.js'], {
  timeout: 2000
});
```

### Killing a process

You can kill the process via the `kill` method:

```ts
const proc = x('ls');

proc.kill();

// or with a signal
proc.kill('SIGHUP');
```

### Node modules/binaries

By default, node's available binaries from `node_modules` will be accessible
in your command.

For example, in a repo which has `eslint` installed:

```ts
await x('eslint', ['.']);
```

In this example, `eslint` will come from the locally installed `node_modules`.

If you'd rather not have `node_modules/.bin` (or the directory of the current
`node` executable) prepended to `PATH`, pass `nodePath: false`:

```ts
await x('eslint', ['.'], {nodePath: false});
```

### Using an abort signal

An abort signal can be passed to a process in order to abort it at a later
time. This will result in the process being killed and `aborted` being set
to `true`.

```ts
const aborter = new AbortController();
const proc = x('node', ['./foo.mjs'], {
  signal: aborter.signal
});

// elsewhere...
aborter.abort();

await proc;

proc.aborted; // true
proc.killed; // true
```

### Using with command strings

If you need to continue supporting commands as strings (e.g. "command arg0 arg1"),
you can use [args-tokenizer](https://github.com/TrySound/args-tokenizer),
a lightweight library for parsing shell command strings into an array.

```ts
import {x} from 'tinyexec';
import {tokenizeArgs} from 'args-tokenizer';

const commandString = 'echo "Hello, World!"';
const [command, ...args] = tokenizeArgs(commandString);
const result = await x(command, args);

result.stdout; // Hello, World!
```

### Synchronous

You can use `xSync` for synchronous (blocking) execution:

```ts
import {xSync} from 'tinyexec';

const result = xSync('ls', ['-l']);

// result.stdout - the stdout as a string
// result.stderr - the stderr as a string
// result.exitCode - the process exit code as a number
```

Like the async API, you can iterate over lines:

```ts
const result = xSync('ls', ['-l']);

for (const line of result) {
  // line will be from stdout then stderr
}
```

Since the synchronous API blocks the event loop, there are some features that are supported in the async API that the sync API does not support:

- `signal`
- `persist`
- `kill()` method
- `stdin` piping
- `pipe()` method

Other options like `timeout`, `throwOnError`, and `nodeOptions` work the same way.

## API

Calling `x(command[, args])` returns an awaitable `Result` which has the
following API methods and properties available:

### `pipe(command[, args[, options]])`

Pipes the current command to another. For example:

```ts
x('ls', ['-l'])
  .pipe('grep', ['js']);
```

The parameters are as follows:

- `command` - the command to execute (_without any arguments_)
- `args` - an array of arguments
- `options` - options object

### `process`

The underlying Node.js `ChildProcess`. tinyexec keeps the surface minimal and does not re‑expose every child_process method/event. Use `proc.process` for advanced access (streams, events, etc.).

```ts
const proc = x('node', ['./foo.mjs']);

proc.process?.stdout?.on('data', (chunk) => {
  // ...
});
proc.process?.once('close', (code) => {
  // ...
});
```

### `kill([signal])`

Kills the current process with the specified signal. By default, this will
use the `SIGTERM` signal.

For example:

```ts
const proc = x('ls');

proc.kill();
```

### `pid`

The current process ID. For example:

```ts
const proc = x('ls');

proc.pid; // number
```

### `aborted`

Whether the process has been aborted or not (via the `signal` originally
passed in the options object).

For example:

```ts
const proc = x('ls');

proc.aborted; // bool
```

### `killed`

Whether the process has been killed or not (e.g. via `kill()` or an abort
signal).

For example:

```ts
const proc = x('ls');

proc.killed; // bool
```

### `exitCode`

The exit code received when the process completed execution.

For example:

```ts
const proc = x('ls');

proc.exitCode; // number (e.g. 1)
```

## Comparison with other libraries

`tinyexec` aims to provide a lightweight layer on top of Node's own
`child_process` API.

Some clear benefits compared to other libraries are that `tinyexec` will be much lighter, have a much
smaller footprint and will have a less abstract interface (less "magic"). It
will also have equal security and cross-platform support to popular
alternatives.

There are various features other libraries include which we are unlikely
to ever implement, as they would prevent us from providing a lightweight layer.

For example, if you'd like write scripts rather than individual commands, and
prefer to use templating, we'd definitely recommend
[zx](https://github.com/google/zx). zx is a much higher level library which
does some of the same work `tinyexec` does but behind a template string
interface.

Similarly, libraries like `execa` will provide helpers for various things
like passing files as input to processes. We opt not to support features like
this since many of them are easy to do yourself (using Node's own APIs).
