TypeScript Conditional Types — Why Unions Collapse to Never

// ============================================
// Conditional Types — Core Patterns
// ============================================

// ---- Basic conditional type ----
// T extends U ? X : Y

type IsString<T> = T extends string ? 'yes' : 'no'

type A = IsString<string>    // 'yes'
type B = IsString<number>    // 'no'
type C = IsString<'hello'>   // 'yes' — string literal extends string

// ---- Distributive behavior: the source of most bugs ----
// When T is a bare type parameter, conditional types distribute over unions

type ToArray<T> = T extends unknown ? T[] : never

type D = ToArray<string | number>
// Resolves to: string[] | number[]
// NOT: (string | number)[]
// TypeScript distributes: (string extends unknown ? string[] : never) |
//                         (number extends unknown ? number[] : never)

// ---- Suppressing distribution with tuples ----
// Wrap T in a tuple to prevent distribution

type ToArrayNonDist<T> = [T] extends [unknown] ? T[] : never

type E = ToArrayNonDist<string | number>
// Resolves to: (string | number)[]
// Distribution suppressed — the entire union is treated as one type

// ---- Built on conditional types: Exclude, Extract, NonNullable ----
// These are in TypeScript's standard library — understanding them requires
// understanding distributive conditional types

type Exclude<T, U> = T extends U ? never : T

type F = Exclude<'a' | 'b' | 'c', 'a'>
// Distributes: ('a' extends 'a' ? never : 'a') |
//              ('b' extends 'a' ? never : 'b') |
//              ('c' extends 'a' ? never : 'c')
// Resolves to: 'b' | 'c'

// ---- Practical: Filter union members by shape ----

type FilterByShape<T, U> = T extends U ? T : never

interface HasId {
  id: string
}

type User = { id: string; name: string }
type Product = { id: string; price: number }
type Error = { message: string }

type Entities = FilterByShape<User | Product | Error, HasId>
// Resolves to: User | Product
// Error is excluded because it lacks 'id'

// ---- Practical: Conditional return type based on input ----
// The conditional type describes the relationship; overloads implement it

type ProcessReturn<T> = T extends string ? string[] : number

function process(value: string): string[]
function process(value: number): number
function process(value: string | number): string[] | number {
  return typeof value === 'string' ? value.split('') : value * 2
}

const resultA = process('hello')  // string[]
const resultB = process(42)       // number
// TypeScript infers ProcessReturn<T> via overloads

// ============================================
// infer Keyword — Type Extraction Patterns
...all the code...
// Resolves to: [code: number, message: string]

// ============================================
// Template Literal Types — String Construction Patterns
// ============================================

// ---- Basic template literal type ----

type EventName = `on${Capitalize<'click' | 'focus' | 'blur'>}`
// Resolves to: 'onClick' | 'onFocus' | 'onBlur'

// ---- Combinatorial expansion ----
// Union × Union = all combinations

type HTTPMethod = 'get' | 'post' | 'put' | 'delete'
type Resource = 'user' | 'post' | 'comment'

type APIRoute = `/${Resource}` | `/${Resource}/${string}`
// Resolves to: '/user' | '/user/${string}' | '/post' | ...

// Combinatorial growth example
type A = 'a' | 'b' | 'c'           // 3 members
type AB = `${A}-${A}`              // 9 members (3×3)
type ABC = `${AB}-${AB}`           // 81 members (9×9) — grows exponentially

// ---- Practical: type-safe CSS property access ----

type CSSProperty = `--${string}`

type CSSValue = {
  [K in CSSProperty]?: string
}

const theme: CSSValue = {
  '--color-primary': '#3b82f6',
  '--color-background': '#ffffff',
  '--spacing-unit': '8px',
}

// TypeScript validates that all keys start with '--'
// const bad: CSSValue = { 'color': 'red' }  // Error

// ---- Practical: type-safe API endpoint builder ----

type ExtractParams<T extends string> =
  T extends `${string}:${infer Param}/${infer Rest}`
    ? Param | ExtractParams<Rest>
    : T extends `${string}:${infer Param}`
      ? Param
      : never

type Params = ExtractParams<'/users/:userId/posts/:postId'>
// Resolves to: 'userId' | 'postId'

// Build a type-safe route function
function createRoute<T extends string>(
  template: T,
  params: Record<ExtractParams<T>, string>
): string {
  let result = template as string
  for (const [key, value] of Object.entries(params)) {
    result = result.replace(`:${key}`, value)
  }
  return result
}

const url = createRoute('/users/:userId/posts/:postId', {
  userId: 'u-123',
  postId: 'p-456',
})
// url: string — '/users/u-123/posts/p-456'

// TypeScript catches missing or extra params:
// createRoute('/users/:userId', { wrong: 'key' })  // Error
// createRoute('/users/:userId', {})                 // Error: missing userId

// ---- Mapped types with template literal keys ----
// Remap object keys using template literals

type Getters<T> = {
  [K in keyof T as `get${Capitalize<string & K>}`]: () => T[K]
}

type User = {
  id: string
  name: string
  email: string
}

type UserGetters = Getters<User>
// Resolves to: {
//   getId: () => string
//   getName: () => string
//   getEmail: () => string
// }

type Setters<T> = {
  [K in keyof T as `set${Capitalize<string & K>}`]: (value: T[K]) => void
}

type UserSetters = Setters<User>
// Resolves to: {
//   setId: (value: string) => void
//   setName: (value: string) => void
//   setEmail: (value: string) => void
// }

// ---- Combining template literals with conditional types ----

type ExtractPrefix<T extends string> =
  T extends `${infer Prefix}:${string}` ? Prefix : T

type Prefix = ExtractPrefix<'content-type:application/json'>
// Resolves to: 'content-type'

type ExtractSuffix<T extends string> =
  T extends `${string}:${infer Suffix}` ? Suffix : T

type Suffix = ExtractSuffix<'content-type:application/json'>
// Resolves to: 'application/json'

// ============================================
// Type-Safe Event Emitter — Conditional + Template Literal Pattern
// ============================================

// ---- Event map: defines events and their payload types ----

type EventMap = {
  'user:login': { userId: string; timestamp: number }
  'user:logout': { userId: string }
  'order:created': { orderId: string; total: number }
  'order:shipped': { orderId: string; trackingNumber: string }
  'error': { code: number; message: string }
}

// ---- Type-safe event emitter ----

class TypedEmitter<TEvents extends Record<string, any>> {
  private listeners = new Map<string, Set<Function>>()

  on<K extends keyof TEvents>(
    event: K,
    handler: (payload: TEvents[K]) => void
  ): () => void {
    if (!this.listeners.has(event as string)) {
      this.listeners.set(event as string, new Set())
    }
    this.listeners.get(event as string)!.add(handler)

    // Return unsubscribe function
    return () => {
      this.listeners.get(event as string)?.delete(handler)
    }
  }

  emit<K extends keyof TEvents>(
    event: K,
    payload: TEvents[K]
  ): void {
    this.listeners.get(event as string)?.forEach((handler) => {
      handler(payload)
    })
  }

  off<K extends keyof TEvents>(
    event: K,
    handler: (payload: TEvents[K]) => void
  ): void {
    this.listeners.get(event as string)?.delete(handler)
  }
}

// ---- Usage: full type safety ----

const emitter = new TypedEmitter<EventMap>()

// Correct: handler payload type matches event
emitter.on('user:login', (data) => {
  console.log(data.userId)    // string — typed
  console.log(data.timestamp) // number — typed
})

// Error: handler receives wrong payload type
// emitter.on('user:login', (data: { wrong: boolean }) => {})

// Error: unknown event name
// emitter.on('unknown:event', () => {})

// Emit with correct payload
emitter.emit('order:created', {
  orderId: 'ord-123',
  total: 99.99,
})

// Error: missing payload property
// emitter.emit('order:created', { orderId: 'ord-123' })

// ---- Wildcard event handler with conditional types ----

type AnyEvent<T> = keyof T

type AnyPayload<T> = T[keyof T]

// Handler that receives all events with discriminated payload

type WildcardHandler<TEvents extends Record<string, any>> = <
  K extends keyof TEvents
>(
  event: K,
  payload: TEvents[K]
) => void

// Register wildcard handler
// Note: simplified for type demonstration — a real implementation iterates
// over known event keys from the EventMap and subscribes individually
function onAny<TEvents extends Record<string, any>>(
  emitter: TypedEmitter<TEvents>,
  handler: WildcardHandler<TEvents>
): () => void {
  // production code would register handler for each key in TEvents
  return () => {
    // unsubscribe logic
  }
}

// ---- Event name builder using template literals ----

type Domain = 'user' | 'order' | 'payment'
type Action = 'created' | 'updated' | 'deleted'

type BuildEventName<D extends string, A extends string> = `${D}:${A}`

type AllEvents = BuildEventName<Domain, Action>
// Resolves to: 'user:created' | 'user:updated' | 'user:deleted' |
//              'order:created' | 'order:updated' | 'order:deleted' |
//              'payment:created' | 'payment:updated' | 'payment:deleted'

// ============================================
// Recursive Deep Path Access — Template Literal + Conditional Pattern
// ============================================

// ---- Deep value extractor ----
// Splits dot-separated path and recurses into object type

type DeepValue<
  T,
  Path extends string
> = Path extends `${infer Key}.${infer Rest}`
  ? Key extends keyof T
    ? DeepValue<T[Key], Rest>
    : never
  : Path extends keyof T
    ? T[Path]
    : never

// ---- Deep path generator ----
// Produces all valid dot-separated paths for an object type

type DeepPaths<T, Prefix extends string = ''> = T extends object
  ? T extends any[] | Date | Function
    ? never
    : {
        [K in keyof T & string]:
          T[K] extends object
            ? T[K] extends any[] | Date | Function
              ? `${Prefix}${K}`
              : `${Prefix}${K}` | DeepPaths<T[K], `${Prefix}${K}.`>
            : `${Prefix}${K}`
      }[keyof T & string]
  : never

// ---- Usage ----

interface AppConfig {
  server: {
    host: string
    port: number
    ssl: {
      enabled: boolean
      cert: string
      key: string
    }
  }
  database: {
    host: string
    port: number
    name: string
    pool: {
      min: number
      max: number
    }
  }
  cache: {
    ttl: number
    driver: 'memory' | 'redis'
  }
}

// All valid paths

type ConfigPaths = DeepPaths<AppConfig>
// Resolves to:
// 'server' | 'server.host' | 'server.port' | 'server.ssl' |
// 'server.ssl.enabled' | 'server.ssl.cert' | 'server.ssl.key' |
// 'database' | 'database.host' | 'database.port' | 'database.name' |
// 'database.pool' | 'database.pool.min' | 'database.pool.max' |
// 'cache' | 'cache.ttl' | 'cache.driver'

// Value type from path

type SslEnabled = DeepValue<AppConfig, 'server.ssl.enabled'>
// Resolves to: boolean

type PoolMax = DeepValue<AppConfig, 'database.pool.max'>
// Resolves to: number

type CacheDriver = DeepValue<AppConfig, 'cache.driver'>
// Resolves to: 'memory' | 'redis'

// ---- Type-safe get function ----

function deepGet<T extends object, P extends DeepPaths<T>>(
  obj: T,
  path: P
): DeepValue<T, P> {
  const keys = (path as string).split('.')
  let result: any = obj
  for (const key of keys) {
    result = result[key]
  }
  return result
}

const config: AppConfig = {
  server: { host: 'localhost', port: 3000, ssl: { enabled: true, cert: '/cert.pem', key: '/key.pem' } },
  database: { host: 'db.local', port: 5432, name: 'app', pool: { min: 2, max: 10 } },
  cache: { ttl: 3600, driver: 'redis' },
}

const sslEnabled = deepGet(config, 'server.ssl.enabled')  // boolean
const poolMax = deepGet(config, 'database.pool.max')      // number
const driver = deepGet(config, 'cache.driver')            // 'memory' | 'redis'

// Error: invalid path
// deepGet(config, 'server.ssl.nonexistent')  // Type error
// deepGet(config, 'invalid.path')            // Type error

// ---- Type-safe set function ----

function deepSet<T extends object, P extends DeepPaths<T>>(
  obj: T,
  path: P,
  value: DeepValue<T, P>
): void {
  const keys = (path as string).split('.')
  let target: any = obj
  for (let i = 0; i < keys.length - 1; i++) {
    target = target[keys[i]]
  }
  target[keys[keys.length - 1]] = value
}

deepSet(config, 'server.port', 8080)         // OK — number
deepSet(config, 'cache.driver', 'memory')    // OK — 'memory' | 'redis'

// Error: wrong value type
// deepSet(config, 'server.port', 'eighty')   // Type error — string not assignable to number

// io.thecodeforge — javascript tutorial

type ApiResponse<T extends string> = T extends 'user'
  ? { id: number; name: string }
  : T extends 'order'
  ? { orderId: number; total: number }
  : never;

// Distribution works on bare T
type ResponseUnion = ApiResponse<'user' | 'order'>;
//    ^? { id: number; name: string } | { orderId: number; total: number }

// Wrapping breaks distribution
type Wrapped<T extends string> = [T] extends ['user']
  ? { id: number }
  : never;

type BrokenUnion = Wrapped<'user' | 'order'>;
//    ^? never

// Production bug: forgot to unwrap before conditional
// Fix: keep T bare in the condition

// io.thecodeforge — javascript tutorial

// Bad: constraint is conditional, errors are silent
// User passes number, gets never, chaos follows
type BadExtract<T> = T extends string ? T : never;
type ResultBad = BadExtract<42>;
//    ^? never

// Better: constraint on generic parameter
// TypeScript yells immediately at the call site
type GoodExtract<T extends string> = T;
type ResultGood = GoodExtract<'hello'>;
//    ^? 'hello'
// type ResultError = GoodExtract<42>;
//    ^? Type '42' does not satisfy the constraint 'string'

// Advanced: conditional constraint based on shape
type ExtractStringValues<T> = {
  [K in keyof T]: T[K] extends string ? T[K] : never;
}[keyof T];

type User = { id: number; name: string; role: 'admin' | 'user' };
type UserStringValues = ExtractStringValues<User>;
//    ^? string