TypeScript Tips That Actually Matter in Real Projects (including the satisfies operator)

// ❌ A type that tries to represent multiple states with optional fields
interface ApiResponse {
  data?: User
  error?: string
  isLoading: boolean
}

// ✅ Each state is explicit and mutually exclusive
type ApiResponse<T> =
  | { status: 'loading' }
  | { status: 'success'; data: T }
  | { status: 'error'; error: string }

function renderUser(response: ApiResponse<User>) {
  switch (response.status) {
    case 'loading':
      return 'Loading...'
    case 'success':
      return response.data.name  // TypeScript knows data exists here
    case 'error':
      return response.error      // TypeScript knows error exists here
  }
}

// ❌ Manually maintaining two overlapping types
interface User {
  id: string
  email: string
  firstName: string
  lastName: string
  role: 'admin' | 'user'
  createdAt: string
}

// Manually duplicated, will drift from User when User changes
interface UpdateUserPayload {
  email?: string
  firstName?: string
  lastName?: string
}

// Manually duplicated again
interface UserPreview {
  id: string
  firstName: string
  lastName: string
}

// ✅ Derived from the source of truth, always in sync
interface User {
  id: string
  email: string
  firstName: string
  lastName: string
  role: 'admin' | 'user'
  createdAt: string
}

// Partial makes all fields optional
type UpdateUserPayload = Partial<Pick<User, 'email' | 'firstName' | 'lastName'>>

// Pick selects specific fields
type UserPreview = Pick<User, 'id' | 'firstName' | 'lastName'>

// Omit removes specific fields
type UserWithoutMeta = Omit<User, 'createdAt' | 'role'>

// Required makes all fields required (opposite of Partial)
type StrictUser = Required<User>

// Readonly makes all fields immutable
type ImmutableUser = Readonly<User>

// Create payload: no id or metadata, those are server-generated
type CreateUserPayload = Omit<User, 'id' | 'createdAt'>

// Update payload: everything optional except what can't change
type UpdateUserPayload = Partial<Omit<User, 'id' | 'createdAt' | 'role'>>

// ❌ Explicit annotation loses specific type information
const config: Record<string, string> = {
  host: 'localhost',
  port: '5432',
}

config.host  // type: string, you've lost 'localhost'
config.nonExistent  // No error! The index signature allows any key

// ❌ No annotation, no validation
const config = {
  host: 'localhost',
  port: '5432',
}

config.host         // type: 'localhost' ✅
config.nonExistent  // Error ✅, but you have no shape validation

// ✅ Validates against the shape AND preserves specific types
type AppConfig = {
  host: string
  port: string
  database: string
}

const config = {
  host: 'localhost',
  port: '5432',
  database: 'myapp',
  unknownKey: 'oops',  // ❌ Error: Object literal may only specify known properties
} satisfies AppConfig

config.host  // type: 'localhost', specific type preserved ✅

type Routes = Record<string, { path: string; exact?: boolean }>

const routes = {
  home: { path: '/' },
  about: { path: '/about' },
  profile: { path: '/profile/:id', exact: true },
} satisfies Routes

routes.home.path   // type: '/', not just string
routes.unknown     // ❌ Error, unknown key caught at compile time

// ❌ TypeScript widens these to string[], you lose the specific values
const STATUSES = ['pending', 'active', 'cancelled', 'completed']

type Status = typeof STATUSES[number]  // type: string, not what you wanted

// ✅ as const preserves literal types
const STATUSES = ['pending', 'active', 'cancelled', 'completed'] as const

type Status = typeof STATUSES[number]
// type: 'pending' | 'active' | 'cancelled' | 'completed' ✅

// The array itself is also typed precisely
const firstStatus = STATUSES[0]  // type: 'pending'

const HTTP_CODES = {
  OK: 200,
  CREATED: 201,
  BAD_REQUEST: 400,
  UNAUTHORIZED: 401,
  NOT_FOUND: 404,
  INTERNAL_ERROR: 500,
} as const

type HttpCode = typeof HTTP_CODES[keyof typeof HTTP_CODES]
// type: 200 | 201 | 400 | 401 | 404 | 500

function handleResponse(code: HttpCode) {
  // TypeScript knows exactly which values are valid
}

handleResponse(HTTP_CODES.OK)   // ✅
handleResponse(999)              // ❌ Error: 999 is not assignable to HttpCode

// ❌ Casting tells TypeScript to trust you, and you might be wrong
async function fetchUser(id: string) {
  const response = await fetch(`/api/users/${id}`)
  const data = await response.json()
  return data as User  // TypeScript believes you. The runtime doesn't care.
}

// ✅ Validate the shape at runtime, TypeScript trusts what you verify

function isUser(value: unknown): value is User {
  return (
    typeof value === 'object' &&
    value !== null &&
    'id' in value &&
    'email' in value &&
    'firstName' in value &&
    typeof (value as any).id === 'string' &&
    typeof (value as any).email === 'string'
  )
}

async function fetchUser(id: string): Promise<User> {
  const response = await fetch(`/api/users/${id}`)
  const data: unknown = await response.json()

  if (!isUser(data)) {
    throw new Error(`Invalid user response for id: ${id}`)
  }

  return data  // TypeScript now knows this is User, and it's been verified
}

// ❌ Three functions doing the same thing for different types
function getFirstUser(items: User[]): User | undefined {
  return items[0]
}

function getFirstProduct(items: Product[]): Product | undefined {
  return items[0]
}

function getFirstOrder(items: Order[]): Order | undefined {
  return items[0]
}

// ❌ any kills type safety entirely
function getFirst(items: any[]): any {
  return items[0]
}

// ✅ One function, full type safety across all types
function getFirst<T>(items: T[]): T | undefined {
  return items[0]
}

const firstUser = getFirst(users)      // type: User | undefined
const firstProduct = getFirst(products) // type: Product | undefined
const firstNumber = getFirst([1, 2, 3]) // type: number | undefined

// Only works with objects that have an id field
function findById<T extends { id: string }>(items: T[], id: string): T | undefined {
  return items.find(item => item.id === id)
}

findById(users, 'user-1')      // ✅ User has id
findById(products, 'prod-1')   // ✅ Product has id
findById([1, 2, 3], 'x')       // ❌ Error: number doesn't have id

async function apiFetch<T>(url: string): Promise<T> {
  const response = await fetch(url)
  if (!response.ok) throw new Error(`HTTP error: ${response.status}`)
  return response.json() as Promise<T>
}

// The return type is inferred from the type parameter
const user = await apiFetch<User>('/api/users/1')     // type: User
const products = await apiFetch<Product[]>('/api/products') // type: Product[]

// ❌ Manually written type that will drift from the actual function
interface UserServiceResult {
  id: string
  name: string
  // ...but what if userService.getUser() changes?
}

function processUser(user: UserServiceResult) {
  // ...
}

// ✅ Types derived directly from the functions, always in sync

function getUser(id: string) {
  return {
    id,
    firstName: 'Gavin',
    lastName: 'Cettolo',
    role: 'admin' as const,
    createdAt: new Date().toISOString(),
  }
}

// Automatically matches whatever getUser returns
type User = ReturnType<typeof getUser>

// Automatically matches whatever getUser accepts
type GetUserParams = Parameters<typeof getUser>
// type: [id: string]

function processUser(user: User) {
  // user has exactly the shape of getUser's return value
  // If getUser changes, processUser is immediately aware
  console.log(user.firstName)
}

import { createStore } from 'some-library'

// Extract the return type without importing a separate type
type Store = ReturnType<typeof createStore>

// Extract what the function expects
type StoreConfig = Parameters<typeof createStore>[0]

// ❌ any propagates silently, errors hide until runtime
function parseConfig(raw: any) {
  return {
    port: raw.port,           // No error even if raw.port doesn't exist
    host: raw.host.trim(),    // Runtime crash if host is undefined
    debug: raw.debug,
  }
}

// ✅ unknown forces you to verify before you use
function parseConfig(raw: unknown): AppConfig {
  if (
    typeof raw !== 'object' ||
    raw === null ||
    !('port' in raw) ||
    !('host' in raw)
  ) {
    throw new Error('Invalid config shape')
  }

  const { port, host } = raw as { port: unknown; host: unknown }

  if (typeof port !== 'number' || typeof host !== 'string') {
    throw new Error('Invalid config field types')
  }

  return { port, host }
}

// API responses
const data: unknown = await response.json()

// Error handling, errors thrown in try/catch are unknown
try {
  await riskyOperation()
} catch (error: unknown) {
  if (error instanceof Error) {
    console.error(error.message)  // Safe: TypeScript knows it's an Error
  }
}

// JSON.parse, the return type is any by default, worth narrowing immediately
const parsed: unknown = JSON.parse(rawString)

// Generate precise string types programmatically
type EventName = 'click' | 'focus' | 'blur'
type HandlerName = `on${Capitalize<EventName>}`
// type: 'onClick' | 'onFocus' | 'onBlur'

type ApiEndpoint = `/api/v1/${'users' | 'products' | 'orders'}`
// type: '/api/v1/users' | '/api/v1/products' | '/api/v1/orders'

// TypeScript will error if you forget to handle a case
function assertNever(value: never): never {
  throw new Error(`Unhandled case: ${JSON.stringify(value)}`)
}

type Shape = 'circle' | 'square' | 'triangle'

function getArea(shape: Shape, size: number): number {
  switch (shape) {
    case 'circle': return Math.PI * size ** 2
    case 'square': return size ** 2
    case 'triangle': return (Math.sqrt(3) / 4) * size ** 2
    default: return assertNever(shape) // Error if a case is missing
  }
}

// ❌ Loose index signature, any string key is valid
interface Config {
  [key: string]: string
}

// ✅ Prefer Record with a union of known keys
type Config = Record<'host' | 'port' | 'database', string>

// Or use satisfies + as const for maximum precision
const config = {
  host: 'localhost',
  port: '5432',
  database: 'myapp',
} satisfies Record<string, string>