typescript-expert（TypeScript expert 搜索）

TypeScript Expert

Covers TypeScript through 5.8 (latest stable as of March 2026). The official handbook at https://www.typescriptlang.org/docs/handbook/ is the canonical reference.

TypeScript is a typed superset of JavaScript that compiles to plain JavaScript. Its type system is structural (not nominal), meaning type compatibility is determined by shape rather than declaration. This has profound implications for how you design types and APIs.

Quick Decision Guide

Core Principles

1. Let TypeScript Infer

TypeScript's inference is powerful. Don't annotate what TypeScript can figure out on its own:

// Unnecessary — TypeScript infers `number`
const count: number = 5;

// Good — let inference work
const count = 5;

// DO annotate function signatures (parameters + return types for public APIs)
function getUser(id: string): Promise<User> { ... }

// Return type annotation catches accidental returns
function parse(input: string): ParseResult {
  if (!input) return null; // Error! null isn't ParseResult — good, we caught a bug
}

2. Prefer unknown over any

any disables type checking. unknown is type-safe — you must narrow it before use:

// Bad — silently breaks type safety
function process(data: any) {
  data.foo.bar; // No error, but might crash at runtime
}

// Good — forces you to check before using
function process(data: unknown) {
  if (typeof data === "object" && data !== null && "foo" in data) {
    // Now TypeScript knows data has a foo property
  }
}

3. Use Strict Mode

Always enable "strict": true in tsconfig.json. It enables all strict type-checking flags including strictNullChecks, noImplicitAny, and strictFunctionTypes. Projects that skip strict mode accumulate hidden bugs that surface painfully later. See best-practices-tsconfig for the full recommended configuration.

4. Model Your Domain with Types

The type system is a tool for encoding business rules. Use discriminated unions to model states, branded types for domain identifiers, and readonly to enforce immutability:

// Model states explicitly — impossible to access data in loading/error state
type AsyncState<T> =
  | { status: "loading" }
  | { status: "error"; error: Error }
  | { status: "success"; data: T };

// Branded types prevent ID mixups at compile time
type UserId = string & { readonly __brand: "UserId" };
type OrderId = string & { readonly __brand: "OrderId" };

function getOrder(orderId: OrderId): Order { ... }
getOrder(userId); // Error! UserId is not assignable to OrderId

5. Structural Typing Implications

TypeScript uses structural typing — if two types have the same shape, they're compatible:

interface Point { x: number; y: number }
interface Coordinate { x: number; y: number }

const p: Point = { x: 1, y: 2 };
const c: Coordinate = p; // OK — same shape

// This means excess property checks only apply to object literals
function plot(point: Point) { ... }
plot({ x: 1, y: 2, z: 3 }); // Error — excess property check on literal
const obj = { x: 1, y: 2, z: 3 };
plot(obj); // OK — no excess check on variable

Common Gotchas

TypeScript 5.x Highlights

Key features added in TypeScript 5.0-5.8 (see features-ts5x for details):

When to Read the References

• Writing a new module/library: Read core-generics and best-practices-patterns
• Debugging a confusing type error: Read advanced-type-guards and core-type-system
• Designing a type-safe API: Read advanced-conditional-types and advanced-mapped-types
• Setting up a new project: Read best-practices-tsconfig
• Migrating from JS or older TS: Read features-ts5x and best-practices-tsconfig
• Performance issues with types: Read best-practices-performance