TypeScript กับ Node.js



@types/node

npm install --save-dev @types/node

ให้ type ของ Node built-in: process, fs, path, os, crypto, http, Buffer, URL ฯลฯ

ระบุเวอร์ชันให้ตรง Node ที่ใช้: @types/node@20 สำหรับ Node 20

import built-in modules

import { readFile, writeFile } from "node:fs/promises";
import path from "node:path";
import { createServer } from "node:http";
import { randomUUID } from "node:crypto";

ใช้ prefix node: — ชัดเจนว่าเป็น built-in (ไม่ใช่ npm package), รองรับใน Node 16+

process.env — string | undefined

process.env.PORT;           // string | undefined
process.env.DATABASE_URL;   // string | undefined

const port = process.env.PORT;
const portNum = Number(port);   // NaN ถ้า undefined

วิธี 1: augment (autocomplete แต่ไม่ validate — บทที่ 32)

// env.d.ts
declare global {
  namespace NodeJS {
    interface ProcessEnv {
      DATABASE_URL: string;
      PORT: string;
      NODE_ENV: "development" | "production" | "test";
    }
  }
}
export {};

⚠️ นี่ โกหก — ถ้า env ไม่มีจริง process.env.DATABASE_URL ยังเป็น undefined ตอน runtime

วิธี 2: zod validate ตอน startup (แนะนำ)

// config/env.ts
import { z } from "zod";

const EnvSchema = z.object({
  DATABASE_URL: z.string().url(),
  PORT: z.coerce.number().int().positive().default(3000),
  NODE_ENV: z.enum(["development", "production", "test"]).default("development"),
  JWT_SECRET: z.string().min(32),
  LOG_LEVEL: z.enum(["debug", "info", "warn", "error"]).default("info"),
});

export const env = EnvSchema.parse(process.env);
// env: { DATABASE_URL: string; PORT: number; NODE_ENV: ...; JWT_SECRET: string; LOG_LEVEL: ... }
// ใช้ทั่วโปรเจกต์
import { env } from "./config/env.js";

const server = createServer().listen(env.PORT);

ถ้า env ขาด/ผิด — crash ตอน startup พร้อมข้อความชัด:

ZodError: [
  { path: ["JWT_SECRET"], message: "String must contain at least 32 character(s)" }
]

โหลด .env file: import "dotenv/config" (ก่อน parse) หรือ Node 20.6+ ใช้ --env-file=.env

ESM ใน Node — ไม่มี __dirname

// CommonJS มี __dirname, __filename
// ESM ไม่มี

// Node 20.11+ / 21.2+
import.meta.dirname;    // เท่ากับ __dirname
import.meta.filename;   // เท่ากับ __filename

const configPath = path.join(import.meta.dirname, "config.json");

// เก่ากว่านั้น
import { fileURLToPath } from "node:url";
const __dirname = path.dirname(fileURLToPath(import.meta.url));

fs — promise API

import { readFile, writeFile, mkdir, readdir, stat } from "node:fs/promises";

const content = await readFile("data.json", "utf-8");   // string (ระบุ encoding)
const buffer = await readFile("image.png");             // Buffer (ไม่ระบุ encoding)

await writeFile("out.txt", "hello\n");
await mkdir("logs", { recursive: true });

const files = await readdir("src");                     // string[]
const info = await stat("data.json");
info.isFile();      // boolean
info.size;          // number
info.mtime;         // Date

// เช็คว่ามีไฟล์
import { access } from "node:fs/promises";
try {
  await access("config.json");
  // มี
} catch {
  // ไม่มี
}

resolveJsonModule: true ใน tsconfig → import JSON ตรง ๆ:

import pkg from "../package.json" with { type: "json" };   // Node 20.10+ (import attributes)
console.log(pkg.version);   // typed

path

import path from "node:path";

path.join("a", "b", "c.txt");          // "a/b/c.txt" (หรือ "a\b\c.txt" บน Windows)
path.resolve("data");                   // absolute path
path.dirname("/a/b/c.txt");             // "/a/b"
path.basename("/a/b/c.txt");            // "c.txt"
path.basename("/a/b/c.txt", ".txt");    // "c"
path.extname("report.2026.pdf");        // ".pdf"
path.parse("/a/b/c.txt");               // { root, dir, base, ext, name }

crypto

import { randomUUID, randomBytes, createHash } from "node:crypto";

const id = randomUUID();                                 // string (UUID v4)
const token = randomBytes(32).toString("hex");           // 64-char hex
const hash = createHash("sha256").update("data").digest("hex");

// password hashing — ใช้ argon2 / bcrypt (library) ไม่ใช่ crypto ดิบ

typed process.argv

process.argv;   // string[] — [node, script, ...args]
const args = process.argv.slice(2);

// ใช้ library ที่ typed: commander, yargs (บทที่ 41)

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

  • ไม่ลง @types/node — process, Buffer, built-in modules เป็น error
  • process.env.X ใช้เป็น number/boolean — เป็น string | undefined เสมอ; z.coerce.number() หรือ Number()
  • augment ProcessEnv แล้วคิดว่า runtime ปลอดภัย — type-only; validate ด้วย zod
  • __dirname ใน ESM — ไม่มี; import.meta.dirname (Node 20.11+) หรือ fileURLToPath
  • readFile ไม่ระบุ encoding — ได้ Buffer ไม่ใช่ string; readFile(path, "utf-8")
  • fs sync API ในโค้ด async — block event loop; ใช้ node:fs/promises
  • import "./file" ไม่มีนามสกุล ใน Node ESM — ต้อง .js (บทที่ 22)

สรุป

  • @types/node (เวอร์ชันตรง Node), import ด้วย prefix node: (node:fs/promises, node:path)
  • process.env.X = string | undefined — validate ด้วย zod schema ที่ startup (z.coerce.number(), crash ถ้าขาด)
  • ESM: ไม่มี __dirname — import.meta.dirname (Node 20.11+) หรือ fileURLToPath(import.meta.url)
  • fs/promises: readFile(path, "utf-8") → string (ไม่ระบุ → Buffer); mkdir({ recursive: true })
  • path.join/resolve/dirname/extname, crypto.randomUUID()/randomBytes()
  • resolveJsonModule: true → import JSON typed

บทถัดไปว่าด้วย generics และ type ขั้นสูง — variance, const type parameter, template literal types และ recursive types