TypeScript Utility Types Deep Dive: Real Examples from Production

// ============================================
// Built-In Utility Types: Complete Reference
// ============================================

declare const prisma: any // mock for examples

// ---- Category 1: Property Manipulation ----

interface User {
  id: string
  name: string
  email: string
  role: 'admin' | 'member'
}

// Partial<T> — All properties become optional
type PartialUser = Partial<User>
// Result: { id?: string; name?: string; email?: string; role?: 'admin' | 'member' }

// PRODUCTION USE: Update payloads where only changed fields are sent
async function updateUser(id: string, data: Partial<User>): Promise<User> {
  return prisma.user.update({ where: { id }, data })
}

// PROBLEM: Partial<User> accepts {} — no fields required
// FIX: Use RequireAtLeastOne (see custom utilities section)

// Required<T> — All properties become required
type RequiredUser = Required<PartialUser>

interface AppConfig {
  port?: number
  host?: string
  database?: string
}

function withDefaults(config: AppConfig): Required<AppConfig> {
  return {
    port: config.port ?? 3000,
    host: config.host ?? 'localhost',
    database: config.database ?? 'app_db',
  }
}

// Readonly<T> — All properties become readonly
type ReadonlyUser = Readonly<User>

function processUser(user: Readonly<User>): void {
  // user.name = 'new name' — COMPILE ERROR
  console.log(user.name)
}

// Pick<T, K> — Select specific properties
type UserPublic = Pick<User, 'id' | 'name'>

function getPublicProfile(user: User): UserPublic {
  return { id: user.id, name: user.name }
}

// Omit<T, K> — Exclude specific properties
type CreateUserInput = Omit<User, 'id'>

async function createUser(data: CreateUserInput): Promise<User> {
  return prisma.user.create({
    data: { ...data, id: crypto.randomUUID() },
  })
}

// ---- Category 2: Record Construction ----

const ROLE_PERMISSIONS: Record<'admin' | 'member' | 'viewer', string[]> = {
  admin: ['read', 'write', 'delete', 'manage'],
  member: ['read', 'write'],
  viewer: ['read'],
}

// Exclude<T, U> — Remove types from a union
type NonAdminRole = Exclude<'admin' | 'member' | 'viewer', 'admin'>
// Result: 'member' | 'viewer'

// Extract<T, U> — Keep types in a union
type AdminOrMember = Extract<'admin' | 'member' | 'viewer', 'admin' | 'member'>
// Result: 'admin' | 'member'

// NonNullable<T> — Remove null and undefined
type SafeUser = NonNullable<User | null | undefined>

async function getUsers(): Promise<SafeUser[]> {
  const results: (User | null)[] = await prisma.user.findMany()
  return results.filter((u): u is SafeUser => u !== null)
}

// ---- Category 3: Function Utilities ----

function createUserFn(name: string, email: string, role: 'admin' | 'member') {
  return { name, email, role }
}

type CreateUserParams = Parameters<typeof createUserFn>
// Result: [name: string, email: string, role: 'admin' | 'member']

type CreateUserReturn = ReturnType<typeof createUserFn>
// Result: { name: string; email: string; role: 'admin' | 'member' }

function withLogging<F extends (...args: any[]) => any>(fn: F) {
  return (...args: Parameters<F>): ReturnType<F> => {
    console.log('Calling', fn.name, 'with', args)
    return fn(...args)
  }
}

// ---- Category 4: Promise Utilities ----

async function getUserHandler(id: string) {
  const user = await prisma.user.findUnique({ where: { id } })
  return { data: user, error: null }
}

type GetUserResponse = ReturnType<typeof getUserHandler>
// Result: Promise<{ data: User | null; error: null }>

type GetUserResolved = Awaited<GetUserResponse>
// Result: { data: User | null; error: null }

type UserPromise = Promise<User>
type UnwrappedUser = Awaited<UserPromise> // Result: User

async function fetchAllUsers(): Promise<User[]> {
  return prisma.user.findMany()
}

type AllUsers = Awaited<ReturnType<typeof fetchAllUsers>> // Result: User[]

// ============================================
// Custom Utility Types for Production
// ============================================

declare const prisma: any
declare function calculateMRR(): Promise<number>
declare function deepMerge<T>(a: T, b: DeepPartial<T>): T

interface User {
  id: string
  name: string
  email: string
  role: 'admin' | 'member'
}

// ---- 1. RequireAtLeastOne<T> ----
type RequireAtLeastOne<T, Keys extends keyof T = keyof T> =
  Pick<T, Exclude<keyof T, Keys>> & {
    [K in Keys]-?: Required<Pick<T, K>> & Partial<Pick<T, Exclude<Keys, K>>>
  }[Keys]

type UpdateUserInput = RequireAtLeastOne<Partial<User>>

const valid1: UpdateUserInput = { name: 'Alice' }
const valid2: UpdateUserInput = { name: 'Alice', email: 'a@test.com' }
// const invalid: UpdateUserInput = {} // COMPILE ERROR

async function updateUser(id: string, data: UpdateUserInput): Promise<User> {
  return prisma.user.update({ where: { id }, data })
}

// ---- 2. DeepPartial<T> ----
type DeepPartial<T> = T extends object ? { [P in keyof T]?: DeepPartial<T[P]> } : T

interface AppConfig {
  server: { port: number; host: string; ssl: { enabled: boolean; cert: string; key: string } }
  database: { url: string; poolSize: number }
}

function mergeConfig(defaults: AppConfig, overrides: DeepPartial<AppConfig>): AppConfig {
  return deepMerge(defaults, overrides)
}

// ---- 3. DeepReadonly<T> ----
type DeepReadonly<T> = T extends object ? { readonly [P in keyof T]: DeepReadonly<T[P]> } : T

// ---- 4. StrictPick<T, K> ----
type StrictPick<T, K extends keyof T> = Pick<T, K>
type NameEmail = StrictPick<User, 'name' | 'email'>
// type Bad = StrictPick<User, 'name' | 'typo'> // error: 'typo' not in keyof

// ---- 5. NonEmptyArray<T> ----
type NonEmptyArray<T> = [T, ...T[]]

function processItems<T>(items: NonEmptyArray<T>): T {
  return items[0] // safe
}
processItems([1, 2, 3])
// processItems([]) // error

// ---- 6. ValueOf<T> ----
type ValueOf<T> = T[keyof T]

const HTTP_STATUS = { OK: 200, CREATED: 201, BAD_REQUEST: 400 } as const
type HttpStatusCode = ValueOf<typeof HTTP_STATUS> // 200 | 201 | 400

// ---- 7. StrictOmit<T, K> ----
type StrictOmit<T, K extends keyof T> = Omit<T, K>
type CreateUserInputStrict = StrictOmit<User, 'id'>

// ---- 8. Nullable<T> ----
type Nullable<T> = T | null

async function findUser(id: string): Promise<Nullable<User>> {
  return prisma.user.findUnique({ where: { id } })
}

// ---- 9. AsyncReturnType<T> ----
type AsyncReturnType<T extends (...args: any[]) => Promise<any>> = Awaited<ReturnType<T>>

async function getDashboardStats() {
  const users = await prisma.user.count()
  const revenue = await calculateMRR()
  return { users, revenue }
}
type DashboardStats = AsyncReturnType<typeof getDashboardStats>
// { users: number; revenue: number }

// ---- 10. Builder Pattern Type ----
type Builder<T> = {
  [K in keyof T]-?: (value: T[K]) => Builder<T>
} & { build(): T }

function createBuilder<T extends object>(): Builder<T> {
  const obj = {} as Partial<T>
  const proxy = new Proxy({} as Builder<T>, {
    get(_, prop) {
      if (prop === 'build') return () => obj as T
      return (value: any) => {
        (obj as any)[prop] = value
        return proxy // FIXED: was 'this'
      }
    },
  })
  return proxy
}

// Usage:
// const user = createBuilder<User>()
//   .id('123').name('Alice').email('a@test.com').role('admin').build()

// ============================================
// API Response Typing with Utility Types
// ============================================

// ---- Source of Truth: Entity Type ----
// All API types are derived from this single definition

interface UserEntity {
  id: string
  email: string
  name: string
  passwordHash: string
  role: 'admin' | 'member' | 'viewer'
  emailVerified: boolean
  createdAt: Date
  updatedAt: Date
  lastLoginAt: Date | null
  stripeCustomerId: string | null
}

// ---- Derived Types ----
// Each type is a transformation of UserEntity

// Public profile — exposed to other users
type UserPublic = Pick<UserEntity, 'id' | 'name' | 'role' | 'createdAt'>
// Never includes email, passwordHash, or stripeCustomerId

// API response — returned to the authenticated user
type UserResponse = Omit<UserEntity, 'passwordHash' | 'stripeCustomerId'>
// Excludes sensitive fields but includes the user's own data

// Create input — fields required to create a user
type CreateUserInput = Pick<UserEntity, 'email' | 'name' | 'role'>
// Server generates: id, passwordHash, createdAt, updatedAt, emailVerified

// Update input — at least one field must be provided
type UpdateUserInput = RequireAtLeastOne<
  Pick<UserEntity, 'name' | 'email' | 'role'>
>
// Cannot update: id, passwordHash, createdAt (server-controlled)
// Must provide at least one field (RequireAtLeastOne)

// Admin view — includes sensitive fields for internal use
type UserAdmin = UserEntity
// Full access — only for admin endpoints

// ---- Standardized API Response Wrapper ----

type ApiResponse<T> =
  | { data: T; error: null }
  | { data: null; error: ApiError }

interface ApiError {
  code: string
  message: string
  details?: Record<string, string[]>
}

// USAGE:
async function getUser(id: string): Promise<ApiResponse<UserResponse>> {
  try {
    const user = await prisma.user.findUnique({ where: { id } })

    if (!user) {
      return {
        data: null,
        error: { code: 'NOT_FOUND', message: 'User not found' },
      }
    }

    // Omit strips sensitive fields from the response
    const { passwordHash, stripeCustomerId, ...response } = user
    return { data: response as UserResponse, error: null }
  } catch (err) {
    return {
      data: null,
      error: {
        code: 'INTERNAL_ERROR',
        message: 'Failed to fetch user',
      },
    }
  }
}

// ---- Paginated Response Type ----

type PaginatedResponse<T> = {
  data: T[]
  pagination: {
    page: number
    pageSize: number
    totalCount: number
    totalPages: number
  }
  error: null
}

// USAGE:
async function listUsers(
  page: number = 1,
  pageSize: number = 20
): Promise<PaginatedResponse<UserPublic>> {
  const [users, totalCount] = await Promise.all([
    prisma.user.findMany({
      skip: (page - 1) * pageSize,
      take: pageSize,
      select: {
        id: true,
        name: true,
        role: true,
        createdAt: true,
      },
    }),
    prisma.user.count(),
  ])

  return {
    data: users,
    pagination: {
      page,
      pageSize,
      totalCount,
      totalPages: Math.ceil(totalCount / pageSize),
    },
    error: null,
  }
}

// ============================================
// Form State Typing with Utility Types
// ============================================

// ---- Form Schema: Single Source of Truth ----

interface CheckoutFormSchema {
  email: string
  cardNumber: string
  expiryDate: string
  cvv: string
  billingAddress: {
    line1: string
    line2: string
    city: string
    state: string
    zip: string
    country: string
  }
}

// ---- Derived Types ----

// Form values: all fields required, matching the schema
type FormValues = Required<CheckoutFormSchema>

// Form errors: all fields nullable strings
type FormErrors = {
  [K in keyof CheckoutFormSchema]: CheckoutFormSchema[K] extends object
    ? { [P in keyof CheckoutFormSchema[K]]: string | null }
    : string | null
}

// Form touched: all fields booleans
type FormTouched = {
  [K in keyof CheckoutFormSchema]: CheckoutFormSchema[K] extends object
    ? { [P in keyof CheckoutFormSchema[K]]: boolean }
    : boolean
}

// Form dirty: tracks which fields have changed
type FormDirty = {
  [K in keyof CheckoutFormSchema]: boolean
}

// ---- Form State Container ----

interface FormState<T> {
  values: Required<T>
  errors: {
    [K in keyof T]: T[K] extends object
      ? { [P in keyof T[K]]: string | null }
      : string | null
  }
  touched: {
    [K in keyof T]: T[K] extends object
      ? { [P in keyof T[K]]: boolean }
      : boolean
  }
  dirty: { [K in keyof T]: boolean }
  isValid: boolean
  isSubmitting: boolean
}

// ---- Generic Form Hook Type ----

function useForm<T extends Record<string, any>>(
  schema: T,
  initialValues: Required<T>
): FormState<T> {
  // Implementation would use useReducer
  return {} as FormState<T>
}

// USAGE:
const form = useForm(CheckoutFormSchema, {
  email: '',
  cardNumber: '',
  expiryDate: '',
  cvv: '',
  billingAddress: {
    line1: '',
    line2: '',
    city: '',
    state: '',
    zip: '',
    country: '',
  },
})

// form.values.email — string
// form.errors.email — string | null
// form.touched.email — boolean
// form.dirty.email — boolean

// ============================================
// Event Handler Typing with Utility Types
// ============================================

import React from 'react'

// ---- Common Event Types ----

type InputChangeHandler = (e: React.ChangeEvent<HTMLInputElement>) => void
type FormSubmitHandler = (e: React.FormEvent<HTMLFormElement>) => void
type ButtonClickHandler = (e: React.MouseEvent<HTMLButtonElement>) => void
type SelectChangeHandler = (e: React.ChangeEvent<HTMLSelectElement>) => void
type KeyboardHandler = (e: React.KeyboardEvent<HTMLInputElement>) => void

// ---- Generic Event Handler Utility ----
// Derives handler type from element and event type

type EventHandler<
  E extends HTMLElement,
  T extends React.SyntheticEvent<E>
> = (event: T) => void

// USAGE:
type MyInputHandler = EventHandler<
  HTMLInputElement,
  React.ChangeEvent<HTMLInputElement>
>

// ---- Form Field Props Utility ----
// Generates typed props for form fields

type FormFieldProps<T> = {
  name: keyof T
  value: T[keyof T]
  onChange: (name: keyof T, value: T[keyof T]) => void
  error?: string | null
  touched?: boolean
}

// USAGE:
interface LoginForm {
  email: string
  password: string
  rememberMe: boolean
}

function TextField({ name, value, onChange, error, touched }: FormFieldProps<LoginForm>) {
  return (
    <div>
      <input
        name={name as string}
        value={value as string}
        onChange={(e) => onChange(name, e.target.value as LoginForm[keyof LoginForm])}
      />
      {touched && error && <span className="error">{error}</span>}
    </div>
  )
}

// ---- Typed Event Handler Factory ----
// Creates type-safe event handlers from a schema

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

// USAGE:
type LoginHandlers = EventHandlers<LoginForm>
// Result: {
//   onEmailChange: (value: string) => void
//   onPasswordChange: (value: string) => void
//   onRememberMeChange: (value: boolean) => void
// }

// ---- Custom Hook for Typed Form Handlers ----

function useTypedForm<T extends Record<string, any>>(
  initialValues: T
): {
  values: T
  errors: { [K in keyof T]: string | null }
  handlers: EventHandlers<T>
  handleSubmit: (onSubmit: (values: T) => void) => FormSubmitHandler
} {
  const [values, setValues] = React.useState<T>(initialValues)
  const [errors, setErrors] = React.useState<{ [K in keyof T]: string | null }>(
    Object.fromEntries(
      Object.keys(initialValues).map((k) => [k, null])
    ) as { [K in keyof T]: string | null }
  )

  const handlers = React.useMemo(() => {
    const result: any = {}
    for (const key of Object.keys(initialValues)) {
      const handlerName = `on${key.charAt(0).toUpperCase() + key.slice(1)}Change`
      result[handlerName] = (value: any) => {
        setValues((prev) => ({ ...prev, [key]: value }))
      }
    }
    return result as EventHandlers<T>
  }, [])

  const handleSubmit = React.useCallback(
    (onSubmit: (values: T) => void): FormSubmitHandler => {
      return (e) => {
        e.preventDefault()
        onSubmit(values)
      }
    },
    [values]
  )

  return { values, errors, handlers, handleSubmit }
}

// USAGE:
function LoginForm() {
  const { values, errors, handlers, handleSubmit } = useTypedForm({
    email: '',
    password: '',
    rememberMe: false,
  })

  return (
    <form onSubmit={handleSubmit((vals) => console.log(vals))}>
      <input
        value={values.email}
        onChange={(e) => handlers.onEmailChange(e.target.value)}
      />
      <input
        type="password"
        value={values.password}
        onChange={(e) => handlers.onPasswordChange(e.target.value)}
      />
      <button type="submit">Login</button>
    </form>
  )
}

// ============================================
// Mapped Types and Template Literal Types
// ============================================

// ---- Mapped Types ----
// Iterate over keys and transform values

// Basic mapped type
type Optional<T> = {
  [K in keyof T]?: T[K]
}

// Mapped type with key remapping (TypeScript 4.1+)
type Getters<T> = {
  [K in keyof T as `get${Capitalize<string & K>}`]: () => T[K]
}

// USAGE:
interface User {
  id: string
  name: string
  email: string
}

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

// Mapped type with value transformation
type Nullable<T> = {
  [K in keyof T]: T[K] | null
}

// Mapped type with conditional filtering
type StringProperties<T> = {
  [K in keyof T as T[K] extends string ? K : never]: T[K]
}

// USAGE:
type UserStrings = StringProperties<User>
// Result: { id: string; name: string; email: string }

// ---- Template Literal Types ----
// Manipulate string types at the type level

// Basic template literal
type EventName = `on${Capitalize<'click' | 'focus' | 'blur'>}`
// Result: 'onClick' | 'onFocus' | 'onBlur'

// API route generation from resource names
type ApiRoute<Resource extends string> =
  | `/api/${Resource}`
  | `/api/${Resource}/:id`

// USAGE:
type UserRoutes = ApiRoute<'users'>
// Result: '/api/users' | '/api/users/:id'

type ProductRoutes = ApiRoute<'products'>
// Result: '/api/products' | '/api/products/:id'

// CSS property generation
type CSSProperty = `--${string}`

function setCSSVariable(name: CSSProperty, value: string) {
  document.documentElement.style.setProperty(name, value)
}

// VALID:
setCSSVariable('--primary-color', '#ff0000')
setCSSVariable('--spacing-lg', '2rem')

// INVALID — compile error:
// setCSSVariable('primary-color', '#ff0000') // missing --

// ---- Combined: Event System Typing ----

type DomainEvents = {
  user: ['created', 'updated', 'deleted']
  order: ['placed', 'shipped', 'delivered', 'canceled']
  payment: ['succeeded', 'failed', 'refunded']
}

type EventKey = {
  [Domain in keyof DomainEvents]: `${Domain}.${DomainEvents[Domain][number]}`
}[keyof DomainEvents]

// Result:
// 'user.created' | 'user.updated' | 'user.deleted' |
// 'order.placed' | 'order.shipped' | 'order.delivered' | 'order.canceled' |
// 'payment.succeeded' | 'payment.failed' | 'payment.refunded'

// Event handler type from event key
type EventHandlerMap = {
  [K in EventKey]: (payload: any) => void
}

// ---- Combined: Database Query Builder Typing ----

type QueryOperator = 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'contains'

type QueryCondition<T> = {
  [K in keyof T as `${string & K}_${QueryOperator}`]?: T[K]
}

// USAGE:
type UserQuery = QueryCondition<User>
// Result: {
//   id_eq?: string
//   id_neq?: string
//   name_eq?: string
//   name_contains?: string
//   email_eq?: string
//   ...
// }

// ============================================
// Performance and Compilation Considerations
// ============================================

// ---- Expensive Patterns ----

// 1. Deep recursive types — exponential compilation cost
type DeepPartial<T> = T extends object
  ? { [P in keyof T]?: DeepPartial<T[P]> }
  : T

// At depth 5 with 10 properties each: 10^5 = 100,000 type nodes
// Compilation time: 2-5 seconds for a single usage

// 2. Large union distribution — combinatorial explosion
type AllCombinations<T extends string> = T extends any
  ? T | `${T}${AllCombinations<Exclude<T, T>>}`
  : never

// With 10 string members: generates thousands of union members
// Compilation time: 10-30 seconds

// 3. Mapped types over large interfaces — linear but significant
type DeepReadonly<T> = T extends object
  ? { readonly [P in keyof T]: DeepReadonly<T[P]> }
  : T

// Applied to an interface with 50 properties and 5 levels deep
// Compilation time: 1-3 seconds

// ---- Optimization Techniques ----

// Technique 1: Limit recursion depth
type DeepPartialOptimized<T, Depth extends number = 3> = Depth extends 0
  ? T
  : T extends object
  ? { [P in keyof T]?: DeepPartialOptimized<T[P], Prev<Depth>> }
  : T

type Prev<D extends number> = D extends 3 ? 2
  : D extends 2 ? 1
  : D extends 1 ? 0
  : 0

// Limits recursion to 3 levels — prevents exponential growth

// Technique 2: Use interfaces instead of type aliases for large objects
// Interfaces are cached by the compiler — type aliases are recomputed

interface UserEntity {
  id: string
  name: string
  email: string
  // ... 50 more properties
}

// Prefer interface over type for large object definitions

// Technique 3: Avoid unnecessary conditional types
// Conditional types trigger type inference — expensive for large unions

// SLOW:
type IsString<T> = T extends string ? true : false
type CheckAll<T> = { [K in keyof T]: IsString<T[K]> }

// FASTER — use indexed access instead of conditional:
type CheckAllFast<T> = { [K in keyof T]: T[K] extends string ? true : false }
// Inline conditionals are faster than nested type aliases

// Technique 4: Cache expensive computations with type aliases
// The compiler caches resolved type aliases

type ExpensiveComputation = DeepPartial<LargeInterface>
// Defined once — reused everywhere without recomputation

type CachedResult = ExpensiveComputation
// No recomputation — uses cached result

// Technique 5: Use 'satisfies' instead of type assertions
// satisfies preserves the inferred type while checking compatibility

const config = {
  port: 3000,
  host: 'localhost',
  database: 'mydb',
} satisfies Partial<AppConfig>
// config.port is number (inferred), not number | undefined (from Partial)
// Type checking happens at the assignment — no separate type computation

// ---- Benchmarking Type Compilation ----
// Use --diagnostics flag to measure compilation time
//
// Command: npx tsc --noEmit --diagnostics
//
// Key metrics:
//   - Check time: time spent type-checking
//   - Bind time: time spent binding symbols
//   - Total time: overall compilation time
//
// If check time > 10s, investigate complex types
// Use --generateTrace to identify expensive types:
//   npx tsc --generateTrace trace.json
//   Open trace.json in chrome://tracing