Node.js with TypeScript: Complete Theory & Practice Guide

1. Theory: Type System Fundamentals

TypeScript is a statically typed superset of JavaScript that compiles to plain JavaScript. It adds optional types, classes, interfaces, and modern ECMAScript features.

┌─────────────────────────────────────────────────────────────┐
│                    TypeScript Compilation                    │
├─────────────────────────────────────────────────────────────┤
│   TypeScript Code (.ts)      JavaScript Code (.js)          │
│   function greet(name: string): string { ... }              │
│             tsc compiles and erases types                   │
│   function greet(name) { ... }                              │
│   • Types removed at compile time                           │
│   • Zero runtime overhead                                   │
│   • 100% JavaScript compatibility                           │
└─────────────────────────────────────────────────────────────┘

type TypeHierarchy = {
    'any': 'Opt-out of type checking (avoid)',
    'unknown': 'Type-safe alternative to any',
    'void': 'No return value',
    'never': 'Function never returns',
    'Primitives': 'string, number, boolean, symbol, bigint',
    'Literal types': '"red" | "blue"',
    'Union types': 'string | number',
    'Intersection types': 'A & B',
    'Generics': 'Type variables (T, U, V)'
};

const typescriptBenefits = {
    earlyErrorDetection: {
        problem: 'Cannot read property on undefined',
        solution: 'Caught at compile time'
    },
    ideSupport: ['Autocomplete', 'Rename refactor', 'Find references'],
    selfDocumenting: 'Types communicate API contracts',
    refactoring: 'Type changes reveal impacted code instantly'
};

2. Theory: Compilation & Runtime

┌─────────────────────────────────────────────────────────────────┐
│                    TypeScript Compilation Flow                   │
├─────────────────────────────────────────────────────────────────┤
│ .ts/.tsx → Parser → AST → Type Checker → Transformer → .js/.d.ts │
│          syntax     type errors     target config output        │
└─────────────────────────────────────────────────────────────────┘

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "commonjs",
    "moduleResolution": "node",
    "strict": true,
    "noImplicitAny": true,
    "strictNullChecks": true,
    "noUnusedLocals": true,
    "noImplicitReturns": true,
    "outDir": "./dist",
    "rootDir": "./src",
    "sourceMap": true,
    "declaration": true,
    "esModuleInterop": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist", "**/*.test.ts"]
}

// TypeScript source
interface User { id: number; name: string; email: string; }
class UserService {
  async getUser(id: number): Promise { return db.findUser(id); }
}

// Compiled JS (types erased)
class UserService {
  async getUser(id) { return db.findUser(id); }
}

3. Basic: Setup & Configuration

# Initialize project
npm init -y
npm install --save-dev typescript @types/node
npx tsc --init
npm install --save-dev nodemon ts-node

{
  "scripts": {
    "build": "tsc",
    "build:watch": "tsc --watch",
    "start": "node dist/server.js",
    "dev": "nodemon --exec ts-node src/server.ts",
    "type-check": "tsc --noEmit",
    "clean": "rm -rf dist"
  }
}

// src/server.ts
import express, { Request, Response, NextFunction, Application } from 'express';

interface User { id: number; name: string; email: string; createdAt: Date; }
interface CreateUserRequest { name: string; email: string; }
interface ApiResponse { success: boolean; data?: T; error?: string; timestamp: string; }

class UserController {
  private users: User[] = [];
  private nextId = 1;
  async createUser(req: Request<{}, {}, CreateUserRequest>, res: Response>): Promise {
    const { name, email } = req.body;
    if (!name || !email) { res.status(400).json({ success: false, error: 'Name and email are required', timestamp: new Date().toISOString() }); return; }
    const newUser: User = { id: this.nextId++, name, email, createdAt: new Date() };
    this.users.push(newUser);
    res.status(201).json({ success: true, data: newUser, timestamp: new Date().toISOString() });
  }
}

const app: Application = express();
app.use(express.json());
const userController = new UserController();
app.post('/api/users', (req, res) => userController.createUser(req, res));
const PORT: number = parseInt(process.env.PORT || '3000', 10);
app.listen(PORT, () => console.log(`Server running on http://localhost:${PORT}`));

4. Theory: Type Safety Benefits

type Status = 'pending' | 'approved' | 'rejected';
type ID = string | number;

function processInput(input: string | number): string {
  if (typeof input === 'string') return input.toUpperCase();
  return input.toFixed(2);
}

function isUser(obj: any): obj is User {
  return obj && typeof obj.id === 'number' && typeof obj.name === 'string';
}

type ApiState =
  | { status: 'idle' }
  | { status: 'loading' }
  | { status: 'success'; data: User[] }
  | { status: 'error'; error: string };

interface Repository {
  findById(id: ID): Promise;
  findAll(): Promise;
  create(entity: Omit): Promise;
  update(id: ID, entity: Partial): Promise;
  delete(id: ID): Promise;
}

// Utility types
type ProductUpdate = Partial;
type CompleteProduct = Required;
type ImmutableProduct = Readonly;
type ProductPreview = Pick;
type ProductWithoutDates = Omit;
type UserRoles = Record;

5. Advanced: Design Patterns

// Dependency Injection sketch
interface Database { query(sql: string, params?: any[]): Promise; }
interface Logger { info(message: string, metadata?: Record): void; }
interface UserRepository { findById(id: number): Promise; }

class UserService {
  constructor(private readonly userRepository: UserRepository, private readonly logger: Logger) {}
  async getUser(id: number): Promise {
    const user = await this.userRepository.findById(id);
    if (!user) throw new Error('User not found');
    return user;
  }
}

// Result type pattern
type Result =
  | { success: true; value: T }
  | { success: false; error: E };

class ResultFactory {
  static ok(value: T): Result { return { success: true, value }; }
  static err(error: E): Result { return { success: false, error }; }
}

6. Advanced: Decorators & Metadata

// Enable: "experimentalDecorators": true, "emitDecoratorMetadata": true
function Get(path: string = '/'): MethodDecorator {
  return (target: any, propertyKey: string | symbol) => {
    const routes = Reflect.getMetadata('routes', target.constructor) || [];
    routes.push({ method: 'get', path, handler: propertyKey });
    Reflect.defineMetadata('routes', routes, target.constructor);
  };
}

function Controller(basePath: string): ClassDecorator {
  return (target: any) => Reflect.defineMetadata('basePath', basePath, target);
}

@Controller('/api/users')
class UserController {
  @Get('/:id')
  async getUser(@Param('id') id: string): Promise {
    return await this.userService.getUser(parseInt(id));
  }
}

7. Theory: Integration Strategies

const migrationStrategies = {
  tsconfig: {
    compilerOptions: { allowJs: true, checkJs: true, outDir: './dist' },
    include: ['src/**/*.ts', 'src/**/*.js']
  },
  incremental: {
    step1: 'Rename .js to .ts',
    step2: 'Fix obvious type errors (use any temporarily)',
    step3: 'Add explicit types and remove any'
  }
};

// Extending Express types
declare global {
  namespace Express {
    interface Request {
      user?: { id: number; role: 'admin' | 'user' };
      startTime: number;
    }
    interface Response {
      sendJson(data: T): this;
    }
  }
}

8. Best Practices

const typescriptStandards = {
  explicitTypes: 'Use explicit function parameter/return types',
  avoidImplicitAny: 'Enable noImplicitAny and avoid fallback any',
  constAssertions: 'Use as const for precise literal types',
  discriminatedUnions: 'Model state machines safely',
  readonlyData: 'Mark immutable fields and inputs readonly'
};

{
  "compilerOptions": {
    "strict": true,
    "noImplicitAny": true,
    "strictNullChecks": true,
    "noUnusedLocals": true,
    "target": "ES2022",
    "module": "commonjs",
    "outDir": "./dist",
    "sourceMap": true,
    "declaration": true,
    "incremental": true
  }
}

// Common TS error examples
const user = await db.findUser(id);
console.log(user.name);   // ❌ possibly undefined
console.log(user?.name);  // ✅ safe

const value: unknown = getValue();
if (typeof value === 'string') console.log(value.toUpperCase()); // ✅

# Quick commands
npm install -D typescript @types/node
npx tsc --init
npx tsc
npx tsc --watch
npx tsc --noEmit
npx ts-node src/server.ts
npm install -D @typescript-eslint/eslint-plugin @typescript-eslint/parser

10 Interview Questions + 10 MCQs

Contextual Learning Links

• Docker for Node.js - compile TS to `dist` and ship minimal production images
• Testing Node.js Apps - strongly typed test helpers and safer refactoring
• Building REST APIs - typed request/response DTOs and validation boundaries
• Environment Config - type-safe config parsing and startup validation
• Deploying Node.js Projects - production TypeScript build and runtime workflow