REST APIs with Express

npm install express
npm install --save-dev @types/express
npx tsx watch src/server.ts      # restarts on every save

import express, { type NextFunction, type Request, type Response } from "express";

export interface Student {
  id: number;
  name: string;
  form: number;
}

interface NewStudent {
  name: string;
  form: number;
}

// A type guard: after it returns true, TypeScript knows `body` is a NewStudent.
function isNewStudent(body: unknown): body is NewStudent {
  if (typeof body !== "object" || body === null) return false;
  const { name, form } = body as Record<string, unknown>;
  return typeof name === "string" && name.trim().length >= 2 && Number.isInteger(form) && (form as number) >= 1 && (form as number) <= 6;
}

export class HttpError extends Error {
  constructor(public status: number, message: string) {
    super(message);
  }
}

export function createApp(students: Student[] = []) {
  const app = express();
  app.use(express.json());                         // parses JSON bodies into req.body
  let nextId = Math.max(0, ...students.map((s) => s.id)) + 1;

  function findStudent(id: string): Student {
    const student = students.find((s) => s.id === Number(id));
    if (!student) throw new HttpError(404, `Student ${id} not found`);
    return student;
  }

  app.get("/students", (_req, res) => {
    res.json(students);
  });

  app.get("/students/:id", (req, res) => {
    res.json(findStudent(req.params.id));
  });

  app.post("/students", (req, res) => {
    if (!isNewStudent(req.body)) throw new HttpError(400, "name (2+ letters) and form (1-6) are required");
    const student: Student = { id: nextId++, name: req.body.name.trim(), form: req.body.form };
    students.push(student);
    res.status(201).location(`/students/${student.id}`).json(student);
  });

  app.patch("/students/:id", (req, res) => {
    const student = findStudent(req.params.id);
    const changes = { ...student, ...req.body, id: student.id };
    if (!isNewStudent(changes)) throw new HttpError(400, "invalid name or form");
    Object.assign(student, { name: changes.name.trim(), form: changes.form });
    res.json(student);
  });

  app.delete("/students/:id", (req, res) => {
    const student = findStudent(req.params.id);
    students.splice(students.indexOf(student), 1);
    res.status(204).end();
  });

  // Unknown routes, then one error handler for everything (Express 5 also catches async errors).
  app.use((_req, res) => {
    res.status(404).json({ error: "Not found" });
  });
  app.use((err: unknown, _req: Request, res: Response, _next: NextFunction) => {
    if (err instanceof HttpError) return res.status(err.status).json({ error: err.message });
    if (err instanceof SyntaxError) return res.status(400).json({ error: "Body must be valid JSON" });
    console.error(err);
    res.status(500).json({ error: "Something went wrong" });
  });

  return app;
}

import { createApp } from "./app";

const port = Number(process.env.PORT ?? 3000);
const app = createApp([{ id: 1, name: "Amina Hassan", form: 4 }]);
app.listen(port, () => console.log(`API on http://localhost:${port}`));

import { after, before, describe, it } from "node:test";
import assert from "node:assert/strict";
import type { AddressInfo } from "node:net";
import type { Server } from "node:http";
import { createApp } from "../src/app";

let server: Server;
let base: string;

before(async () => {
  server = createApp([{ id: 1, name: "Amina Hassan", form: 4 }]).listen(0);   // port 0 = any free port
  await new Promise((resolve) => server.once("listening", resolve));
  base = `http://localhost:${(server.address() as AddressInfo).port}`;
});
after(() => server.close());

const post = (path: string, body: string) =>
  fetch(base + path, { method: "POST", headers: { "Content-Type": "application/json" }, body });

describe("students API", () => {
  it("creates a student and returns 201 with a Location header", async () => {
    const res = await post("/students", JSON.stringify({ name: "Juma Said", form: 3 }));
    assert.equal(res.status, 201);
    assert.equal(res.headers.get("location"), "/students/2");
    assert.deepEqual(await res.json(), { id: 2, name: "Juma Said", form: 3 });
  });

  it("rejects invalid input and broken JSON with 400", async () => {
    assert.equal((await post("/students", JSON.stringify({ name: "J", form: 9 }))).status, 400);
    assert.equal((await post("/students", "{not json")).status, 400);
  });

  it("updates, deletes and then 404s", async () => {
    const patched = await fetch(`${base}/students/1`, {
      method: "PATCH", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ form: 5 }),
    });
    assert.equal((await patched.json()).form, 5);
    assert.equal((await fetch(`${base}/students/1`, { method: "DELETE" })).status, 204);
    assert.equal((await fetch(`${base}/students/1`)).status, 404);
  });
});

node --import tsx --test test/*.test.ts     # runs the HTTP tests