vl (violet)

deno CI

Shell scripting with TypeScript. Runs on top of Deno.

vl started as a port of zx to deno. The main motivation for this package was the lack of typescript support in zx. That’s where I got the idea to use deno, since it supports TypeScript natively.

Table of contents

Motivation

Bash is great, but when it comes to writing scripts, it has it’s limitations and people tend to go for more expressive programming languages. JavaScript/TypeScript is a great choice, since they are approachable by a huge number of developers. The vl package provides provides wrappers around child_process, and a number of other things for all your shell scripting needs. Since vl uses deno, it has access to both the rich standard library of deno, and the battle tested standard libraries of node through it’s node compatibility.

Example Program

#!/usr/bin/env vl

import "https://deno.land/x/violet/globals.d.ts";

const { create, mkdir } = Deno;

await Promise.all([
  $`sleep 1; echo 1`,
  <span class="katex"><span class="katex-mathml"><math xmlns="http://www.w3.org/1998/Math/MathML"><semantics><mrow><mi mathvariant="normal">‘</mi><mi>s</mi><mi>l</mi><mi>e</mi><mi>e</mi><mi>p</mi><mn>2</mn><mo separator="true">;</mo><mi>e</mi><mi>c</mi><mi>h</mi><mi>o</mi></mrow><annotation encoding="application/x-tex">`sleep 2; echo </annotation></semantics></math></span><span class="katex-html" aria-hidden="true"><span class="base"><span class="strut" style="height:0.8889em;vertical-align:-0.1944em;"></span><span class="mord">‘</span><span class="mord mathnormal">s</span><span class="mord mathnormal" style="margin-right:0.01968em;">l</span><span class="mord mathnormal">ee</span><span class="mord mathnormal">p</span><span class="mord">2</span><span class="mpunct">;</span><span class="mspace" style="margin-right:0.1667em;"></span><span class="mord mathnormal">ec</span><span class="mord mathnormal">h</span><span class="mord mathnormal">o</span></span></span></span>{2}`,
  $`sleep 3; echo 3`,
]);

await fetch("https://google.com");

await mkdir("tests");
await create("tests/test.txt");

cd("tests");
await $`ls`;
cd("..");

// clean up
await $`rm -rf tests`;

Usage

$command

Executes the given command by spawning a subprocess. Everything passed through ${} will be automatically quoted.

const fileName = "awesome";
await <span class="katex"><span class="katex-mathml"><math xmlns="http://www.w3.org/1998/Math/MathML"><semantics><mrow><mi mathvariant="normal">‘</mi><mi>t</mi><mi>o</mi><mi>u</mi><mi>c</mi><mi>h</mi></mrow><annotation encoding="application/x-tex">`touch </annotation></semantics></math></span><span class="katex-html" aria-hidden="true"><span class="base"><span class="strut" style="height:0.6944em;"></span><span class="mord">‘</span><span class="mord mathnormal">t</span><span class="mord mathnormal">o</span><span class="mord mathnormal">u</span><span class="mord mathnormal">c</span><span class="mord mathnormal">h</span></span></span></span>{awesome}.txt`;

You can also pass an array of arguments.

const flags = ["--oneline", "--decorate", "--color"];
const { exitCode } = await <span class="katex"><span class="katex-mathml"><math xmlns="http://www.w3.org/1998/Math/MathML"><semantics><mrow><mi mathvariant="normal">‘</mi><mi>g</mi><mi>i</mi><mi>t</mi><mi>l</mi><mi>o</mi><mi>g</mi></mrow><annotation encoding="application/x-tex">`git log </annotation></semantics></math></span><span class="katex-html" aria-hidden="true"><span class="base"><span class="strut" style="height:0.8889em;vertical-align:-0.1944em;"></span><span class="mord">‘</span><span class="mord mathnormal" style="margin-right:0.03588em;">g</span><span class="mord mathnormal">i</span><span class="mord mathnormal" style="margin-right:0.01968em;">tl</span><span class="mord mathnormal">o</span><span class="mord mathnormal" style="margin-right:0.03588em;">g</span></span></span></span>{flags}`;

Pipelines

#!/usr/bin/env vl

import "https://deno.land/x/violet/globals.d.ts";

await $`echo "Hello, stdout!"`.pipe(
  fs.createWriteStream("/tmp/output.txt", {}),
);

await $`cat /tmp/output.txt`;

Environment variables

#!/usr/bin/env vl

import "https://deno.land/x/violet/globals.d.ts";

Deno.env.set("FOO", "bar");

await <span class="katex"><span class="katex-mathml"><math xmlns="http://www.w3.org/1998/Math/MathML"><semantics><mrow><mi mathvariant="normal">‘</mi><mi>e</mi><mi>c</mi><mi>h</mi><mi>o</mi></mrow><annotation encoding="application/x-tex">`echo </annotation></semantics></math></span><span class="katex-html" aria-hidden="true"><span class="base"><span class="strut" style="height:0.6944em;"></span><span class="mord">‘</span><span class="mord mathnormal">ec</span><span class="mord mathnormal">h</span><span class="mord mathnormal">o</span></span></span></span>FOO > tmp.txt`;
await $`cat tmp.txt`;

Functions

fetch works, since it’s natively supported in deno.

const resp = await fetch("https://wttr.in");
console.log(await resp.text());

ask reads a line from stdin.

const resp = await ask("What is your name?");
console.log(resp);

choose prompts the user to choose from the provided options.

const resp = await choose("Would you like a foo or a bar?", ["foo", "bar"]);
console.log(resp);

sleep sleeps for specified ms.

await sleep(2000);

noThrow() Changes the behaviour of $ to not throw an exception on non-zero exit codes. You can still access the exitCode from the response.

const { exitCode } = await noThrow($`exit 1`);
console.log(exitCode);

quiet() Changes the behaviour of $ to disable verbose output.

usage:

await quiet($`echo foobar`); // command and output will not be displayed.

os package.

usage:

await <span class="katex"><span class="katex-mathml"><math xmlns="http://www.w3.org/1998/Math/MathML"><semantics><mrow><mi mathvariant="normal">‘</mi><mi>e</mi><mi>c</mi><mi>h</mi><mi>o</mi></mrow><annotation encoding="application/x-tex">`echo </annotation></semantics></math></span><span class="katex-html" aria-hidden="true"><span class="base"><span class="strut" style="height:0.6944em;"></span><span class="mord">‘</span><span class="mord mathnormal">ec</span><span class="mord mathnormal">h</span><span class="mord mathnormal">o</span></span></span></span>{os.homedir()}`;

retry()

Retries a command as many times as specified. Returns the first successful attempt, or will throw after specified attempts count.

usage:

await retry(5)`curl localhost`;

// or with a specified delay (500ms)
await retry(5, 500)`curl localhost`;

startSpinner()

Displays a spinner as an loading indicator. Useful with long running processes.

usage:

const { stopSpinner } = startSpinner();
await sleep(5000);
stopSpinner();

Configuration

$.shell

Which shell is used. Default is bash.

$.shell = "/usr/bin/zsh";

CLI argument --shell=/usr/bin/zsh can be used to achieve the same result.

$.verbose can be used to specify verbosity.

Default is true.

CLI argument --quiet sets verbosity to false.

Install

Prerequisites

You need to have deno installed. You can find installation instructions at deno.land.

deno install --allow-all -f https://deno.land/x/violet@<version_number>/vl.ts

Credits

The project wouldn’t have been possible without these resources, so I’m forever grateful for the existence of these!