{"id":15547299,"url":"https://github.com/uhop/dollar-shell","last_synced_at":"2025-04-23T18:23:33.767Z","repository":{"id":253588892,"uuid":"843947797","full_name":"uhop/dollar-shell","owner":"uhop","description":"Run shell commands with ease in Node, Deno, Bun. Tiny, simple, no dependency package with TypeScript typings.","archived":false,"fork":false,"pushed_at":"2024-11-25T21:51:57.000Z","size":97,"stargazers_count":2,"open_issues_count":2,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-21T06:09:26.972Z","etag":null,"topics":["dollar","shell","spawn","stream"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/uhop.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"uhop","buy_me_a_coffee":"uhop"}},"created_at":"2024-08-17T22:47:47.000Z","updated_at":"2024-11-05T14:22:28.000Z","dependencies_parsed_at":"2025-03-06T08:43:43.150Z","dependency_job_id":null,"html_url":"https://github.com/uhop/dollar-shell","commit_stats":{"total_commits":91,"total_committers":2,"mean_commits":45.5,"dds":0.01098901098901095,"last_synced_commit":"496c452bd08553cba674b5439e75f92528e8c9e9"},"previous_names":["uhop/dollar-shell"],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uhop%2Fdollar-shell","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uhop%2Fdollar-shell/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uhop%2Fdollar-shell/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uhop%2Fdollar-shell/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/uhop","download_url":"https://codeload.github.com/uhop/dollar-shell/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250488304,"owners_count":21438759,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dollar","shell","spawn","stream"],"created_at":"2024-10-02T13:08:35.545Z","updated_at":"2025-04-23T18:23:33.741Z","avatar_url":"https://github.com/uhop.png","language":"JavaScript","funding_links":["https://github.com/sponsors/uhop","https://buymeacoffee.com/uhop"],"categories":[],"sub_categories":[],"readme":"# dollar-shell [![NPM version][npm-image]][npm-url]\n\n[npm-image]:      https://img.shields.io/npm/v/dollar-shell.svg\n[npm-url]:        https://npmjs.org/package/dollar-shell\n\n`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 package with TypeScript typings.\n\nThe idea is to run OS/shell commands and/or use them in stream pipelines as sources, sinks,\nand transformation steps using [web streams](https://developer.mozilla.org/en-US/docs/Web/API/Streams_API).\nIt can be used together with [stream-chain](https://npmjs.org/package/stream-chain) and\n[stream-json](https://npmjs.org/package/stream-json) to create efficient pipelines.\nIt helps using shell commands in utilities written in JavaScript/TypeScript running with\nNode, Deno, or Bun.\n\nAvailable components:\n\n* `$` \u0026mdash; spawn a process using a template string.\n  * `$.from` \u0026mdash; spawn a process and use its `stdout` as a source stream.\n  * `$.to` \u0026mdash; spawn a process and use its `stdin` as a sink stream.\n  * `$.io` AKA `$.through` \u0026mdash; spawn a process and use it as\n  a transformation step in our pipeline.\n* `$sh` \u0026mdash; run a shell command using a template string.\n  * `$sh.from` \u0026mdash; run a shell command and use its `stdout` as a source stream.\n  * `$sh.to` \u0026mdash; run a shell command and use its `stdin` as a sink stream.\n  * `$sh.io` AKA `$sh.through` \u0026mdash; run a shell command and use it as\n  a transformation step in our pipeline.\n* Advanced components:\n  * `spawn()` \u0026mdash; spawn a process with advanced ways to configure and control it.\n  * `$$` \u0026mdash; spawn a process using a template string based on `spawn()`.\n  * `shell()` \u0026mdash; a helper to spawn a shell command using a template string based on `spawn()`.\n  * Various helpers for them.\n\n## Introduction\n\nRun a command:\n\n```js\nimport $ from 'dollar-shell';\n\nconst result = await $`echo hello`;\nconsole.log(result.code, result.signal, result.killed);\n```\n\nRun a shell command:\n\n```js\nimport {$sh} from 'dollar-shell';\n\nconst result = await $sh`ls .`;\nconsole.log(result.code, result.signal, result.killed);\n```\n\nRun a shell command (an alias or a function) and show its result:\n\n```js\nimport {$sh} from 'dollar-shell';\n\n// custom alias that prints `stdout` and runs an interactive shell\nconst $p = $sh({shellArgs: ['-ic'], stdout: 'inherit'});\n\nconst result = await $p`nvm ls`;\n// prints to the console the result of the command\n```\n\nRun a pipeline:\n\n```js\nimport $ from 'dollar-shell';\nimport chain from 'stream-chain';\nimport lines from 'stream-chain/utils/lines.js';\n\nchain([\n  $.from`ls -l .`,\n  $.io`grep LICENSE`,\n  $.io`wc`,\n  new TextDecoderStream(),\n  lines(),\n  line =\u003e console.log(line)\n]);\n```\n\n## Installation\n\n```bash\nnpm i --save dollar-shell\n```\n\n## Documentation\n\nBelow is the documentation for the main components: `spawn()`, `$$`, `$` and `$sh`.\nAdditional information can be found in the [wiki](https://github.com/uhop/dollar-shell/wiki).\n\n### `spawn()`\n\nSpawn a process with advanced ways to configure and control it.\n\nThe signature: `spawn(command, options)`\n\nArguments:\n\n* `command` \u0026mdash; an array of strings. The first element is the command to run. The rest are its arguments.\n* `options` \u0026mdash; an optional object with options to configure the process:\n  * `cwd` \u0026mdash; the optional current working directory as a string. Defaults to `process.cwd()`.\n  * `env` \u0026mdash; the optional environment variables as an object (key-value pairs). Defaults to `process.env`.\n  * `stdin` \u0026mdash; the optional source stream. Defaults to `null`.\n  * `stdout` \u0026mdash; the optional destination stream. Defaults to `null`.\n  * `stderr` \u0026mdash; the optional destination stream. Defaults to `null`.\n\n`stdin`, `stdout` and `stderr` can be a string (one of `'inherit'`, `'ignore'`, `'pipe'` or `'piped'`)\nor `null`. The latter is equivalent to `'ignore'`. `'piped'` is an alias of `'pipe'`:\n\n* `'inherit'` \u0026mdash; inherit streams from the parent process. For output steams (`stdout` and `stderr`),\nit means that they will be piped to the same target, e.g., the console.\n* `'ignore'` \u0026mdash; the stream is ignored.\n* `'pipe'` \u0026mdash; the stream is available for reading or writing.\n\nReturns a sub-process object with the following properties:\n\n* `command` \u0026mdash; the command that was run as an array of strings.\n* `options` \u0026mdash; the options that were passed to `spawn()`.\n* `exited` \u0026mdash; a promise that resolves to the exit code of the process. It is used to wait for the process to exit.\n* `finished` \u0026mdash; a boolean. It is `true` when the process has finished and `false` otherwise.\n* `killed` \u0026mdash; a boolean. It is `true` when the process has been killed and `false` otherwise.\n* `exitCode` \u0026mdash; the exit code of the process as a number. It is `null` if the process hasn't exited yet.\n* `signalCode` \u0026mdash; the signal code of the process as a string. It is `null` if the process hasn't exited yet.\n* `stdin` \u0026mdash; the source stream of the process if `options.stdin` was `'pipe'`. It is `null` otherwise.\n* `stdout` \u0026mdash; the destination stream of the process if `options.stdout` was `'pipe'`. It is `null` otherwise.\n* `stderr` \u0026mdash; the destination stream of the process if `options.stderr` was `'pipe'`. It is `null` otherwise.\n* `kill()` \u0026mdash; 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.\n\n**Important:** all streams are exposed as [web streams](https://developer.mozilla.org/en-US/docs/Web/API/Streams_API).\n\n#### Examples\n\n```js\nimport {spawn} from 'dollar-shell';\n\nconst sp = spawn(['sleep', '5'])\nawait new Promise(resolve =\u003e setTimeout(resolve, 1000));\nsp.kill();\nawait sp.exited;\n\nsp.finished === true;\nsp.killed === true;\n```\n\n### `$$`\n\nThe same as `spawn()`, but it returns a tag function that can be used as a template string.\n\nThe signatures:\n\n```js\nconst sp1 = $$`ls -l ${myFile}`;  // runs a command the defaults\n\nconst sp2 = $$(options)`ls -l .`; // runs a command with custom spawn options\n\nconst $tag = $$(options);         // returns a tag function\nconst sp3 = $tag`ls -l .`;        // runs a command with custom spawn options\n```\n\nThis function is effectively a helper for `spawn()`. It parses the template string\ninto an array of string arguments. Each inserted value is included\nas a separate argument if it was surrounded by whitespaces.\n\nThe second signature is used to run a command with custom spawn options. See `spawn()` above for more details.\n\nThe first signature returns a sub-process object. See `spawn()` for more details. The second signature\nreturns a tag function that can be used as a template string.\n\n### `$`\n\nThis function is similar to `$$` but it uses different default spawn options related to streams and\ndifferent (simpler) return values:\n\n* `$` \u0026mdash; all streams are ignored. It returns a promise that resolves to an object with the following properties:\n  * `code` \u0026mdash; the exit code of the process. See `spawn()`'s `exitCode` above for more details.\n  * `signal` \u0026mdash; the signal code of the process. See `spawn()`'s `signalCode` above for more details.\n  * `killed` \u0026mdash; a boolean. It is `true` when the process has been killed and `false` otherwise. See `spawn()`'s `killed` above for more details.\n* `$.from` \u0026mdash; sets `stdout` to `pipe` and returns `stdout` of the process. It can be used to process the output. See `spawn()`'s `stdout` above for more details.\n* `$.to` \u0026mdash; sets `stdin` to `pipe` and returns `stdin` of the process. It can be used to pipe the input. See `spawn()`'s `stdin` above for more details.\n* `$.io` AKA `$.through` \u0026mdash; sets `stdin` and `stdout` to `pipe` and 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.\n\n### `$sh`\n\nThis function mirrors `$` but runs the command with the shell. It takes an options object that extends\nthe spawn options with the following properties:\n\n* `shellPath` \u0026mdash; the path to the shell.\n  * On Unix-like systems it defaults to the value of\nthe `SHELL` environment variable if specified. Otherwise it is `'/bin/sh'` or `'/system/bin/sh'` on Android.\n  * On Windows it defaults to the value of the `ComSpec` environment variable if specified.\nOtherwise it is `cmd.exe`.\n* `shellArgs` \u0026mdash; an array of strings that are passed to the shell as arguments.\n  * On Unix-like systems it defaults to `['-c']`.\n  * On Windows it defaults to `['/d', '/s', '/c']` for `cmd.exe`\nor `['-e']` for `pwsh.exe` or `powershell.exe`.\n\nThe rest is identical to `$`: `$sh`, `$sh.from`, `$sh.to` and `$sh.io`/`$sh.through`.\n\n## License\n\nBSD-3-Clause\n\n## Release History\n\n* 1.1.0 *Added `asDuplex` to the sub-process object.*\n* 1.0.5 *Updated dev dependencies.*\n* 1.0.4 *Fixed `raw()` for spawn commands.*\n* 1.0.3 *Added TSDoc comments, improved docs, fixed typos, added the missing copying of properties.*\n* 1.0.2 *Technical release: fixed references in the package file.*\n* 1.0.1 *Technical release: more tests, better documentation.*\n* 1.0.0 *The initial release.*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuhop%2Fdollar-shell","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fuhop%2Fdollar-shell","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuhop%2Fdollar-shell/lists"}