// string = the infinite set of all possible string values
// number = the infinite set of all possible number values
// boolean = { true, false }
// null    = { null }
// undefined = { undefined }

// ❌ This will not compile — you cannot construct a value of type `never`
const x: never = "hello"
// Error: Type 'string' is not assignable to type 'never'.

// ✅ Functions that never return have return type `never`
function fail(message: string): never {
  throw new Error(message)
}

// ✅ Exhaustiveness guard — the default branch proves union is exhausted
function handleShape(shape: Circle | Square): number {
  switch (shape.kind) {
    case 'circle': return Math.PI * shape.radius ** 2
    case 'square': return shape.side ** 2
    default:
      // If a new union member is added without a case, this line becomes an error
      const _exhaustive: never = shape
      throw new Error(`Unhandled shape: ${JSON.stringify(_exhaustive)}`)
  }
}

// ❌ `any` — exits the type system silently
function processAny(value: any): string {
  return value.toUpperCase() // No error at compile time. May crash at runtime.
}

// ✅ `unknown` — forces a narrowing check before use
function processUnknown(value: unknown): string {
  if (typeof value !== 'string') {
    throw new Error(`Expected string, got ${typeof value}`)
  }
  return value.toUpperCase() // Safe — type is narrowed to `string` here
}

// The set hierarchy: never ⊂ "hello" ⊂ string ⊂ string | number ⊂ unknown
const literal: "hello" = "hello"
const str: string = literal          // ✅ {"hello"} ⊂ string
const union: string | number = str   // ✅ string ⊂ string | number
const top: unknown = union           // ✅ string | number ⊂ unknown

const back: string = union           // ❌ string | number ⊄ string (number not in string)

type Named = { name: string }
type Person = { name: string; age: number }

const person: Person = { name: 'Alice', age: 30 }
const named: Named = person  // ✅ Person ⊂ Named — Person has everything Named requires, plus more

// ❌ Excess property check fires on a fresh object literal
const named: Named = { name: 'Alice', age: 30 }
// Error: Object literal may only specify known properties,
// and 'age' does not exist in type 'Named'.

// ✅ Structurally valid — excess property check does NOT fire for variables
const person = { name: 'Alice', age: 30 }
const named2: Named = person  // Fine — the variable is not a "fresh" literal

// `const` — TypeScript infers the literal type because the value can never change
const direction = 'north'
// Inferred: "north" (literal type)

// `let` — TypeScript widens to the base type because the variable may be reassigned
let direction2 = 'north'
// Inferred: string

// Arrays widen by default
const directions = ['north', 'south']
// Inferred: string[] (not the tuple ["north", "south"])

// Without `as const` — all values widen
const config = {
  endpoint: '/api/v1',
  retries: 3,
  methods: ['GET', 'POST'],
}
// config.endpoint: string   (widened)
// config.methods: string[]  (widened)

// With `as const` — all values become readonly literals
const config2 = {
  endpoint: '/api/v1',
  retries: 3,
  methods: ['GET', 'POST'],
} as const
// config2.endpoint: "/api/v1"            (literal)
// config2.methods: readonly ["GET", "POST"]  (readonly tuple)

// ❌ Structural typing makes these interchangeable — wrong
type UserId = string
type OrderId = string

function getOrder(userId: UserId, orderId: OrderId): Order { /* ... */ }

const uid: UserId = 'user_abc'
const oid: OrderId = 'order_xyz'

getOrder(oid, uid) // ✅ Compiles — but the arguments are swapped! A semantic bug.

// ✅ Branded types — structurally incompatible despite the same base type
type UserId  = string & { readonly __brand: 'UserId' }
type OrderId = string & { readonly __brand: 'OrderId' }

// Smart constructor — the only way to produce a UserId
function toUserId(raw: string): UserId {
  if (!raw.startsWith('user_')) throw new Error(`Invalid UserId: ${raw}`)
  return raw as UserId
}

function getOrder(userId: UserId, orderId: OrderId): void { /* ... */ }

const uid  = toUserId('user_abc')
const oid  = raw as OrderId  // For demonstration — use a real constructor in production

getOrder(oid, uid)
// ❌ Error: Argument of type 'OrderId' is not assignable to parameter of type 'UserId'.