// ❌ `any` version — type information is destroyed
function identity(value: any): any {
  return value
}

const result = identity('hello')
// result: any — the compiler has no idea what came back
result.toUpperCase()  // No error. Also no guarantee it works.

// ✅ Generic version — type information flows through
function identity<T>(value: T): T {
  return value
}

const result = identity('hello')
// result: string — TypeScript inferred T = string from the argument
result.toUpperCase()  // ✅ Safe — string has toUpperCase

// A generic container type
interface Box<T> {
  value: T
  transform: <U>(fn: (val: T) => U) => Box<U>
}

// A generic API response wrapper
type ApiResult<T, E = Error> =
  | { status: 'success'; data: T }
  | { status: 'error'; error: E }

// Usage — T is inferred from the data property
const result: ApiResult<User> = { status: 'success', data: { name: 'Alice', email: 'alice@example.com' } }

// ❌ Without constraint — T could be anything, so no properties are safe to access
function getLength<T>(value: T): number {
  return value.length  // ❌ Error: Property 'length' does not exist on type 'T'
}

// ✅ With constraint — T is guaranteed to have a `length` property
function getLength<T extends { length: number }>(value: T): number {
  return value.length  // ✅ Safe — T is a subset of {length: number}
}

getLength('hello')      // ✅ string has length
getLength([1, 2, 3])    // ✅ number[] has length
getLength({ length: 5 }) // ✅ explicit shape satisfies the constraint
getLength(42)            // ❌ number has no length property

// ❌ Unsafe — the key might not exist on obj
function getProperty(obj: object, key: string): unknown {
  return (obj as any)[key]
}

// ✅ Type-safe — K is constrained to the actual keys of T
function getProperty<T, K extends keyof T>(obj: T, key: K): T[K] {
  return obj[key]
}

const user = { name: 'Alice', age: 30, email: 'alice@example.com' }

const name = getProperty(user, 'name')    // string — T[K] = User['name']
const age  = getProperty(user, 'age')     // number — T[K] = User['age']
getProperty(user, 'password')             // ❌ 'password' is not a key of user

// T defaults to string if not specified
interface Paginated<T = string> {
  items: T[]
  total: number
  page: number
}

const stringPage: Paginated = { items: ['a', 'b'], total: 2, page: 1 }  // T = string
const userPage: Paginated<User> = { items: [user], total: 1, page: 1 }  // T = User

// Multiple parameters with defaults
type ApiResult<T, E = Error> =
  | { ok: true; value: T }
  | { ok: false; error: E }

// E defaults to Error for the common case
const result: ApiResult<User> = { ok: true, value: user }
// Custom error type when needed
const result2: ApiResult<User, ValidationError> = { ok: false, error: validationError }

// ❌ Standard generic — T is inferred as string[], losing the literal types
function makeArray<T>(items: T[]): T[] {
  return items
}

const arr = makeArray(['north', 'south', 'east', 'west'])
// arr: string[] — widened; the literal union is lost

// ✅ `const` type parameter — T is inferred as the literal tuple
function makeArray<const T>(items: T): T {
  return items
}

const arr2 = makeArray(['north', 'south', 'east', 'west'] as const)
// arr2: readonly ["north", "south", "east", "west"] — literal tuple preserved
type Direction = typeof arr2[number]  // "north" | "south" | "east" | "west"

// ❌ `any` destroys type information — the caller gets nothing useful back
function first(arr: any[]): any {
  return arr[0]
}

// ✅ Generic preserves type information
function first<T>(arr: T[]): T | undefined {
  return arr[0]
}

const n = first([1, 2, 3])    // n: number | undefined
const s = first(['a', 'b'])   // s: string | undefined

// ❌ Over-constrained — forces callers to pass a specific type unnecessarily
function processUser<T extends User>(value: T): string {
  return value.name  // Only uses `name` — the User constraint is what we need, not T extends User
}

// ✅ Use the direct type when you don't need to preserve T through the return type
function processUser(value: User): string {
  return value.name
}

// ✅ Use T extends User when you need to return the full T, not just User
function processUserFull<T extends User>(value: T): T {
  console.log(value.name)
  return value  // Returns the full T, preserving any extra properties
}