dollar-shell 1.1.0 → 1.1.1

package/README.md

@@ -1,7 +1,7 @@
 # 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
+[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 package with TypeScript typings.
 
@@ -14,21 +14,21 @@ 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.
+- `$` — 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
 
@@ -98,35 +98,35 @@ 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`.
+- `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.
+- `'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.
+- `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).
 
@@ -135,7 +135,7 @@ Returns a sub-process object with the following properties:
 ```js
 import {spawn} from 'dollar-shell';
 
-const sp = spawn(['sleep', '5'])
+const sp = spawn(['sleep', '5']);
 await new Promise(resolve => setTimeout(resolve, 1000));
 sp.kill();
 await sp.exited;
@@ -151,12 +151,12 @@ The same as `spawn()`, but it returns a tag function that can be used as a templ
 The signatures:
 
 ```js
-const sp1 = $$`ls -l ${myFile}`;  // runs a command the defaults
+const sp1 = $$`ls -l ${myFile}`; // runs a command the defaults
 
 const sp2 = $$(options)`ls -l .`; // runs a command with custom spawn options
 
-const $tag = $$(options);         // returns a tag function
-const sp3 = $tag`ls -l .`;        // runs a command 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 parses the template string
@@ -173,28 +173,28 @@ 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:
 
-* `$` — all streams are ignored. It 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` — 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.
-* `$.to` — 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.
-* `$.io` AKA `$.through` — 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.
+- `$` — all streams are ignored. It 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` — 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.
+- `$.to` — 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.
+- `$.io` AKA `$.through` — 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.
 
 ### `$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`.
+- `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`.
 
@@ -204,10 +204,11 @@ BSD-3-Clause
 
 ## Release History
 
-* 1.1.0 *Added `asDuplex` to the sub-process object.*
-* 1.0.5 *Updated dev dependencies.*
-* 1.0.4 *Fixed `raw()` for spawn commands.*
-* 1.0.3 *Added TSDoc comments, improved docs, fixed typos, added the missing copying of properties.*
-* 1.0.2 *Technical release: fixed references in the package file.*
-* 1.0.1 *Technical release: more tests, better documentation.*
-* 1.0.0 *The initial release.*
+- 1.1.1 _Updated dev dependencies._
+- 1.1.0 _Added `asDuplex` to the sub-process object._
+- 1.0.5 _Updated dev dependencies._
+- 1.0.4 _Fixed `raw()` for spawn commands._
+- 1.0.3 _Added TSDoc comments, improved docs, fixed typos, added the missing copying of properties._
+- 1.0.2 _Technical release: fixed references in the package file._
+- 1.0.1 _Technical release: more tests, better documentation._
+- 1.0.0 _The initial release._

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dollar-shell",
   "description": "Run shell commands and use them in streams with ease in Node, Deno, Bun. Tiny, simple, no dependency package.",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "type": "module",
   "main": "./src/index.js",
   "types": "./src/index.d.ts",
@@ -17,7 +17,9 @@
     "test:bun": "tape6-bun --flags FO",
     "test:deno": "deno run -A `tape6-runner main` --flags FO",
     "test:deno-original": "tape6-deno --flags FO",
-    "ts-check": "tsc --noEmit"
+    "ts-check": "tsc --noEmit",
+    "lint": "prettier --check .",
+    "lint:fix": "prettier --write ."
   },
   "files": [
     "/src",
@@ -46,8 +48,8 @@
   },
   "license": "BSD-3-Clause",
   "devDependencies": {
-    "tape-six": "^0.12.2",
-    "typescript": "^5.6.2"
+    "tape-six": "^1.4.1",
+    "typescript": "^5.9.3"
   },
   "tape6": {
     "tests": [

package/src/index.d.ts

@@ -148,7 +148,10 @@ export interface ShellEscapeOptions {
 /**
  * Escapes a value using the specified options.
  */
-export declare function shellEscape(value: {toString(): string}, options?: ShellEscapeOptions): string;
+export declare function shellEscape(
+  value: {toString(): string},
+  options?: ShellEscapeOptions
+): string;
 
 /**
  * The path of the current shell.
@@ -158,7 +161,11 @@ export declare function currentShellPath(): string;
 /**
  * Builds a shell command from a command using the `shell` and its `args`.
  */
-export declare function buildShellCommand(shell: string | undefined, args: string[] | undefined, command: string): string[];
+export declare function buildShellCommand(
+  shell: string | undefined,
+  args: string[] | undefined,
+  command: string
+): string[];
 
 /**
  * Backticks (tag) function.

package/src/index.js

@@ -59,7 +59,9 @@ $.through = $.io = throughProcess;
 
 // define shell functions
 
-export const shell = bqShell(shellEscape, (command, options) => spawn(buildShellCommand(options?.shellPath, options?.shellArgs, command), options));
+export const shell = bqShell(shellEscape, (command, options) =>
+  spawn(buildShellCommand(options?.shellPath, options?.shellArgs, command), options)
+);
 export {shell as sh};
 
 export const $sh = bqShell(shellEscape, (command, options) => {
@@ -68,17 +70,26 @@ export const $sh = bqShell(shellEscape, (command, options) => {
 });
 
 const fromShell = bqShell(shellEscape, (command, options) => {
-  const sp = spawn(buildShellCommand(options?.shellPath, options?.shellArgs, command), Object.assign({}, options, {stdout: 'pipe'}));
+  const sp = spawn(
+    buildShellCommand(options?.shellPath, options?.shellArgs, command),
+    Object.assign({}, options, {stdout: 'pipe'})
+  );
   return sp.stdout;
 });
 
 const toShell = bqShell(shellEscape, (command, options) => {
-  const sp = spawn(buildShellCommand(options?.shellPath, options?.shellArgs, command), Object.assign({}, options, {stdin: 'pipe'}));
+  const sp = spawn(
+    buildShellCommand(options?.shellPath, options?.shellArgs, command),
+    Object.assign({}, options, {stdin: 'pipe'})
+  );
   return sp.stdin;
 });
 
 const throughShell = bqShell(shellEscape, (command, options) => {
-  const sp = spawn(buildShellCommand(options?.shellPath, options?.shellArgs, command), Object.assign({}, options, {stdin: 'pipe', stdout: 'pipe'}));
+  const sp = spawn(
+    buildShellCommand(options?.shellPath, options?.shellArgs, command),
+    Object.assign({}, options, {stdin: 'pipe', stdout: 'pipe'})
+  );
   return sp.asDuplex;
 });
 

package/src/shell/unix.js

@@ -7,4 +7,8 @@ export const shellEscape = s => "'" + String(s).replace(/'/g, "'\\''") + "'";
 export const currentShellPath = () => getEnv('SHELL') || (isAndroid ? '/system/bin/sh' : '/bin/sh');
 
 // derived from https://github.com/nodejs/node/blob/43f699d4d2799cfc17cbcad5770e1889075d5dbe/lib/child_process.js#L620
-export const buildShellCommand = (shell, args, command) => [shell || currentShellPath(), ...(args || ['-c']), command];
+export const buildShellCommand = (shell, args, command) => [
+  shell || currentShellPath(),
+  ...(args || ['-c']),
+  command
+];

package/src/shell/windows.js

@@ -58,7 +58,8 @@ export const shellEscape = (s, options, isFirst) => {
       '"';
     return isFirst ? result.replace(/(0xFF)|([\W])|(\w+)/g, escapeCmd) : result;
   }
-  if (isPwsh(shell)) return s.replace(/([\t\r\n\f\x00\x1B\x07\x08\x0B\"])|([\W])|(\w+)/g, escapePowerShell);
+  if (isPwsh(shell))
+    return s.replace(/([\t\r\n\f\x00\x1B\x07\x08\x0B\"])|([\W])|(\w+)/g, escapePowerShell);
   return s;
 };
 

package/src/spawn/deno.js

@@ -26,7 +26,11 @@ class Subprocess {
 
     this.controller = new AbortController();
 
-    const spawnOptions = {signal: this.controller.signal, args: command.slice(1), windowsRawArguments: true};
+    const spawnOptions = {
+      signal: this.controller.signal,
+      args: command.slice(1),
+      windowsRawArguments: true
+    };
     options.cwd && (spawnOptions.cwd = options.cwd);
     options.env && (spawnOptions.env = options.env);
 

package/src/utils.js

@@ -16,7 +16,8 @@ if (typeof Deno !== 'undefined') {
 }
 export {getEnv, isWindows, isAndroid};
 
-export const verifyStrings = strings => Array.isArray(strings) && strings.every(s => typeof s === 'string');
+export const verifyStrings = strings =>
+  Array.isArray(strings) && strings.every(s => typeof s === 'string');
 
 export const toBase64 = s => {
   // const buf = new TextEncoder().encode(s),
@@ -34,4 +35,6 @@ export const raw = value => ({[rawValueSymbol]: value});
 export const isRawValue = value => value && typeof value === 'object' && rawValueSymbol in value;
 export const getRawValue = value => value[rawValueSymbol];
 
-export const winCmdEscape = isWindows ? value => raw(String(value).replace(/./g, '^$&')) : value => String(value);
+export const winCmdEscape = isWindows
+  ? value => raw(String(value).replace(/./g, '^$&'))
+  : value => String(value);