dzx

Deno shell tools inspired by zx

#!/usr/bin/env dzx
/// <reference path="https://deno.land/x/dzx/types.d.ts" />

console.log(`Hello from ${$.blue.bold("dzx")}!`);

const branch = await $`git branch --show-current`;
await $`dep deploy --branch=${branch}`;

await Promise.all([
  $`deno lint --unstable`,
  $`deno fmt --check`,
  $`deno test --allow-all`,
]);

const name = "foo bar";
await $`mkdir /tmp/${name}`; // <-- string will be safly quoted to: /tmp/'foo bar'

Content

Install
Usage
- Permissions
- Worker
- Methods
- Modules
- Variables
CLI
Contributing
License

Install

deno install --allow-all -r -f https://deno.land/x/dzx/dzx.ts

Usage

To start writing a dzx script, add next shebang at the beginning of your script:

#!/usr/bin/env dzx

To enable typings for typescript in your IDE, you can add a tripple slash reference to the top of the file,

#!/usr/bin/env dzx
/// <reference path="https://deno.land/x/dzx/types.d.ts" />

or you can import all symbol directly from the dzx/mod.ts module instead of using globals.

#!/usr/bin/env dzx
import { $, cd, fs, io, log, path } from "https://deno.land/x/dzx/mod.ts";

After making your script executable,

chmod +x ./script.ts

you can simply run it with:

./script.ts

Permissions

You can use dzx without installation by using next shebang. This also allows you to explicitly set the permissions for your script.

#!/usr/bin/env deno run --allow-run --allow-read --allow-env https://deno.land/x/dzx/dzx.ts
/// <reference path="https://deno.land/x/dzx/types.d.ts" />

console.log(`Hello ${$.blue.bold("world")}!`);

Worker

This is currently an exerminental feature. Permission flags doens’t support values currently. Read permissions are required by default. Workers are currently not supported with bundle and compile commands.

If dzx is called with -w or --worker, the script is executed inside an isolated web worker. If enabled, you can also set explicit permissions for your script.

Methods

$`command`: Executes a shell command.

const count = parseInt(await $`ls -1 | wc -l`);
console.log(`Files count: ${count}`);

If the executed program was successful, an instance of ProcessOutput will be return.

class ProcessOutput {
  readonly stdout: string;
  readonly stderr: string;
  readonly combined: string;
  readonly status: Deno.ProcessStatus;
  toString(): string;
}

If the executed program returns a non-zero exit code, a ProcessError will be thrown.

The ProcessError class extends from the Error class and implements all properties and methods from ProcessOutput.

try {
  await $`exit 1`;
} catch (error) {
  console.log(`Exit code: ${error.status.code}`);
  console.log(`Error: ${error.stderr}`);
}

cd(): Set the current working directory. If path does not exist, an error is thrown.
quote`string`: The quote methods quotes safly a string. by default the shq package is used. Can be overidden with $.quote.

Modules

$.[style]: Cliffy’s color module. A chainable wrapper for Deno’s std/fmt/colors module. Available on the global $ symbol.
```
console.log($.blue.bold("Hello world!"));
```
async: Deno’s std/async module.
```
await async.delay(1000);
```

path: Deno’s std/path module.

console.log(path.basename(import.meta.url));

io: Deno’s std/io module.

const data = await io.readAll(Deno.stdin);

fs: Deno’s std/fs module.
```
fs.ensureDir("./tmp");
```
log: Deno’s std/log module.
```
log.info("Some info!");
```

flags: Deno’s std/flags module.

console.log($.blue.bold("Hello world!"));

Variables

$.shell: Set the shell that is used by $`command`.
$.mainModule: The dzx main module (readonly).
$.verbose: Enable debugging output (log shell commands and execution time).
$.throwErrors: Throw errors instead of calling Deno.exit.
$.startTime: Th execution start time in ms.
$.time: The time left since execution start (now() - $.startTime).
$.quote: Parser method that is used to safely quote strings. Used by: $`command`

CLI

Usage:   dzx [script] [args...]
  Version: v0.2.0

  Description:

    🦕 A custom deno runtime for fun.

  Options:

    -h, --help       - Show this help.
    -V, --version    - Show the version number for this program.
    -A, --allow-all  - Allow all permissions.                                           (Depends: --worker)
    --allow-env      - Allow environment access.                                        (Depends: --worker)
    --allow-hrtime   - Allow high resolution time measurement.                          (Depends: --worker)
    --allow-net      - Allow network access.                                            (Depends: --worker)
    --allow-plugin   - Allow loading plugins.                                           (Depends: --worker)
    --allow-read     - Allow file system read access.                                   (Depends: --worker)
    --allow-run      - Allow running subprocesses.                                      (Depends: --worker)
    --allow-write    - Allow file system write access.                                  (Depends: --worker)
    -w, --worker     - Run script in an isolated web worker with it's own permissions.

  Commands:

    bundle   [script]                   - Bundle an dzx script to a standalone deno sript.
    compile  [script] [permissions...]  - Combile an dzx script to a standalone binary.

dzx [script] [...args]: Run an local or remote dzx script (optional in a web worker).
```
dzx --worker ./examplte.ts
```

dzx bundle [script]: Bundle an dzx script to a standalone deno sript. Can also read from stdin.

dzx bundle ./examplte.ts > bundle.js
deno run --allow-read --allow-env --allow-run bundle.js

dzx compile [script] [...permissions]: Combile an dzx script to a standalone binary. Can also read from stdin.
```
dzx compile ./examplte.ts --allow-read --allow-env --allow-run
```

Contributing

Any kind of contribution is welcome!

License

MIT