TypeScript Explained: Why Types Make JavaScript Bulletproof

// --- WITHOUT TypeScript (plain JavaScript behaviour) ---
// This function has no idea what 'user' looks like.
// Call it wrong and you get a silent runtime bug.
function greetUserJS(user) {
  // If 'user' is undefined, this crashes at runtime — not at write-time
  return `Hello, ${user.firstName}!`;
}

console.log(greetUserJS({ firstName: 'Alice' }));  // Hello, Alice!
console.log(greetUserJS(undefined));               // 💥 TypeError at runtime


// --- WITH TypeScript ---
// We define the exact shape a User must have.
interface User {
  firstName: string;
  lastName: string;
  email: string;
}

// The function now ONLY accepts a value that matches the User shape.
// TypeScript will refuse to compile if you pass anything else.
function greetUser(user: User): string {
  // 'user.firstName' is guaranteed to be a string — no null checks needed here
  return `Hello, ${user.firstName} ${user.lastName}!`;
}

const alice: User = {
  firstName: 'Alice',
  lastName: 'Nguyen',
  email: 'alice@example.com',
};

console.log(greetUser(alice)); // Hello, Alice Nguyen!

// Trying to call with wrong data — TypeScript catches this BEFORE you run the code:
// greetUser('Alice');  
// Error: Argument of type 'string' is not assignable to parameter of type 'User'

// --- INTERFACE: describes the shape of a product in our store ---
interface Product {
  id: number;
  name: string;
  priceInCents: number;   // storing price as integer cents avoids floating-point bugs
  inStock: boolean;
  tags: string[];         // an array of strings
}

// Interfaces can be extended — great for specialised variants
interface DigitalProduct extends Product {
  downloadUrl: string;    // only digital products have this field
  fileSizeMb: number;
}

// --- TYPE ALIAS: perfect for unions and computed types ---
// A cart item is a Product plus a quantity — intersection type
type CartItem = Product & {
  quantity: number;
};

// An API response is either data or an error — union type
type ApiResponse<T> = 
  | { success: true; data: T }        // happy path
  | { success: false; error: string }; // error path

// --- Real usage: a function that processes a cart ---
function calculateCartTotal(cartItems: CartItem[]): number {
  return cartItems.reduce((total, item) => {
    // TypeScript knows 'item.priceInCents' is a number — no coercion needed
    return total + item.priceInCents * item.quantity;
  }, 0);
}

const shoppingCart: CartItem[] = [
  { id: 1, name: 'Mechanical Keyboard', priceInCents: 12999, inStock: true, tags: ['hardware', 'peripherals'], quantity: 1 },
  { id: 2, name: 'USB-C Cable',         priceInCents: 1499,  inStock: true, tags: ['accessories'],            quantity: 3 },
];

const totalCents = calculateCartTotal(shoppingCart);
console.log(`Total: $${(totalCents / 100).toFixed(2)}`); // Total: $167.96

// --- ApiResponse in action ---
function handleProductFetch(response: ApiResponse<Product>): void {
  if (response.success) {
    // TypeScript NARROWS the type here — it knows 'response.data' exists
    console.log(`Fetched: ${response.data.name}`);
  } else {
    // Inside this branch TypeScript knows 'response.error' exists
    console.error(`Fetch failed: ${response.error}`);
  }
}

// A generic wrapper for fetch — works for ANY resource type
// 'T' is a placeholder that TypeScript fills in based on how you call this function
async function fetchResource<T>(url: string): Promise<ApiResponse<T>> {
  try {
    const response = await fetch(url);

    if (!response.ok) {
      // Return a typed error response
      return { success: false, error: `HTTP ${response.status}: ${response.statusText}` };
    }

    // TypeScript treats the parsed JSON as type T — we're asserting trust here
    const data = await response.json() as T;
    return { success: true, data };

  } catch (networkError) {
    return { success: false, error: 'Network request failed' };
  }
}

// --- Our domain types ---
interface BlogPost {
  id: number;
  title: string;
  body: string;
  authorId: number;
}

interface Comment {
  id: number;
  postId: number;
  text: string;
}

// --- Same function, different types — TypeScript tracks both ---
async function loadBlogData(): Promise<void> {
  // TypeScript infers 'result' as ApiResponse<BlogPost>
  const postResult = await fetchResource<BlogPost>(
    'https://jsonplaceholder.typicode.com/posts/1'
  );

  if (postResult.success) {
    // TypeScript KNOWS postResult.data is a BlogPost here
    // — so .title is valid, .nonExistentField would be a compile error
    console.log(`Post title: ${postResult.data.title}`);
  }

  // TypeScript infers 'commentResult' as ApiResponse<Comment>
  const commentResult = await fetchResource<Comment>(
    'https://jsonplaceholder.typicode.com/comments/1'
  );

  if (commentResult.success) {
    // TypeScript knows this is a Comment — .text is valid
    console.log(`First comment: ${commentResult.data.text.slice(0, 40)}...`);
  }
}

// --- A simpler generic utility to demonstrate the concept ---
// Takes any array, returns the first and last elements with full type safety
function getArrayBounds<T>(items: T[]): { first: T; last: T } | null {
  if (items.length === 0) return null;
  return {
    first: items[0],
    last: items[items.length - 1],
  };
}

const temperatures = [18.2, 22.7, 19.1, 25.3, 21.0];
const bounds = getArrayBounds(temperatures); // TypeScript infers T as number

if (bounds) {
  console.log(`Coldest recorded: ${bounds.first}°C`);
  console.log(`Most recent: ${bounds.last}°C`);
}

// TypeScript would flag this — you can't do .toFixed() on a string:
// const nameBounds = getArrayBounds(['Alice', 'Bob']);
// console.log(nameBounds?.first.toFixed(2)); // Error: Property 'toFixed' does not exist on type 'string'

{
  "compilerOptions": {
    // What version of JavaScript to compile DOWN to
    // 'ES2020' supports async/await, optional chaining, etc.
    "target": "ES2020",

    // Module system — use 'NodeNext' for Node.js, 'ESNext' for bundlers
    "module": "NodeNext",
    "moduleResolution": "NodeNext",

    // Where compiled .js files go — keep them separate from your source
    "outDir": "./dist",

    // Where TypeScript looks for your source files
    "rootDir": "./src",

    // ✅ THE MOST IMPORTANT FLAG — enables all strict checks at once
    // This includes: strictNullChecks, noImplicitAny, strictFunctionTypes, etc.
    "strict": true,

    // Errors if you declare a variable and never use it
    // Keeps your codebase clean during refactors
    "noUnusedLocals": true,

    // Errors if a function parameter is declared but never used
    "noUnusedParameters": true,

    // Errors if a code path in a function doesn't return a value
    // Catches missing return statements in switch/if branches
    "noImplicitReturns": true,

    // Allows importing .json files as typed modules
    "resolveJsonModule": true,

    // Enables source maps so debuggers show your .ts files, not compiled .js
    "sourceMap": true,

    // Allows TypeScript to understand ES modules alongside CommonJS
    "esModuleInterop": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist", "**/*.test.ts"]
}