From c8b00a9b7ef5b07de225205941f233a1d3538cc3 Mon Sep 17 00:00:00 2001 From: Eugene Lazutkin Date: Mon, 2 Sep 2024 16:31:53 -0500 Subject: [PATCH] Added the read me. --- README.md | 200 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 200 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..14df339 --- /dev/null +++ b/README.md @@ -0,0 +1,200 @@ +# dollar-shell [![NPM version][npm-image]][npm-url] + +[npm-image]: https://img.shields.io/npm/v/dollar-shell.svg +[npm-url]: https://npmjs.org/package/dollar-shell + +`dollar-shell` is a micro-library for running shell commands and using them in streams with ease in Node, Deno, Bun. It is a tiny, simple, no dependency module. + +The idea is to run OS/shell commands and/or use them in stream pipelines as sources, sinks, +and transformation steps using [web streams](https://developer.mozilla.org/en-US/docs/Web/API/Streams_API). +It can be used together with [stream-chain](https://npmjs.org/package/stream-chain) and +[stream-json](https://npmjs.org/package/stream-json) to create efficient pipelines. +It helps using shell commands in utilities written in JavaScript/TypeScript running with +Node, Deno, or Bun. + +Available components: + +* `$` — spawn a process using a template string. + * `$.from` — spawn a process and use its `stdout` as a source stream. + * `$.to` — spawn a process and use its `stdin` as a sink stream. + * `$.io` AKA `$.through` — spawn a process and use it as + a transformation step in our pipeline. +* `$sh` — run a shell command using a template string. + * `$sh.from` — run a shell command and use its `stdout` as a source stream. + * `$sh.to` — run a shell command and use its `stdin` as a sink stream. + * `$sh.io` AKA `$sh.through` — run a shell command and use it as + a transformation step in our pipeline. +* Advanced components: + * `spawn()` — spawn a process with advanced ways to configure and control it. + * `$$` — spawn a process using a template string based on `spawn()`. + * `shell()` — a helper to spawn a shell command using a template string based on `spawn()`. + * Various helpers for them. + +## Introduction + +Run a command: + +```js +import $ from 'dollar-shell'; + +const result = await $`echo hello`; +console.log(result.code, result.signal, result.killed); +``` + +Run a shell command: + +```js +import {$sh} from 'dollar-shell'; + +const result = await $sh`ls .`; +console.log(result.code, result.signal, result.killed); +``` + +Run a shell command (an alias or a function) and show its result: + +```js +import {$sh} from 'dollar-shell'; + +// custom alias that prints `stdout` and runs an interactive shell +const $p = $sh({shellArgs: ['-ic'], stdout: 'inherit'}); + +const result = await $p`nvm ls`; +// prints to the console the result of the command +``` + +Run a pipeline: + +```js +import $ from 'dollar-shell'; +import chain from 'stream-chain'; +import lines from 'stream-chain/utils/lines.js'; + +chain([ + $.from`ls -l .`, + $.io`grep LICENSE`, + $.io`wc` + lines, + line => console.log(line) +]); +``` + +## Installation + +```bash +npm i --save dollar-shell +``` + +## Documentation + +Below is the documentation for the main components: `spawn()`, `$` and `$sh`. +Additional information can be found in the [wiki](https://github.com/uhop/dollar-shell/wiki). + +### `spawn()` + +The signature: `spawn(command, options)` + +Arguments: + +* `command` — an array of strings. The first element is the command to run. The rest are its arguments. +* `options` — an optional object with options to configure the process: + * `cwd` — the optional current working directory as a string. Defaults to `process.cwd()`. + * `env` — the optional environment variables as an object (key-value pairs). Defaults to `process.env`. + * `stdin` — the optional source stream. Defaults to `null`. + * `stdout` — the optional destination stream. Defaults to `null`. + * `stderr` — the optional destination stream. Defaults to `null`. + +`stdin`, `stdout` and `stderr` can be a string (one of `'inherit'`, `'ignore'`, `'pipe'` or `'piped'`) +or `null`. The latter is equivalent to `'ignore'`. `'piped'` is an alias of `'pipe'`: + +* `'inherit'` — inherit streams from the parent process. For output steams (`stdout` and `stderr`), +it means that they will be piped to the same target, e.g., the console. +* `'ignore'` — the stream is ignored. +* `'pipe'` — the stream is available for reading or writing. + +Returns a sub-process object with the following properties: + +* `command` — the command that was run as an array of strings. +* `options` — the options that were passed to `spawn()`. +* `exited` — a promise that resolves to the exit code of the process. It is used to wait for the process to exit. +* `finished` — a boolean. It is `true` when the process has finished and `false` otherwise. +* `killed` — a boolean. It is `true` when the process has been killed and `false` otherwise. +* `exitCode` — the exit code of the process as a number. It is `null` if the process hasn't exited yet. +* `signalCode` — the signal code of the process as a string. It is `null` if the process hasn't exited yet. +* `stdin` — the source stream of the process if `options.stdin` was `'pipe'`. It is `null` otherwise. +* `stdout` — the destination stream of the process if `options.stdout` was `'pipe'`. It is `null` otherwise. +* `stderr` — the destination stream of the process if `options.stderr` was `'pipe'`. It is `null` otherwise. +* `kill()` — kills the process. `killed` will be `true` as soon as the process has been killed. It can be used to pipe the input and output. See `spawn()`'s `stdin` and `stdout` above for more details. + +**Important:** all streams are exposed as [web streams](https://developer.mozilla.org/en-US/docs/Web/API/Streams_API). + +#### Examples + +```js +import {spawn} from 'dollar-shell'; + +const sp = spawn(['sleep', '5']) +await new Promise(resolve => setTimeout(resolve, 1000)); +sp.kill(); +await sp.exited; + +sp.finished === true; +sp.killed === true; +``` + +### `$$` + +The signatures: + +```js +const sp1 = $$`ls -l ${myFile}`; // runs a command ignoring streams + +const sp2 = $$(options)`ls -l .`; // runs a command ignoring streams + // with custom spawn options + +const $tag = $$(options); // returns a tag function +const sp3 = $tag`ls -l .`; // runs a command with custom spawn options +``` + +This function is effectively a helper for `spawn()`. It splits a strings into an array +of string arguments encoding inserted values if necessary. + +The second signature is used to run a command with custom spawn options. See `spawn()` above for more details. + +The first signature returns a sub-process object. See `spawn()` for more details. The second signature +returns a tag function that can be used as a template string. + +### `$` + +This function is similar to `$$` but it uses different default spawn options related to streams and +different (simpler) return values: + +* `$` — returns a promise that resolves to an object with the following properties: + * `code` — the exit code of the process. See `spawn()`'s `exitCode` above for more details. + * `signal` — the signal code of the process. See `spawn()`'s `signalCode` above for more details. + * `killed` — a boolean. It is `true` when the process has been killed and `false` otherwise. See `spawn()`'s `killed` above for more details. +* `$.from` — returns `stdout` of the process. It can be used to process the output. See `spawn()`'s `stdout` above for more details. +* `$.to` — returns `stdin` of the process. It can be used to pipe the input. See `spawn()`'s `stdin` above for more details. +* `$.io` AKA `$.through` — returns `stdin` and `stdout` of the process as a `{readable, writable}` pair. It can be used to create a pipeline where an external process can be used as a transform step. + +### `$sh` + +This function mirrors `$` but runs the command with the shell. It takes an options object that extends +the spawn options with the following properties: + +* `shellPath` — the path to the shell. On Unix-like systems it defaults to the value of +the `SHELL` environment variable if specified. Otherwise it is `'/bin/sh'` or `'/system/bin/sh'` on Android. +On Windows it defaults to the value of the `ComSpec` environment variable if specified. +Otherwise it is `cmd.exe`. +* `shellArgs` — an array of strings that are passed to the shell as arguments. +On Unix-like systems it defaults to `['-c']`. On Windows it defaults to `['/d', '/s', '/c']` for `cmd.exe` +or `['-e']` for `pwsh.exe` or `powershell.exe`. + +The rest is identical to `$`: `$sh`, `$sh.from`, `$sh.to` and `$sh.io`/`$sh.through`. + +## License + +BSD-3-Clause + +## Release History + +- 1.0.0 *The initial release.*