How Node really works · Chapter 29 of 34

CLI task manager

By the end of this chapter you can build a command-line tool that reads its arguments, keeps its data in a file, and tells the shell whether it worked. Build it in your browser: a real editor and terminal, AI that explains, and tests that tell you when it works.

  • Part: Projects
  • 5 tasks
  • Node.js
  • In the all labs plan

The first 2 chapters of How Node really works are free. This one comes with the all labs plan.

Why you need this

Ravi runs the kitchen from a notebook: "Order milk", "Call the printer guy", and every morning he copies yesterday's unfinished lines onto a new page. Kabir wants a command on the shop laptop instead: node cli.js add Order milk, node cli.js list, node cli.js done 1.

A script that reads process.argv[2] and rewrites a file works until the first mistake: a typo saves junk, a crash halfway leaves half a file, a removed task's number comes back on a new one, and a shell script calling the tool cannot tell success from failure.

What you build: 5 tasks

Each task has tests. You write the code in the lab's editor and press Check.

  1. Task 1

    loadTasks and saveTasks: load and save the task file safely

    In exercise.js, write loadTasks(file). It returns a promise of the store saved in file, { nextId, tasks }, where each task is { id, text, done }. When the file does not exist (ENOENT) it resolves to { nextId: 1, tasks: [] }. Any other problem rejects with the real error: a file that is not valid JSON rejects with a SyntaxError, and a folder where the file should be rejects with code EISDIR.

    Write saveTasks(file, store). It saves the store as JSON with 2-space indentation and a newline at the end, exactly what JSON.stringify(store, null, 2) gives plus '\n'. Write it to a temporary file in the same folder first and then rename that over file, so a crash never leaves half a file. When it has finished, no temporary file is left in the folder.

  2. Task 2

    cli.js: add tasks and list them

    cli.js is run as node cli.js <command> ..., from the folder that holds the list, which is tasks.json there by default. Read the arguments with parseArgs (words as positionals) and use loadTasks and saveTasks.

    add <text...> joins every word after add with single spaces (trimmed), saves a new task { id: nextId, text, done: false }, adds 1 to nextId, and prints Added #<id>: <text>. list prints one line per task in the order they were added, #<id> [ ] <text>, with [x] instead of [ ] for a done task, or No tasks when there are none. Both exit with code 0 and print nothing on stderr. A first add on a new folder creates tasks.json.

  3. Task 3

    cli.js: mark tasks done and remove them without reusing ids

    done <id> marks that task done, saves, and prints Done #<id>: <text>. remove <id> takes the task out of the list, saves, and prints Removed #<id>: <text>. Both exit with code 0.

    Ids are never reused: after tasks 1, 2 and 3 exist and 3 is removed, the next add is #4, not #3, because nextId only ever counts up and is stored in the file (after that add, nextId is 5).

  4. Task 4

    cli.js: exit with the right code and message when something is wrong

    When it goes wrong, print a line starting with Error: on stderr, nothing on stdout, and exit with code 1. That covers done or remove with an id that is not in the list (the message contains no task #<id>, for example no task #9) and a task file that cannot be read or parsed.

    When it is used wrongly, print a message and the usage text (it contains Usage:) on stderr, nothing on stdout, and exit with code 2. That covers no command, an unknown command such as brew, add with no text, done or remove whose id is not a whole number above 0 (such as abc), and an unknown option such as --colour.

    Whenever a command fails, the task file is left exactly as it was: nothing is saved, and a broken file is never replaced by an empty list. Set process.exitCode instead of calling process.exit, so no output is lost.

  5. Task 5

    cli.js: keep the list in any file and show only pending tasks

    --file <path> (or -f <path>) chooses the task file instead of tasks.json, relative to the folder the command runs in. It works before or after the command and its words: node cli.js -f kitchen.json add Clean the stove and node cli.js done 1 --file kitchen.json both use kitchen.json, and tasks.json is not touched.

    --pending makes list show only the tasks that are not done, in the same format, or No tasks when none are left.

What you will learn

  • parseArgs: a command, its words and its flags, in any order.
  • Exit codes and stderr: telling the shell, and the person, what went wrong.
  • Missing or broken: which file errors mean "start empty" and which mean "stop".
  • Ids that never come back: a counter stored with the data.

More in Projects

Build "CLI task manager" yourself

Tapri’s order server must never stall at the 4 pm rush. You learn why it would. A real editor and terminal in your browser, AI that explains, and a Check that says when it works.

The first 2 chapters of How Node really works are free. This one comes with the all labs plan.