Type Assertions and Casting

// Type assertion tells TypeScript "this is a string"
let value: unknown = "hello";

// Without assertion - error
// let length = value.length;  // ❌ Error: 'unknown' has no property 'length'

// With assertion - works
let length = (value as string).length;  // ✅ TypeScript knows it's a string
console.log(length);  // 5

// Assertion doesn't change the value
console.log(typeof value);  // "string" (it was always a string)

// Common use case: DOM elements
const button = document.getElementById("myButton");
// Type: HTMLElement | null

// Assert specific element type
const typedButton = button as HTMLButtonElement;
// Now TypeScript knows it's a button, not just HTMLElement

// Another example with fetch
async function getUser(id: number) {
  const response = await fetch(`/api/users/${id}`);
  const data = await response.json();  // Type: any
  
  // Assert the shape of data
  const user = data as { name: string; email: string };
  console.log(user.name);
  console.log(user.email);
}

// Asserting from any/unknown
let data: any = { name: "Yusuf", age: 25 };
let user = data as { name: string; age: number };

console.log(user.name);  // "Yusuf"
console.log(user.age);   // 25

// Asserting to more specific type
interface User {
  name: string;
  email: string;
}

interface Admin extends User {
  role: string;
  permissions: string[];
}

let basicUser: User = {
  name: "Amina",
  email: "amina@example.com"
};

// This would error without validation, but with assertion:
// let admin = basicUser as Admin;  // Unsafe! basicUser doesn't have role/permissions

// Correct usage: when you KNOW the object has the properties
let fullData: any = {
  name: "Amina",
  email: "amina@example.com",
  role: "admin",
  permissions: ["read", "write"]
};

let admin = fullData as Admin;
console.log(admin.role);  // "admin"

// Asserting DOM elements
const input = document.querySelector(".email-input") as HTMLInputElement;
input.value = "yusuf@example.com";
input.focus();

const link = document.querySelector("a") as HTMLAnchorElement;
link.href = "https://example.com";

// Asserting API responses
interface ApiResponse {
  status: number;
  data: any;
}

async function fetchData(): Promise<any> {
  const response = await fetch("/api/data");
  const json = await response.json();
  
  const apiResponse = json as ApiResponse;
  return apiResponse.data;
}

// Asserting in expressions
function getLength(value: string | number): number {
  if (typeof value === "string") {
    return value.length;
  }
  return (value as number).toString().length;
}

// Complex interface assertion
interface Product {
  id: number;
  name: string;
  price: number;
  category: string;
}

interface Order {
  orderId: number;
  products: Product[];
  total: number;
  customer: {
    name: string;
    email: string;
  };
}

// Asserting parsed JSON
const jsonString = `{
  "orderId": 1001,
  "products": [
    {"id": 1, "name": "Laptop", "price": 450000, "category": "Electronics"}
  ],
  "total": 450000,
  "customer": {"name": "Yusuf", "email": "yusuf@example.com"}
}`;

const order = JSON.parse(jsonString) as Order;

console.log(`Order #${order.orderId}`);
console.log(`Customer: ${order.customer.name}`);
console.log(`Total: ₦${order.total}`);

// Type assertion with union types
type Status = "pending" | "approved" | "rejected";

function getStatus(): string {
  return "pending";
}

const status = getStatus() as Status;  // Assert it's one of the literal types
console.log(status);

// Asserting object literals
const config = {
  apiUrl: "https://api.example.com",
  timeout: 30000,
  retries: 3
} as {
  apiUrl: string;
  timeout: number;
  retries: number;
};

// Alternative: inline type
const settings = {
  host: "localhost",
  port: 8080
} as { host: string; port: number };

// Angle bracket syntax (older style)
let value: unknown = "hello";

// Using angle brackets
let length1 = (<string>value).length;

// Equivalent to 'as' syntax
let length2 = (value as string).length;

// Both do the same thing
console.log(length1);  // 5
console.log(length2);  // 5

// With interfaces
interface User {
  name: string;
  age: number;
}

let data: any = { name: "Yusuf", age: 25 };

// Angle bracket style
let user1 = <User>data;

// 'as' style (preferred)
let user2 = data as User;

// DOM elements
const element1 = <HTMLInputElement>document.getElementById("email");
const element2 = document.getElementById("email") as HTMLInputElement;

// Why 'as' is preferred:
// 1. Works in JSX/TSX files (angle brackets conflict with JSX)
// 2. More readable and consistent
// 3. Recommended by TypeScript team

// Without const assertion
let status1 = "pending";  // Type: string

// With const assertion
let status2 = "pending" as const;  // Type: "pending" (literal type)

// status2 = "approved";  // ❌ Error: can't assign to literal type

// Object with const assertion
const config1 = {
  host: "localhost",
  port: 8080
};
// Type: { host: string; port: number; }
// config1.host = "example.com";  // ✅ Works (mutable)

const config2 = {
  host: "localhost",
  port: 8080
} as const;
// Type: { readonly host: "localhost"; readonly port: 8080; }
// config2.host = "example.com";  // ❌ Error: readonly
// config2.port = 3000;            // ❌ Error: readonly

// Array with const assertion
const colors1 = ["red", "green", "blue"];
// Type: string[]
colors1.push("yellow");  // ✅ Works (mutable)

const colors2 = ["red", "green", "blue"] as const;
// Type: readonly ["red", "green", "blue"]
// colors2.push("yellow");  // ❌ Error: readonly
// colors2[0] = "purple";   // ❌ Error: readonly

// Const assertion for configuration
const apiConfig = {
  endpoints: {
    users: "/api/users",
    products: "/api/products",
    orders: "/api/orders"
  },
  methods: {
    get: "GET",
    post: "POST",
    put: "PUT",
    delete: "DELETE"
  },
  timeout: 30000
} as const;

// All properties are deeply readonly and have literal types
type Endpoint = typeof apiConfig.endpoints[keyof typeof apiConfig.endpoints];
// Type: "/api/users" | "/api/products" | "/api/orders"

type Method = typeof apiConfig.methods[keyof typeof apiConfig.methods];
// Type: "GET" | "POST" | "PUT" | "DELETE"

// Using const assertion for enums
const UserRole = {
  ADMIN: "admin",
  EDITOR: "editor",
  VIEWER: "viewer"
} as const;

type Role = typeof UserRole[keyof typeof UserRole];
// Type: "admin" | "editor" | "viewer"

function checkRole(role: Role): void {
  if (role === UserRole.ADMIN) {
    console.log("Administrator");
  }
}

checkRole(UserRole.ADMIN);  // ✅ Works
checkRole("admin");         // ✅ Works (same literal type)

// Const assertion with tuples
const point1 = [10, 20];  // Type: number[]
const point2 = [10, 20] as const;  // Type: readonly [10, 20]

// Using as const for precise types
const directions = ["north", "south", "east", "west"] as const;
type Direction = typeof directions[number];
// Type: "north" | "south" | "east" | "west"

// Non-null assertion with !
function getElement(id: string): HTMLElement | null {
  return document.getElementById(id);
}

// Without assertion - need to check for null
const element1 = getElement("myButton");
if (element1) {
  element1.textContent = "Click me";
}

// With non-null assertion - assert it's not null
const element2 = getElement("myButton")!;  // Assert: not null
element2.textContent = "Click me";  // No null check needed

// Danger: if element is actually null, this crashes!
// const missing = getElement("nonexistent")!;
// missing.textContent = "Oops";  // Runtime error!

// With optional properties
interface Config {
  host: string;
  port?: number;
}

const config: Config = { host: "localhost" };

// Without assertion
const port1 = config.port ?? 8080;
console.log(port1 + 1000);  // 9080

// With non-null assertion (dangerous if port is undefined!)
const port2 = config.port!;
console.log(port2 + 1000);  // NaN if port is undefined!

// Array access
const users = ["Yusuf", "Amina", "Chidi"];

// Without assertion
const firstUser = users[0];
if (firstUser) {
  console.log(firstUser.toUpperCase());
}

// With assertion (assumes first element exists)
const secondUser = users[0]!;
console.log(secondUser.toUpperCase());

// Safer: use optional chaining instead
const element3 = getElement("myButton");
element3?.addEventListener("click", () => {
  console.log("Clicked");
});

// Better: check explicitly
const element4 = getElement("myButton");
if (element4) {
  element4.textContent = "Click me";
} else {
  console.error("Element not found");
}

// TypeScript prevents unsafe assertions
let num = 42;
// let str = num as string;  // ❌ Error: number not assignable to string

// Double assertion (escape hatch)
let str1 = num as unknown as string;  // ✅ Compiles
let str2 = num as any as string;      // ✅ Compiles

// But at runtime...
// console.log(str1.toUpperCase());  // Runtime error! num is still 42

// When you might need this (rare):
class Animal {
  name: string = "";
}

class Dog extends Animal {
  breed: string = "";
}

class Cat extends Animal {
  color: string = "";
}

// TypeScript won't allow this directly
let animal: Animal = new Dog();
// let cat = animal as Cat;  // ❌ Error: Dog not assignable to Cat

// But you can force it (don't do this!)
let cat = animal as unknown as Cat;
// This compiles but is wrong! animal is a Dog, not a Cat

// Correct approach: use type guards
function isCat(animal: Animal): animal is Cat {
  return animal instanceof Cat;
}

if (isCat(animal)) {
  // Safe: TypeScript knows it's a Cat
  console.log(animal.color);
}

// Another dangerous example
const obj = { name: "Yusuf" };
// const num = obj as number;  // ❌ Error: object not assignable to number

// Forced (very dangerous!)
const forced = obj as unknown as number;
// console.log(forced.toFixed(2));  // Runtime crash!

// Real-world escape hatch (use sparingly)
// Sometimes needed for library types that are incorrect
interface LegacyAPI {
  data: string;  // Library says it's string
}

const response: any = {
  data: { user: "Yusuf" }  // But actually returns object
};

// You KNOW the type is wrong, so you force it
const corrected = response as unknown as { data: { user: string } };
console.log(corrected.data.user);  // Works

// Better: Fix the type definition instead of double assertion

// Pattern 1: Validate structure before asserting
interface User {
  id: number;
  name: string;
  email: string;
}

function processUser(data: unknown): void {
  // Validate first
  if (
    typeof data === "object" &&
    data !== null &&
    "id" in data &&
    "name" in data &&
    "email" in data &&
    typeof (data as any).id === "number" &&
    typeof (data as any).name === "string" &&
    typeof (data as any).email === "string"
  ) {
    // Now safe to assert
    const user = data as User;
    console.log(`User: ${user.name}`);
    console.log(`Email: ${user.email}`);
  } else {
    console.error("Invalid user data");
  }
}

processUser({ id: 1, name: "Yusuf", email: "yusuf@example.com" });  // ✅ Works
processUser({ name: "Invalid" });  // ✅ Handles gracefully

// Pattern 2: Type guard function
function isUser(data: unknown): data is User {
  return (
    typeof data === "object" &&
    data !== null &&
    "id" in data &&
    "name" in data &&
    "email" in data &&
    typeof (data as any).id === "number" &&
    typeof (data as any).name === "string" &&
    typeof (data as any).email === "string"
  );
}

function safeProcessUser(data: unknown): void {
  if (isUser(data)) {
    // No assertion needed - type guard does it
    console.log(`User: ${data.name}`);
    console.log(`Email: ${data.email}`);
  } else {
    console.error("Invalid user data");
  }
}

// Pattern 3: Assertion with fallback
function getConfig(): unknown {
  // Simulates unknown config source
  return { host: "localhost", port: 8080 };
}

const config = getConfig();
const safeConfig = (
  typeof config === "object" && config !== null
    ? config
    : { host: "localhost", port: 8080 }
) as { host: string; port: number };

console.log(`Server: ${safeConfig.host}:${safeConfig.port}`);

// Pattern 4: Narrow before asserting
function processValue(value: string | number | boolean): void {
  if (typeof value === "string") {
    // Already narrowed by typeof
    console.log(value.toUpperCase());
  } else if (typeof value === "number") {
    console.log(value.toFixed(2));
  } else {
    // TypeScript knows it's boolean
    console.log(value ? "Yes" : "No");
  }
}

// Safe assertion with try-catch
function parseUserJSON(json: string): User | null {
  try {
    const data = JSON.parse(json);
    
    // Validate structure
    if (
      typeof data === "object" &&
      data !== null &&
      typeof data.id === "number" &&
      typeof data.name === "string" &&
      typeof data.email === "string"
    ) {
      return data as User;
    }
    
    console.error("Invalid user structure");
    return null;
  } catch (error) {
    console.error("Invalid JSON:", error);
    return null;
  }
}

const validJSON = '{"id":1,"name":"Yusuf","email":"yusuf@example.com"}';
const invalidJSON = '{"name":"Missing fields"}';

const user1 = parseUserJSON(validJSON);
if (user1) {
  console.log(`User: ${user1.name}`);
}

const user2 = parseUserJSON(invalidJSON);
if (user2) {
  console.log(`User: ${user2.name}`);
} else {
  console.log("Failed to parse user");
}

// Assertion function that throws
function assertIsUser(data: unknown): asserts data is User {
  if (!isUser(data)) {
    throw new Error("Data is not a valid User");
  }
}

function strictProcessUser(data: unknown): void {
  try {
    assertIsUser(data);
    // TypeScript knows data is User here
    console.log(`User: ${data.name}`);
  } catch (error) {
    console.error((error as Error).message);
  }
}

strictProcessUser({ id: 1, name: "Yusuf", email: "yusuf@example.com" });
strictProcessUser({ name: "Invalid" });

// Type-safe DOM manipulation
class FormHandler {
  private form: HTMLFormElement;
  private nameInput: HTMLInputElement;
  private emailInput: HTMLInputElement;
  private submitButton: HTMLButtonElement;
  
  constructor(formId: string) {
    // Get form element
    const formElement = document.getElementById(formId);
    if (!formElement) {
      throw new Error(`Form with id "${formId}" not found`);
    }
    this.form = formElement as HTMLFormElement;
    
    // Get input elements with validation
    this.nameInput = this.getInput("name");
    this.emailInput = this.getInput("email");
    this.submitButton = this.getButton("submit");
    
    this.setupEventListeners();
  }
  
  private getInput(name: string): HTMLInputElement {
    const input = this.form.querySelector(`input[name="${name}"]`);
    if (!input) {
      throw new Error(`Input "${name}" not found`);
    }
    return input as HTMLInputElement;
  }
  
  private getButton(name: string): HTMLButtonElement {
    const button = this.form.querySelector(`button[name="${name}"]`);
    if (!button) {
      throw new Error(`Button "${name}" not found`);
    }
    return button as HTMLButtonElement;
  }
  
  private setupEventListeners(): void {
    this.form.addEventListener("submit", (e) => {
      e.preventDefault();
      this.handleSubmit();
    });
    
    this.nameInput.addEventListener("input", () => {
      this.validateName();
    });
    
    this.emailInput.addEventListener("input", () => {
      this.validateEmail();
    });
  }
  
  private validateName(): boolean {
    const isValid = this.nameInput.value.length >= 2;
    this.nameInput.classList.toggle("invalid", !isValid);
    return isValid;
  }
  
  private validateEmail(): boolean {
    const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
    const isValid = emailRegex.test(this.emailInput.value);
    this.emailInput.classList.toggle("invalid", !isValid);
    return isValid;
  }
  
  private handleSubmit(): void {
    if (this.validateName() && this.validateEmail()) {
      console.log("Form submitted:", {
        name: this.nameInput.value,
        email: this.emailInput.value
      });
    } else {
      console.error("Form validation failed");
    }
  }
}

// Usage (after DOM is loaded)
// const handler = new FormHandler("userForm");

// Type-safe API response handling
interface ApiResponse<T> {
  success: boolean;
  data?: T;
  error?: string;
}

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

interface Product {
  id: number;
  name: string;
  price: number;
}

class ApiClient {
  private baseUrl: string;
  
  constructor(baseUrl: string) {
    this.baseUrl = baseUrl;
  }
  
  private async request<T>(
    endpoint: string,
    options?: RequestInit
  ): Promise<ApiResponse<T>> {
    try {
      const response = await fetch(`${this.baseUrl}${endpoint}`, options);
      const data = await response.json();
      
      // Validate response structure
      if (
        typeof data === "object" &&
        data !== null &&
        "success" in data &&
        typeof data.success === "boolean"
      ) {
        return data as ApiResponse<T>;
      }
      
      return {
        success: false,
        error: "Invalid response format"
      };
    } catch (error) {
      return {
        success: false,
        error: (error as Error).message
      };
    }
  }
  
  async getUser(id: number): Promise<User | null> {
    const response = await this.request<User>(`/users/${id}`);
    
    if (response.success && response.data) {
      // Validate User structure
      const data = response.data;
      if (
        typeof data === "object" &&
        "id" in data &&
        "name" in data &&
        "email" in data
      ) {
        return data as User;
      }
    }
    
    return null;
  }
  
  async getProducts(): Promise<Product[]> {
    const response = await this.request<Product[]>("/products");
    
    if (response.success && response.data) {
      const data = response.data;
      if (Array.isArray(data)) {
        // Validate each product
        const valid = data.every(item =>
          typeof item === "object" &&
          "id" in item &&
          "name" in item &&
          "price" in item
        );
        
        if (valid) {
          return data as Product[];
        }
      }
    }
    
    return [];
  }
}

// Usage
const api = new ApiClient("https://api.example.com");

api.getUser(1).then(user => {
  if (user) {
    console.log(`User: ${user.name}`);
  }
});

api.getProducts().then(products => {
  products.forEach(product => {
    console.log(`${product.name}: ₦${product.price}`);
  });
});

// Type-safe localStorage wrapper
class TypedStorage<T> {
  constructor(private key: string) {}
  
  save(data: T): void {
    try {
      const json = JSON.stringify(data);
      localStorage.setItem(this.key, json);
    } catch (error) {
      console.error("Failed to save to storage:", error);
    }
  }
  
  load(): T | null {
    try {
      const json = localStorage.getItem(this.key);
      if (!json) {
        return null;
      }
      
      const data = JSON.parse(json);
      return data as T;  // Assertion after parsing
    } catch (error) {
      console.error("Failed to load from storage:", error);
      return null;
    }
  }
  
  remove(): void {
    localStorage.removeItem(this.key);
  }
}

// User preferences
interface UserPreferences {
  theme: "light" | "dark";
  language: string;
  notifications: boolean;
}

const prefsStorage = new TypedStorage<UserPreferences>("user-prefs");

// Save preferences
prefsStorage.save({
  theme: "dark",
  language: "en",
  notifications: true
});

// Load preferences
const prefs = prefsStorage.load();
if (prefs) {
  console.log(`Theme: ${prefs.theme}`);
  console.log(`Language: ${prefs.language}`);
}

// Shopping cart
interface CartItem {
  productId: number;
  name: string;
  price: number;
  quantity: number;
}

const cartStorage = new TypedStorage<CartItem[]>("shopping-cart");

// Save cart
cartStorage.save([
  { productId: 1, name: "Laptop", price: 450000, quantity: 1 },
  { productId: 2, name: "Mouse", price: 5000, quantity: 2 }
]);

// Load cart
const cart = cartStorage.load();
if (cart) {
  const total = cart.reduce((sum, item) => sum + item.price * item.quantity, 0);
  console.log(`Cart total: ₦${total}`);
}

// ✅ Good: Validate before asserting
interface User {
  name: string;
  email: string;
}

function isUser(data: unknown): data is User {
  return (
    typeof data === "object" &&
    data !== null &&
    "name" in data &&
    "email" in data &&
    typeof (data as any).name === "string" &&
    typeof (data as any).email === "string"
  );
}

function processUser(data: unknown): void {
  if (isUser(data)) {
    console.log(data.name);  // Safe
  }
}

// ❌ Avoid: Assertion without validation
function badProcessUser(data: unknown): void {
  const user = data as User;  // Unsafe!
  console.log(user.name);     // Might crash
}

// ✅ Good: Use 'as' syntax
const element = document.getElementById("btn") as HTMLButtonElement;

// ❌ Avoid: Angle brackets (not JSX-compatible)
const badElement = <HTMLButtonElement>document.getElementById("btn");

// ✅ Good: Optional chaining
const btn = document.getElementById("btn");
btn?.addEventListener("click", () => {});

// ❌ Avoid: Non-null assertion
const unsafeBtn = document.getElementById("btn")!;
unsafeBtn.click();  // Might crash

// ✅ Good: Const assertion for literals
const config = {
  host: "localhost",
  port: 8080
} as const;

// ❌ Avoid: Double assertion
const dangerous = 42 as unknown as string;  // Never do this!

// ✅ Good: Document assertions
// API returns 'any' but we know it's a User from documentation
const user = apiResponse as User;