diff options
Diffstat (limited to 'vanilla/node_modules/tinyexec/README.md')
| -rw-r--r-- | vanilla/node_modules/tinyexec/README.md | 269 |
1 files changed, 0 insertions, 269 deletions
diff --git a/vanilla/node_modules/tinyexec/README.md b/vanilla/node_modules/tinyexec/README.md deleted file mode 100644 index 0bdace7..0000000 --- a/vanilla/node_modules/tinyexec/README.md +++ /dev/null @@ -1,269 +0,0 @@ -# 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 forceably killed -- `persist` - if `true`, the process will continue after the host exits -- `stdin` - another `Result` can be used as the input to this process -- `nodeOptions` - any valid options to node's underlying `spawn` function -- `throwOnError` - if true, non-zero exit codes will throw an error - -### 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`. - -### 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! -``` - -## 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). |