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.
- 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.
- 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.
- 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).
- 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.
- 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.