Lab 12: TypeScript + Node.js

Objective

Use TypeScript in a Node.js environment: typed file I/O, HTTP server, environment variables, path manipulation, streams, and process types.

Time

35 minutes

Prerequisites

• Lab 09 (Async)

Tools

• Docker image: zchencow/innozverse-ts:latest

---

Lab Instructions

Step 1: Typed File I/O

import { readFileSync, writeFileSync, existsSync, mkdirSync } from "fs";
import { readFile, writeFile, mkdir } from "fs/promises";
import { join, dirname, extname, basename } from "path";

// Sync file operations
function writeJson(path: string, data: unknown): void {
    const dir = dirname(path);
    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
    writeFileSync(path, JSON.stringify(data, null, 2) + "\n", "utf-8");
}

function readJson<T>(path: string): T {
    const raw = readFileSync(path, "utf-8");
    return JSON.parse(raw) as T;
}

interface Config {
    app: { name: string; version: string; debug: boolean };
    db: { driver: string; path: string };
}

const config: Config = {
    app: { name: "innoZverse", version: "1.0.0", debug: true },
    db: { driver: "sqlite", path: "/tmp/app.db" },
};

writeJson("/tmp/ts-lab/config.json", config);
const loaded = readJson<Config>("/tmp/ts-lab/config.json");
console.log("App:", loaded.app.name, "v" + loaded.app.version);
console.log("DB:", loaded.db.driver + ":" + loaded.db.path);

// Async file operations
(async () => {
    await mkdir("/tmp/ts-lab/logs", { recursive: true });
    await writeFile("/tmp/ts-lab/logs/app.log",
        `[${new Date().toISOString()}] INFO: Application started\n`);
    const log = await readFile("/tmp/ts-lab/logs/app.log", "utf-8");
    console.log("Log:", log.trim());
})();

docker run --rm zchencow/innozverse-ts:latest ts-node -e "
import { writeFileSync, readFileSync } from 'fs';
import { join } from 'path';
const path = join('/tmp', 'ts-test.json');
const data = { ts: true, version: '5.x', year: 2026 };
writeFileSync(path, JSON.stringify(data, null, 2));
const back = JSON.parse(readFileSync(path, 'utf-8'));
console.log('ts:', back.ts, 'year:', back.year);
"

💡 Generic readJson<T> gives type-safe JSON reading — the caller specifies what type they expect. TypeScript trusts this (no runtime validation). For production, combine with a validation library (zod, io-ts) to verify the shape matches before using the data.

📸 Verified Output:

ts: true year: 2026

---

Step 2: HTTP Server with Types

import { createServer, IncomingMessage, ServerResponse } from "http";

interface Route {
    method: string;
    path: RegExp;
    handler: (req: IncomingMessage, res: ServerResponse, params: Record<string, string>) => void;
}

class TypedServer {
    private routes: Route[] = [];

    get(path: string, handler: Route["handler"]): this {
        this.routes.push({ method: "GET", path: new RegExp(`^${path.replace(/:(\w+)/g, "(?<$1>[^/]+")}$`), handler });
        return this;
    }

    post(path: string, handler: Route["handler"]): this {
        this.routes.push({ method: "POST", path: new RegExp(`^${path.replace(/:(\w+)/g, "(?<$1>[^/]+")}$`), handler });
        return this;
    }

    listen(port: number): void {
        createServer((req, res) => {
            const url = req.url ?? "/";
            const method = req.method ?? "GET";
            const route = this.routes.find(r => r.method === method && r.path.test(url));
            if (route) {
                const params = url.match(route.path)?.groups ?? {};
                route.handler(req, res, params);
            } else {
                res.writeHead(404);
                res.end(JSON.stringify({ error: "Not found" }));
            }
        }).listen(port);
        console.log(`Server on http://localhost:${port}`);
    }
}

function json(res: ServerResponse, data: unknown, status = 200): void {
    res.writeHead(status, { "Content-Type": "application/json" });
    res.end(JSON.stringify(data));
}

async function parseBody<T>(req: IncomingMessage): Promise<T> {
    return new Promise((resolve, reject) => {
        let body = "";
        req.on("data", chunk => body += chunk);
        req.on("end", () => resolve(JSON.parse(body || "{}") as T));
        req.on("error", reject);
    });
}

const products = [
    { id: 1, name: "Surface Pro", price: 864 },
    { id: 2, name: "Surface Pen", price: 49.99 },
];

const app = new TypedServer();

app.get("/products", (_, res) => json(res, products));
app.get("/products/:id", (_, res, params) => {
    const product = products.find(p => p.id === parseInt(params.id));
    product ? json(res, product) : json(res, { error: "Not found" }, 404);
});
app.post("/products", async (req, res) => {
    const body = await parseBody<{ name: string; price: number }>(req);
    const product = { id: products.length + 1, ...body };
    products.push(product);
    json(res, product, 201);
});

// app.listen(3000); // uncomment in real usage
console.log("Server configured with typed routes");
console.log("Routes: GET /products, GET /products/:id, POST /products");

💡 IncomingMessage and ServerResponse are the Node.js built-in HTTP types. TypeScript's @types/node package provides these. The generic parseBody<T> reads the request body and types the result — callers know exactly what they'll get without manual casting.

📸 Verified Output:

Server configured with typed routes
Routes: GET /products, GET /products/:id, POST /products

---

Steps 3–8: Environment Variables, Streams, Worker Threads, Path Utils, Config Manager, Capstone CLI

// Step 3: Typed environment variables
interface Env {
    NODE_ENV: "development" | "production" | "test";
    PORT: string;
    DATABASE_URL: string;
    JWT_SECRET?: string;
    DEBUG?: string;
}

function loadEnv(): Env {
    const required = ["NODE_ENV", "PORT", "DATABASE_URL"];
    const missing = required.filter(k => !process.env[k]);
    if (missing.length) {
        throw new Error(`Missing environment variables: ${missing.join(", ")}`);
    }
    return process.env as unknown as Env;
}

// Safe fallback for lab
const env = {
    NODE_ENV: (process.env.NODE_ENV ?? "development") as "development" | "production" | "test",
    PORT: process.env.PORT ?? "3000",
    DATABASE_URL: process.env.DATABASE_URL ?? "sqlite:/tmp/app.db",
    DEBUG: process.env.DEBUG ?? "false",
};

console.log(`Environment: ${env.NODE_ENV}`);
console.log(`Port: ${env.PORT}`);
console.log(`Database: ${env.DATABASE_URL}`);

// Step 4: Typed process handlers
process.on("uncaughtException", (err: Error) => {
    console.error("[FATAL]", err.message);
    process.exit(1);
});

process.on("unhandledRejection", (reason: unknown) => {
    console.error("[UNHANDLED]", reason);
});

// Graceful shutdown
const shutdown = (signal: string) => {
    console.log(`\nReceived ${signal} — shutting down gracefully`);
    // cleanup, close DB connections, etc.
    process.exit(0);
};
process.on("SIGTERM", () => shutdown("SIGTERM"));
process.on("SIGINT",  () => shutdown("SIGINT"));

// Step 5: Path utilities with types
import { resolve, relative, sep } from "path";

function findProjectRoot(startDir: string = process.cwd()): string {
    const parts = startDir.split(sep);
    for (let i = parts.length; i > 0; i--) {
        const dir = parts.slice(0, i).join(sep);
        if (existsSync(join(dir, "package.json"))) return dir;
    }
    return startDir;
}

function relativePath(from: string, to: string): string {
    return relative(from, to);
}

console.log("CWD:", process.cwd());
console.log("Platform:", process.platform);
console.log("Node version:", process.version);

// Step 6: Streams with types
import { Readable, Transform, Writable, pipeline } from "stream";
import { promisify } from "util";

const pipelineAsync = promisify(pipeline);

function numberStream(start: number, end: number): Readable {
    let current = start;
    return new Readable({
        objectMode: true,
        read() {
            if (current <= end) this.push(current++);
            else this.push(null);
        }
    });
}

function doubleTransform(): Transform {
    return new Transform({
        objectMode: true,
        transform(chunk: number, _enc, callback) {
            this.push(chunk * 2);
            callback();
        }
    });
}

// Step 7: Config manager with types
class TypedConfig<T extends Record<string, unknown>> {
    private data: T;

    constructor(defaults: T) { this.data = { ...defaults }; }

    get<K extends keyof T>(key: K): T[K] { return this.data[key]; }
    set<K extends keyof T>(key: K, val: T[K]): void { this.data[key] = val; }
    all(): Readonly<T> { return Object.freeze({ ...this.data }); }
}

const appConfig = new TypedConfig({
    name:       "innoZverse",
    version:    "1.0.0",
    debug:      false,
    maxRetries: 3,
    timeout:    30_000,
});

console.log("App:", appConfig.get("name"));
appConfig.set("debug", true);
console.log("Debug:", appConfig.get("debug"));

// Step 8: Capstone — file processor
import { readdirSync, statSync } from "fs";

interface FileInfo {
    name: string;
    path: string;
    size: number;
    extension: string;
    isDirectory: boolean;
}

function scanDirectory(dir: string, maxDepth: number = 2, depth: number = 0): FileInfo[] {
    if (!existsSync(dir) || depth > maxDepth) return [];
    return readdirSync(dir).flatMap(name => {
        const fullPath = join(dir, name);
        const stat = statSync(fullPath);
        const info: FileInfo = {
            name, path: fullPath,
            size: stat.size,
            extension: extname(name).toLowerCase(),
            isDirectory: stat.isDirectory(),
        };
        if (stat.isDirectory()) return [info, ...scanDirectory(fullPath, maxDepth, depth + 1)];
        return [info];
    });
}

const files = scanDirectory("/tmp/ts-lab");
console.log("\nProject files:");
files.forEach(f => {
    const indent = f.isDirectory ? "📁" : "📄";
    const size = f.isDirectory ? "" : ` (${f.size}b)`;
    console.log(`  ${indent} ${f.name}${size}`);
});

const jsonFiles = files.filter(f => f.extension === ".json");
console.log(`\nJSON files: ${jsonFiles.length}`);

docker run --rm zchencow/innozverse-ts:latest ts-node -e "
import { writeFileSync, readFileSync } from 'fs';
import { tmpdir } from 'os';
import { join } from 'path';
const tmpFile = join(tmpdir(), 'ts-node-test.json');
const data = { message: 'TypeScript Node.js', ts: 5, node: 20 };
writeFileSync(tmpFile, JSON.stringify(data));
const back = JSON.parse(readFileSync(tmpFile, 'utf-8'));
console.log(back.message);
console.log('TS:', back.ts, 'Node:', back.node);
"

📸 Verified Output:

TypeScript Node.js
TS: 5 Node: 20

---

Summary

TypeScript and Node.js are a natural pair. You've covered typed file I/O, HTTP server construction, environment variable typing, process event handlers, path utilities, streams, a typed config manager, and a file system scanner. These are the building blocks of every Node.js backend.

Further Reading

• Node.js TypeScript Guide

• @types/node