refactor: upgrade to Node.js 20 ESM + TypeScript with security chapter

- Add package.json with type:module for ESM throughout
- Add TypeScript 5 strict mode with NodeNext module resolution
- Add src/core-apis/fs.ts: modern fs/promises, streams, pipeline
- Add src/http-server/server.ts: minimal router from scratch (no frameworks)
- Add src/security/security.ts: path traversal, prototype pollution, password hashing
- Add tests using Node.js 20 native node:test runner (no Jest/Mocha)
- Add GitHub Actions CI testing on Node.js 18, 20, and 22

Author: Wscats

.github/workflows/ci.yml

@@ -0,0 +1,25 @@
+name: CI
+
+on:
+  push:
+    branches: [main, refactor]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: ['18.x', '20.x', '22.x']
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: 'npm'
+      - run: npm ci
+      - run: npm run typecheck
+      - run: npm run build
+      - name: Run tests with Node.js native test runner
+        run: node --test dist/tests/**/*.test.js

package.json

@@ -0,0 +1,28 @@
+{
+  "name": "node-tutorial",
+  "version": "2.0.0",
+  "description": "☺️ Node.js 20 Tutorial — ESM, TypeScript, Core APIs, Fastify, Security",
+  "type": "module",
+  "scripts": {
+    "dev": "tsx watch src/index.ts",
+    "build": "tsc",
+    "test": "node --test",
+    "test:watch": "node --test --watch",
+    "lint": "eslint src tests --ext .ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@typescript-eslint/eslint-plugin": "^7.0.0",
+    "@typescript-eslint/parser": "^7.0.0",
+    "eslint": "^9.0.0",
+    "tsx": "^4.7.0",
+    "typescript": "^5.4.0"
+  },
+  "dependencies": {
+    "fastify": "^4.27.0"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}

src/core-apis/fs.ts

@@ -0,0 +1,102 @@
+/**
+ * Chapter 1: Core APIs — fs module
+ * Node.js 20 LTS with ESM and TypeScript
+ */
+
+import { readFile, writeFile, readdir, stat, mkdir, rm } from 'node:fs/promises'
+import { createReadStream, createWriteStream } from 'node:fs'
+import { pipeline } from 'node:stream/promises'
+import { join, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { createGzip } from 'node:zlib'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const TEMP_DIR = join(__dirname, '../../tmp')
+
+// ─── 1. Basic file operations ─────────────────────────────────────────────────
+export async function readTextFile(filePath: string): Promise<string> {
+  return readFile(filePath, 'utf-8')
+}
+
+export async function writeTextFile(filePath: string, content: string): Promise<void> {
+  await writeFile(filePath, content, 'utf-8')
+}
+
+// ─── 2. Directory listing with stats ─────────────────────────────────────────
+export interface FileInfo {
+  name: string
+  size: number
+  isDirectory: boolean
+  modifiedAt: Date
+}
+
+export async function listDirectory(dirPath: string): Promise<FileInfo[]> {
+  const entries = await readdir(dirPath)
+  const infos = await Promise.all(
+    entries.map(async (name) => {
+      const fullPath = join(dirPath, name)
+      const stats = await stat(fullPath)
+      return {
+        name,
+        size: stats.size,
+        isDirectory: stats.isDirectory(),
+        modifiedAt: stats.mtime,
+      }
+    })
+  )
+  return infos
+}
+
+// ─── 3. Stream-based file copy with gzip compression ─────────────────────────
+export async function compressFile(
+  inputPath: string,
+  outputPath: string
+): Promise<void> {
+  const source = createReadStream(inputPath)
+  const gzip = createGzip()
+  const destination = createWriteStream(outputPath)
+  // pipeline handles backpressure and cleanup automatically
+  await pipeline(source, gzip, destination)
+}
+
+// ─── 4. Recursive directory creation ─────────────────────────────────────────
+export async function ensureDir(dirPath: string): Promise<void> {
+  await mkdir(dirPath, { recursive: true })
+}
+
+// ─── Demo runner ──────────────────────────────────────────────────────────────
+async function main() {
+  console.log('=== Node.js 20 fs Module Demo ===\n')
+
+  // Create temp directory
+  await ensureDir(TEMP_DIR)
+  console.log(`✅ Created temp dir: ${TEMP_DIR}`)
+
+  // Write a file
+  const testFile = join(TEMP_DIR, 'hello.txt')
+  await writeTextFile(testFile, 'Hello from Node.js 20!\nThis uses ESM + TypeScript.')
+  console.log(`✅ Written: ${testFile}`)
+
+  // Read it back
+  const content = await readTextFile(testFile)
+  console.log(`✅ Read content:\n${content}`)
+
+  // List directory
+  const files = await listDirectory(TEMP_DIR)
+  console.log(`\n✅ Directory listing (${TEMP_DIR}):`)
+  files.forEach(f => console.log(`  ${f.isDirectory ? '📁' : '📄'} ${f.name} (${f.size} bytes)`))
+
+  // Compress
+  const gzFile = join(TEMP_DIR, 'hello.txt.gz')
+  await compressFile(testFile, gzFile)
+  console.log(`\n✅ Compressed to: ${gzFile}`)
+
+  // Cleanup
+  await rm(TEMP_DIR, { recursive: true, force: true })
+  console.log(`\n✅ Cleaned up temp dir`)
+}
+
+// Run if this is the entry point
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  main().catch(console.error)
+}

src/http-server/server.ts

@@ -0,0 +1,111 @@
+/**
+ * Chapter 2: HTTP Server from scratch
+ * Node.js 20 native http module — no frameworks
+ */
+
+import { createServer, type IncomingMessage, type ServerResponse } from 'node:http'
+import { URL } from 'node:url'
+
+type Handler = (req: IncomingMessage, res: ServerResponse) => void | Promise<void>
+
+interface Route {
+  method: string
+  path: string
+  handler: Handler
+}
+
+// ─── Minimal Router ───────────────────────────────────────────────────────────
+export class Router {
+  private routes: Route[] = []
+
+  get(path: string, handler: Handler): this {
+    this.routes.push({ method: 'GET', path, handler })
+    return this
+  }
+
+  post(path: string, handler: Handler): this {
+    this.routes.push({ method: 'POST', path, handler })
+    return this
+  }
+
+  async handle(req: IncomingMessage, res: ServerResponse): Promise<void> {
+    const url = new URL(req.url ?? '/', `http://${req.headers.host}`)
+    const route = this.routes.find(
+      r => r.method === req.method && r.path === url.pathname
+    )
+
+    if (!route) {
+      res.writeHead(404, { 'Content-Type': 'application/json' })
+      res.end(JSON.stringify({ error: 'Not Found' }))
+      return
+    }
+
+    try {
+      await route.handler(req, res)
+    } catch (err) {
+      res.writeHead(500, { 'Content-Type': 'application/json' })
+      res.end(JSON.stringify({ error: 'Internal Server Error' }))
+    }
+  }
+}
+
+// ─── JSON helpers ─────────────────────────────────────────────────────────────
+export function json(res: ServerResponse, data: unknown, status = 200): void {
+  res.writeHead(status, { 'Content-Type': 'application/json' })
+  res.end(JSON.stringify(data))
+}
+
+export async function parseBody<T>(req: IncomingMessage): Promise<T> {
+  return new Promise((resolve, reject) => {
+    let body = ''
+    req.on('data', chunk => { body += chunk })
+    req.on('end', () => {
+      try { resolve(JSON.parse(body)) }
+      catch (e) { reject(new Error('Invalid JSON')) }
+    })
+    req.on('error', reject)
+  })
+}
+
+// ─── Demo server ──────────────────────────────────────────────────────────────
+interface User {
+  id: number
+  name: string
+  email: string
+}
+
+const users: User[] = [
+  { id: 1, name: 'Alice', email: 'alice@example.com' },
+  { id: 2, name: 'Bob', email: 'bob@example.com' },
+]
+
+const router = new Router()
+
+router.get('/health', (_req, res) => {
+  json(res, { status: 'ok', uptime: process.uptime() })
+})
+
+router.get('/users', (_req, res) => {
+  json(res, users)
+})
+
+router.post('/users', async (req, res) => {
+  const body = await parseBody<Omit<User, 'id'>>(req)
+  const newUser: User = { id: users.length + 1, ...body }
+  users.push(newUser)
+  json(res, newUser, 201)
+})
+
+export function startServer(port = 3000): ReturnType<typeof createServer> {
+  const server = createServer((req, res) => router.handle(req, res))
+  server.listen(port, () => {
+    console.log(`🚀 Server running at http://localhost:${port}`)
+  })
+  return server
+}
+
+// Run if entry point
+import { fileURLToPath } from 'node:url'
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  startServer(3000)
+}

src/security/security.ts

@@ -0,0 +1,129 @@
+/**
+ * Chapter 6: Security Best Practices
+ * Common Node.js security pitfalls and mitigations
+ */
+
+import { join, resolve, normalize } from 'node:path'
+import { readFile } from 'node:fs/promises'
+import { createHash, randomBytes, scrypt, timingSafeEqual } from 'node:crypto'
+import { promisify } from 'node:util'
+
+const scryptAsync = promisify(scrypt)
+
+// ─── 1. Path Traversal Prevention ────────────────────────────────────────────
+const SAFE_BASE_DIR = '/var/www/public'
+
+/**
+ * Safely resolve a user-provided path within a base directory.
+ * Prevents path traversal attacks like ../../etc/passwd
+ */
+export function safeResolvePath(userInput: string, baseDir = SAFE_BASE_DIR): string {
+  const normalized = normalize(userInput).replace(/^(\.\.(\/|\\|$))+/, '')
+  const resolved = resolve(join(baseDir, normalized))
+
+  if (!resolved.startsWith(resolve(baseDir))) {
+    throw new Error(`Path traversal detected: ${userInput}`)
+  }
+
+  return resolved
+}
+
+// ─── 2. Prototype Pollution Prevention ───────────────────────────────────────
+/**
+ * Safely merge objects without allowing prototype pollution.
+ * Blocks keys like __proto__, constructor, prototype
+ */
+export function safeMerge<T extends object>(target: T, source: Record<string, unknown>): T {
+  const BLOCKED_KEYS = new Set(['__proto__', 'constructor', 'prototype'])
+
+  for (const [key, value] of Object.entries(source)) {
+    if (BLOCKED_KEYS.has(key)) {
+      console.warn(`[Security] Blocked prototype pollution attempt: key="${key}"`)
+      continue
+    }
+    if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+      const existing = (target as Record<string, unknown>)[key]
+      if (existing && typeof existing === 'object') {
+        safeMerge(existing as object, value as Record<string, unknown>)
+      } else {
+        (target as Record<string, unknown>)[key] = safeMerge({}, value as Record<string, unknown>)
+      }
+    } else {
+      (target as Record<string, unknown>)[key] = value
+    }
+  }
+  return target
+}
+
+// ─── 3. Secure Password Hashing ──────────────────────────────────────────────
+const SALT_LENGTH = 32
+const KEY_LENGTH = 64
+
+export async function hashPassword(password: string): Promise<string> {
+  const salt = randomBytes(SALT_LENGTH).toString('hex')
+  const derivedKey = await scryptAsync(password, salt, KEY_LENGTH) as Buffer
+  return `${salt}:${derivedKey.toString('hex')}`
+}
+
+export async function verifyPassword(password: string, hash: string): Promise<boolean> {
+  const [salt, storedKey] = hash.split(':')
+  const derivedKey = await scryptAsync(password, salt, KEY_LENGTH) as Buffer
+  const storedKeyBuffer = Buffer.from(storedKey, 'hex')
+  // Use timing-safe comparison to prevent timing attacks
+  return timingSafeEqual(derivedKey, storedKeyBuffer)
+}
+
+// ─── 4. Input Sanitization ────────────────────────────────────────────────────
+/**
+ * Sanitize user input to prevent XSS when rendering HTML
+ */
+export function escapeHtml(input: string): string {
+  return input
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#x27;')
+}
+
+/**
+ * Validate that a string is a safe SQL identifier (no injection)
+ */
+export function isSafeIdentifier(name: string): boolean {
+  return /^[a-zA-Z_][a-zA-Z0-9_]*$/.test(name)
+}
+
+// ─── Demo ─────────────────────────────────────────────────────────────────────
+async function main() {
+  console.log('=== Node.js Security Best Practices Demo ===\n')
+
+  // Path traversal
+  try {
+    safeResolvePath('../../etc/passwd')
+  } catch (e) {
+    console.log(`✅ Path traversal blocked: ${(e as Error).message}`)
+  }
+
+  // Prototype pollution
+  const obj = { a: 1 }
+  safeMerge(obj, { '__proto__': { polluted: true }, b: 2 })
+  console.log(`✅ Prototype pollution blocked. obj.b = ${(obj as Record<string, unknown>).b}`)
+  console.log(`✅ ({} as any).polluted = ${({} as Record<string, unknown>).polluted}`)
+
+  // Password hashing
+  const hash = await hashPassword('my-secret-password')
+  const valid = await verifyPassword('my-secret-password', hash)
+  const invalid = await verifyPassword('wrong-password', hash)
+  console.log(`\n✅ Password hash: ${hash.slice(0, 30)}...`)
+  console.log(`✅ Correct password: ${valid}`)
+  console.log(`✅ Wrong password: ${invalid}`)
+
+  // HTML escaping
+  const userInput = '<script>alert("xss")</script>'
+  console.log(`\n✅ Escaped HTML: ${escapeHtml(userInput)}`)
+}
+
+import { fileURLToPath } from 'node:url'
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  main().catch(console.error)
+}