Week 1: Node.js & TypeScript Fundamentals

1. The Event Loop & Non-Blocking I/O

Node.js runs your JavaScript on a single thread, which sounds like a limitation until you understand what it doesn't block on. When your code calls something I/O-bound — reading a file, querying a database, making an HTTP request — Node hands that work off to the underlying system (via libuv's thread pool or the OS's async I/O) and keeps executing other code. When the I/O finishes, its callback is queued to run on the main thread. That queue-and-resume mechanism is the event loop.

console.log("1: start");

setTimeout(() => console.log("2: timeout"), 0);

fs.readFile(__filename, () => console.log("3: file read done"));

console.log("4: end");

// Output order: 1, 4, 3 (or 2), 2 (or 3)
// "1" and "4" run synchronously, back to back -- the event loop
// never gets a chance to run anything else until the synchronous
// code finishes. "2" and "3" are both async callbacks whose exact
// relative order depends on I/O timing, but BOTH always run after
// every synchronous line above them, never interleaved with it.

The practical consequence: any CPU-bound work you do synchronously — a huge JSON parse, a tight loop, a heavy computation — blocks that single thread completely, and every other request your server is handling stalls until it finishes. This is the single most important mental model in this course: Node's concurrency model is excellent for I/O-bound work (which is most of what a typical REST API does — waiting on a database, waiting on another service) and actively bad for CPU-bound work done on the main thread.

2. Modules, npm/pnpm & Project Structure

Modern Node projects use ES modules (import/ export) rather than the older CommonJS require/ module.exports — this course uses ES modules throughout, since that's also what TypeScript and modern tooling default to:

export function add(a: number, b: number): number {
  return a + b;
}

export const PI = 3.14159;

import { add, PI } from "./math.js"; // note the .js extension, even in a .ts file

console.log(add(2, 3), PI);

package.json is every Node project's manifest — dependencies, scripts, and metadata npm uses to install and run your project:

{
  "name": "week-01-fundamentals",
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "build": "tsc",
    "start": "node dist/main.js",
    "dev": "tsx watch src/main.ts"
  },
  "dependencies": {},
  "devDependencies": {
    "typescript": "^5.5.0",
    "tsx": "^4.16.0",
    "@types/node": "^20.14.0"
  }
}

"type": "module" tells Node to treat .js files as ES modules by default, which matters once TypeScript compiles down to plain JavaScript. Dependency versions follow semantic versioning (MAJOR.MINOR.PATCH): a caret like ^5.5.0 allows npm to install any 5.x.x release but never 6.0.0, since a major version bump signals a breaking change by convention.

my-api/
├── src/
│   ├── main.ts          # entry point
│   ├── routes/           # Express routers (Week 2+)
│   └── lib/              # shared utilities
├── dist/                 # compiled output (gitignored)
├── package.json
├── tsconfig.json
└── .gitignore

3. TypeScript Setup for Node

TypeScript adds a compile-time type system on top of JavaScript — it catches an entire class of bugs (calling a function with the wrong argument type, accessing a property that doesn't exist) before your code ever runs, at the cost of a compile step. tsconfig.json is where you tell the compiler how to do that compilation:

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

"strict": true is the single most important setting in this file — it enables the full set of strict type-checking rules (no implicit any, strict null checks, and more), and every lesson in this course assumes it's on. Turning it off makes TypeScript significantly less useful; you'd be paying the compile-step cost without most of the safety benefit. "module": "NodeNext" paired with "moduleResolution": "NodeNext" tells TypeScript to compile using the same module resolution rules Node itself uses at runtime, which is why the import in Section 2's main.ts needed an explicit .js extension even though the source file is .ts — the compiler emits that path unchanged into the compiled output, where the file really is .js.

npm install
npm run build   # runs tsc, compiles src/ -> dist/
npm start       # runs the compiled output with node

# or, for local development without a manual compile step:
npm run dev     # tsx watch src/main.ts -- recompiles and restarts on save

tsx compiles and runs TypeScript directly in development without a separate build step — you'll use npm run dev constantly through this course, and reserve the full tsc build for what actually ships (Week 14's Docker image runs the compiled dist/ output, never tsx itself).

4. Writing & Running Your First Script

Put the event loop and TypeScript setup together in one small script that demonstrates non-blocking I/O concretely:

import { readFile } from "node:fs/promises";

async function main(): Promise<void> {
  console.log("Starting two reads at the same time...");

  const start = Date.now();

  // Both reads are kicked off before either has to finish --
  // this is non-blocking I/O in practice, not just in theory.
  const [pkg, tsconfig] = await Promise.all([
    readFile("package.json", "utf-8"),
    readFile("tsconfig.json", "utf-8"),
  ]);

  console.log(`Both files read in ${Date.now() - start}ms`);
  console.log(`package.json is ${pkg.length} bytes`);
  console.log(`tsconfig.json is ${tsconfig.length} bytes`);
}

main().catch((err: unknown) => {
  console.error("Failed:", err);
  process.exitCode = 1;
});

Promise.all starts both reads concurrently rather than sequentially — the total time is roughly the time of the slower read, not the sum of both, because neither read blocks the thread while waiting on disk I/O. main().catch(...) at the top level is a pattern you'll use constantly: an unhandled rejection in an async function doesn't crash Node the way a thrown synchronous error does, so catching it explicitly and setting process.exitCode is what makes a script fail loudly and with the correct exit code, instead of silently.

5. Hands-on Exercise

6. Knowledge Check

Four quick questions. Expand each to check your answer.