The Complete TypeScript Mastery Guide

Introduction - What Is TypeScript & Why It Exists

1.1 Definition

TypeScript (TS) is an open-source language developed and maintained by Microsoft. It is a strict syntactical superset of JavaScript - every valid JavaScript program is also a valid TypeScript program - that adds an optional static structural type system on top of JS semantics. TypeScript never changes JavaScript's runtime behavior; it only adds a compile-time layer that is erased before the code runs.

Key mental model: TypeScript types are a development-time tool. At runtime, there is no TypeScript - only plain JavaScript. This has a critical implication: TypeScript can be lied to (e.g., via as, any, unsafe casts) and it cannot protect you against bad data arriving from the network, disk, or user input unless you validate it (see §18 on runtime validation).

1.2 Why TypeScript? (Beyond the Basics)

1.3 JavaScript vs TypeScript - Concrete Comparison

// JavaScript - no static checks, error only discovered at runtime (or never, silently)
let user = { name: "Asha", age: 25 };
user.age = "twenty five"; // no error, silently corrupts data

// TypeScript - the type annotation creates a compile-time contract
let typedUser: { name: string; age: number } = { name: "Asha", age: 25 };
typedUser.age = "twenty five"; // Incorrect - compile error:
// Type 'string' is not assignable to type 'number'.

1.4 How TypeScript Works Internally (Compiler Pipeline)

Understanding the pipeline is what separates "I use TS" from "I understand TS":

1. Parsing - Source .ts text is tokenized and parsed into an Abstract Syntax Tree (AST).
2. Binding - The binder walks the AST and creates symbols (a "Symbol" is TypeScript's internal representation of a named entity - variable, function, class, etc.) and builds scopes.
3. Type Checking - The type checker walks the AST, resolves types (via inference and annotations), and validates every expression against the type rules. This is where 95% of "the compiler complains" moments come from.
4. Emit - Type annotations are stripped and the AST is transformed/down-leveled to the JavaScript target (e.g., ES2020, CommonJS/ESM modules) and written to .js files. Optionally, .d.ts declaration files and source maps are emitted.

Because type erasure happens at step 4, types cannot be used for runtime logic (e.g., you cannot do if (x instanceof SomeInterface) - interfaces don't exist at runtime; only classes, which compile to real JS constructor functions, support instanceof).

1.5 The Learning & Production Roadmap

Practice discipline that senior engineers follow:

• Enable strict: true from day one of a project - retrofitting strict mode onto a large loose codebase is far more expensive than starting strict.
• Treat the type system as executable documentation: if a reviewer has to ask "what shape is this?", the types are incomplete.
• Never treat any as a shortcut to "make the red squiggly go away" - it is a designed escape hatch to be used sparingly and explicitly, not a default.

Installation, Setup & tsconfig.json Deep Dive

2.1 Prerequisites

Install Node.js (LTS version) from https://nodejs.org - TypeScript's compiler (tsc) runs on Node.

Install TypeScript:

npm install -g typescript   # global CLI (fine for learning)
npm install -D typescript   # project-local (required for production - pins version per-repo)
tsc -v                      # verify installation

Production best practice: always install TypeScript as a local devDependency, never rely on a global install. This guarantees every developer and every CI runner compiles with the exact same compiler version, avoiding "works on my machine" type-checking drift.

Initialize configuration:

npx tsc --init

This generates tsconfig.json, the single source of truth for how the compiler behaves.

2.2 Compiling & Running

tsc                      # compiles the whole project per tsconfig.json
tsc app.ts               # compiles a single file, ignoring tsconfig module resolution nuances
tsc -w                   # watch mode - recompiles on save; use during local development
node dist/app.js         # run the emitted JavaScript

For iterative development, most production teams skip the manual tsc + node cycle and use ts-node, tsx, or a bundler (esbuild, swc, vite) for near-instant feedback, then use tsc --noEmit purely as a type-checking gate in CI (bundlers strip types without checking them - tsc is what catches errors).

2.3 tsconfig.json - Every Option That Matters in Production

{
  "compilerOptions": {
    /* --- Type Checking (strictness) --- */
    "strict": true,                              // umbrella flag - turns on all strict flags below
    "noImplicitAny": true,                       // (included in strict) disallow untyped `any` fallbacks
    "strictNullChecks": true,                    // (included in strict) null/undefined are NOT part of every type
    "strictFunctionTypes": true,                 // (included in strict) sound function parameter checking
    "strictBindCallApply": true,                 // (included in strict) type-check .bind/.call/.apply
    "strictPropertyInitialization": true,        // (included in strict) class fields must be initialized
    "noImplicitThis": true,                      // (included in strict) error on `this` with implied `any`
    "alwaysStrict": true,                        // (included in strict) emit "use strict" in JS output
    "noUncheckedIndexedAccess": true,            // index signature access returns `T | undefined` (huge safety win, NOT in strict by default)
    "exactOptionalPropertyTypes": true,          // `foo?: string` means "absent or string", NOT "string | undefined"
    "noImplicitOverride": true,                  // require explicit `override` keyword when overriding base methods
    "noFallthroughCasesInSwitch": true,          // catch missing `break` in switch statements
    "noUnusedLocals": true,                      // flag unused local variables
    "noUnusedParameters": true,                  // flag unused function parameters

    /* --- Modules & Interop --- */
    "module": "NodeNext",                        // or "ESNext" for bundler-based frontends
    "moduleResolution": "NodeNext",              // matches Node's actual ESM/CJS resolution algorithm
    "esModuleInterop": true,                     // allows `import express from "express"` for CJS packages
    "resolveJsonModule": true,                   // allows `import data from "./data.json"`
    "isolatedModules": true,                     // ensures every file can be transpiled independently (required by esbuild/swc/babel)
    "verbatimModuleSyntax": true,                // forces explicit `import type` for type-only imports (faster builds, no ambiguity)

    /* --- Emit --- */
    "target": "ES2022",                          // JS language level of the OUTPUT
    "outDir": "./dist",                          // compiled output folder
    "rootDir": "./src",                          // source folder (enforces output mirrors input structure)
    "declaration": true,                         // emit .d.ts files - REQUIRED if you publish a library
    "declarationMap": true,                      // enables "go to definition" into your TS source from consumers
    "sourceMap": true,                           // enables debugger breakpoints in original .ts files
    "removeComments": false,                     // keep comments (JSDoc) in emitted .d.ts for consumer IntelliSense

    /* --- Interop / Safety --- */
    "skipLibCheck": true,                        // skip type-checking .d.ts files of dependencies (big compile-speed win, safe in practice)
    "forceConsistentCasingInFileNames": true,    // avoid cross-OS casing bugs (macOS/Windows are case-insensitive, Linux CI is not)
    "allowJs": false,                            // set true only during incremental JS→TS migration
    "checkJs": false,                            // set true alongside allowJs to type-check the JS files too

    /* --- Paths --- */
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]                           // path aliases - must be mirrored in your bundler/test runner config
    }
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist", "**/*.spec.ts"]
}

Senior-level tsconfig guidance:

• Never ship a production repo without strict: true. Anything less is an unfinished migration, not a design choice.
• noUncheckedIndexedAccess is one of the highest-value flags most teams forget - without it, arr[i] and obj[key] are typed as if they always succeed, which is false and a common source of runtime undefined bugs.
• For monorepos, use TypeScript Project References ("composite": true, "references": [{ "path": "../shared" }]) so tsc --build only recompiles changed packages - this is what makes large monorepos compile fast.
• Keep tsconfig.base.json at the repo root with shared strict settings, and let each package extend it - this is the DRY principle applied to configuration.

Variables & the Complete Type System

3.1 let, const, and (avoid) var

let score: number = 98.6;   // reassignable, block-scoped
const PI: number = 3.14159; // NOT reassignable, block-scoped
var legacy = "avoid";       // function-scoped, hoisted, error-prone - do not use in modern TS

Production rule: default to const. Only use let when a binding is genuinely reassigned (loop counters, accumulator variables, values reassigned in conditional branches). var should never appear in a modern TypeScript codebase - enforce this with the ESLint rule no-var.

3.2 Primitive Types

3.3 The Special Types - any, unknown, void, never

// any - completely disables type checking for that value. AVOID.
let danger: any = "hello";
danger.toUpperCase().thisMethodDoesNotExist(); // compiles fine, crashes at runtime

// unknown - the type-safe counterpart to any. Anything can be assigned TO it,
// but it cannot be USED until narrowed. This is the correct type for
// "data I don't yet know the shape of" (e.g., API responses, JSON.parse results).
let result: unknown = fetchSomething();
if (typeof result === "string") {
  console.log(result.toUpperCase()); // Correct - safe - narrowed
}

// void - a function that returns nothing meaningful.
function logMessage(msg: string): void {
  console.log(msg);
}

// never - a value that can never occur: functions that always throw,
// or infinite loops, or the empty branch of an exhaustive union.
function fail(message: string): never {
  throw new Error(message);
}

any vs unknown - the single most important type-safety decision in TS. any opts a value entirely out of the type system (bidirectionally assignable to and from anything). unknown opts in to safety - it can receive anything, but you must prove its shape (via typeof, instanceof, a type guard, or a schema validator) before you can operate on it.

Rule for production code: ban any via ESLint (@typescript-eslint/no-explicit-any), and use unknown at every true boundary (API responses, JSON.parse, third-party untyped libraries, catch clause errors).

3.4 Type Inference vs Explicit Annotation

let inferred = "hello"; // TS infers `string` - no annotation needed
let explicit: string = "hi"; // explicit annotation - useful for function signatures & public APIs

Guideline: let TypeScript infer types for local variables where the initial value makes the type obvious. Use explicit annotations for function parameters, return types, and public API boundaries where the contract must be clear to consumers.