Writing short utility scripts in JavaScript or TypeScript is actually ok

Sometimes, you want to make some part of the workflow automated, so you don't need to repeat the same manual tasks again and again.
When it's a bunch of commands that you need to execute sequentially, most people go for bash scripts (UNIX people, Windows users maybe prefer some PowerShell scripts).

I work mostly with TypeScript projects now.

For some time I did write all my scripts in bash too, mainly for one reason - bash is (almost) everywhere. But nowadays, so is JavaScript...

With the new tooling in the NPM ecosystem like npx it's super easy to execute a specific binary, regardless of whether it's installed in your project node_modules, globally or not installed at all.

Example problem

I worked with Lokalise on one of my previous projects. It's a localisation platform - you upload your i18n [[1]] files there, select what languages you want to support and they give you a nice dashboard for translating those texts. You can translate them by yourself, invite some teammates or even hire professional translators (I think it's paid by words translated?).

[[1]]: short for internationalization

The project is a backend app with microservice architecture stored in a monorepo. For some time, there was only one service that really needed translations - the notification service (sending out emails and push notifications in various languages). Uploading files to Lokalise was easy - just drag & drop a directory with translations to the webpage and you're done.
Now, we introduced another feature, in a sensor service, which also requires translations.

Of course I could drag & drop the files from notification service first, upload them and then do the same with translations from the sensor service... but it takes time. A lot of time, actually, because Lokalise scans each file path for the language, checks how many translations keys are there, whether they're already in their database, were they updated and so on.

I thought to myself - I should create a script that will "bundle" all translation files from all services that need translations to a single directory so I can drag & drop everything at the same time = have Lokalise scan it all in one pass.

Bashing up the script

So, as mentioned above, I started with a bash script. I'm not an expert in bash, but I know my terminal and use command line tools all the time, I shouldn't have any problems coding this - I thought to myself.

I need to know where I am

Maybe you also have encountered this "issue", but the script you wrote can be executed from almost anywhere. Consider script ~/scripts/ls.sh like this

#!/bin/bash
set -euo pipefail
ls

Depending on how from where you execute your script, it will produce different results.
For example this will list all files in your home directory

cd ~
./scripts/ls.sh

while this will list contents of scripts directory

cd ~/scripts
./ls.sh

Usually you want to make sure you're in the same directory where the script is located. The common way to achieve this is combining $0 variable and dirname function.

The $0 variable contains full path to the script/executable, while dirname returns a file path with its final component (usually file name) removed which gives you the path to a directory containing the file you provided as an argument.

#!/bin/bash
set -euo pipefail

SCRIPT_DIR=$(dirname $0)
ls $SCRIPT_DIR

The above script will always list files in the same directory it is located.

Maps, hash tables or rather associative arrays

In the script I'm writing, I want to have a map: from where the script should copy the files (key) mapped to a path where the files should be copied (value).

Of course I don't remember the syntax for it, but I'm pretty sure they're supported. Quick chat with ChatGPT (because who uses Google or StackOverflow for this right now) and here's the answer.

ChatGPT

In Bash, you can create an associative array, which serves as a dictionary in other programming languages. Associative arrays allow you to map keys to values, and they are available in Bash versions 4 and above. Here's how you can create and use a dictionary in Bash:

#!/bin/bash

# Declare an associative array (dictionary)
declare -A my_dict

# Add key-value pairs to the dictionary
my_dict["key1"]="value1"
my_dict["key2"]="value2"
my_dict["key3"]="value3"

# Access values using keys
echo "Value corresponding to key1: ${my_dict["key1"]}"
echo "Value corresponding to key2: ${my_dict["key2"]}"

# Iterate over the keys and values in the dictionary
for key in "${!my_dict[@]}"; do
    value="${my_dict[$key]}"
    echo "Key: $key, Value: $value"
done

Output:

Value corresponding to key1: value1
Value corresponding to key2: value2
Key: key1, Value: value1
Key: key2, Value: value2
Key: key3, Value: value3

In this example, we declare the my_dict as an associative array using the declare -A command. Then, we add key-value pairs to the dictionary using the syntax my_dict["key"]="value". To access values, we use the syntax ${my_dict["key"]}.

To iterate over the keys and values in the dictionary, we use a for loop with "${!my_dict[@]}", which expands to all the keys of the dictionary.

Keep in mind that associative arrays are only available in Bash 4 and above. If you are using an older version of Bash, you won't be able to use this feature. You can check your Bash version by running bash --version.

Did I read the whole answer? Of course not.

Did I copy the produced script and modified to what I need? Of course!

Here's the relevant part of my script:

#!/bin/bash
set -euo pipefail

# ...
declare -A TRANSLATION_FILE_PATHS
TRANSLATION_FILE_PATHS["$ROOT_DIR/apps/notification-service/static/locals/"]="$BUNDLE_DIR/locals"
TRANSLATION_FILE_PATHS["$ROOT_DIR/apps/sensor-service/src/i18n/"]="$BUNDLE_DIR/sensor-service/src/i18n"

# quick debug
for key in "${!TRANSLATION_FILE_PATHS[@]}"; do
	value="${TRANSLATION_FILE_PATHS[$key]}"
	echo "Key: $key, Value: $value"
done

What's the end result?

Error?! WHY?!

Well, if you read carefully the response from ChatGPT, you probably know. This feature is available from bash 4+.

bash --version says I have

GNU bash, version 3.2.57(1)-release (arm64-apple-darwin22)

Damn you, Apple.

What is the workaround for this? I didn't even wanted to check.

Checked it anyway, didn't like it (simply have two arrays and read the items from the same index) and I reminded myself I work in a TypeScript codebase.

Translating to TS

Having explored the idea in bash (go away! I mean, stay, but why are you always like this), I had the mental model of what I want to do:

1. Have a map of from/to pairs for translation files
2. For each pair, copy files from the from path to the to path
3. Done, maybe print the path to the bundle I guess.

Of course there is a bit more to it, like make sure the paths exists (I care only about the bundle directory, the from paths should always exists, it's up to developer to make sure they've provided correct paths in the map). I even added a "make sure we clear old data" logic.

The end script looks like this

import { format } from 'date-fns';
import * as fs from 'fs';
import path from 'path';

const currentDate = format(new Date(), 'yyyy-MM-dd');

const rootDir = path.join(__dirname, '../..');
const bundleDir = path.join(rootDir, 'tmp', 'lokalise', `lokalise-${currentDate}`);

const translationFilePaths: { from: string; to: string }[] = [
  {
    from: 'apps/notification-service/static/locals/',
    to: 'locals',
  },
  {
    from: 'apps/sensor-service/src/i18n/',
    to: 'sensor-service/src/i18n/',
  },
];

for (const { from, to } of translationFilePaths) {
  const rootFrom = `${rootDir}/${from}`;
  const bundleTo = `${bundleDir}/${to}`;
  if (fs.existsSync(bundleTo)) {
    fs.rmSync(bundleTo, { recursive: true });
  }
  fs.mkdirSync(bundleTo, { recursive: true });
  fs.cpSync(rootFrom, bundleTo, { recursive: true, preserveTimestamps: true });
}

console.log('Lokalise bundle created at ', bundleDir);

How to execute this? Just npx ts-node path-to-script.ts or other runner for TypeScript.

I've added this script to the package.json file:

{
  "scripts": {
    "lokalise:bundle": "ts-node tools/scripts/lokalise-bundle.ts"
  }
}

Conclusion

Using language such as TypeScript (or JavaScript, Python, whatever scripting language you can code in) gives you much more flexibility over using just bash.

Even though I have less and less love for JS everyday, in this case I can say it's the easiest way. With a lot of built-in functions in Node, you can do a lot of stuff without needing any external dependencies.

The only downside is that you must make sure there is something that can execute your script. In my case, the mentioned ts-node is already installed when you work on the project.

I don't need to worry about the CI environment, as the outputs of this command still require manual process of upload to Lokalise (there is some API, but the drag & drop method preserves the file hierarchy = when I download them from the dashboard after translations are done, they come back with the same structure; not sure if this works with API as well, might look into it as well later).

Stats

Fighting with bash:

• 1h of work
• ended up frustrated
• learned something new, but unfortunately not usable (associative arrays not supported in bash < 4)

Converting to TypeScript script:

• 20m (including refactor and code review)
  • although I had whole process explored
• no fighting with weird things from bash
• had idea for this post