# TypeScript Language Reference
## Languages — The Codex Coding
**URL:** https://thecodex.expert/coding/languages/typescript/
**Type:** language-reference | **Confidence:** high | **Last verified:** 2026-06-01

## CANONICAL DEFINITION
TypeScript is a statically typed superset of JavaScript, developed by Microsoft, that adds optional type annotations, interfaces, generics, and advanced type system features to JavaScript — compiling to plain JavaScript with all types erased, providing compile-time type safety without any runtime overhead.

## QUICK FACTS
- **Created:** 2012 by Anders Hejlsberg at Microsoft
- **Version:** TypeScript 5.x (2024)
- **Relation:** Strict superset of JavaScript — all valid JS is valid TS
- **Typing:** Static, structural (not nominal)
- **Output:** Compiles to plain JavaScript; all types erased
- **Runtime:** None — TypeScript types do not exist at runtime

## CRITICAL NOTES
- **Types are erased at runtime** — `instanceof MyInterface` fails; interfaces don't exist at runtime
- **strict mode is NOT on by default** — always set `"strict": true` in tsconfig.json
- **Structural typing**: compatible shape = compatible type, regardless of declared name
- **Valid JS = valid TS**: rename .js to .ts and it compiles (may have type errors, but compiles)
- **Type system is Turing-complete**: conditional + mapped types can express arbitrary computations

## KEY TYPES
- Primitives: string, number, boolean, bigint, symbol, undefined, null
- Special: any (disables type checking), unknown (safe any), never (unreachable), void
- Compound: `T[]` or `Array<T>`, `[T, U]` (tuple), `Record<K,V>`, `Map<K,V>`, `Set<T>`
- Utility types: `Partial<T>`, `Required<T>`, `Readonly<T>`, `Pick<T,K>`, `Omit<T,K>`, `ReturnType<F>`, `Parameters<F>`

## INTERFACES VS TYPE ALIASES
- `interface`: for object shapes; supports declaration merging; extensible with `extends`
- `type`: for unions, intersections, primitives, mapped types, conditional types; cannot be merged
- Generally interchangeable for object shapes; prefer interface for public APIs

## CONFIGURATION
- `tsconfig.json` key settings:
  - `"strict": true` — enables all strict checks (REQUIRED)
  - `"target": "ES2020"` — emitted JS version
  - `"module": "ESNext"` — module system
  - `"noEmit": true` — type-check only, no output (used with esbuild/SWC for emit)

## COMPILATION TOOLS
- `tsc`: official — full type checking + emit; slowest
- esbuild: Go-based — strips types, no checking; ~100x faster; Vite uses this
- SWC: Rust-based — strips types, no checking; Next.js 12+ uses this
- Pattern: `tsc --noEmit` in CI for type checking; esbuild/SWC for builds

## SOURCES
- TypeScript Handbook: typescriptlang.org/docs/handbook/
- TypeScript spec: github.com/microsoft/TypeScript/tree/main/doc
- ECMAScript spec: tc39.es/ecma262/ (TypeScript is a superset)

*The Codex Coding — thecodex.expert/coding/ — Free forever — Mumbai, India*