// Type hierarchy (simplified)
never     → Bottom type (nothing is assignable to it except never)
  ↓
specific  → string, number, boolean, etc.
  ↓
unknown   → Top type (all types assignable to it)
  ↓
any       → Escape hatch (opts out of type checking)

let value: any;
 
value = 42; // ✓ OK
value = "hello"; // ✓ OK
value = true; // ✓ OK
value = { x: 10 }; // ✓ OK
value = [1, 2, 3]; // ✓ OK
 
// No type checking on operations
value.toUpperCase(); // ✓ No error (runtime error if value isn't a string)
value.nonExistentMethod(); // ✓ No error (runtime error)
let x: number = value; // ✓ No error

// Temporarily use any during migration
let legacyData: any = getLegacyData();
 
// Plan to replace with proper types later
interface LegacyData {
  // ... proper types
}

// Third-party library without type definitions
declare const thirdPartyLib: any;
 
let result = thirdPartyLib.doSomething();

// JSON parsing (though unknown is better)
let data: any = JSON.parse(jsonString);

// Quick prototype - fix types later
function quickTest(data: any) {
  console.log(data);
}

function processUser(user: any) {
  // TypeScript allows this even though it might crash
  console.log(user.name.toUpperCase());
  return user.age * 2;
}
 
// These all compile without errors
processUser({ name: "Alice", age: 30 }); // Works
processUser({ name: null, age: 30 }); // Runtime error!
processUser({}); // Runtime error!
processUser(null); // Runtime error!

function getData(): any {
  return { name: "Alice" };
}
 
let data = getData(); // Type: any
let name = data.name; // Type: any (pollution spreads!)
let upper = name.toUpperCase(); // Type: any (still spreading!)

// Implicit any (with noImplicitAny: false)
function log(message) {
  // Parameter 'message' implicitly has 'any' type
  console.log(message);
}
 
let x; // Variable 'x' implicitly has type 'any'
x = 5;
x = "hello";

let value: unknown;
 
value = 42; // ✓ OK
value = "hello"; // ✓ OK
value = true; // ✓ OK
value = { x: 10 }; // ✓ OK
 
// But you can't use it without checking
value.toUpperCase(); // ✗ Error: Object is of type 'unknown'
let x: number = value; // ✗ Error: Type 'unknown' is not assignable to type 'number'
 
// Must narrow the type first
if (typeof value === "string") {
  value.toUpperCase(); // ✓ OK - TypeScript knows it's a string here
}

function processValue(value: unknown) {
  if (typeof value === "string") {
    console.log(value.toUpperCase()); // value is string here
  } else if (typeof value === "number") {
    console.log(value.toFixed(2)); // value is number here
  } else if (typeof value === "boolean") {
    console.log(value ? "yes" : "no"); // value is boolean here
  }
}

function handleError(error: unknown) {
  if (error instanceof Error) {
    console.log(error.message); // error is Error here
  } else {
    console.log("Unknown error:", error);
  }
}

function isString(value: unknown): value is string {
  return typeof value === "string";
}
 
function isObject(value: unknown): value is Record<string, unknown> {
  return typeof value === "object" && value !== null;
}
 
function process(value: unknown) {
  if (isString(value)) {
    console.log(value.toUpperCase()); // value is string
  } else if (isObject(value)) {
    console.log(Object.keys(value)); // value is object
  }
}

function processData(data: unknown) {
  if (
    typeof data === "object" &&
    data !== null &&
    "name" in data &&
    "age" in data
  ) {
    // data is object with name and age properties
    let obj = data as { name: unknown; age: unknown };
    console.log(obj.name, obj.age);
  }
}

function parseJSON(jsonString: string): unknown {
  return JSON.parse(jsonString);
}
 
let data = parseJSON('{"name": "Alice", "age": 30}');
 
// Must validate before use
if (
  typeof data === "object" &&
  data !== null &&
  "name" in data &&
  "age" in data
) {
  let user = data as { name: string; age: number };
  console.log(user.name); // Safe to use
}

async function fetchData(url: string): Promise<unknown> {
  let response = await fetch(url);
  return response.json();
}
 
let data = await fetchData("/api/users");
 
// Validate structure
function isUser(value: unknown): value is { name: string; age: number } {
  return (
    typeof value === "object" &&
    value !== null &&
    "name" in value &&
    typeof (value as any).name === "string" &&
    "age" in value &&
    typeof (value as any).age === "number"
  );
}
 
if (isUser(data)) {
  console.log(data.name); // Type-safe
}

try {
  riskyOperation();
} catch (error: unknown) {
  if (error instanceof Error) {
    console.error(error.message);
  } else if (typeof error === "string") {
    console.error(error);
  } else {
    console.error("An unknown error occurred");
  }
}

// any - unsafe
let anyValue: any = "hello";
anyValue.toFixed(2); // No error, but runtime crash!
 
// unknown - safe
let unknownValue: unknown = "hello";
unknownValue.toFixed(2); // ✗ Error: Object is of type 'unknown'
 
if (typeof unknownValue === "number") {
  unknownValue.toFixed(2); // ✓ OK - type checked first
}

// Function that never returns normally
function throwError(message: string): never {
  throw new Error(message);
}
 
// Infinite loop - never returns
function infiniteLoop(): never {
  while (true) {
    // Loop forever
  }
}
 
// Variable that can never have a value
let impossible: never;
impossible = 5; // ✗ Error: Type 'number' is not assignable to type 'never'
impossible = "hi"; // ✗ Error: Type 'string' is not assignable to type 'never'

// Throws an error
function fail(message: string): never {
  throw new Error(message);
}
 
// Infinite loop
function keepProcessing(): never {
  while (true) {
    processNextTask();
  }
}
 
// Process exits
function exit(code: number): never {
  process.exit(code);
}
 
// Using never in control flow
function processValue(value: string | number): string {
  if (typeof value === "string") {
    return value.toUpperCase();
  } else if (typeof value === "number") {
    return value.toFixed(2);
  }
 
  // TypeScript knows this is unreachable
  fail("Invalid value type");
  // No return needed - never indicates function doesn't return
}

type Shape =
  | { kind: "circle"; radius: number }
  | { kind: "square"; size: number }
  | { kind: "rectangle"; width: number; height: number };
 
function getArea(shape: Shape): number {
  switch (shape.kind) {
    case "circle":
      return Math.PI * shape.radius ** 2;
    case "square":
      return shape.size ** 2;
    case "rectangle":
      return shape.width * shape.height;
    default:
      // If we forget a case, this catches it
      let exhaustiveCheck: never = shape;
      throw new Error(`Unhandled shape: ${exhaustiveCheck}`);
  }
}

type Shape =
  | { kind: "circle"; radius: number }
  | { kind: "square"; size: number }
  | { kind: "rectangle"; width: number; height: number }
  | { kind: "triangle"; base: number; height: number }; // New!
 
function getArea(shape: Shape): number {
  switch (shape.kind) {
    case "circle":
      return Math.PI * shape.radius ** 2;
    case "square":
      return shape.size ** 2;
    case "rectangle":
      return shape.width * shape.height;
    default:
      // ✗ Error: Type 'triangle' is not assignable to type 'never'
      let exhaustiveCheck: never = shape;
      throw new Error(`Unhandled shape: ${exhaustiveCheck}`);
  }
}
// TypeScript forces us to handle the triangle case!

function assertNever(value: never): never {
  throw new Error(`Unexpected value: ${value}`);
}
 
function getArea(shape: Shape): number {
  switch (shape.kind) {
    case "circle":
      return Math.PI * shape.radius ** 2;
    case "square":
      return shape.size ** 2;
    case "rectangle":
      return shape.width * shape.height;
    default:
      return assertNever(shape); // Compile error if not exhaustive
  }
}

type StringAndNumber = string & number; // Type: never
// Can't be both string AND number
 
type A = { type: "a"; value: string };
type B = { type: "b"; value: number };
 
type Impossible = A & B; // Type: never
// Can't have type "a" and type "b" simultaneously
 
// Useful in conditional types
type OnlyStrings<T> = T extends string ? T : never;
 
type Result = OnlyStrings<string | number | boolean>;
// Type: string (number and boolean become never)

type NonNullable<T> = T extends null | undefined ? never : T;
 
type Result = NonNullable<string | number | null | undefined>;
// Type: string | number

interface ApiResponse<T> {
  status: "success" | "error";
  data?: T;
  error?: string;
}
 
async function fetchUser(id: number): Promise<ApiResponse<unknown>> {
  try {
    let response = await fetch(`/api/users/${id}`);
    let data = await response.json();
    return { status: "success", data };
  } catch (error: unknown) {
    if (error instanceof Error) {
      return { status: "error", error: error.message };
    }
    return { status: "error", error: "Unknown error" };
  }
}
 
// Using the response
let response = await fetchUser(1);
 
if (response.status === "success" && response.data) {
  let data = response.data;
 
  // Validate structure
  if (
    typeof data === "object" &&
    data !== null &&
    "name" in data &&
    "email" in data
  ) {
    let user = data as { name: string; email: string };
    console.log(`User: ${user.name} (${user.email})`);
  }
} else {
  console.error("Error:", response.error);
}

class NetworkError extends Error {
  constructor(
    message: string,
    public statusCode: number
  ) {
    super(message);
    this.name = "NetworkError";
  }
}
 
class ValidationError extends Error {
  constructor(
    message: string,
    public field: string
  ) {
    super(message);
    this.name = "ValidationError";
  }
}
 
function handleError(error: unknown): never {
  if (error instanceof NetworkError) {
    console.error(`Network error (${error.statusCode}):`, error.message);
  } else if (error instanceof ValidationError) {
    console.error(`Validation error in ${error.field}:`, error.message);
  } else if (error instanceof Error) {
    console.error("Error:", error.message);
  } else {
    console.error("Unknown error:", error);
  }
 
  process.exit(1); // Function never returns
}
 
try {
  riskyOperation();
} catch (error: unknown) {
  handleError(error); // Returns never, so no code after this runs
}

interface User {
  type: "user";
  name: string;
  email: string;
}
 
interface Admin {
  type: "admin";
  name: string;
  email: string;
  permissions: string[];
}
 
type Account = User | Admin;
 
function isAdmin(account: unknown): account is Admin {
  return (
    typeof account === "object" &&
    account !== null &&
    "type" in account &&
    account.type === "admin" &&
    "permissions" in account &&
    Array.isArray((account as Admin).permissions)
  );
}
 
function processAccount(account: unknown) {
  if (isAdmin(account)) {
    // TypeScript knows account is Admin here
    console.log(`Admin: ${account.name}`);
    console.log(`Permissions: ${account.permissions.join(", ")}`);
  } else {
    console.log("Not an admin account");
  }
}

type State =
  | { status: "idle" }
  | { status: "loading" }
  | { status: "success"; data: string }
  | { status: "error"; error: string };
 
function renderState(state: State): string {
  switch (state.status) {
    case "idle":
      return "Ready to start";
    case "loading":
      return "Loading...";
    case "success":
      return `Data: ${state.data}`;
    case "error":
      return `Error: ${state.error}`;
    default:
      // Exhaustive check
      let exhaustive: never = state;
      throw new Error(`Unhandled state: ${exhaustive}`);
  }
}
 
// Using the state machine
let currentState: State = { status: "idle" };
console.log(renderState(currentState)); // "Ready to start"
 
currentState = { status: "loading" };
console.log(renderState(currentState)); // "Loading..."
 
currentState = { status: "success", data: "Hello, World!" };
console.log(renderState(currentState)); // "Data: Hello, World!"

// never is assignable to everything
let n: never = getNever();
let str: string = n; // ✓ OK
let num: number = n; // ✓ OK
let obj: object = n; // ✓ OK
 
// Nothing (except never) is assignable to never
let n2: never;
n2 = 5; // ✗ Error
n2 = "hello"; // ✗ Error
n2 = getNever(); // ✓ OK
 
// Everything is assignable to unknown
let u: unknown;
u = 5; // ✓ OK
u = "hello"; // ✓ OK
u = { x: 10 }; // ✓ OK
 
// unknown is not assignable to other types (without checking)
let u2: unknown = "hello";
let str2: string = u2; // ✗ Error
 
// any breaks the type system
let a: any = 5;
let str3: string = a; // ✓ OK (but unsafe!)
a = "hello";
let num2: number = a; // ✓ OK (but unsafe!)

// ✗ Avoid
function parse(json: string): any {
  return JSON.parse(json);
}
 
// ✓ Better
function parse(json: string): unknown {
  return JSON.parse(json);
}

// ✓ Good
function process(value: unknown) {
  if (typeof value === "string") {
    return value.toUpperCase();
  }
  throw new Error("Expected string");
}

// ✓ Good - catches missing cases at compile time
function handle(value: "a" | "b") {
  switch (value) {
    case "a":
      return "A";
    case "b":
      return "B";
    default:
      let exhaustive: never = value;
      throw new Error(`Unhandled: ${exhaustive}`);
  }
}

{
  "compilerOptions": {
    "strict": true,
    "noImplicitAny": true,
    "strictNullChecks": true,
    "noUncheckedIndexedAccess": true
  }
}

// If you must use any, explain why
let data: any; // TODO: Add proper types after API stabilizes

// ✗ Bad
function log(data: any) {
  console.log(data);
}
 
// ✓ Better
function log(data: unknown) {
  console.log(data); // console.log accepts unknown
}

// ✗ Bad
function process(data: unknown) {
  return data.value; // Error!
}
 
// ✓ Good
function process(data: unknown) {
  if (typeof data === "object" && data !== null && "value" in data) {
    return (data as { value: unknown }).value;
  }
}

type Status = "pending" | "active" | "done";
 
// ✗ Risky - no compile error if you add a new status
function getMessage(status: Status): string {
  if (status === "pending") return "Pending...";
  if (status === "active") return "Active!";
  if (status === "done") return "Done!";
  return "Unknown"; // Silently handles new cases
}
 
// ✓ Better - compile error if you add a new status
function getMessage(status: Status): string {
  switch (status) {
    case "pending":
      return "Pending...";
    case "active":
      return "Active!";
    case "done":
      return "Done!";
    default:
      let exhaustive: never = status;
      throw new Error(`Unhandled: ${exhaustive}`);
  }
}

// ✗ Bad - never should be for truly impossible values
let value: never = 42; // Error: Type 'number' is not assignable to type 'never'
 
// ✓ Good - never for functions that don't return
function throwError(): never {
  throw new Error();
}