Capstone A: help, usage and the summary line

The tracker of the previous lessons works and is unpleasant to use. A reader who forgets a command gets unknown command: undefined, a title typed with no words gets the message of the model, and a list of ten tasks prints ten lines with no count. The polish of this lesson is small and it is what separates a script from a tool.

Two files change and no file is added. The commands module grows a usage text and a summary function, and the command line prints the one and ends with the other. The tests of the previous lesson do not change, which is a sign that the polish stayed at the edge of the program.

The help text

The usage text is an array of lines joined by a newline, so each line is readable in the source and the whole text is one string. It names the program the way a reader types it, lists the five commands with one line each, and is printed by help, by --help and by every wrong call.

help is a command like the others and returns the status 0, because asking for the text is not an error. A wrong call prints the text to the error stream and returns 2, so a script that runs the command with an empty variable can tell the two cases apart.

The file src/commands.js:

vi src/commands.js

const { Task, TaskError } = require('./task'); const USAGE = [ 'usage: node bin/tasks.js <command> [argument]', '', ' add <title> add a task', ' list print every task and a summary', ' done <id> mark a task as done', ' remove <id> remove a task', ' help print this text', ].join('\n'); function parse(argv) { const [name, ...rest] = argv; if (name === 'help' || name === '--help' || name === '-h') { return { type: 'help' }; } if (name === 'add') { const title = rest.join(' ').trim(); if (title === '') { return { type: 'usage', message: 'add needs a title' }; } return { type: 'add', title }; } if (name === 'list') { return { type: 'list' }; } if (name === 'done' || name === 'remove') { const id = Number(rest[0]); if (rest.length !== 1 || !Number.isInteger(id) || id < 1) { return { type: 'usage', message: name + ' takes one task id' }; } return { type: name, id }; } return { type: 'usage', message: name === undefined ? 'no command given' : 'unknown command: ' + name }; } function find(tasks, id) { const task = tasks.find((entry) => entry.id === id); if (task === undefined) { throw new TaskError('no task with id ' + id); } return task; } function add(tasks, title) { const id = tasks.reduce((highest, task) => Math.max(highest, task.id), 0) + 1; return tasks.concat(new Task(id, title)); } function complete(tasks, id) { find(tasks, id); return tasks.map((task) => (task.id === id ? task.complete() : task)); } function remove(tasks, id) { find(tasks, id); return tasks.filter((task) => task.id !== id); } function render(tasks) { if (tasks.length === 0) { return 'no tasks'; } return tasks .map((task) => task.id + '. [' + (task.done ? 'x' : ' ') + '] ' + task.title) .join('\n'); } function summary(tasks) { const done = tasks.filter((task) => task.done).length; return tasks.length + ' task(s), ' + done + ' done'; } module.exports = { USAGE, add, complete, parse, remove, render, summary };

The parser also took on the two checks that a reader meets first: add with no words is a usage problem rather than a task with an empty title, and no command at all gets a message that names the gap. Both are questions about the arguments, which is the parser's business, and neither of them needs the file to be read.

A wrong call

A wrong call is anything the parser cannot turn into an action: a title that is not there, an id that is not a number, a command that does not exist. The command line prints the message, then the usage text, and returns 2 without loading the file, so a typo cannot change the list.

Printing the whole text for every mistake is a choice. A tool with twenty commands prints one line and leaves the rest to help; a tool with five can afford to repeat itself, and the reader who typed done abc gets the list of commands in the same breath as the complaint.

node bin/tasks.js add
echo "the exit status: $?"
node bin/tasks.js done abc
echo "the exit status: $?"

Both blocks below are part of the session in the last section of this lesson. The status 2 is the same for the two, because the two are the same kind of problem, and the message names the command that needs fixing instead of the parser that found it.

The summary line

summary counts the tasks and the ones that are done and returns one line: 3 task(s), 1 done. The command line prints it after every command that changes the list and after list, so the reader always sees the state and not only the change.

Two formats would be needed for one and for many tasks in a language with plurals; the task(s) form is the cheap way out and it is honest. The lesson on Intl shows the proper answer for a program that prints to a person in a language with more than two forms.

The line is printed by the command line and not by the module, because the module returns values and the program prints them. A function that returns a string is testable without a fake console; a function that prints has to be tested by reading the output.

Three statuses in one session

The session starts in a folder without a task file. It asks for the help text, lists an empty list, adds three tasks, completes the second one, lists again, and then makes three mistakes: no title, an id that is not a number and an id that no task has. The three statuses at the end are 2, 2 and 1.

node bin/tasks.js help
node bin/tasks.js list
node bin/tasks.js add write the model
node bin/tasks.js add write the tests
node bin/tasks.js add ship it
node bin/tasks.js done 2
node bin/tasks.js list
node bin/tasks.js add
echo "the exit status: $?"
node bin/tasks.js done abc
echo "the exit status: $?"
node bin/tasks.js remove 99
echo "the exit status: $?"

usage: node bin/tasks.js <command> [argument]

  add <title> add a task
  list print every task and a summary
  done <id> mark a task as done
  remove <id> remove a task
  help print this text
no tasks
0 task(s), 0 done
added the task 1
1 task(s), 0 done
added the task 2
2 task(s), 0 done
added the task 3
3 task(s), 0 done
task 2 is done
3 task(s), 1 done
1. [ ] write the model
2. [x] write the tests
3. [ ] ship it
3 task(s), 1 done
error: add needs a title
usage: node bin/tasks.js <command> [argument]

  add <title> add a task
  list print every task and a summary
  done <id> mark a task as done
  remove <id> remove a task
  help print this text
the exit status: 2
error: done takes one task id
usage: node bin/tasks.js <command> [argument]

  add <title> add a task
  list print every task and a summary
  done <id> mark a task as done
  remove <id> remove a task
  help print this text
the exit status: 2
error: no task with id 99
the exit status: 1

The list of ten lines that a reader dreads is four lines here: three tasks and the count. The empty list prints no tasks and a count of zero rather than nothing at all, which is the difference between a command that had nothing to show and one that failed.

The statuses are the three of the lesson on bin and npx, and the messages come in two streams: the usage text of a wrong call goes to stderr, the list goes to stdout. Redirect the two to different files and the split becomes visible.

Exercises

  1. Print the usage text with console.log(USAGE) and with console.log(...USAGE.split('\n')). Which one prints one line, and why?
  2. Add a clear command that removes every task. Which status does it return on an empty list, and why?
  3. Make the summary line singular for one task. Which two cases does the function now have, and where does the test go?
  4. Send the list to stderr instead of stdout with console.error and pipe the command into a file. Which stream ends up in the file?
  5. Return 1 instead of 2 for a wrong call and run the session again. Which statuses change, and which caller could no longer tell a wrong call from a missing task?

Questions

A new set of questions in a new order every time. Choose one answer for each, then check.

  1. Which status does a wrong call return in this project?

    Answer

    2

    A wrong call is neither a success nor a failure of the work, and the convention gives it 2.

  2. What does this program print? const USAGE = ["usage: tasks", " add <title>"]; console.log(USAGE.join("\n").split("\n").length);

    Answer

    2

    The join and the split cancel out, so the count is the number of lines in the array.

  3. What does the summary line of this project count?

    Answer

    Every task and the tasks that are done

    One line gives the size of the list and how much of it is finished.

  4. What does this program print? const tasks = [{ done: true }, { done: false }, { done: true }]; console.log(tasks.length + " task(s), " + tasks.filter((task) => task.done).length + " done");

    Answer

    3 task(s), 2 done

    Three tasks in the array and two of them have the flag set.

  5. Where does the usage text of a wrong call go?

    Answer

    To stderr, with the message

    A reader who pipes stdout into a file then gets the list and not the complaint.

  6. What does this program print? function summary(tasks) { if (tasks.length === 0) { return "no tasks"; } return tasks.length + " task(s)"; } console.log(summary([]), summary([{}, {}]));

    Answer

    no tasks 2 task(s)

    The empty list takes the first return and the two entries take the count.

  7. Why does the module return the summary instead of printing it?

    Answer

    A function that returns a string can be tested without a fake console

    The printing stays in the command line, and the module is a plain function of its input.

  8. What does this program print? const action = { type: "usage", message: "add needs a title" }; console.log(action.type === "usage", action.message.startsWith("add"));

    Answer

    true true

    The type matches and the message begins with the command that needs the argument.

  9. What is the difference between help and --help here?

    Answer

    Nothing, both print the text and return 0

    Both spellings are the same action, and asking for the text is not an error.

  10. What does this program print? const lines = ["usage: tasks", "", " list"]; console.log(lines.join("\n"));

    Answer

    usage: tasks list

    The empty string keeps its place, so the joined text has a blank line in it.

The programs and commands on this page were run with Node.js 24.22.1 and linted with ESLint 10.14.0 on Alpine Linux 3.24.3 (x86_64) in a Docker container.

Article author: Arthur Isaev