Learning TypeScript: Fundamentals, Data Structures, & Algorithms

Welcome to your first-year Software Engineering guide to TypeScript (TS)! This repository is designed specifically for polytechnic students. It focuses on terminal-based execution (no HTML/CSS required) to teach you programming fundamentals, how TypeScript differs from JavaScript, and how to implement classic data structures and algorithms with strong type safety.

---

📚 Table of Contents

1. TypeScript vs. JavaScript: The Fundamentals
2. Prerequisites & Setup
3. Running the Code Examples
4. Course Walkthrough & Exercises
5. Suggested Lab Curriculum Schedule
6. Automated Testing Guide
7. Code Quality & Styling (ESLint & Prettier)
8. Complexity Reference Guide (Big O)
9. Algorithms & Data Structures Pedagogical Notes
10. Terminal Mini-Project Guide

---

1. TypeScript vs. JavaScript: The Fundamentals

TypeScript is a syntactic superset of JavaScript. This means any valid JavaScript code is also valid TypeScript. However, TypeScript adds static typing on top of JavaScript's dynamic type system.

Key Differences Comparison

Feature	JavaScript (JS)	TypeScript (TS)
Typing Discipline	Dynamic: Variables can hold any type; types are determined and coerced at runtime.	Static: Types are declared and checked when compiling; variables have locked types.
Error Detection	Runtime: Type errors (e.g., calling a non-existent function) crash only when the code executes.	Compile-Time: Errors are highlighted in your code editor and stop compilation before execution.
Tooling & IDEs	Limited autocompletion because the editor doesn't know the shapes of variables.	Advanced Intellisense, auto-imports, and refactoring because TS knows exact object shapes.
Compilation Step	Runs directly in browsers or Node.js without compiling.	Must be compiled (transpiled) into plain JS using the TypeScript Compiler (tsc).

---

2. Prerequisites & Setup

To run this repository on your computer, you must have Node.js installed.

Step-by-Step Installation

1. Download Node.js: Install the LTS version from nodejs.org.
2. Clone / Open the Project: Navigate to this directory in your terminal.
3. Install Dependencies: Run the following command in your terminal to install the TypeScript compiler, testing runner, and styling tools:

   npm install

---

3. Running the Code Examples

We have pre-configured short terminal commands in package.json to let you execute each chapter's example instantly.

Command	Description	What it Runs
npm run build	Compiles TS files to JS	TypeScript compiler (tsc) outputs to dist/
npm run run:01-js	JS Runtime Bug Demo	Executes src/01_ts_vs_js/runtime_error.js using Node
npm run run:01-ts	TS Compile-time Protection	Executes src/01_ts_vs_js/compile_error.ts using ts-node
npm run run:02	Basic Types, Enums, and Unions	Executes src/02_basic_types/types.ts using ts-node
npm run run:03	Functions and Type Narrowing	Executes src/03_functions/functions.ts using ts-node
npm run run:04-stack	LIFO Stack Data Structure	Executes src/04_data_structures/stack.ts using ts-node
npm run run:04-list	Singly Linked List Structure	Executes src/04_data_structures/linked_list.ts using ts-node
npm run run:05-sort	Bubble Sort (Numeric & Generic)	Executes src/05_algorithms/bubble_sort.ts using ts-node
npm run run:05-search	Binary Search (number | null)	Executes src/05_algorithms/binary_search.ts using ts-node
npm run run:06	Readline Terminal I/O Demo	Executes src/06_readline/readline_demo.ts using ts-node
npm start	Interactive Task Queue CLI	Launches the terminal mini-project menu loop
npm run test	Run all unit tests	Executes all vitest test suites in the repository
npm run test:watch	Run tests in watch mode	Starts interactive vitest watcher for exercises
npm run test:ci	Run CI tests	Runs vitest only on completed chapters to check types
npm run lint	Scan code syntax style	Audits all TypeScript files using ESLint checks
npm run format	Auto-format files	Standardizes file formats using Prettier styling

---

4. Course Walkthrough & Exercises

The codebase is organized logically into chapters, configurations, and student exercises:

⚙️ Configuration & Tooling Files

• package.json: Declares third-party libraries (TypeScript, ts-node, ESLint, Prettier, Vitest) and execution shortcuts.
• tsconfig.json: Standard strict compiler guidelines.
• .eslintrc.json: Syntax style rules designed to ignore template stubs while checking for code safety.
• .prettierrc: Enforces quotes, semicolons, and indentations.
• .github/workflows/ci.yml: Continuous integration pipeline executing compiling, style checks, and tests on push.

📂 src/01_ts_vs_js/

• runtime_error.js: Demonstrates silent coercion errors and runtime null pointer crashes in JS.
• compile_error.ts: Shows TypeScript flagging those same bugs during development.

📂 src/02_basic_types/ and src/03_functions/

• types.ts: Covers primitive types, arrays, tuples, enums, unions, and any vs unknown.
• functions.ts: Covers parameters, return typing, defaults, rest operators, and callback types.

📂 src/04_data_structures/ and src/05_algorithms/

• stack.ts: Functional LIFO Stack implementation.
• linked_list.ts: Functional Singly Linked List.
• bubble_sort.ts: Numeric and generic sorting implementation.
• binary_search.ts: Fast $O(\log n)$ search returning unions.

📂 src/06_readline/

• readline_demo.ts: Explains the Node.js native readline module in TypeScript. Demonstrates:
  1. Callback-based user input.
  2. Modern async/await promise queries (used in our final project).
  3. Processing text files line-by-line using input streams (sample.txt).

📂 src/exercises/ (Practice Labs)

This directory contains code challenges designed for students to write their own implementations:

1. queue.ts: Implement a generic First-In, First-Out (FIFO) Queue.
2. linear_search.ts: Implement a generic Linear Search returning number | null.

---

5. Suggested Lab Curriculum Schedule

For teachers structuring a syllabus, or students studying independently, here is the recommended path through this repository:

graph TD
    A["Lab 1: JS vs TS (Ch 1)"] --> B["Lab 2: Basic Types (Ch 2)"]
    B --> C["Lab 3: Typing Functions (Ch 3)"]
    C --> D["Lab 4: The Stack & LinkedList (Ch 4)"]
    D --> E["Lab 5: CHALLENGE - Build a Queue (Exercise)"]
    E --> F["Lab 6: Sorting & Search Algorithms (Ch 5)"]
    F --> G["Lab 7: CHALLENGE - Linear Search (Exercise)"]
    G --> I["Lab 8: Node Readline Terminal I/O (Ch 6)"]
    I --> H["Lab 9: Final Project (CLI Task Manager)"]

Loading

1. Lab 1: Understanding Compile-time Safety
   • Files: runtime_error.js and compile_error.ts
   • Activity: Run npm run run:01-js and observe the crash. Open compile_error.ts and inspect how TS catches this before running. Run npm run run:01-ts.
2. Lab 2: Declaring Data Types
   • Files: types.ts
   • Activity: Read through the file and run npm run run:02. Notice the difference between any and unknown type safety.
3. Lab 3: Input & Output Contracts
   • Files: functions.ts
   • Activity: Study how function parameters, return types, optional/default values, and callback signatures are typed. Run npm run run:03.
4. Lab 4: Building Data Structures
   • Files: stack.ts and linked_list.ts
   • Activity: Study the generic implementations. Run them using npm run run:04-stack and npm run run:04-list to trace how elements move.
5. Lab 5: Practice Exercise — FIFO Queue
   • Files: queue.ts (Test suite: queue.test.ts)
   • Activity: Complete the Queue implementation TODO stubs. Run npm run test or npm run test:watch to verify your solution against the unit tests.
6. Lab 6: Complex Algorithms
   • Files: bubble_sort.ts and binary_search.ts
   • Activity: Study how Bubble Sort utilizes comparators and how Binary Search operates in $O(\log n)$ time. Run npm run run:05-sort and npm run run:05-search.
7. Lab 7: Practice Exercise — Linear Search
   • Files: linear_search.ts (Test suite: linear_search.test.ts)
   • Activity: Open the exercise file, implement the linear search logic, and run npm run test to check if your code passes the assertions.
8. Lab 8: Input/Output and Streams
   • Files: readline_demo.ts (Data source: sample.txt)
   • Activity: Run npm run run:06 and interact with the terminal inputs. Examine readline_demo.ts to see how streams and async processes work.
9. Lab 9: The Terminal Project
   • Files: index.ts (CLI Menu), task_manager.ts (Logic), and types.ts (Models)
   • Activity: Run npm start to interact with the Task Queue. Review the codebase to see how it ties all the semester's concepts (data structures, sorting, binary search, readline, interfaces) together.

---

6. Automated Testing Guide

We use Vitest for running unit tests. The tests check if code is implemented correctly.

Run Tests Once

To run all test suites once (great for checking if your exercises are correct):

npm run test

(Initially, the Queue and Linear Search tests will fail. Your goal is to write code in src/exercises/ to make them pass!)

Run Tests in Watch Mode

To start an interactive runner that automatically re-runs tests every time you save a file:

npm run test:watch

---

7. Code Quality & Styling (ESLint & Prettier)

In software engineering, teams use automated tools to ensure consistent code styling and code safety.

Linter (ESLint)

To run ESLint and scan your code for potential bugs, unused variables, or bad styling practices:

npm run lint

Formatter (Prettier)

To automatically format all your files (fixing indentation, quotes, semi-colons):

npm run format

---

8. Complexity Reference Guide (Big O)

To learn about computational efficiency, time complexity, and space complexity, read the dedicated guide:

• Big O Complexity Reference Guide: Explains constant $O(1)$, logarithmic $O(\log n)$, linear $O(n)$, and quadratic $O(n^2)$ costs, comparing our implemented structures.

---

9. Algorithms & Data Structures Pedagogical Notes

The Power of TypeScript Generics <T>

Without TypeScript generics, writing a stack or linked list in JavaScript means it can accept any data type, meaning you could push a number, then a string, then a boolean, leading to bugs. In TypeScript, declaring createStack<string>() tells the compiler to only allow strings to be pushed, protecting your queue from type mismatches.

Handling Nullability (| null)

In many languages (including JavaScript), accessing elements on a null reference causes sudden crashes. TypeScript enforces strict null checks. When traversing a linked list node (node.next), TypeScript forces you to check if the next node is null before accessing node.next.value.

---

10. Terminal Mini-Project Guide

The culminating project is located in src/project/. It is an interactive, menu-driven command-line Task Queue & Priority Processor.

Project Codebase Architecture

• types.ts: Declares the Task interface, the TaskPriority enum, and the TaskQueue type.
• task_manager.ts: Contains pure/utility functions for:
  • Enqueuing tasks (addTask).
  • Sorting tasks by priority (High -> Medium -> Low) using custom Bubble Sort.
  • Sorting tasks by ID and using Binary Search to look up tasks.
  • Dequeuing tasks (processNextTask).
• index.ts: Standard CLI input-output loop.

How to Run and Interact

Start the program using:

npm start

You will be prompted with a menu to add tasks, sort them by priority level, search for tasks by ID, process them, and print the queue status directly to the terminal!