TypeScript โปรเจกต์: REST API



โปรเจกต์รวบยอด — REST API ที่ type-safe ตั้งแต่ request body ถึง database

API

GET    /notes         รายการ
GET    /notes/:id      ตัวเดียว
POST   /notes          สร้าง
PUT    /notes/:id      แก้ไข
DELETE /notes/:id      ลบ

setup

npm init -y && npm pkg set type=module
npm install express better-sqlite3 zod
npm install --save-dev typescript tsx @types/express @types/better-sqlite3 @types/node vitest supertest @types/supertest

โครงสร้าง

notes-api/
├── src/
│   ├── index.ts          entry
│   ├── app.ts            สร้าง express app (แยกจาก listen เพื่อเทสต์)
│   ├── db.ts
│   ├── notes/
│   │   ├── schema.ts     zod
│   │   ├── repository.ts
│   │   └── routes.ts
│   └── middleware/
│       ├── errors.ts
│       └── async-handler.ts
└── tests/notes.test.ts

src/notes/schema.ts

import { z } from "zod";

export const NoteSchema = z.object({
  id: z.number().int().positive(),
  title: z.string(),
  body: z.string(),
  createdAt: z.string(),
  updatedAt: z.string(),
});
export type Note = z.infer<typeof NoteSchema>;

export const NoteInputSchema = z.object({
  title: z.string().trim().min(1).max(200),
  body: z.string().max(100_000).default(""),
});
export type NoteInput = z.infer<typeof NoteInputSchema>;

export const IdParamSchema = z.object({
  id: z.coerce.number().int().positive(),
});

src/middleware/errors.ts

export class NotFoundError extends Error {
  constructor(resource: string) {
    super(`${resource} ไม่พบ`);
    this.name = "NotFoundError";
  }
}

import { type ErrorRequestHandler } from "express";
import { ZodError } from "zod";

export const errorHandler: ErrorRequestHandler = (err, _req, res, _next) => {
  if (err instanceof ZodError) {
    res.status(422).json({
      error: "validation failed",
      issues: err.issues.map((i) => ({ path: i.path.join("."), message: i.message })),
    });
    return;
  }
  if (err instanceof NotFoundError) {
    res.status(404).json({ error: err.message });
    return;
  }
  console.error("unhandled error:", err);
  res.status(500).json({ error: "internal server error" });
};

src/middleware/async-handler.ts

import { type RequestHandler } from "express";

export function asyncHandler(fn: RequestHandler): RequestHandler {
  return (req, res, next) => {
    Promise.resolve(fn(req, res, next)).catch(next);
  };
}

src/db.ts

import Database from "better-sqlite3";

export function createDb(path: string): Database.Database {
  const db = new Database(path);
  db.pragma("journal_mode = WAL");
  db.exec(`
    CREATE TABLE IF NOT EXISTS notes (
      id         INTEGER PRIMARY KEY AUTOINCREMENT,
      title      TEXT NOT NULL,
      body       TEXT NOT NULL DEFAULT '',
      created_at TEXT NOT NULL DEFAULT (datetime('now')),
      updated_at TEXT NOT NULL DEFAULT (datetime('now'))
    )
  `);
  return db;
}

src/notes/repository.ts

import type Database from "better-sqlite3";
import { NotFoundError } from "../middleware/errors.js";
import { type Note, type NoteInput } from "./schema.js";

interface NoteRow {
  id: number;
  title: string;
  body: string;
  created_at: string;
  updated_at: string;
}

function toNote(row: NoteRow): Note {
  return {
    id: row.id,
    title: row.title,
    body: row.body,
    createdAt: row.created_at,
    updatedAt: row.updated_at,
  };
}

export class NoteRepository {
  constructor(private db: Database.Database) {}

  list(): Note[] {
    const rows = this.db
      .prepare<[], NoteRow>("SELECT * FROM notes ORDER BY id DESC")
      .all();
    return rows.map(toNote);
  }

  get(id: number): Note {
    const row = this.db
      .prepare<[number], NoteRow>("SELECT * FROM notes WHERE id = ?")
      .get(id);
    if (!row) throw new NotFoundError(`note #${id}`);
    return toNote(row);
  }

  create(input: NoteInput): Note {
    const result = this.db
      .prepare("INSERT INTO notes (title, body) VALUES (?, ?)")
      .run(input.title, input.body);
    return this.get(Number(result.lastInsertRowid));
  }

  update(id: number, input: NoteInput): Note {
    const result = this.db
      .prepare("UPDATE notes SET title = ?, body = ?, updated_at = datetime('now') WHERE id = ?")
      .run(input.title, input.body, id);
    if (result.changes === 0) throw new NotFoundError(`note #${id}`);
    return this.get(id);
  }

  delete(id: number): void {
    const result = this.db.prepare("DELETE FROM notes WHERE id = ?").run(id);
    if (result.changes === 0) throw new NotFoundError(`note #${id}`);
  }
}

src/notes/routes.ts

import { Router } from "express";
import { NoteRepository } from "./repository.js";
import { NoteInputSchema, IdParamSchema } from "./schema.js";
import { asyncHandler } from "../middleware/async-handler.js";

export function noteRoutes(repo: NoteRepository): Router {
  const router = Router();

  router.get("/", asyncHandler(async (_req, res) => {
    res.json(repo.list());
  }));

  router.get("/:id", asyncHandler(async (req, res) => {
    const { id } = IdParamSchema.parse(req.params);   // throw ZodError → 422
    res.json(repo.get(id));
  }));

  router.post("/", asyncHandler(async (req, res) => {
    const input = NoteInputSchema.parse(req.body);
    res.status(201).json(repo.create(input));
  }));

  router.put("/:id", asyncHandler(async (req, res) => {
    const { id } = IdParamSchema.parse(req.params);
    const input = NoteInputSchema.parse(req.body);
    res.json(repo.update(id, input));
  }));

  router.delete("/:id", asyncHandler(async (req, res) => {
    const { id } = IdParamSchema.parse(req.params);
    repo.delete(id);
    res.status(204).end();
  }));

  return router;
}

src/app.ts

import express, { type Express } from "express";
import type Database from "better-sqlite3";
import { NoteRepository } from "./notes/repository.js";
import { noteRoutes } from "./notes/routes.js";
import { errorHandler } from "./middleware/errors.js";

export function createApp(db: Database.Database): Express {
  const app = express();
  app.use(express.json({ limit: "1mb" }));

  app.get("/health", (_req, res) => res.json({ status: "ok" }));
  app.use("/notes", noteRoutes(new NoteRepository(db)));

  app.use(errorHandler);   // สุดท้ายเสมอ
  return app;
}

src/index.ts

import { createApp } from "./app.js";
import { createDb } from "./db.js";

const db = createDb(process.env.DB_PATH ?? "notes.db");
const app = createApp(db);
const port = Number(process.env.PORT ?? 3000);

const server = app.listen(port, () => {
  console.log(`listening on :${port}`);
});

process.on("SIGTERM", () => {
  server.close(() => {
    db.close();
    process.exit(0);
  });
});

tests/notes.test.ts

import { describe, it, expect, beforeEach } from "vitest";
import request from "supertest";
import Database from "better-sqlite3";
import { createApp } from "../src/app.js";
import { createDb } from "../src/db.js";

describe("notes API", () => {
  let app: ReturnType<typeof createApp>;

  beforeEach(() => {
    const db = new Database(":memory:");
    createDb(":memory:");   // (จริง ๆ ควร refactor createDb ให้รับ Database)
    // สร้าง schema ใน :memory: db
    db.exec(`CREATE TABLE notes (id INTEGER PRIMARY KEY AUTOINCREMENT,
      title TEXT NOT NULL, body TEXT NOT NULL DEFAULT '',
      created_at TEXT NOT NULL DEFAULT (datetime('now')),
      updated_at TEXT NOT NULL DEFAULT (datetime('now')))`);
    app = createApp(db);
  });

  it("POST /notes → 201 + note", async () => {
    const res = await request(app)
      .post("/notes")
      .send({ title: "เรียน TS", body: "บทที่ 43" });

    expect(res.status).toBe(201);
    expect(res.body).toMatchObject({ id: expect.any(Number), title: "เรียน TS" });
  });

  it("POST /notes ว่าง title → 422", async () => {
    const res = await request(app).post("/notes").send({ title: "" });
    expect(res.status).toBe(422);
    expect(res.body.issues).toBeDefined();
  });

  it("GET /notes/:id ไม่มี → 404", async () => {
    const res = await request(app).get("/notes/999");
    expect(res.status).toBe(404);
  });

  it("full CRUD", async () => {
    const { body: created } = await request(app).post("/notes").send({ title: "a", body: "b" });
    await request(app).put(`/notes/${created.id}`).send({ title: "c", body: "d" }).expect(200);
    await request(app).get(`/notes/${created.id}`).expect(200);
    await request(app).delete(`/notes/${created.id}`).expect(204);
    await request(app).get(`/notes/${created.id}`).expect(404);
  });
});
npx vitest run

จุดที่รวมทั้งซีรีส์

ส่วนบท
Express typed handler, middleware, error handler, async wrapper39
zod schema + z.infer + .parse() (throw ZodError)30
z.coerce.number() สำหรับ route params30, 36
custom error NotFoundError + instanceof ใน error handler27
repository pattern (class รับ Database)12, 19
แยก app.ts (createApp) จาก index.ts (listen) — เทสต์ได้37
better-sqlite3 generic prepare<Params, Row>11
supertest + :memory: db, beforeEach fresh34

เรื่องที่คนมักพลาด

  • req.body typed แล้วไม่ validate — zod .parse() ทุก body (throw → error handler → 422)
  • error handler ก่อน route — ต้องอยู่หลัง (app.use(errorHandler) สุดท้าย)
  • async handler ไม่ wrap — error หาย; asyncHandler
  • createApp เรียก app.listen ข้างใน — เทสต์ไม่ได้; แยก createApp(db) จาก listen
  • better-sqlite3 .get() คืน row | undefined — เช็คก่อน toNote
  • z.number() สำหรับ route param — param เป็น string; z.coerce.number()
  • ไม่ db.close() ตอน shutdown — WAL file ค้าง

สรุป

  • โครง: createApp(db) (ไม่ listen) + index.ts (listen + shutdown) — เทสต์ผ่าน supertest(app)
  • zod schema = validate + type: NoteInputSchema.parse(req.body), IdParamSchema.parse(req.params) (z.coerce.number())
  • repository class รับ Database — prepare<Params, Row>().get()/all()/run(); throw NotFoundError
  • error handler เดียว — ZodError → 422, NotFoundError → 404, อื่น → 500 (หลัง route ทั้งหมด)
  • asyncHandler wrap ทุก async route
  • test: supertest + new Database(":memory:") + beforeEach fresh + go test -race เทียบไม่มี (JS single-thread)

บทสุดท้ายจากที่นี่มี 3 โปรเจกต์: state machine, form validator, React app — บทถัดไปคือ typed finite state machine