TypeScript Tutorial: Building a Simple Interactive Code Debugger

Written by

learnmodernjavascript

in

Debugging is an essential skill for any software developer. It’s the process of finding and fixing errors (bugs) in your code. Even experienced programmers spend a significant amount of time debugging. This tutorial will guide you through building a simple, interactive code debugger using TypeScript, a superset of JavaScript that adds static typing. We’ll explore the core concepts of debugging, how to implement basic debugging features, and how to use them effectively. This project will not only teach you about debugging techniques but also provide hands-on experience in building a practical tool.

Why Debugging Matters

Bugs are inevitable. They can range from minor typos to critical errors that crash your application. Without effective debugging, identifying and fixing these issues can be a time-consuming and frustrating process. Debugging allows you to:

  • Understand Code Behavior: Step through your code line by line, observing the values of variables and the flow of execution.
  • Identify Errors: Pinpoint the exact location of bugs in your code.
  • Fix Errors: Correct the code to eliminate the bugs.
  • Improve Code Quality: Learn from your mistakes and write better code in the future.

Debugging tools streamline this process, making it faster and more efficient. By learning to use these tools and techniques, you become a more productive and skilled developer.

Setting Up Your Environment

Before we start, you’ll need the following:

  • Node.js and npm (Node Package Manager): Used to manage JavaScript packages and run our code. You can download it from https://nodejs.org/.
  • TypeScript: We’ll install it globally using npm: npm install -g typescript
  • A Code Editor: VS Code, Sublime Text, or Atom are popular choices. VS Code has excellent TypeScript support.

Once you have these installed, create a new project directory and initialize a Node.js project:

mkdir code-debugger
cd code-debugger
npm init -y

This creates a package.json file, which manages your project’s dependencies.

Creating the TypeScript Configuration

Next, we need to set up the TypeScript compiler. Run the following command in your terminal:

tsc --init

This creates a tsconfig.json file. This file contains configuration options for the TypeScript compiler. Open tsconfig.json and make the following adjustments (or ensure these are set):

{
  "compilerOptions": {
    "target": "es5",
    "module": "commonjs",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src/**/*"]
}

Here’s what these options mean:

  • target: "es5": Specifies the JavaScript version to compile to.
  • module: "commonjs": Specifies the module system to use.
  • outDir: "./dist": Specifies the output directory for compiled JavaScript files.
  • rootDir: "./src": Specifies the root directory of your TypeScript files.
  • strict: true: Enables strict type checking.
  • esModuleInterop: true: Enables interoperability between CommonJS and ES modules.
  • skipLibCheck: true: Skips type checking of declaration files.
  • forceConsistentCasingInFileNames: true: Enforces consistent casing in filenames.
  • include: ["src/**/*"]: Specifies which files to include in the compilation.

Project Structure

Create the following directory structure in your project:


code-debugger/
├── package.json
├── tsconfig.json
├── src/
│   └── index.ts
└── dist/

All your TypeScript code will go in the src directory. The compiled JavaScript files will be in the dist directory.

Implementing the Debugger Core

Let’s start by creating a simple function that we want to debug. In src/index.ts, add the following code:


function calculateSum(a: number, b: number): number {
  const result = a + b;
  return result;
}

const num1 = 5;
const num2 = 10;
const sum = calculateSum(num1, num2);
console.log(`The sum of ${num1} and ${num2} is: ${sum}`);

This is a basic function that calculates the sum of two numbers. Now, let’s create a very basic debugger. We will focus on the core concepts here, rather than building a full-fledged debugger UI.

First, we need a way to “pause” the execution of the code at specific points. We can achieve this using the debugger keyword in JavaScript. This keyword tells the browser or the Node.js environment to pause execution and open the debugger tools. Modify src/index.ts as follows:


function calculateSum(a: number, b: number): number {
  debugger; // Breakpoint 1
  const result = a + b;
  debugger; // Breakpoint 2
  return result;
}

const num1 = 5;
const num2 = 10;
const sum = calculateSum(num1, num2);
debugger; // Breakpoint 3
console.log(`The sum of ${num1} and ${num2} is: ${sum}`);

Now, when you run this code, the debugger will pause at each debugger statement. You’ll need to run this with Node.js in a way that allows you to inspect the code. In your terminal, navigate to your project directory and run:

node --inspect-brk dist/index.js

This command starts the Node.js process and pauses at the first line of the script. Open your browser’s developer tools (usually by pressing F12) and go to the “Sources” tab. You should see your index.ts file. You can then step through the code line by line, inspect variables, and see the flow of execution. You will need to compile the TypeScript first:

tsc

This command compiles your TypeScript code and places the output in the dist directory.

Adding Breakpoints and Stepping Through Code

The debugger keyword is the simplest way to set a breakpoint. However, you can also set breakpoints directly in your code editor (like VS Code). Click in the gutter (the space next to the line numbers) to set a breakpoint. When you run the code, the debugger will pause at that line.

In the debugger tools, you’ll typically find options to:

  • Step Over: Execute the next line of code.
  • Step Into: If the next line is a function call, step into that function.
  • Step Out: Step out of the current function.
  • Continue: Resume execution until the next breakpoint or the end of the program.

Experiment with these options to understand how the code executes step by step.

Inspecting Variables

One of the most crucial debugging features is the ability to inspect the values of variables. In the debugger, you’ll usually see a “Variables” pane that shows the current values of all variables in scope. As you step through the code, the values will update, allowing you to track how the variables change and identify potential issues.

For example, if you have a variable named result, you can see its value as the calculateSum function runs. If the value is not what you expect, you know there’s a problem in the calculation.

Debugging Complex Code

Debugging becomes more challenging as your code becomes more complex. Here are some tips:

  • Divide and Conquer: If you suspect a bug, try to isolate the problem by commenting out sections of code or breaking it down into smaller, testable functions.
  • Use Logging: Insert console.log() statements to print the values of variables at various points in your code. This can help you track the flow of execution and identify where the problem lies.
  • Reproduce the Bug: Try to recreate the bug in a controlled environment. This will help you understand the root cause and ensure your fix works.
  • Read Error Messages: Carefully examine error messages. They often provide valuable clues about the source of the problem.
  • Use a Debugger: As demonstrated above, use the built-in debugging tools in your code editor or browser to step through the code, inspect variables, and identify the exact location of the bug.
  • Test Thoroughly: Write unit tests to ensure that your code works as expected and to catch bugs early in the development process.

Example: Debugging a Simple Loop

Let’s look at an example of debugging a simple loop. Consider the following code:


function calculateFactorial(n: number): number {
  let factorial = 1;
  for (let i = 1; i <= n; i++) {
    factorial *= i;
  }
  return factorial;
}

const number = 5;
const result = calculateFactorial(number);
console.log(`The factorial of ${number} is: ${result}`);

This code calculates the factorial of a number. Let’s say there’s a bug, and the result is incorrect. We can use the debugger to find the problem.

Add breakpoints inside the loop, and inspect the values of i and factorial at each iteration:


function calculateFactorial(n: number): number {
  let factorial = 1;
  for (let i = 1; i <= n; i++) {
    debugger; // Breakpoint inside the loop
    factorial *= i;
  }
  return factorial;
}

const number = 5;
const result = calculateFactorial(number);
console.log(`The factorial of ${number} is: ${result}`);

Run the code with the debugger, and step through the loop. You’ll see how factorial changes with each iteration. If the result is incorrect, you can easily identify the point at which the calculation goes wrong.

Common Debugging Mistakes and How to Fix Them

Here are some common mistakes developers make when debugging and how to avoid them:

  • Not Using a Debugger: Relying solely on console.log() can be inefficient. Use a debugger to step through code and inspect variables.
  • Setting Breakpoints Incorrectly: Place breakpoints in the wrong locations, wasting time. Think carefully about where the problem might be and set breakpoints accordingly.
  • Ignoring Error Messages: Error messages provide crucial information. Read them carefully and understand what they are telling you.
  • Making Unnecessary Changes: Avoid making random code changes in the hope of fixing the bug. Understand the problem first.
  • Not Testing Thoroughly: After fixing a bug, test your code thoroughly to ensure the fix works and doesn’t introduce new issues.
  • Not Reproducing the Bug: If you can’t reproduce the bug, it’s difficult to fix. Try to recreate the bug in a controlled environment.

Enhancing the Debugger (Advanced Features)

Once you’re comfortable with the basics, you can explore more advanced debugging features:

  • Conditional Breakpoints: Set breakpoints that only trigger when a specific condition is met (e.g., when a variable has a certain value).
  • Watch Expressions: Define expressions to watch in the debugger. The debugger will automatically evaluate these expressions and display their values as you step through the code.
  • Call Stack: Examine the call stack to see the sequence of function calls that led to the current point in your code. This is useful for understanding how your code is structured and how different functions interact.
  • Remote Debugging: Debug code running on a different machine or in a different environment (e.g., a web server).

Key Takeaways

  • Debugging is an essential skill for software development.
  • TypeScript code can be debugged using the same techniques as JavaScript.
  • The debugger keyword pauses code execution.
  • Use breakpoints, stepping, and variable inspection to understand code behavior.
  • Error messages provide valuable clues.
  • Practice and experience are key to becoming a proficient debugger.

FAQ

Here are some frequently asked questions about debugging:

  1. What is the difference between a breakpoint and a debugger?

    A breakpoint is a specific location in your code where you want the debugger to pause execution. The debugger is the tool (e.g., in your code editor or browser) that allows you to control the execution of your code, step through it, and inspect variables.

  2. Why is my debugger not working?

    Make sure you have set up your environment correctly (Node.js, TypeScript, code editor). Ensure that you are compiling your TypeScript code before running it. Also, double-check that you are running the code in debug mode (e.g., using node --inspect-brk).

  3. How do I debug code in a web browser?

    Most modern web browsers have built-in developer tools. Open the developer tools (usually by pressing F12), go to the “Sources” tab, and you can set breakpoints and step through your JavaScript code. If you’re using TypeScript, you might need to debug the compiled JavaScript files (in the dist directory) or use source maps to debug the original TypeScript code.

  4. What are source maps?

    Source maps are files that map your compiled JavaScript code back to your original TypeScript code. They allow you to debug your TypeScript code directly in the browser’s developer tools, even though the browser is executing the compiled JavaScript. To use source maps, you need to configure your TypeScript compiler to generate them (check the sourceMap option in your tsconfig.json).

By using these tools and techniques, you’ll be able to quickly identify and fix bugs, leading to more reliable and robust software. Debugging is not just about fixing errors; it is about understanding your code at a deeper level. The more you practice, the more efficient you’ll become at finding and resolving issues. You’ll gain a better understanding of how your code works and how to prevent bugs in the first place. Embrace the debugging process as a learning opportunity; it’s a critical skill for any successful developer.

More posts