TypeScript: Building a Simple Command-Line Task Manager

Written by

learnmodernjavascript

in

In the world of software development, managing tasks efficiently is paramount. Whether you’re a seasoned developer or just starting your coding journey, the ability to organize and execute tasks from the command line can significantly boost your productivity. This tutorial will guide you through building a simple, yet functional, command-line task manager using TypeScript. We’ll explore the core concepts, step-by-step implementation, and best practices to create a tool that can help you stay organized and on top of your projects. This project is designed for beginners to intermediate developers who want to deepen their understanding of TypeScript and command-line application development.

Why Build a Command-Line Task Manager?

Command-line interfaces (CLIs) offer a powerful and often overlooked way to interact with your computer. They provide a direct, efficient means of executing commands, scripting tasks, and automating processes. A task manager built as a CLI is particularly useful for several reasons:

  • Efficiency: Quickly add, list, and complete tasks without the overhead of a graphical user interface.
  • Automation: Easily integrate task management into your scripts and automated workflows.
  • Customization: Tailor the task manager to your specific needs and preferences.
  • Learning: Building a CLI app is a great way to learn about TypeScript, file I/O, and command-line argument parsing.

By the end of this tutorial, you’ll have a fully functional task manager that you can use to manage your daily tasks directly from your terminal. Let’s get started!

Prerequisites

Before we begin, make sure you have the following installed on your system:

  • Node.js and npm (Node Package Manager): TypeScript requires Node.js to run. npm is used to manage project dependencies.
  • TypeScript: Install TypeScript globally using npm: npm install -g typescript
  • A Text Editor or IDE: Such as VS Code, Sublime Text, or Atom.

Setting Up Your Project

First, create a new directory for your project and navigate into it using your terminal:

mkdir task-manager-cli
cd task-manager-cli

Next, initialize a new Node.js project. This will create a package.json file, which will manage your project’s dependencies and metadata:

npm init -y

Now, install the TypeScript compiler and a library for handling command-line arguments. We’ll use commander for this purpose. We’ll also use @types/node to get TypeScript type definitions for Node.js modules:

npm install typescript commander @types/node --save-dev

Create a tsconfig.json file in the root directory. This file configures the TypeScript compiler. Here’s a basic configuration:

{
  "compilerOptions": {
    "target": "es2016",
    "module": "commonjs",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src/**/*"]
}
  • target: Specifies the JavaScript version to compile to.
  • module: Specifies the module system to use (CommonJS in this case).
  • outDir: Specifies the output directory for compiled JavaScript files.
  • rootDir: Specifies the root directory of your source files.
  • strict: Enables strict type-checking options.
  • esModuleInterop: Enables interoperability between CommonJS and ES modules.
  • skipLibCheck: Skips type checking of declaration files.
  • forceConsistentCasingInFileNames: Enforces consistent casing in file names.
  • include: Specifies the files to include in the compilation.

Finally, create a src directory and a file named index.ts inside it. This is where we’ll write our TypeScript code.

Implementing the Task Manager

1. Basic Structure and Command Parsing

Let’s start by importing the commander library and setting up the basic command-line interface. Open src/index.ts and add the following code:

import { program } from 'commander';

program
  .name('task-manager')
  .description('A simple command-line task manager')
  .version('1.0.0');

program.parse(process.argv);

This code does the following:

  • Imports the program object from the commander library.
  • Sets the name, description, and version of our CLI tool.
  • Parses the command-line arguments using process.argv.

To run this, you’ll need to compile the TypeScript code and then execute it. Add a script to your package.json file to compile TypeScript:

{
  "scripts": {
    "build": "tsc",
    "start": "node dist/index.js"
  }
}

Now, run npm run build to compile the TypeScript code. Then, run npm start to execute the compiled JavaScript. You should see nothing, but you can check the version using node dist/index.js --version.

2. Adding Commands

Let’s add some commands to our task manager. We’ll start with the following commands:

  • add: Adds a new task.
  • list: Lists all tasks.
  • complete: Marks a task as complete.

Modify src/index.ts as follows:

import { program } from 'commander';
import { addTask, listTasks, completeTask } from './tasks';

program
  .name('task-manager')
  .description('A simple command-line task manager')
  .version('1.0.0');

program
  .command('add ')
  .description('Add a new task')
  .action((task: string) => {
    addTask(task);
  });

program
  .command('list')
  .description('List all tasks')
  .action(() => {
    listTasks();
  });

program
  .command('complete ')
  .description('Mark a task as complete')
  .action((id: string) => {
    completeTask(parseInt(id, 10));
  });

program.parse(process.argv);

In this code:

  • We import functions addTask, listTasks, and completeTask from a module we’ll create later (./tasks).
  • We define the add command, which takes a task as an argument.
  • We define the list command, which doesn’t take any arguments.
  • We define the complete command, which takes a task ID as an argument.

Now, let’s create the src/tasks.ts file and implement the functions:

import * as fs from 'fs';
import * as path from 'path';

interface Task {
  id: number;
  text: string;
  completed: boolean;
}

const TASKS_FILE = path.join(__dirname, '..', 'tasks.json');

// Helper function to read tasks from the file
const readTasks = (): Task[] => {
  try {
    const data = fs.readFileSync(TASKS_FILE, 'utf8');
    return JSON.parse(data);
  } catch (error) {
    return [];
  }
};

// Helper function to write tasks to the file
const writeTasks = (tasks: Task[]): void => {
  fs.writeFileSync(TASKS_FILE, JSON.stringify(tasks, null, 2), 'utf8');
};

let nextId = 1;

export const addTask = (taskText: string): void => {
  const tasks = readTasks();
  const newTask: Task = {
    id: nextId++, // Increment the ID
    text: taskText,
    completed: false,
  };
  tasks.push(newTask);
  writeTasks(tasks);
  console.log(`Task added: ${newTask.text} (ID: ${newTask.id})`);
};

export const listTasks = (): void => {
  const tasks = readTasks();
  if (tasks.length === 0) {
    console.log('No tasks yet.');
    return;
  }

  tasks.forEach(task => {
    const status = task.completed ? '[x]' : '[ ]';
    console.log(`${task.id}. ${status} ${task.text}`);
  });
};

export const completeTask = (taskId: number): void => {
  const tasks = readTasks();
  const taskIndex = tasks.findIndex(task => task.id === taskId);

  if (taskIndex === -1) {
    console.log(`Task with ID ${taskId} not found.`);
    return;
  }

  tasks[taskIndex].completed = true;
  writeTasks(tasks);
  console.log(`Task ${taskId} marked as complete.`);
};

In this code:

  • We import the fs (file system) and path modules from Node.js.
  • We define a Task interface to represent the structure of a task.
  • We define the path to the tasks file (tasks.json).
  • We implement readTasks, writeTasks, addTask, listTasks, and completeTask functions.
  • addTask reads existing tasks, creates a new task object, adds it to the array, and writes the updated array back to the file.
  • listTasks reads tasks from the file and prints them to the console.
  • completeTask finds a task by its ID, marks it as complete, and writes the updated array back to the file.

Important: The code reads and writes tasks to a tasks.json file in the project’s root directory. The first time you run the application, this file will be created. The nextId variable is used to generate unique IDs for tasks. This implementation is suitable for a simple task manager. For more complex applications, consider using a database to store the tasks.

Compile the code again with npm run build and then run your task manager. You can now add, list, and complete tasks. For example:

# Add a task
npm start add "Grocery shopping"

# List tasks
npm start list

# Complete a task
npm start complete 1

3. Error Handling

Good error handling is crucial for a robust application. Let’s add some basic error handling to our task manager. Modify the completeTask function in src/tasks.ts to handle the case where the task ID is not found:

export const completeTask = (taskId: number): void => {
  const tasks = readTasks();
  const taskIndex = tasks.findIndex(task => task.id === taskId);

  if (taskIndex === -1) {
    console.log(`Task with ID ${taskId} not found.`);
    return;
  }

  tasks[taskIndex].completed = true;
  writeTasks(tasks);
  console.log(`Task ${taskId} marked as complete.`);
};

In this version, we check if the taskIndex is -1, which means the task with the given ID wasn’t found. If it’s not found, we print an error message and return.

You can also add error handling to the addTask and listTasks functions to handle potential file system errors. For example, wrap the file system operations in a try...catch block to catch potential errors like file not found or permission issues.

4. Improving User Experience

While the task manager is functional, we can improve the user experience. Here are some suggestions:

  • More informative output: Display more information about the tasks, such as the date and time they were added.
  • Task prioritization: Allow users to set priorities for tasks (e.g., high, medium, low).
  • Task due dates: Allow users to set due dates for tasks.
  • Color-coding: Use colors in the output to highlight different task statuses or priorities.
  • Confirmation prompts: Ask for confirmation before deleting tasks or marking them as complete.

Let’s add a simple improvement – displaying the date and time a task was added. First, install the date-fns library:

npm install date-fns

Then, modify src/tasks.ts:

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

interface Task {
  id: number;
  text: string;
  completed: boolean;
  addedAt: string; // Add addedAt property
}

const TASKS_FILE = path.join(__dirname, '..', 'tasks.json');

const readTasks = (): Task[] => {
  try {
    const data = fs.readFileSync(TASKS_FILE, 'utf8');
    return JSON.parse(data);
  } catch (error) {
    return [];
  }
};

const writeTasks = (tasks: Task[]): void => {
  fs.writeFileSync(TASKS_FILE, JSON.stringify(tasks, null, 2), 'utf8');
};

let nextId = 1;

export const addTask = (taskText: string): void => {
  const tasks = readTasks();
  const newTask: Task = {
    id: nextId++, // Increment the ID
    text: taskText,
    completed: false,
    addedAt: format(new Date(), 'yyyy-MM-dd HH:mm:ss'), // Add the current date and time
  };
  tasks.push(newTask);
  writeTasks(tasks);
  console.log(`Task added: ${newTask.text} (ID: ${newTask.id})`);
};

export const listTasks = (): void => {
  const tasks = readTasks();
  if (tasks.length === 0) {
    console.log('No tasks yet.');
    return;
  }

  tasks.forEach(task => {
    const status = task.completed ? '[x]' : '[ ]';
    console.log(`${task.id}. ${status} ${task.text} - Added: ${task.addedAt}`); // Display the addedAt property
  });
};

export const completeTask = (taskId: number): void => {
  const tasks = readTasks();
  const taskIndex = tasks.findIndex(task => task.id === taskId);

  if (taskIndex === -1) {
    console.log(`Task with ID ${taskId} not found.`);
    return;
  }

  tasks[taskIndex].completed = true;
  writeTasks(tasks);
  console.log(`Task ${taskId} marked as complete.`);
};

In this code:

  • We import the format function from date-fns.
  • We add an addedAt property of type string to the Task interface.
  • In the addTask function, we set the addedAt property to the current date and time, formatted using date-fns.
  • In the listTasks function, we display the addedAt property when listing tasks.

Rebuild and run the application to see the updated output. This is a small but effective enhancement that makes the task manager more user-friendly.

Common Mistakes and How to Fix Them

Here are some common mistakes developers make when building command-line applications and how to avoid them:

  • Incorrect File Paths: Using incorrect file paths can lead to errors when reading or writing task data. Always use relative paths correctly or use the path module to construct paths. Double-check your paths.
  • Uncaught Errors: Not handling errors can cause your application to crash unexpectedly. Always use try...catch blocks to handle potential errors, especially when working with file system operations. Log errors to the console or a file to help with debugging.
  • Missing Dependencies: Forgetting to install project dependencies will cause your code to fail. Always run npm install to install all dependencies listed in your package.json file.
  • Incorrect Argument Parsing: Command-line argument parsing can be tricky. Make sure you correctly define the arguments for your commands using a library like commander. Test your commands with different arguments to ensure they work as expected.
  • Not Using TypeScript Types: Not using TypeScript types defeats the purpose of TypeScript. Define interfaces and types to represent your data structures. This helps catch errors during development and improves code readability.

Key Takeaways

  • Project Setup: Setting up a TypeScript project with Node.js and a command-line argument parser is the first step.
  • Command Definition: Defining commands using a library like commander is essential for creating a user-friendly CLI.
  • File I/O: Reading and writing data to files is necessary for persisting task data. Use the fs module for this purpose, and handle potential errors.
  • Error Handling: Implement robust error handling to make your application more reliable.
  • User Experience: Consider how to improve the user experience by providing clear output, using color-coding, and adding features like task prioritization.

FAQ

Here are some frequently asked questions about building a command-line task manager:

  1. How do I add more features to my task manager? You can add more commands (e.g., delete, edit), add features like task dependencies, or integrate with external services.
  2. How can I store tasks more efficiently? For more complex applications, consider using a database (e.g., SQLite, PostgreSQL, MongoDB) instead of storing tasks in a JSON file.
  3. How do I handle user input? You can use libraries like readline to handle more complex user input, such as prompts and interactive menus.
  4. How can I test my task manager? Use a testing framework like Jest or Mocha to write unit tests for your functions, ensuring they behave as expected.
  5. What are the best practices for CLI design? Provide clear help messages, use consistent command structures, and provide informative output to the user.

This tutorial provides a solid foundation for building a command-line task manager using TypeScript. You can expand on this foundation by adding more features, improving the user interface, and integrating with other tools and services. Remember to always focus on writing clean, well-documented code, and handling errors gracefully.

By following the steps outlined in this tutorial and experimenting with the code, you’ll not only gain practical experience with TypeScript and command-line application development but also improve your overall coding skills. Building a CLI task manager is more than just creating a tool; it’s about learning the fundamental principles of software development in a practical and engaging way. The ability to manage tasks efficiently is a valuable skill in any project, and with this knowledge, you can begin to make your workflow more organized and productive, one command at a time.

More posts