TheLazy.Dev
Portfolio GitHub

Blog

deno |shell

Extending the deno cli using a shell function

vonheikemen

Heiker

Posted on April 19, 2021

Extending the deno cli using a shell function

Puedes leer la versión en español aquí

I've been using deno more and more these days and I must tell you they are still things that bug me. But I did manage to solve some of those problems by "adding" some sub-commands to the cli. No, it's not dark magic, it's just a trick that I learned a while ago and that I'm going to share with you today.

What do we need for this?

In theory any shell that allows you to declare functions should be enough. In this post I'll be showing you the examples using a POSIX compliant syntax, so they should work on shells like bash, zsh or ash.

What do we want to achieve?

I would love for deno to have some built-in equivalent of npm scripts, but it doesn't seem like is going to happen any time soon. I wish I could do something like this.

deno start hello world
Enter fullscreen mode Exit fullscreen mode

It would also be nice if I could initialize those scripts, because they have to live somewhere.

deno init
Enter fullscreen mode Exit fullscreen mode

But as you know those sub-commands don't exists and that's what we are going to fix today (kinda).

Let us begin

The first step is to locate that one file you know your shell always execute. In zsh there's ~/.zshrc. bash has ~/.bashrc. Those two are the only ones I know, if you use any other shell try to find in its documentation the equivalent of that.

The definition

You ready now? Okay, now in that file you're going to write this.

deno()
{
  echo "Hello"
}
Enter fullscreen mode Exit fullscreen mode

Now if you restart your shell (or "reload" your configuration) and try to call deno you should get Hello. Isn't that nice? Awesome, but now we have created a problem, we can't use deno. But fear not, we are on a good path.

Come back to me deno

If we want to call the deno command we need to use the command known as command. Something like this.

command deno --version
Enter fullscreen mode Exit fullscreen mode

And that will get us all the info deno has about itself.

deno x.x.x (release, x86_64-unknown-linux-gnu)
v8 x
typescript x.x
Enter fullscreen mode Exit fullscreen mode

With this new knowledge we can solve our problem. Let's use that in our function.

deno()
{
  echo "You're using"
  command deno --version
}
Enter fullscreen mode Exit fullscreen mode

And when we call it we should get this.

$ deno

You're using
deno x.x.x (release, x86_64-unknown-linux-gnu)
v8 x
typescript x.x
Enter fullscreen mode Exit fullscreen mode

Going back to normal

We know how to call the deno command but we still need to make our function behave like the "real deno." We are going to do this in a way that can give us the oportunity to extend its behavior later on. For this we are going to use a case statement.

deno()
{
  local cmd=$1; shift;

  case "$cmd" in
    *)
      command deno $cmd $@
    ;;
  esac
}
Enter fullscreen mode Exit fullscreen mode

The first thing this function does is assign the first parameter ($1) to the variable cmd and then remove it from the arguments list ($@). After that we compare cmd with a pattern. For now the only pattern we have is * which is a wildcard that matches everything, is basically our default case. Let's make a test.

deno --version
Enter fullscreen mode Exit fullscreen mode

It's getting better. But notice that if we try to use deno without any arguments it'll give us an error. To fix that we are going to check if the first parameter is empty, and if it is we just call deno.

deno()
{
  if [ -z "$1" ];then
    command deno
    return
  fi

  local cmd=$1; shift;

  case "$cmd" in
    *)
      command deno $cmd $@
    ;;
  esac
}
Enter fullscreen mode Exit fullscreen mode

Calling all sub-commands

We are right were we want to be, we can finally start adding our own sub-commands. Let's figure out how this would work.

  deno()
  {
    if [ -z "$1" ];then
      command deno
      return
    fi

    local cmd=$1; shift;

    case "$cmd" in
+     hello)
+       command deno eval "console.log('deno says hello')"
+     ;;
      *)
        command deno $cmd $@
      ;;
    esac
  }
Enter fullscreen mode Exit fullscreen mode

Now call this new hello command.

$ deno hello

deno says hello
Enter fullscreen mode Exit fullscreen mode

So we know for sure this thing works.

deno scripts

We can work on our improvised replacement for npm scripts. There is a common convention in node where we use a start command to "boot up" our application or project. Let's start with that.

  deno()
  {
    if [ -z "$1" ];then
      command deno
      return
    fi

    local cmd=$1; shift;

    case "$cmd" in
+     start)
+       command deno run --allow-run ./Taskfile.js start $@
+     ;;
      *)
        command deno $cmd $@
      ;;
    esac
  }
Enter fullscreen mode Exit fullscreen mode

This command will execute a file called Taskfile.js using deno. The --allow-run will let us use Deno.run in our code to call external commands. It's test time.

Make that Taskfile.js.

const cmd = ['echo', 'Taskfile: ', ...Deno.args];
Deno.run({ cmd });
Enter fullscreen mode Exit fullscreen mode

Now use start.

$ deno start hello

Taskfile: start hello
Enter fullscreen mode Exit fullscreen mode

Just lovely. The next step will be to create a "smarter" Taskfile.js, one that can call different tasks. I've done something like this in the past (check out the details of it in here), so I'm going to show you the code I would use.

const entrypoint = "./src/main.js";

run(Deno.args, {
  start(...args) {
    exec(["deno", "run", entrypoint, ...args]);
  },
  list() {
    console.log('Available tasks: ');
    Object.keys(this).forEach((k) => console.log(`* ${k}`));
  },
});

function run([name, ...args], tasks) {
  if(tasks[name]) {
    tasks[name](...args);
  } else {
    console.log(`Task "${name}" not found\n`);
    tasks.list();
  }
}

async function exec(args) {
  const proc = await Deno.run({ cmd: args }).status();

  if (proc.success == false) {
    Deno.exit(proc.code);
  }

  return proc;
}
Enter fullscreen mode Exit fullscreen mode

With this we can execute the file ./src/main.js using deno start. But now we have a problem, we don't want to write all of that every time we create a new project. What we will do is create another command called init to copy this template into our project folder.

  deno()
  {
    if [ -z "$1" ];then
      command deno
      return
    fi

    local cmd=$1; shift;

    case "$cmd" in
      start)
        command deno run --allow-run ./Taskfile.js start $@
      ;;
+     init)
+       cp /path/to/template/Taskfile.js ./
+       echo "Taskfile.js created"
+     ;;
      *)
        command deno $cmd $@
      ;;
    esac
  }
Enter fullscreen mode Exit fullscreen mode

Everything is looking good. The last thing we will deal with is calling other tasks besides start. With npm we can call any script we want using npm run, the equivalent for us will be called x.

  deno()
  {
    if [ -z "$1" ];then
      command deno
      return
    fi

    local cmd=$1; shift;

    case "$cmd" in
+     x)
+       command deno run --allow-run ./Taskfile.js $@
+     ;;
      start)
        command deno run --allow-run ./Taskfile.js start $@
      ;;
      init)
        cp /path/to/template/Taskfile.js ./
        echo "Taskfile.js created"
      ;;
      *)
        command deno $cmd $@
      ;;
    esac
  }
Enter fullscreen mode Exit fullscreen mode

We are all set. If we had a "task" called test:api we can invoke it using this.

deno x test:api
Enter fullscreen mode Exit fullscreen mode

A little extra convenience

One more thing, I would like to have a way of calling a specific script and be able to call all my most used libraries without using URLs. We can do this with the help of import-maps, .json files that can bind an "alias" to a URL.

I use one like this.

{
  "imports": {
    "@std/": "https://deno.land/std@0.93.0/",
    "@npm/": "https://jspm.dev/",

    "ansi-colors": "https://jspm.dev/ansi-colors@4.1.1",
    "arg": "https://jspm.dev/arg@5.0.0",
    "cheerio": "https://jspm.dev/cheerio@1.0.0-rc.5",
    "exec": "https://deno.land/x/exec@0.0.5/mod.ts",
    "ramda": "https://jspm.dev/ramda@0.27.1",

    "@utils/": "/path/to/deno/utils/"
  }
}
Enter fullscreen mode Exit fullscreen mode

deno can read this if we provide its path using the --import-map flag. Let's add a command that uses that.

  deno()
  {
    if [ -z "$1" ];then
      command deno
      return
    fi

    local cmd=$1; shift;

    case "$cmd" in
      x)
        command deno run --allow-run ./Taskfile.js $@
      ;;
      start)
        command deno run --allow-run ./Taskfile.js start $@
      ;;
      init)
        cp /path/to/template/Taskfile.js ./
        echo "Taskfile.js created"
      ;;
+     s|script)
+       command deno run --import-map="/path/to/deno/import-map.json" $@
+     ;;
      *)
        command deno $cmd $@
      ;;
    esac
  }
Enter fullscreen mode Exit fullscreen mode

As with everything else, we need to test this thing. Create a script with this.

import dayjs from '@npm/dayjs';
import c from 'ansi-colors';

c.enabled = !Deno.noColor;

const date = dayjs().format('{YYYY} MM-DDTHH:mm:ss SSS [Z] A');

console.log(c.green(date));
Enter fullscreen mode Exit fullscreen mode

Might want to specify the library version. Instead of using @npm/dayjs, use @npm/dayjs@1.10.4

And now call it.

$ deno script ./test.js

Download https://jspm.dev/dayjs@1.10.4
Download https://jspm.dev/npm:dayjs@1.10.4!cjs
{2021} 04-18T11:28:05 929 Z AM
Enter fullscreen mode Exit fullscreen mode

Ha! Now I have all I want.

The final result

After all this process your deno function should look like this.

deno()
{
  if [ -z "$1" ];then
    command deno
    return
  fi

  local cmd=$1; shift

  case "$cmd" in
    x)
      command deno run --allow-run ./Taskfile.js $@
    ;;
    start)
      command deno run --allow-run ./Taskfile.js start $@
    ;;
    init)
      cp /path/to/template/Taskfile.js ./
      echo "Taskfile.js created"
    ;;
    s|script)
      command deno run --import-map="/path/to/deno/import-map.json" $@
    ;;
    *)
      command deno $cmd $@
    ;;
  esac
}
Enter fullscreen mode Exit fullscreen mode

Conclusion

So, what did we do today? We "hid" the deno command inside a function in order to be able to add sub-commands that we created. We managed to build an equivalent to npm run for deno and finally we used import maps to simplify the declaration of our dependencies in a script. Not bad for a day's work.

Thank you for your time. If you find this article useful and want to support my efforts, consider leaving a tip in ko-fi.com/vonheikemen.

buy me a coffee

💖 💪 🙅 🚩
vonheikemen
Heiker

Posted on April 19, 2021

Join Our Newsletter. No Spam, Only the good stuff.

Sign up to receive the latest update from our blog.

Related

Optimizando tu día laboral: creando Comandos.
bash Optimizando tu día laboral: creando Comandos.

May 15, 2024

Command Line 101
cli Command Line 101

January 15, 2024

Tipos de Dados, Variáveis e Interagindo com o Usuário #02
python Tipos de Dados, Variáveis e Interagindo com o Usuário #02

March 28, 2022

Extending the deno cli using a shell function
deno Extending the deno cli using a shell function

April 19, 2021

Extendiendo deno cli usando una función
deno Extendiendo deno cli usando una función

April 19, 2021