We know that that JavaScript is an interpreted language. Running it needs some interpreter to read our lines of code and execute them.

We’ve already seen that web browsers can run JavaScript. Web browsers provide a runtime environment for JavaScript.

NodeJS is another runtime environment for running JavaScript. It allows us to run JavaScript files from a terminal.

There are some similarities and differences between how NodeJS runs JavaScript, and how web browsers run JavaScript. For instance:

• Both support the same core language (e.g. defining variables, if statements, for loops, etc).
• Web browsers expose 🧶 🧶 expose To expose an API means to provide functions or values to the programmer. Sometimes we expose these over the internet, using HTTP+JSON. Other times we expose them directly as symbols you can import into your program. extra APIs that can be used from JavaScript, e.g. the DOM.
• NodeJS exposes extra APIs that can be used from JavaScript, e.g. reading and writing files in the filesystem.
• Some APIs are implemented differently, e.g. if you call console.log in a web browser it will log to the web inspector console (hidden by default), whereas in NodeJS it will log to stdout (the default output of a program).

People use NodeJS so that they can run code they’ve written in a terminal. Some example reasons:

• Because they want to use NodeJS’s extra capabilities in their code (e.g. reading files).
• Because they want to use a JavaScript as part of a shell pipeline.
• Because they want their program to run for a long time on a server.

You’ve already written JavaScript programs and run them in the NodeJS runtime environment - every time you run a command like node index.js or npm test you’re running JavaScript with NodeJS.

Most of the programs you wrote and ran like this in the Introduction to Programming course were short-lived experiments (learning a concept and trying it out), or tests.

We’re going to start thinking about writing programs intended to be run like this.

Below we have a small NodeJS program. It is a bit like wc. It counts words in a file which contain the letter e.

Our program accepts one command line argument - the path of the file to read and count.

Our program’s output to stdout is just the number of words which contain an e.

Our program uses the same language (JavaScript) as we’ve written before, but uses some different APIs.

import process from "node:process";
import { promises as fs } from "node:fs";

const argv = process.argv.slice(2);
if (argv.length != 1) {
    console.error(`Expected exactly 1 argument (a path) to be passed but got ${argv.length}.`);
    process.exit(1);
}
const path = argv[0];

const content = await fs.readFile(path, "utf-8");
const countOfWordsContainingEs = content
  .split(" ")
  .filter((word) => word.includes("e"))
  .length;
console.log(countOfWordsContainingEs);

Let’s play computer with this program - line by line:

import process from "node:process";

This import is loading some code from somewhere that isn’t this file.

We’ve seen import before. Here, instead of importing from a file we’ve written, we’re importing the process module which is built into NodeJS.

This is an example of the same language features (import) being used slightly differently (the "node:" is a special prefix to say “specially from node”).

The process module is built into NodeJS for managing our process 🧶 🧶 Process The running instance of our program: the code, state, memory, and system resources. . We can use it to find out what arguments were passed to the process when it started, find out what user ran the process, exit the process, and more.

import { promises as fs } from "node:fs";

We’re importing another module.

The fs module is built into NodeJS for interacting with the filesystem.

This time, we’re not importing the whole module. We are destructuring 🧶 🧶 Destructuring Destructuring is a form of variable assignment where we give variables values based on where we can find them structurally in another value. Examples:

We can write const [first, second] = [3, 1]; to assign first = 3 and second = 1.

We can write const {name, age} = {name: "Amir", age: 34}; to assign name = "Amir" and age = 34. . The node:fs module exposes an object, and we are saying “import the promises property from the fs module, and bind it to the name fs”.

It is like writing import { promises } from "node:fs"; const fs = promises;.

The fs module exposes two alternate APIs with functions with the same name (like readFile):

• The default fs module was written before async/await was added to JavaScript, and requires using callbacks, which can be annoying.
• fs has a submodule called promises which can be used with async/await, and is generally much more convenient.

We want to use the promises submodule, because it’s much more convenient for us to use async/await. But if we just wrote import { promises } from "node:fs";, we’d be binding the submodule to the name promises, and everywhere we used it we’d need to write promises.readFile. This is less clear than fs.readFile, because promises is a very general name. So we rename promises to fs, and can use it like fs.readFile.

We are really doing this because we wish the async/await APIs were the default APIs exposed by the fs module, and this lets us pretend that they are in the rest of our code.

const argv = process.argv.slice(2);

We’re getting the argv array from the process module, and slicing it. We can see in the process.argv documentation that process.argv[0] will be the path to node, and process.argv[1] will be the path to this file. We don’t care about those, so we’ll skip them - as far as we’re concerned the arguments start at index 2.

Again, Array.slice is exactly the same as we know from JavaScript, but process.argv is a new API we can use to get the array we need.

Play computer with the rest of the program - read each line, and explain what you think that line does. After you make your predictions, expand the explanations below and compare them to your predictions.

if (argv.length != 1) {
    console.error(`Expected exactly 1 argument (a path) to be passed but got ${argv.length}.`);
    process.exit(1);
}

const path = argv[0];

const content = await fs.readFile(path, "utf-8");

const countOfWordsContainingEs = content
  .split(" ")
  .filter((word) => word.includes("e"))
  .length;

console.log(countOfWordsContainingEs);

We’ve seen that we can use code that was built into NodeJS - we don’t need to write everything ourselves.

We can also use code that other people have written, which isn’t built into NodeJS. You’ve probably seen this before, e.g. using jest for testing.

This can be really useful - it means we can benefit from work others have already done, and focus on just solving the part of a problem which is unique to us. It’s like making shell pipelines - instead of having to solve every problem from scratch, we can plug together different tools that other people have already made.

Let’s expand the functionality of our program. Rather than always searching for words containing the letter e, let’s allow the user to specify what character they’re searching for.

This means we want to introduce a flag. And programs that accept flags, should also document themselves. One common convention is that if you run a program with the flag --help, it will tell you how to use it.

But writing all of this code to parse flags, to output information about the flags, and so on, is a lot of work.

So let’s use a library 🧶 🧶 library A library is a collection of code that we can use, but which isn’t part of our project. for this. We will use a library called commander.

To use a library, we need to fetch the code we’re going to use. When using NodeJS, we use a tool called npm for this.

First we need a package.json file - this a file that npm will read to understand your project. This is the same as the package.json file you’ve seen when using npm in the past.

Make this package.json file in the same directory as your e-word-counting program:

{
    "type": "module"
}

The package.json contains a JSON object with information about your project. For now, we’re just telling npm that our project is a module - this means we are allowed to use import in our program.

From a terminal which is cd’d to the same directory as your package.json file, run npm install commander.

This command does two things:

1. Look in your package.json file - notice that now has a dependencies section listing commander. This means that if someone else downloads your program, they know they need to install commander to use it.
2. There’s now a node_modules directory alongside your package.json. Inside that is a directory named commander which contains the code for the commander library. This means node now knows how to find the code when you try to import it.

Now that we have commander installed, let’s try using it in our program:

import { program } from "commander";
import { promises as fs } from "node:fs";
import process from "node:process";

program
    .name("count-containing-words")
    .description("Counts words in a file that contain a particular character")
    .option("-c, --char <char>", "The character to search for", "e");

program.parse();

const argv = program.args;
if (argv.length != 1) {
    console.error(`Expected exactly 1 argument (a path) to be passed but got ${argv.length}.`);
    process.exit(1);
}
const path = argv[0];
const char = program.opts().char;

const content = await fs.readFile(path, "utf-8");
const countOfWordsContainingChar = content
  .split(" ")
  .filter((word) => word.includes(char))
  .length;
console.log(countOfWordsContainingChar);

Let’s run through what we changed:

program
    .name("count-containing-words")
    .description("Counts words in a file that contain a particular character")
    .option("-c, --char <char>", "The character to search for", "e");

We told commander information about our program. We gave it a name, a description, and told it that it should allow a user to pass a flag name -c (or equivalently --char), and use a default value of - for that flag if it’s not specified.

program.parse();

We asked commander to interpret the command line arguments our program was given, based on what options we wanted to allow. If it sees something it doesn’t understand, it will error.

const argv = program.args;

Instead of asking NodeJS’s process module for all of the program’s arguments, we’re asking commander to tell us “after you understood and removed all the flags, what arguments were left?”

Then our if check about the number of arguments is exactly the same as before.

const char = program.opts().char;

We are getting the char flag that commander interpreted and storing it in a variable.

const countOfWordsContainingChar = content
  .split(" ")
  .filter((word) => word.includes(char))
  .length;
console.log(countOfWordsContainingChar);

We have renamed our countOfWordsContainingEs variable to countOfWordsContainingChar because we’re no longer always looking for hyphens, and changed the includes call to look for the value of the char variable instead of always an e.

We only needed to make a few small changes to get all of this new functionality:

• Support for accepting a new command line flag.
• --help support explaining how to use the program.
• Detection for if someone passes flags that aren’t known, and warning them about this (and even suggesting what they maybe meant).

We could have written all of this code ourselves. But using a library meant we could focus on what’s unique about our problem, rather than spending time implementing flag parsing.

This is a very common task in software development in the real world, joining together libraries (written by other people) to create some new unique solution.