Migration Guide

function getUserEmail(id: string): string | undefined {
  const user = users.find(u => u.id === id)
  return user?.email
}

// Easy to forget null checks
const email = getUserEmail('123')
sendEmail(email.toUpperCase()) // 💥 Runtime error!

function getUserEmail(id: string): Option<string> {
  const user = users.find(u => u.id === id)
  return user ? some(user.email) : none()
}

// Type system forces you to handle absence
const email = unwrapOr(getUserEmail('123'), 'noreply@example.com')
sendEmail(email.toUpperCase()) // ✓ Always safe

// ❌ Before
function findUser(id: string): User | undefined
function getConfig(key: string): string | null
function parseNumber(str: string): number | undefined

// ✅ After
function findUser(id: string): Option<User>
function getConfig(key: string): Option<string>
function parseNumber(str: string): Option<number>

// ❌ Before
function findUser(id: string): User | undefined {
  const user = users.find(u => u.id === id)
  return user ?? undefined
}

// ✅ After
function findUser(id: string): Option<User> {
  const user = users.find(u => u.id === id)
  return user ? some(user) : none()
}

// Or simpler:
function findUser(id: string): Option<User> {
  return fromNullable(users.find(u => u.id === id))
}

// ❌ Before
const first = arr[0] ?? undefined
const found = arr.find(predicate) ?? undefined

// ✅ After
const first = fromNullable(arr[0])
const found = fromNullable(arr.find(predicate))

// ❌ Before
const user = findUser(id)
if (user !== undefined) {
  console.log(user.name)
} else {
  console.log('Not found')
}

// ✅ After
const user = findUser(id)
match(user, {
  onSome: u => console.log(u.name),
  onNone: () => console.log('Not found')
})

// ❌ Before
const email = user?.email?.toLowerCase()

// ✅ After
const email = pipe(
  fromNullable(user),
  map(u => u.email),
  map(e => e.toLowerCase())
)

// ❌ Before
const timeout = config.timeout ?? 5000

// ✅ After
const timeout = unwrapOr(fromNullable(config.timeout), 5000)

// ❌ Before
function getTeamLeadEmail(userId: string): string | undefined {
  const user = users.find(u => u.id === userId)
  if (!user) return undefined

  const team = teams.find(t => t.id === user.teamId)
  if (!team) return undefined

  const lead = users.find(u => u.id === team.leadId)
  if (!lead) return undefined

  return lead.email
}

// ✅ After
function getTeamLeadEmail(userId: string): Option<string> {
  return pipe(
    findUserById(userId),
    flatMap(user => findTeamById(user.teamId)),
    flatMap(team => findUserById(team.leadId)),
    map(lead => lead.email)
  )
}

// ❌ Before
const value = maybeValue ?? defaultValue

// ✅ After
const value = unwrapOr(maybeValue, defaultValue)

// ❌ Before
const value = maybeValue ?? expensiveComputation()

// ✅ After
const value = unwrapOrElse(maybeValue, () => expensiveComputation())

// Start here ✓
declare function findUser(id: string): Option<User>

// Then here
function getTeamLead(userId: string): Option<User> {
  return pipe(
    findUser(userId),  // Already migrated
    flatMap(user => findTeam(user.teamId))
  )
}

// New code using Option
declare function findUserOption(id: string): Option<User>

// Legacy wrapper
function findUser(id: string): User | undefined {
  return toNullable(findUserOption(id))
}

// Gradually phase out legacy wrapper

// database.ts - fully migrated
export declare function findById(id: string): Option<User>

// api.ts - partially migrated, uses conversion
import { findById } from './database'
const user = toNullable(findById(id))

// Eventually migrate api.ts too

// Bad - doesn't handle None
const email = unwrap(getUserEmail(id)) // Throws!

// Good
const email = unwrapOr(getUserEmail(id), 'noreply@example.com')

// Confusing - mixed types
function process(x: Option<string>): string | undefined

// Clear - consistent types
function process(x: Option<string>): Option<string>