dax
Cross platform shell tools for Deno inspired by zx.
Differences with zx
- Cross platform shell.
- Makes more code work on Windows.
- Allows exporting the shellâs environment to the current process.
- Uses deno_task_shellâs parser.
- Minimal globals or global configuration.
- Only a default instance of
$
, but itâs not mandatory to use this.
- Only a default instance of
- No custom CLI.
- Good for application code in addition to use as a shell script replacement.
- Named after my cat.
Executing commands
import $ from "https://deno.land/x/dax/mod.ts";
// run a command
await $`echo 5`; // outputs: 5
// more complex example outputting 1 to stdout and 2 to stderr
await $`echo 1 && deno eval 'console.error(2);'`;
// parallel
await Promise.all([
$`sleep 1 ; echo 1`,
$`sleep 2 ; echo 2`,
$`sleep 3 ; echo 3`,
]);
Getting output
Get the stdout of a command (makes stdout âquietâ):
const result = await $`echo 1`.text();
console.log(result); // 1
Get the result of stdout as json (makes stdout âquietâ):
const result = await $`echo '{ "prop": 5 }'`.json();
console.log(result.prop); // 5
Get the result of stdout as bytes (makes stdout âquietâ):
const result = await $`echo 'test'`.bytes();
console.log(result); // Uint8Array(5) [ 116, 101, 115, 116, 10 ]
Get the result of stdout as a list of lines (makes stdout âquietâ):
const result = await $`echo 1 && echo 2`.lines();
console.log(result); // ["1", "2"]
Working with a lower level result that provides more details:
const result = await $`deno eval 'console.log(1); console.error(2);'`
.stdout("piped")
.stderr("piped");
console.log(result.code); // 0
console.log(result.stdoutBytes); // Uint8Array(2) [ 49, 10 ]
console.log(result.stdout); // 1\n
console.log(result.stderr); // 5\n
const output = await $`echo '{ "test": 5 }'`.stdout("piped");
console.log(output.stdoutJson);
Getting the combined output:
const result = await $`deno eval 'console.log(1); console.error(2); console.log(3);'`
.captureCombined();
console.log(result.combined); // 1\n2\n3\n
Providing arguments to a command
Use an expression in a template literal to provide a single argument to a command:
const dirName = "some_dir";
await $`mkdir ${dirName}`; // executes as: mkdir some_dir
Arguments are escaped so strings with spaces get escaped and remain as a single argument:
const dirName = "Dir with spaces";
await $`mkdir ${dirName}`; // executes as: mkdir 'Dir with spaces'
Alternatively, provide an array for multiple arguments:
const dirNames = ["some_dir", "other dir"];
await $`mkdir ${dirNames}`; // executes as: mkdir some_dir 'other dir'
If you do not want to escape arguments in a template literal, you can opt out completely, by using $.raw
:
const args = "arg1 arg2 arg3";
await $.raw`echo ${args}`; // executes as: echo arg1 arg2 arg3
Providing stdout of one command to another is possible as follows:
// Note: This will read trim the last newline of the other command's stdout
const result = await $`echo 1`.stdout("piped"); // need to set stdout as piped for this to work
const finalText = await $`echo ${result}`.text();
console.log(finalText); // 1
âŚthough itâs probably more straightforward to just collect the output text of a command and provide that:
const result = await $`echo 1`.text();
const finalText = await $`echo ${result}`.text();
console.log(finalText); // 1
Providing stdin
await $`command`.stdin("inherit"); // default
await $`command`.stdin("null");
await $`command`.stdin(new Uint8Array[1, 2, 3, 4]());
await $`command`.stdin(someReaderOrReadableStream);
await $`command`.stdinText("some value");
Streaming API
Awaiting a command will get the CommandResult
, but calling .spawn()
on a command without await
will return a CommandChild
. This has some methods on it to get web streams of stdout and stderr of the executing command if the corresponding pipe is set to "piped"
. These can then be sent wherever youâd like, such as to the body of a $.request
or another commandâs stdin.
For example, the following will output 1, wait 2 seconds, then output 2 to the current processâ stderr:
const child = $`echo 1 && sleep 1 && echo 2`.stdout("piped").spawn();
await $`deno eval 'await Deno.stdin.readable.pipeTo(Deno.stderr.writable);'`
.stdin(child.stdout());
Setting environment variables
Done via the .env(...)
method:
// outputs: 1 2 3 4
await $`echo $var1 $var2 $var3 $var4`
.env("var1", "1")
.env("var2", "2")
// or use object syntax
.env({
var3: "3",
var4: "4",
});
Setting cwd for command
Use .cwd("new_cwd_goes_here")
:
// outputs that it's in the someDir directory
await $`deno eval 'console.log(Deno.cwd());'`.cwd("./someDir");
Silencing a command
Makes a command not output anything to stdout and stderr.
await $`echo 5`.quiet();
await $`echo 5`.quiet("stdout"); // or just stdout
await $`echo 5`.quiet("stderr"); // or just stderr
Output a command before executing it
The following code:
const text = "example";
await $`echo ${text}`.printCommand();
Outputs the following (with the command text in blue):
> echo example
example
$
Enabling on a Like with any default in Dax, you can build a new $
turning on this option so this will occur with all commands (see Custom $
).
That said, since enabling this has a low change of breaking downstream code, you can mutate a $
to enable it by calling $.setPrintCommand(true);
.
$.setPrintCommand(true);
const text = "example";
await $`echo ${text}`; // will output `> echo example` before running the command
Timeout a command
This will exit with code 124.
// timeout a command after a specified time
await $`echo 1 && sleep 100 && echo 2`.timeout("1s");
Aborting a command
Instead of awaiting the template literal, you can get a command child by calling the .spawn()
method:
const child = $`echo 1 && sleep 100 && echo 2`.spawn();
// abort the child after 1s
await $.sleep("1s");
child.abort();
await child; // Error: Aborted with exit code: 124
Exporting the environment of the shell to JavaScript
When executing commands in the shell, the environment will be contained to the shell and not exported to the current process. For example:
await $`cd src && export MY_VALUE=5`;
// will output nothing
await $`echo $MY_VALUE`;
// will both NOT output it's in the src dir
await $`echo $PWD`;
console.log(Deno.cwd());
You can change that by using exportEnv()
on the command:
await $`cd src && export MY_VALUE=5`.exportEnv();
// will output "5"
await $`echo $MY_VALUE`;
// will both output it's in the src dir
await $`echo $PWD`;
console.log(Deno.cwd());
Logging
Dax comes with some helper functions for logging:
// logs with potential indentation
// Note: everything is logged over stderr by default
$.log("Hello!");
// log with the first word as bold green
$.logStep("Fetching data from server...");
// or force multiple words to be green by using two arguments
$.logStep("Setting up", "local directory...");
// similar to $.logStep, but with red
$.logError("Error Some error message.");
// similar to $.logStep, but with yellow
$.logWarn("Warning Some warning message.");
// logs out text in gray
$.logLight("Some unimportant message.");
You may wish to indent some text when logging, use $.logGroup
to do so:
// log indented within (handles de-indenting when an error is thrown)
await $.logGroup(async () => {
$.log("This will be indented.");
await $.logGroup(async () => {
$.log("This will indented even more.");
// do maybe async stuff here
});
});
// or use $.logGroup with $.logGroupEnd
$.logGroup();
$.log("Indented 1");
$.logGroup("Level 2");
$.log("Indented 2");
$.logGroupEnd();
$.logGroupEnd();
As mentioned previously, Dax logs to stderr for everything by default. This may not be desired, so you can change the current behaviour of a $
object by setting a logger for either âinfoâ, âwarnâ, or âerrorâ.
// Set the loggers. For example, log everything
// on stdout instead of stderr
$.setInfoLogger(console.log);
$.setWarnLogger(console.log);
$.setErrorLogger(console.log);
// or a more advanced scenario
$.setInfoLogger((...args: any[]) => {
console.error(...args);
// write args to a file here...
};)
Selections / Prompts
There are a few selections/prompts that can be used.
By default, all prompts will exit the process if the user cancelled their selection via ctrl+c. If you donât want this behaviour, then use the maybe
variant functions.
$.prompt
/ $.maybePrompt
Gets a string value from the user:
const name = await $.prompt("What's your name?");
// or provide an object, which has some more options
const name = await $.prompt({
message: "What's your name?",
default: "Dax", // prefilled value
noClear: true, // don't clear the text on result
});
// or hybrid
const name = await $.prompt("What's your name?", {
default: "Dax",
});
// with a character mask (for password / secret input)
const password = await $.prompt("What's your password?", {
mask: true,
});
Again, you can use $.maybePrompt("What's your name?")
to get a nullable return value for when the user presses ctrl+c
.
$.confirm
/ $.maybeConfirm
Gets the answer to a yes or no question:
const result = await $.confirm("Would you like to continue?");
// or with more options
const result = await $.confirm({
message: "Would you like to continue?",
default: true,
});
// or hybrid
const result = await $.confirm("Would you like to continue?", {
default: false,
noClear: true,
});
$.select
/ $.maybeSelect
Gets a single value:
const index = await $.select({
message: "What's your favourite colour?",
options: [
"Red",
"Green",
"Blue",
],
});
$.multiSelect
/ $.maybeMultiSelect
Gets multiple or no values:
const indexes = await $.multiSelect({
message: "Which of the following are days of the week?",
options: [
"Monday",
{
text: "Wednesday",
selected: true, // defaults to false
},
"Blue",
],
});
Progress indicator
You may wish to indicate that some progress is occurring.
Indeterminate
const pb = $.progress("Updating Database");
await pb.with(async () => {
// do some work here
});
The .with(async () => { ... })
API will hide the progress bar when the action completes including hiding it when an error is thrown. If you donât want to bother with this though you can just call pb.finish()
instead.
const pb = $.progress("Updating Database");
try {
// do some work here
} finally {
pb.finish();
}
Determinate
Set a length to be determinate, which will display a progress bar:
const items = [/*...*/];
const pb = $.progress("Processing Items", {
length: items.length,
});
await pb.with(async () => {
for (const item of items) {
await doWork(item);
pb.increment(); // or use pb.position(val)
}
});
Synchronous work
The progress bars are updated on an interval (via setInterval
) to prevent rendering more than necessary. If you are doing a lot of synchronous work the progress bars wonât update. Due to this, you can force a render where you think it would be appropriate by using the .forceRender()
method:
const pb = $.progress("Processing Items", {
length: items.length,
});
pb.with(() => {
for (const item of items) {
doWork(item);
pb.increment();
pb.forceRender();
}
});
Path API
The path API offers an immutable PathRef
class, which is a similar concept to Rustâs PathBuf
struct.
// create a `PathRef`
let srcDir = $.path("src");
// get information about the path
srcDir.isDir(); // false
// do actions on it
srcDir.mkdir();
srcDir.isDir(); // true
srcDir.isRelative(); // true
srcDir = srcDir.resolve(); // resolve the path to be absolute
srcDir.isRelative(); // false
srcDir.isAbsolute(); // true
// join to get other paths and do actions on them
const textFile = srcDir.join("subDir").join("file.txt");
textFile.writeTextSync("some text");
console.log(textFile.readTextSync()); // "some text"
const jsonFile = srcDir.join("otherDir", "file.json");
console.log(jsonFile.parentOrThrow()); // path for otherDir
jsonFile.writeJsonSync({
someValue: 5,
});
console.log(jsonFile.readJsonSync().someValue); // 5
It also works to provide these paths to commands:
const srcDir = $.path("src").resolve();
await $`echo ${srcDir}`;
PathRef
s can be created in the following ways:
const pathRelative = $.path("./relative");
const pathAbsolute = $.path("/tmp");
const pathFileUrl = $.path(new URL("file:///tmp")); // converts to /tmp
const pathStringFileUrl = $.path("file:///tmp"); // converts to /tmp
const pathImportMeta = $.path(import.meta); // the path for the current module
There are a lot of helper methods here, so check the documentation on PathRef for more details.
Helper functions
Changing the current working directory of the current process:
$.cd("someDir");
console.log(Deno.cwd()); // will be in someDir directory
// or change the directory of the process to be in
// the directory of the current script
$.cd(import.meta);
Sleeping asynchronously for a specified amount of time:
await $.sleep(100); // ms
await $.sleep("1.5s");
await $.sleep("1m30s");
Getting path to an executable based on a command name:
console.log(await $.which("deno")); // outputs the path to deno executable
Check if a command exists:
console.log(await $.commandExists("deno"));
console.log($.commandExistsSync("deno"));
Attempting to do an action until it succeeds or hits the maximum number of retries:
await $.withRetries({
count: 5,
// you may also specify an iterator here which is useful for exponential backoff
delay: "5s",
action: async () => {
await $`cargo publish`;
},
});
âDedentâ or remove leading whitespace from a string:
console.log($.dedent`
This line will appear without any indentation.
* This list will appear with 2 spaces more than previous line.
* As will this line.
Empty lines (like the one above) will not affect the common indentation.
`);
This line will appear without any indentation.
* This list will appear with 2 spaces more than previous line.
* As will this line.
Empty lines (like the one above) will not affect the common indentation.
Re-export of deno_stdâs path (though you might want to just use the path API described above):
$.path.basename("./deno/std/path/mod.ts"); // mod.ts
Re-export of deno_stdâs fs:
for await (const file of $.fs.expandGlob("**/*.ts")) {
console.log(file);
}
Remove ansi escape sequences from a string:
$.stripAnsi("\u001B[4mHello World\u001B[0m");
//=> 'Hello World'
Making requests
Dax ships with a slightly less verbose wrapper around fetch
that will throw by default on non-2xx
status codes (this is configurable per status code).
Download a file as JSON:
const data = await $.request("https://plugins.dprint.dev/info.json").json();
console.log(data.plugins);
Or as text:
const text = await $.request("https://example.com").text();
Or get the long form:
const response = await $.request("https://plugins.dprint.dev/info.json");
console.log(response.code);
console.log(await response.json());
See the documentation on RequestBuilder
for more details. It should be as flexible as fetch
, but uses a builder API (ex. set headers via .header(...)
).
Showing progress
You can have downloads show a progress bar by using the .showProgress()
builder method:
const url = "https://dl.deno.land/release/v1.29.1/deno-x86_64-unknown-linux-gnu.zip";
const downloadPath = await $.request(url)
.showProgress()
.pipeToPath();
Shell
The shell is cross platform and uses the parser from deno_task_shell.
Sequential lists:
// result will contain the directory in someDir
const result = await $`cd someDir ; deno eval 'console.log(Deno.cwd())'`;
Boolean lists:
// outputs to stdout with 1\n\2n
await $`echo 1 && echo 2`;
// outputs to stdout with 1\n
await $`echo 1 || echo 2`;
Setting env var for command in the shell (generally you can just use .env(...)
though):
// result will contain the directory in someDir
const result = await $`test=123 deno eval 'console.log(Deno.env.get('test'))'`;
console.log(result.stdout); // 123
Shell variables (these arenât exported):
// the 'test' variable WON'T be exported to the sub processes, so
// that will print a blank line, but it will be used in the final echo command
await $`test=123 && deno eval 'console.log(Deno.env.get('test'))' && echo $test`;
Env variables (these are exported):
// the 'test' variable WILL be exported to the sub processes and
// it will be used in the final echo command
await $`export test=123 && deno eval 'console.log(Deno.env.get('test'))' && echo $test`;
Variable substitution:
const result = await $`echo $TEST`.env("TEST", "123").text();
console.log(result); // 123
Custom cross platform shell commands
Currently implemented (though not every option is supported):
cd
- Change directory command.- Note that shells donât export their environment by default.
echo
- Echo command.exit
- Exit command.cp
- Copies files.mv
- Moves files.rm
- Remove files or directories command.mkdir
- Makes directories.- Ex.
mkdir -p DIRECTORY...
- Commonly used to make a directory and all its parents with no error if it exists.
- Ex.
pwd
- Prints the current/working directory.sleep
- Sleep command.test
- Test command.touch
- Creates a file (note: flags have not been implemented yet).unset
- Unsets an environment variable.- More to come. Will try to get a similar list as https://deno.land/manual/tools/task_runner#built-in-commands
You can also register your own commands with the shell parser (see below).
Note that these cross platform commands can be bypassed by running them through sh
: sh -c <command>
(ex. sh -c cp source destination
). Obviously doing this wonât work on Windows though.
Cross platform shebang support
Users on unix-based platforms often write a script like so:
#!/usr/bin/env -S deno run
console.log("Hello there!");
âŚwhich can be executed on the command line by running ./file.ts
. This doesnât work on the command line in Windows, but it does on all platforms in dax:
await $`./file.ts`;
Builder APIs
The builder APIs are what the library uses internally and theyâre useful for scenarios where you want to re-use some setup state. Theyâre immutable so every function call returns a new object (which is the same thing that happens with the objects returned from $
and $.request
).
CommandBuilder
CommandBuilder
can be used for building up commands similar to what the tagged template $
does:
import { CommandBuilder } from "https://deno.land/x/dax/mod.ts";
const commandBuilder = new CommandBuilder()
.cwd("./subDir")
.stdout("inheritPiped") // output to stdout and pipe to a buffer
.noThrow();
const otherBuilder = commandBuilder
.stderr("null");
const result = await commandBuilder
// won't have a null stderr
.command("deno run my_script.ts")
.spawn();
const result2 = await otherBuilder
// will have a null stderr
.command("deno run my_script.ts")
.spawn();
You can also register your own custom commands using the registerCommand
or registerCommands
methods:
const commandBuilder = new CommandBuilder()
.registerCommand(
"true",
() => Promise.resolve({ kind: "continue", code: 0 }),
);
const result = await commandBuilder
// now includes the 'true' command
.command("true && echo yay")
.spawn();
RequestBuilder
RequestBuilder
can be used for building up requests similar to $.request
:
import { RequestBuilder } from "https://deno.land/x/dax/mod.ts";
const requestBuilder = new RequestBuilder()
.header("SOME_VALUE", "some value to send in a header");
const result = await requestBuilder
.url("https://example.com")
.timeout("10s")
.text();
$
Custom You may wish to create your own $
function that has a certain setup context (for example, custom commands or functions on $
, a defined environment variable or cwd). You may do this by using the exported build$
with CommandBuilder
and/or RequestBuilder
, which is essentially what the main default exported $
uses internally to build itself. In addition, you may also add your own functions to $
:
import { build$, CommandBuilder, RequestBuilder } from "https://deno.land/x/dax/mod.ts";
// creates a $ object with the provided starting environment
const $ = build$({
commandBuilder: new CommandBuilder()
.cwd("./subDir")
.env("HTTPS_PROXY", "some_value"),
requestBuilder: new RequestBuilder()
.header("SOME_NAME", "some value"),
extras: {
add(a: number, b: number) {
return a + b;
},
},
});
// this command will use the env described above, but the main
// process won't have its environment changed
await $`deno run my_script.ts`;
console.log(await $.request("https://plugins.dprint.dev/info.json").json());
// use your custom function
console.log($.add(1, 2));
This may be useful also if you want to change the default configuration. Another example:
const commandBuilder = new CommandBuilder()
.exportEnv()
.noThrow();
const $ = build$({ commandBuilder });
// since exportEnv() was set, this will now actually change
// the directory of the executing process
await $`cd test && export MY_VALUE=5`;
// will output "5"
await $`echo $MY_VALUE`;
// will output it's in the test dir
await $`echo $PWD`;
// won't throw even though this command fails (because of `.noThrow()`)
await $`deno eval 'Deno.exit(1);'`;
$
from another $
Building You can build a $
from another $
by calling $.build$({ /* options go here */ })
.
This might be useful in scenarios where you want to use a $
with a custom logger.
const local$ = $.build$();
local$.setInfoLogger((...args: any[]) => {
// a more real example might be logging to a file
console.log("Logging...");
console.log(...args);
});
local$.log("Hello!");
Outputs:
Logging...
Hello!