Node.js & TypeScript Pro Playbook

interface User { username: string; age: number }

function greet(u: User) {
  return `Hi ${u.usernam}`;   // ✗ TS: Property 'usernam' does not exist
}                              //   caught while typing — never ships

greet({ username: "ada" });   // ✗ TS: 'age' is missing
// plain JS: both bugs run fine, then explode at runtime

type Named = { name: string };
function hello(x: Named) { return `hi ${x.name}`; }

const dog = { name: "Rex", legs: 4 };  // not declared as Named...
hello(dog);                             // ✓ structurally compatible

// inference: annotate the boundary, not every local
function total(items: { price: number }[]) {
  return items.reduce((s, i) => s + i.price, 0);  // return inferred: number
}

// interface: object contract you might extend
interface User { id: string; name: string }
interface Admin extends User { role: "admin" }

// type: unions and things interface can't do
type Status = "active" | "banned" | "pending";   // union — needs type
type Point = [number, number];                    // tuple
type WithId<T> = T & { id: string };              // intersection/generic
// rule of thumb: interface for objects/APIs, type for everything else

type Shape =
  | { kind: "circle"; r: number }
  | { kind: "rect"; w: number; h: number };

function area(s: Shape): number {
  switch (s.kind) {
    case "circle": return Math.PI * s.r ** 2;   // s narrowed to circle
    case "rect":   return s.w * s.h;            // s narrowed to rect
    default: {
      const _exhaustive: never = s;   // ✗ compile error if a case is missing
      return _exhaustive;
    }
  }
}

function first<T>(arr: T[]): T | undefined { return arr[0]; }
const n = first([1, 2, 3]);       // n: number  (not any!)
const s = first(["a", "b"]);      // s: string

// constrained generic: T must have an id
function byId<T extends { id: string }>(items: T[], id: string) {
  return items.find((x) => x.id === id);   // returns T | undefined
}
byId(users, "u1");                // keeps the full User type

interface User { id: string; name: string; password: string }

type UserPatch  = Partial<User>;              // all optional (PATCH)
type UserSummary = Pick<User, "id" | "name">;  // list view
type SafeUser   = Omit<User, "password">;      // API response (no secret)
type UsersById  = Record<string, User>;        // { [id]: User } lookup

function toResponse(u: User): SafeUser {
  const { password, ...safe } = u; return safe;   // never leak the secret
}

// BAD: any disables checking and spreads
function parseA(json: string): any { return JSON.parse(json); }
parseA("{}").anything.goes();     // no error → runtime crash

// GOOD: unknown forces a check
function parseU(json: string): unknown { return JSON.parse(json); }
const data = parseU("{}");
if (typeof data === "object" && data && "name" in data) {
  // narrowed — safe to use data.name here
}
// never: exhaustiveness (topic 15) & functions that always throw
function fail(msg: string): never { throw new Error(msg); }

// assertion — no check, dangerous with external data
const risky = JSON.parse(body) as User;    // lies if body isn't a User

// type guard — verifies, then narrows safely
function isUser(x: unknown): x is User {
  return typeof x === "object" && x !== null
    && "id" in x && typeof (x as any).id === "string";
}
const data: unknown = JSON.parse(body);
if (isUser(data)) { save(data); }          // ✓ safe & typed
else { throw new Error("bad payload"); }
// best for whole-object validation: a schema library (zod) — topic 21

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "outDir": "dist",
    "sourceMap": true,
    "esModuleInterop": true
  },
  "include": ["src"]
}

import { z } from "zod";

const CreateUser = z.object({
  email: z.string().email(),
  age: z.number().int().min(0),
});
type CreateUser = z.infer<typeof CreateUser>;   // static type, in sync

app.post("/users", (req, res) => {
  const result = CreateUser.safeParse(req.body);   // runtime check
  if (!result.success) return res.status(400).json(result.error);
  const user = result.data;      // ✓ verified AND typed as CreateUser
  save(user);
});

// 1) most libs: install types if not bundled
//    npm i -D @types/express     (DefinitelyTyped)

// 2) type an untyped JS module yourself (my-lib.d.ts)
declare module "legacy-lib" {
  export function doThing(n: number): string;
}

// 3) AUGMENT an existing type (add req.user to Express) — express.d.ts
declare global {
  namespace Express { interface Request { user?: { id: string } } }
}
export {};   // make this file a module