Brunobkr/llama.cpp_AlgMor24_github

1# tinyexec 📟2 3> A minimal package for executing commands4 5This package was created to provide a minimal way of interacting with child6processes without having to manually deal with streams, piping, etc.7 8## Installing9 10```sh11$ npm i -S tinyexec12```13 14## Usage15 16A process can be spawned and awaited like so:17 18```ts19import {x} from 'tinyexec';20 21const result = await x('ls', ['-l']);22 23// result.stdout - the stdout as a string24// result.stderr - the stderr as a string25// result.exitCode - the process exit code as a number26```27 28By default, tinyexec does not throw on non‑zero exit codes. Check `result.exitCode` or pass `{throwOnError: true}`.29 30Output is returned exactly as produced; trailing newlines are not trimmed. If you need trimming, do it explicitly:31 32```ts33const clean = result.stdout.replace(/\r?\n$/, '');34```35 36You may also iterate over the lines of output via an async loop:37 38```ts39import {x} from 'tinyexec';40 41const proc = x('ls', ['-l']);42 43for await (const line of proc) {44  // line will be from stderr/stdout in the order you'd see it in a term45}46```47 48### Options49 50Options can be passed to have finer control over spawning of the process:51 52```ts53await x('ls', [], {54  timeout: 100055});56```57 58The options object can have the following properties:59 60- `signal` - an `AbortSignal` to allow aborting of the execution61- `timeout` - time in milliseconds at which the process will be forcibly killed62- `persist` - if `true`, the process will continue after the host exits63- `stdin` - `string` or another `Result` that will be used as the input to the process64- `nodeOptions` - any valid options to node's underlying `spawn` function65- `throwOnError` - if true, non-zero exit codes will throw an error66- `nodePath` - if `false`, `node_modules/.bin` directories and the current node executable's directory will not be prepended to `PATH` (defaults to `true`)67 68### Passing a string to stdin69 70You can pass a string to `stdin`, which is useful for whitespace-sensitive values and for secrets that shouldn’t be exposed in shell history:71 72```ts73const result = await x('gh', ['auth', 'login', '--with-token'], {74  stdin: process.env.GITHUB_TOKEN75});76 77console.log(result.exitCode);78```79 80### Piping to another process81 82You can pipe a process to another via the `pipe` method:83 84```ts85const proc1 = x('ls', ['-l']);86const proc2 = proc1.pipe('grep', ['.js']);87const result = await proc2;88 89console.log(result.stdout);90```91 92`pipe` takes the same options as a regular execution. For example, you can93pass a timeout to the pipe call:94 95```ts96proc1.pipe('grep', ['.js'], {97  timeout: 200098});99```100 101### Killing a process102 103You can kill the process via the `kill` method:104 105```ts106const proc = x('ls');107 108proc.kill();109 110// or with a signal111proc.kill('SIGHUP');112```113 114### Node modules/binaries115 116By default, node's available binaries from `node_modules` will be accessible117in your command.118 119For example, in a repo which has `eslint` installed:120 121```ts122await x('eslint', ['.']);123```124 125In this example, `eslint` will come from the locally installed `node_modules`.126 127If you'd rather not have `node_modules/.bin` (or the directory of the current128`node` executable) prepended to `PATH`, pass `nodePath: false`:129 130```ts131await x('eslint', ['.'], {nodePath: false});132```133 134### Using an abort signal135 136An abort signal can be passed to a process in order to abort it at a later137time. This will result in the process being killed and `aborted` being set138to `true`.139 140```ts141const aborter = new AbortController();142const proc = x('node', ['./foo.mjs'], {143  signal: aborter.signal144});145 146// elsewhere...147aborter.abort();148 149await proc;150 151proc.aborted; // true152proc.killed; // true153```154 155### Using with command strings156 157If you need to continue supporting commands as strings (e.g. "command arg0 arg1"),158you can use [args-tokenizer](https://github.com/TrySound/args-tokenizer),159a lightweight library for parsing shell command strings into an array.160 161```ts162import {x} from 'tinyexec';163import {tokenizeArgs} from 'args-tokenizer';164 165const commandString = 'echo "Hello, World!"';166const [command, ...args] = tokenizeArgs(commandString);167const result = await x(command, args);168 169result.stdout; // Hello, World!170```171 172### Synchronous173 174You can use `xSync` for synchronous (blocking) execution:175 176```ts177import {xSync} from 'tinyexec';178 179const result = xSync('ls', ['-l']);180 181// result.stdout - the stdout as a string182// result.stderr - the stderr as a string183// result.exitCode - the process exit code as a number184```185 186Like the async API, you can iterate over lines:187 188```ts189const result = xSync('ls', ['-l']);190 191for (const line of result) {192  // line will be from stdout then stderr193}194```195 196Since 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:197 198- `signal`199- `persist`200- `kill()` method201- `stdin` piping202- `pipe()` method203 204Other options like `timeout`, `throwOnError`, and `nodeOptions` work the same way.205 206## API207 208Calling `x(command[, args])` returns an awaitable `Result` which has the209following API methods and properties available:210 211### `pipe(command[, args[, options]])`212 213Pipes the current command to another. For example:214 215```ts216x('ls', ['-l'])217  .pipe('grep', ['js']);218```219 220The parameters are as follows:221 222- `command` - the command to execute (_without any arguments_)223- `args` - an array of arguments224- `options` - options object225 226### `process`227 228The 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.).229 230```ts231const proc = x('node', ['./foo.mjs']);232 233proc.process?.stdout?.on('data', (chunk) => {234  // ...235});236proc.process?.once('close', (code) => {237  // ...238});239```240 241### `kill([signal])`242 243Kills the current process with the specified signal. By default, this will244use the `SIGTERM` signal.245 246For example:247 248```ts249const proc = x('ls');250 251proc.kill();252```253 254### `pid`255 256The current process ID. For example:257 258```ts259const proc = x('ls');260 261proc.pid; // number262```263 264### `aborted`265 266Whether the process has been aborted or not (via the `signal` originally267passed in the options object).268 269For example:270 271```ts272const proc = x('ls');273 274proc.aborted; // bool275```276 277### `killed`278 279Whether the process has been killed or not (e.g. via `kill()` or an abort280signal).281 282For example:283 284```ts285const proc = x('ls');286 287proc.killed; // bool288```289 290### `exitCode`291 292The exit code received when the process completed execution.293 294For example:295 296```ts297const proc = x('ls');298 299proc.exitCode; // number (e.g. 1)300```301 302## Comparison with other libraries303 304`tinyexec` aims to provide a lightweight layer on top of Node's own305`child_process` API.306 307Some clear benefits compared to other libraries are that `tinyexec` will be much lighter, have a much308smaller footprint and will have a less abstract interface (less "magic"). It309will also have equal security and cross-platform support to popular310alternatives.311 312There are various features other libraries include which we are unlikely313to ever implement, as they would prevent us from providing a lightweight layer.314 315For example, if you'd like write scripts rather than individual commands, and316prefer to use templating, we'd definitely recommend317[zx](https://github.com/google/zx). zx is a much higher level library which318does some of the same work `tinyexec` does but behind a template string319interface.320 321Similarly, libraries like `execa` will provide helpers for various things322like passing files as input to processes. We opt not to support features like323this since many of them are easy to do yourself (using Node's own APIs).324