TypeScript: Types, Generics, Utility Types and Narrowing Reference Guide

# New project (Node)
npm init -y
npm install -D typescript @types/node
npx tsc --init                        # generates tsconfig.json

# Direct run without a build step
npm install -D tsx
npx tsx src/index.ts                  # ts-node replacement, ESM-friendly

# Type check only (no emit)
npx tsc --noEmit

# Format + lint
npm install -D eslint typescript-eslint prettier
npx eslint . --fix

# Bun / Deno — first-class TS support, no install needed
bun run src/index.ts
deno run src/index.ts

// Generic function
function pluck(obj: T, key: K): T[K] {
  return obj[key];
}
pluck({ name: "Ada", age: 36 }, "name");   // string

// Generic class with default
class Box {
  constructor(public value: T) {}
}

// Conditional + infer — peel off the array element type
type ElementOf = T extends readonly (infer U)[] ? U : never;
type N = ElementOf;              // number

// Mapped type with key remapping
type Getters = {
  [K in keyof T as `get${Capitalize}`]: () => T[K];
};
type UserGetters = Getters<{ name: string; age: number }>;
// { getName: () => string; getAge: () => number }

// Branded / nominal types via intersection
type UserId = string & { readonly __brand: "UserId" };
const asUserId = (s: string): UserId => s as UserId;

// Discriminated union — the canonical pattern
type Shape =
  | { kind: "circle"; r: number }
  | { kind: "square"; side: number };

function area(s: Shape): number {
  switch (s.kind) {
    case "circle": return Math.PI * s.r ** 2;
    case "square": return s.side ** 2;
    default:       return assertNever(s);   // exhaustive
  }
}
function assertNever(x: never): never { throw new Error(`unreachable: ${x}`); }

// User-defined type guards
function isString(x: unknown): x is string {
  return typeof x === "string";
}

// Assertion functions
function assertDefined(x: T | undefined): asserts x is T {
  if (x === undefined) throw new Error("undefined");
}

// satisfies — keep literal types AND check shape
const config = {
  port: 3000,
  level: "info",
} satisfies { port: number; level: "info" | "warn" | "error" };
// type of config.level stays "info" (literal), not the union.

{
  "compilerOptions": {
    /* Output */
    "target":             "ES2022",
    "module":             "NodeNext",
    "moduleResolution":   "NodeNext",
    "outDir":             "dist",
    "rootDir":            "src",
    "sourceMap":          true,
    "declaration":        true,

    /* Strictness — turn ALL of these on */
    "strict":                       true,
    "noUncheckedIndexedAccess":     true,
    "noImplicitOverride":           true,
    "noFallthroughCasesInSwitch":   true,
    "exactOptionalPropertyTypes":   true,
    "noImplicitReturns":            true,

    /* Hygiene */
    "skipLibCheck":               true,
    "esModuleInterop":            true,
    "forceConsistentCasingInFileNames": true,
    "isolatedModules":            true,

    /* Project paths */
    "baseUrl": "src",
    "paths": { "@/*": ["*"] }
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

// Tiny typed HTTP client — generics + Zod for runtime validation.
import { z } from "zod";

const User = z.object({
  id: z.number().int().positive(),
  name: z.string(),
  email: z.string().email(),
});
type User = z.infer;

class HttpError extends Error {
  constructor(public status: number, message: string) { super(message); }
}

async function getJSON(
  url: string,
  schema: S,
  init?: RequestInit,
): Promise> {
  const res = await fetch(url, init);
  if (!res.ok) throw new HttpError(res.status, await res.text());

  const data: unknown = await res.json();
  const parsed = schema.safeParse(data);
  if (!parsed.success) throw new Error(`Bad payload: ${parsed.error.message}`);
  return parsed.data;
}

const u: User = await getJSON("https://api.example.com/users/42", User);
console.log(u.email);                     // type-safe + runtime-validated