xsh

Some random NodeJS helper functions for shell execution

Install

npm install xsh --save-dev
Copy

Usage

xsh >= 1.0.0 is an ES module written in TypeScript, requiring node >= 22.18.

import xsh from "xsh";

xsh.exec("echo hello");
Copy

CJS consumers can still require it (node >= 22.18 require(esm)):

const xsh = require("xsh");

xsh.exec("echo hello");
Copy

API

See the full API reference for every function, option, and type.

Promise

You can set a custom Promise with:

import AveAzul from "aveazul";

xsh.Promise = AveAzul;
Copy

Or set to the native Promise with:

xsh.Promise = null;
Copy

mkCmd

xsh.mkCmd(["echo", "hello"]);
xsh.mkCmd("echo", "hello");
Copy

Both return the string "echo hello".

exec

xsh.exec(shellCommand, [options], [callback] );
Copy

Execute shellCommand asynchronously with Node.js child_process.exec. xsh.exec adds flexible command fragments, a callback/error shape, and a thenable result that also exposes the child process and its output streams.

Arguments

• shellCommand - can be combination of multiple strings and arrays. Array is joined with " " into strings. All final strings are joined with " ".

• options - optional options

  • If it's either true or false, it sets silent flag for output to console.
  • It can also be an object with silent and any option accepted by Node.js exec.
  • maxBuffer defaults to 20 MiB.
  • This can be the first, last, or second to last (if last is the callback) argument.

• callback - optional, if provided, it will be called as follows:

callback( code !== 0 ? new Error("...") : undefined, { stdout, stderr } )

error.output is set to { stdout, stderr}. error.code is set to code.

Returns

• With callback - The child object returned by exec

• Without callback - An object with following:

{
  then, catch, promise, child, stdout, stderr
}
Copy

Where:

• then - a wrapper function for calling the promise.then
• catch - a wrapper function for calling the promise.catch
• promise - rejects with the error or resolves with { stdout, stderr }
• child - the child from exec
• stdout and stderr - alias to child.stdout and child.stderr

exec Examples

• With Promise:

xsh.exec("echo hello").then(r => { console.log("result", r.stdout); });
Copy

• With options:

xsh.exec("pwd", {cwd: "/tmp"}).then(r => { console.log("result", r.stdout)})
Copy

• With callback:

xsh.exec("echo hello", (r) => {console.log("result", r.stdout)})
Copy

• shellCommand as a combination of strings and array of strings:

xsh.exec("echo", ["hello", "world"], {silent: false})
Copy

Would run shell command: echo hello world

envPath.addToFront

xsh.envPath.addToFront(path, [env]);
Copy

Add path to the front of process.env.PATH. If it already exists, then it is moved to the front.

If you don't want to operate on process.env you can pass in a second argument that's either an object or a string that's the path to change.

envPath.addToEnd

xsh.envPath.addToEnd(path, [env]);
Copy

Add path to the end of process.env.PATH. If it already exists, then it is moved to the end.

If you don't want to operate on process.env you can pass in a second argument that's either an object or a string that's the path to change.

envPath.add

xsh.envPath.add(path, [env]);
Copy

If path doesn't exist in process.env.PATH then it's added to the end.

If you don't want to operate on process.env you can pass in a second argument that's either an object or a string that's the path to change.

pushd / popd

xsh.pushd(dir);
// ...
xsh.popd();
Copy

pushd saves process.cwd() on a stack, then chdirs into dir, returning the new cwd. popd chdirs back to the directory most recently saved by pushd, returning it. popd throws if the stack is empty.