type Animal = { name: string }
type Dog    = Animal & { breed: string }

// ❌ This looks reasonable but is unsound
type DogHandler   = (dog: Dog) => void
type AnimalHandler = (animal: Animal) => void

// A function that handles Dogs CANNOT safely replace one that handles Animals
// — the caller might pass a Cat (which satisfies Animal but not Dog)
const handler: DogHandler = (dog) => console.log(dog.breed)
const animalHandler: AnimalHandler = handler  // Unsound!

// The caller passes a Cat — valid for AnimalHandler, not for DogHandler:
animalHandler({ name: 'Cat' })  // 💥 dog.breed is undefined at runtime

// ✅ Contravariance is correct — an AnimalHandler can safely substitute a DogHandler
// because it handles MORE values (any Animal, not just Dogs)
const animalHandler: AnimalHandler = (animal) => console.log(animal.name)
const dogHandler: DogHandler = animalHandler  // ✅ Safe — Animal ⊃ Dog; handles Dogs too

type UserId  = string
type OrderId = string

function cancelOrder(userId: UserId, orderId: OrderId): void {
  api.delete(`/users/${userId}/orders/${orderId}`)
}

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

cancelOrder(oid, uid)  // ✅ Compiles — but the arguments are swapped. A production 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 correct way to create a UserId
function toUserId(raw: string): UserId {
  // Optionally: add validation here (format check, etc.)
  if (!raw.startsWith('user_')) throw new Error(`Invalid UserId format: ${raw}`)
  return raw as UserId  // The ONE safe cast, contained inside the constructor
}

function toOrderId(raw: string): OrderId {
  if (!raw.startsWith('order_')) throw new Error(`Invalid OrderId format: ${raw}`)
  return raw as OrderId
}

function cancelOrder(userId: UserId, orderId: OrderId): void {
  api.delete(`/users/${userId}/orders/${orderId}`)
}

const uid = toUserId('user_abc')
const oid = toOrderId('order_xyz')

cancelOrder(oid, uid)
// ❌ Error: Argument of type 'OrderId' is not assignable to parameter of type 'UserId'.
// The compiler now prevents the semantic mix-up.

cancelOrder(uid, oid)  // ✅ Correct order

// The state tag exists only at the type level — no runtime property
type FormState<State extends 'draft' | 'submitted' | 'validated'> = {
  data: FormData
  __state: State  // This field is never actually populated at runtime
}

function createDraft(data: FormData): FormState<'draft'> {
  return { data, __state: 'draft' as any }
}

function submit(form: FormState<'draft'>): FormState<'submitted'> {
  // Only `draft` forms can be submitted — encoded in the type
  return { data: form.data, __state: 'submitted' as any }
}

function validate(form: FormState<'submitted'>): FormState<'validated'> {
  // Only `submitted` forms can be validated — encoded in the type
  return { data: form.data, __state: 'validated' as any }
}

const form = createDraft(data)
validate(form)    // ❌ Error: 'draft' is not assignable to 'submitted' — cannot skip submission
submit(form)      // ✅

type Result<T, E = Error> =
  | { ok: true;  value: T }
  | { ok: false; error: E }

// Functions that can fail return Result<T, E> — callers are forced to handle both paths
async function fetchUser(id: string): Promise<Result<User, ApiError>> {
  const response = await fetch(`/api/users/${id}`)
  if (!response.ok) {
    return { ok: false, error: { code: response.status, message: response.statusText } }
  }
  const data = await response.json()
  return { ok: true, value: UserSchema.parse(data) }
}

// Caller — CFA drives exhaustive handling
const result = await fetchUser('user_abc')

if (result.ok) {
  console.log(result.value.name)  // result: { ok: true; value: User }
} else {
  console.error(result.error.code)  // result: { ok: false; error: ApiError }
}
// No `throw` — no unhandled exception — the error path is impossible to ignore

// Without `using` — manual cleanup; easy to forget in error paths
{
  const db = await openDatabaseConnection()
  try {
    await db.query('SELECT 1')
  } finally {
    await db.close()  // Must be in finally — easy to miss
  }
}

// ✅ With `using` — disposal is guaranteed, even if an error is thrown
{
  await using db = openDatabaseConnection()
  // db[Symbol.asyncDispose] is called automatically at block exit
  await db.query('SELECT 1')
}  // db is closed here — always, no try/finally needed

// ✅ Union type — zero runtime footprint, full type safety
type Direction = 'north' | 'south' | 'east' | 'west'

// ✅ `const` object — runtime access, tree-shakeable
const Direction = { North: 'north', South: 'south', East: 'east', West: 'west' } as const
type Direction = typeof Direction[keyof typeof Direction]