TypeScript Reference

Both define object shapes, but they differ in key ways. Interfaces support declaration merging (multiple interface declarations with the same name are automatically combined), making them ideal for library APIs that users might need to extend. Types support union types (type ID = string | number), intersection types, mapped types, and conditional types. A common convention is to use interfaces for public API contracts and types for unions, utility types, and internal definitions.

Use unknown whenever you receive a value of uncertain type but want to maintain type safety. Unlike any, which disables all type checking, unknown requires you to narrow the type before performing operations. For example, you cannot call .toUpperCase() on an unknown value until you verify it is a string with typeof. This makes unknown the type-safe alternative for values from external sources like API responses or user input.

Generic constraints use extends to limit which types can be passed as type arguments. For example, <T extends HasLength> requires that T has a length property. This allows you to write function logLength<T extends HasLength>(arg: T) that accepts strings, arrays, or any object with a length property, while rejecting types like number that lack it. Constraints can also use keyof: <K extends keyof T> restricts K to valid property names of T.

A discriminated union is a union type where each member has a common literal property (the discriminant) that TypeScript uses for narrowing. For example, type Shape = { kind: "circle"; radius: number } | { kind: "rect"; width: number; height: number }. In a switch on s.kind, TypeScript knows the exact type in each case branch. Use this pattern for state machines, action types in reducers, and any scenario with a finite set of distinct variants.

Partial<T> makes all properties optional, useful for update functions where you only change some fields. Pick<T, K> creates a type with only the selected properties: Pick<User, "name" | "age"> gives { name: string; age: number }. Omit<T, K> is the inverse, creating a type with all properties except the specified ones. These can be composed: Partial<Pick<User, "name" | "email">> creates a type where name and email are both optional.

The satisfies operator (TypeScript 4.9+) validates that a value matches a type without widening its inferred type. For example, const palette = { red: [255, 0, 0], green: "#00ff00" } satisfies Record<string, string | number[]> checks that palette matches the Record type, but palette.red is still inferred as number[] (not string | number[]), so you can call .map() on it. Without satisfies, you would lose the specific type information.

Type-only imports (import type { User } from "./types") are completely erased during compilation, producing no JavaScript output. This ensures that importing a type from a large module does not pull that module into your bundle. You can also use inline syntax: import { type Config, createApp } from "./app" to mix type and value imports in a single statement. This is especially important with bundlers that use tree-shaking.

Enable "strict": true to activate all strict checks at once, including strictNullChecks (null and undefined must be explicitly handled), noImplicitAny (all variables must have explicit or inferable types), strictFunctionTypes (function parameter types are checked contravariantly), and strictPropertyInitialization (class properties must be initialized). These options catch the most common TypeScript errors at compile time and are recommended for all new projects.