Utilities

This page documents miscellaneous utilities that are used by the dollar-shell package. In most cases they are used in the dollar-shell package itself and unlikely to be used elsewhere.

Usage

import {
  isWindows,
  cwd,
  currentExecPath,
  runFileArgs,
  shellEscape,
  currentShellPath,
  buildShellCommand
} from 'dollar-shell';

Docs

The TypeScript declaration:

declare const isWindows: boolean;

declare function cwd(): string;
declare function currentExecPath(): string;
declare const runFileArgs: string[];

interface ShellEscapeOptions {
  shellPath?: string;
}

declare function shellEscape(
  s: {toString(): string},
  options?: ShellEscapeOptions
): string;

declare function currentShellPath(): string;
declare function buildShellCommand(
  shell: string | undefined,
  args: string[] | undefined,
  command: string
): string[];

isWindows

This boolean constant is true if the current platform is Windows and false otherwise.

cwd()

This function returns the current working directory as a string in a platform-agnostic way.

currentExecPath()

This function returns the current executable path as a string in a platform-agnostic way. It returns the path of the current JS/TS runtime: Node, Deno or Bun. It can be used to run a JavaScript/TypeScript file.

runFileArgs

This array of strings contains the arguments passed to the current JS/TS interpreter by default. Current values:

Runtime	Value
Node	[]
Deno	['run']
Bun	['run']

Notes: usually Deno requires that permissions were explicitly granted. It is done with various flags, such as --allow-read, --allow-write, etc. While it is possible to specify -A or --allow-all on the command line, it is not recommended, so it is not included here. Make sure to check the documentation of the runtime you are using and specify proper flags.

shellEscape(value, options)

This function escapes the given value (converted to a string) for the current shell. It takes an object with an optional shellPath property that specifies the shell to use. If not specified, the current shell is used (see currentShellPath() below).

shellEscape() returns the escaped value as a string.

On Unix-like systems it escapes strings using single quotes.

On Windows if cmd.exe is detected, it escapes arguments using rules described in How-to: Escape Characters, Delimiters and Quotes at the Windows command line. Other shells are not escaped and should be escaped manually.

currentShellPath()

This function returns the path of the current shell executable as a string in a platform-agnostic way.

On Unix-like systems it returns the value of the SHELL environment variable. If it is not set, it returns /bin/sh or /system/bin/sh on Android.

On Windows it returns the value of the ComSpec environment variable. If it is not set, it returns cmd.exe.

buildShellCommand(shell, args, command)

This function builds a shell command from the given shell, args and command:

• shell is the path to the shell executable as a string or undefined. Defaults to currentShellPath().
• args is an array of strings or undefined. Defaults to shell-specific arguments described below.
• command is the shell command as a string.

args defaults to:

• ['-c'] on Unix-like systems.
• ['/d', '/s', '/c'] on Windows for cmd.exe.
• ['-c'] on Windows for pwsh.exe/powershell.exe.
  • If '-e' is passed instead, the command will be base64-encoded to side-step escape rules.

buildShellCommand() returns an array of strings that can be passed to the spawn() function.

raw(value)

This function is used by to bypass the default shell escaping rules and pass the value as is in template strings:

import {$sh, raw} from 'dollar-shell';

const $cmd = $sh({stdout: 'inherit', stderr: 'inherit'});

await $cmd`echo ${raw('"hello"')}`;

winCmdEscape(value)

This function is used by to escape the given value for Windows cmd.exe.

Internally Windows keeps arguments as a string and it is up to individual applications to interpret/parse it. In some cases the default shell escaping rules are not enough, so this function can be used to escape it differently:

import {$sh, winCmdEscape} from 'dollar-shell';

const $cmd = $sh({stdout: 'inherit', stderr: 'inherit'});

await $cmd`echo ${winCmdEscape('"hello"')}`;

Backgrounders:

• cmd.exe: How-to: Escape Characters, Delimiters and Quotes at the Windows command line
• PowerShell: How-to: Escape characters, Delimiters and Quotes