JavaScript / TypeScript (Node.js) — The Modern Backend Engine

import { db } from "../database.js";
import { readFile } from "node:fs/promises";
import path from "node:path";

export async function getCourseWithSyllabus(req, res, next) {
  try {
    const courseId = Number(req.params.id);

    // 1. Concurrent non-blocking I/O using Promise.all
    const [course, syllabusRaw] = await Promise.all([
      db.query("SELECT * FROM courses WHERE id = $1", [courseId]),
      readFile(path.join(process.cwd(), "data", "syllabi.json"), "utf-8")
    ]);

    if (!course.rows[0]) {
      return res.status(404).json({ error: "Course not found" });
    }

    const syllabusMap = JSON.parse(syllabusRaw);
    const fullCourse = {
      ...course.rows[0],
      syllabus: syllabusMap[courseId] || []
    };

    return res.status(200).json(fullCourse);
  } catch (error) {
    // 2. Always forward unhandled errors to the centralized error middleware!
    console.error("Failed to load course:", error);
    next(error);
  }
}

// 1. Generic API Response Contract shared across all services
export interface ApiResponse<T> {
  success: boolean;
  data?: T;
  error?: string;
  timestamp: string;
}

// 2. Domain Models
export interface Course {
  id: number;
  title: string;
  price: number;
  status: 'draft' | 'published' | 'archived';
}

// 3. Type Narrowing Example
export function formatError(error: unknown): string {
  if (error instanceof Error) {
    return error.message; // Compiler knows 'error' is an Error instance here
  }
  if (typeof error === 'string') {
    return error; // Compiler knows 'error' is a string
  }
  return "An unknown internal error occurred";
}

// 1. SHARED CONTRACT (Imported by BOTH frontend and backend)
export interface CourseDTO {
  id: number;
  title: string;
  price: number;
  status: 'draft' | 'published';
}

// 2. BACKEND CONTROLLER (Node.js)
import type { CourseDTO } from "@company/shared-types";
app.get("/api/courses/:id", async (req, res: Response<CourseDTO>) => {
  const course: CourseDTO = await courseService.getById(Number(req.params.id));
  res.json(course); // TypeScript guarantees the response matches CourseDTO!
});

// 3. FRONTEND CONSUMER (Next.js / React)
import type { CourseDTO } from "@company/shared-types";
const res = await fetch("/api/courses/42");
const course: CourseDTO = await res.json();
console.log(course.title); // Instant autocomplete and zero field-name mismatches!