TypeScript Strict Mode Explained: What It Does and Why You Need It

{
  "compilerOptions": {
    // Enabling 'strict' is equivalent to enabling ALL eight flags below.
    // We're spelling them out here so you can see exactly what you're getting.
    "strict": true,

    // --- What 'strict: true' implicitly sets ---

    // 1. null and undefined are NOT assignable to other types.
    //    This is the single most impactful flag.
    "strictNullChecks": true,

    // 2. Variables can't silently become 'any' when TypeScript can't infer a type.
    "noImplicitAny": true,

    // 3. 'this' in functions must have an explicit type — prevents confusing runtime errors.
    "noImplicitThis": true,

    // 4. Class properties must be assigned in the constructor (or declared with '!').
    "strictPropertyInitialization": true,

    // 5. Function parameter types are checked contravariantly (prevents subtle type holes).
    "strictFunctionTypes": true,

    // 6. .bind(), .call(), .apply() are type-checked against the original function signature.
    "strictBindCallApply": true,

    // 7. Every JS file gets 'use strict' emitted at the top automatically.
    "alwaysStrict": true,

    // 8. Catch clause variables are typed as 'unknown' instead of 'any' (TS 4.4+).
    "useUnknownInCatchVariables": true,

    // Recommended companions (not part of 'strict' but work well with it)
    "noUncheckedIndexedAccess": true,  // array[index] returns T | undefined, not just T
    "exactOptionalPropertyTypes": true // { name?: string } means string, NOT string | undefined
  }
}

// --- WITHOUT strict mode (the dangerous default) ---

// TypeScript doesn't complain here — but this function CAN return null.
// Without strictNullChecks, TypeScript believes the return type is just 'User'.
function findUserByIdUnsafe(userId: number) {
  const users = [
    { id: 1, name: 'Alice', email: 'alice@example.com' },
    { id: 2, name: 'Bob',   email: 'bob@example.com'   },
  ];
  // Array.find() returns T | undefined — but without strictNullChecks,
  // TypeScript lets you treat the result as always being T. Danger.
  return users.find(user => user.id === userId);
}

const unsafeUser = findUserByIdUnsafe(99); // User with id 99 does NOT exist
console.log(unsafeUser.name); // RUNTIME CRASH: Cannot read properties of undefined


// --- WITH strict mode (the safe, honest version) ---

interface User {
  id:    number;
  name:  string;
  email: string;
}

// With strictNullChecks active, TypeScript correctly infers the return
// type as 'User | undefined'. You're forced to handle both cases.
function findUserById(userId: number): User | undefined {
  const users: User[] = [
    { id: 1, name: 'Alice', email: 'alice@example.com' },
    { id: 2, name: 'Bob',   email: 'bob@example.com'   },
  ];
  return users.find(user => user.id === userId);
}

// TypeScript now REFUSES to compile this without a null check:
// const brokenUser = findUserById(99);
// console.log(brokenUser.name); // ERROR: Object is possibly 'undefined'

// The correct pattern — narrow the type before using it:
const safeUser = findUserById(1);
if (safeUser !== undefined) {
  // TypeScript knows safeUser is type 'User' inside this block — not 'User | undefined'
  console.log(`Found user: ${safeUser.name} (${safeUser.email})`);
} else {
  console.log('No user found with that ID.');
}

// --- noImplicitAny in action ---

// WITHOUT noImplicitAny, TypeScript silently types 'data' as 'any'.
// Type safety is completely gone for this parameter and everything downstream.
function processDataUnsafe(data) { // TS would allow this without noImplicitAny
  return data.toUpperCase(); // Could crash if 'data' is a number
}

// WITH noImplicitAny — you must declare the type. No more silent escape hatches.
function processData(data: string): string {
  // TypeScript knows this is a string — .toUpperCase() is safe and autocomplete works
  return data.toUpperCase();
}

console.log(processData('hello, world')); // Output: HELLO, WORLD

// ================================================================
// strictPropertyInitialization — Class property safety
// ================================================================

class OrderService {
  // Without strictPropertyInitialization, you could declare these and
  // forget to assign them. At runtime, they'd both be 'undefined'.
  private apiBaseUrl: string;
  private maxRetries: number;

  constructor(apiBaseUrl: string, maxRetries: number) {
    // TypeScript verifies these assignments happen here.
    // Remove either line and you get: "Property has no initializer and
    // is not definitely assigned in the constructor."
    this.apiBaseUrl   = apiBaseUrl;
    this.maxRetries   = maxRetries;
  }

  getOrderEndpoint(orderId: string): string {
    // Safe — TypeScript knows apiBaseUrl is definitely a string here
    return `${this.apiBaseUrl}/orders/${orderId}`;
  }
}

// A class that uses lazy initialization (e.g. set by a framework after construction)
class ReportGenerator {
  // The '!' (definite assignment assertion) tells TypeScript:
  // "Trust me — this WILL be assigned before it's read."
  // Use this sparingly and only when you're 100% sure.
  private templateEngine!: { render: (template: string) => string };

  // Called by a framework (e.g. Angular's ngOnInit) after construction
  initialize(engine: { render: (template: string) => string }): void {
    this.templateEngine = engine;
  }

  generateReport(template: string): string {
    return this.templateEngine.render(template);
  }
}


// ================================================================
// useUnknownInCatchVariables — Safe error handling
// ================================================================

interface ApiError {
  statusCode: number;
  message:    string;
}

// A helper that checks if a thrown value matches our ApiError shape
function isApiError(error: unknown): error is ApiError {
  // We check every property before trusting the shape
  return (
    typeof error === 'object'  &&
    error !== null             &&
    'statusCode' in error      &&
    'message' in error
  );
}

async function fetchOrderDetails(orderId: string): Promise<void> {
  try {
    // Simulating a fetch call that might throw
    const response = await fetch(`https://api.example.com/orders/${orderId}`);

    if (!response.ok) {
      // We throw a structured object, not just a string
      throw { statusCode: response.status, message: 'Order not found' } as ApiError;
    }

    const order = await response.json();
    console.log('Order details:', order);

  } catch (error) {
    // With useUnknownInCatchVariables, 'error' is typed as 'unknown'.
    // TypeScript REFUSES to compile: console.log(error.message)
    // because it doesn't know error has a .message property.

    if (isApiError(error)) {
      // Inside this block TypeScript knows 'error' is ApiError
      console.error(`API Error ${error.statusCode}: ${error.message}`);
    } else if (error instanceof Error) {
      // Standard JS Error objects (network failures, etc.)
      console.error(`Network error: ${error.message}`);
    } else {
      // Someone threw a string, number, or something else entirely
      console.error('An unexpected error occurred:', String(error));
    }
  }
}

// Quick demo of the OrderService
const orderService = new OrderService('https://api.example.com', 3);
console.log(orderService.getOrderEndpoint('ORD-4892'));

// Calling fetchOrderDetails (won't actually run without a real server)
// fetchOrderDetails('ORD-4892');

// ================================================================
// STEP 1: The problem noUncheckedIndexedAccess solves
// (Not in strict bundle — add it separately)
// ================================================================

const productNames: string[] = ['Laptop', 'Mouse', 'Keyboard'];

// WITHOUT noUncheckedIndexedAccess:
// TypeScript types productNames[5] as 'string' — but it's actually undefined at runtime
const firstProduct  = productNames[0]; // TypeScript says: string ✓
const missingProduct = productNames[5]; // TypeScript says: string ✗ (it's actually undefined)
// console.log(missingProduct.toUpperCase()); // RUNTIME CRASH

// WITH noUncheckedIndexedAccess:
// TypeScript correctly types productNames[n] as 'string | undefined'
// You're forced to check before using it
function getProductName(index: number): string {
  const product = productNames[index]; // Type: string | undefined

  if (product === undefined) {
    return 'Unknown Product';
  }

  return product; // Type narrowed to: string
}

console.log(getProductName(0)); // Laptop
console.log(getProductName(5)); // Unknown Product


// ================================================================
// STEP 2: Incremental migration pattern
// ================================================================

// In files not yet migrated, add this at the very top:
// // @ts-nocheck
// This suppresses ALL TypeScript errors in that file.
// It's a tactical retreat, not surrender — remove it file by file.


// ================================================================
// STEP 3: strictFunctionTypes — a subtle but important flag
// ================================================================

// This flag enforces contravariance on function parameter types.
// Here's a concrete example of the bug it prevents:

type StringHandler  = (value: string) => void;
type AnimalHandler  = (animal: { name: string; sound: string }) => void;

// Without strictFunctionTypes, TypeScript allowed assigning a more specific
// function type to a broader one — creating a silent type hole.
function processWithHandler(
  handler: (value: string) => void,
  input: string
): void {
  handler(input);
}

function uppercaseHandler(value: string): void {
  console.log(`Processed: ${value.toUpperCase()}`);
}

processWithHandler(uppercaseHandler, 'hello world');


// ================================================================
// STEP 4: A complete strict-mode tsconfig for a new project
// ================================================================

/*
{
  "compilerOptions": {
    "target":                        "ES2022",
    "module":                        "ESNext",
    "moduleResolution":              "bundler",
    "strict":                        true,
    "noUncheckedIndexedAccess":      true,
    "exactOptionalPropertyTypes":    true,
    "noImplicitReturns":             true,   // Functions must always return a value
    "noFallthroughCasesInSwitch":    true,   // switch cases must have break/return
    "forceConsistentCasingInFileNames": true,
    "skipLibCheck":                  true
  }
}
*/

console.log(getProductName(0));
console.log(getProductName(5));