百科.dev
全部条目在线工具AI 编程趋势榜开源项目技术资讯提交条目
登录
< 返回工具列表
T

tinyexec

> 编程语言
开源

一个围绕子进程的微小、更高级别的接口

373 stars0 点赞2 次浏览
访问官网GitHub

工具介绍

一个围绕子进程的微小、更高级别的接口

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

bash
$ npm i -S tinyexec

Usage

A process can be spawned and awaited like so:

typescript
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:

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

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

typescript
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:

typescript
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:

typescript
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:

typescript
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:

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

Killing a process

You can kill the process via the kill method:

typescript
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:

typescript
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:

typescript
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.

typescript
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, a lightweight library for parsing shell command strings into an array.

typescript
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:

typescript
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:

typescript
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:

typescript
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.).

typescript
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:

typescript
const proc = x('ls');

proc.kill();

pid

The current process ID. For example:

typescript
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:

typescript
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:

typescript
const proc = x('ls');

proc.killed; // bool

exitCode

The exit code received when the process completed execution.

For example:

typescript
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. 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).

Issues· 0 开放

查看全部 Issues在 GitHub 打开

暂无开放 Issues,或尚未同步最近议题。

> 标签

TypeScript

暂无评论,来聊聊你的看法吧

> 工具信息

发布日期2026年8月1日
最后更新2026年9月17日
分类编程语言
定价开源

> 相关工具

T
TypeScript
JavaScript 的超集,为前端与全栈提供静态类型
P
Python
通用编程语言,广泛用于 Web、数据与 AI
G
Go
Google 推出的简洁高效系统语言