Practical Error Handling with fp-ts by whatiskadudoing/fp-ts-skills
npx skills add https://github.com/whatiskadudoing/fp-ts-skills --skill 'Practical Error Handling with fp-ts'本技能教你如何在不使用 try/catch 混乱代码的情况下处理错误。没有学术术语——只有针对实际问题的实用模式。
核心理念:错误就是数据。与其将它们抛入虚空并希望有人捕获,不如将它们作为 TypeScript 可以跟踪的值返回。
异常在你的类型中是不可见的。它们破坏了函数之间的契约。
// 这个函数签名承诺的内容:
function getUser(id: string): User
// 它实际做的事情:
function getUser(id: string): User {
if (!id) throw new Error('ID required')
const user = db.find(id)
if (!user) throw new Error('User not found')
return user
}
// 调用者不知道这可能会失败
const user = getUser(id) // 可能会爆炸!
你最终会得到这样的代码:
// 混乱:到处都是 try/catch
function processOrder(orderId: string) {
let order
try {
order = getOrder(orderId)
} catch (e) {
console.error('Failed to get order')
return null
}
let user
try {
user = getUser(order.userId)
} catch (e) {
console.error('Failed to get user')
return null
}
let payment
try {
payment = chargeCard(user.cardId, order.total)
} catch (e) {
console.error('Payment failed')
return null
}
return { order, user, payment }
}
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
import * as E from 'fp-ts/Either'
import { pipe } from 'fp-ts/function'
// 现在 TypeScript 知道这可能会失败
function getUser(id: string): E.Either<string, User> {
if (!id) return E.left('ID required')
const user = db.find(id)
if (!user) return E.left('User not found')
return E.right(user)
}
// 调用者被迫处理两种情况
const result = getUser(id)
// result 是 Either<string, User> - 错误或成功,永远不会同时出现
Either<E, A> 很简单:它要么包含一个错误(E),要么包含一个值(A)。
Left = 错误情况
Right = 成功情况(可以理解为 "right" 即 "正确")
import * as E from 'fp-ts/Either'
// 创建值 const success = E.right(42) // Right(42) const failure = E.left('Oops') // Left('Oops')
// 检查你拥有什么 if (E.isRight(result)) { console.log(result.right) // 成功值 } else { console.log(result.left) // 错误 }
// 更好的方式:使用 fold 进行模式匹配
const message = pipe(
result,
E.fold(
(error) => Failed: ${error},
(value) => Got: ${value}
)
)
// 使用 tryCatch 包装任何抛出错误的函数
const parseJSON = (json: string): E.Either<Error, unknown> =>
E.tryCatch(
() => JSON.parse(json),
(e) => (e instanceof Error ? e : new Error(String(e)))
)
parseJSON('{"valid": true}') // Right({ valid: true })
parseJSON('not json') // Left(SyntaxError: ...)
// 对于要重用的函数,使用 tryCatchK
const safeParseJSON = E.tryCatchK(
JSON.parse,
(e) => (e instanceof Error ? e : new Error(String(e)))
)
import * as E from 'fp-ts/Either'
import { pipe } from 'fp-ts/function'
// 转换成功值
const doubled = pipe(
E.right(21),
E.map(n => n * 2)
) // Right(42)
// 转换错误
const betterError = pipe(
E.left('bad'),
E.mapLeft(e => `Error: ${e}`)
) // Left('Error: bad')
// 为错误提供默认值
const value = pipe(
E.left('failed'),
E.getOrElse(() => 0)
) // 0
// 将可为空的值转换为 Either
const fromNullable = E.fromNullable('not found')
fromNullable(user) // 如果存在则为 Right(user),如果为 null/undefined 则为 Left('not found')
真正的威力来自于链接。每个步骤都可能失败,但你可以将其写成一个清晰的管道。
// 混乱:每个步骤都可能失败,到处都是嵌套的 try/catch
function processUserOrder(userId: string, productId: string): Result | null {
let user
try {
user = getUser(userId)
} catch (e) {
logError('User fetch failed', e)
return null
}
if (!user.isActive) {
logError('User not active')
return null
}
let product
try {
product = getProduct(productId)
} catch (e) {
logError('Product fetch failed', e)
return null
}
if (product.stock < 1) {
logError('Out of stock')
return null
}
let order
try {
order = createOrder(user, product)
} catch (e) {
logError('Order creation failed', e)
return null
}
return order
}
import * as E from 'fp-ts/Either'
import { pipe } from 'fp-ts/function'
// 每个函数都返回 Either<Error, T>
const getUser = (id: string): E.Either<string, User> => { ... }
const getProduct = (id: string): E.Either<string, Product> => { ... }
const createOrder = (user: User, product: Product): E.Either<string, Order> => { ... }
// 将它们链接在一起 - 第一个错误会停止链式调用
const processUserOrder = (userId: string, productId: string): E.Either<string, Order> =>
pipe(
getUser(userId),
E.filterOrElse(
user => user.isActive,
() => 'User not active'
),
E.chain(user =>
pipe(
getProduct(productId),
E.filterOrElse(
product => product.stock >= 1,
() => 'Out of stock'
),
E.chain(product => createOrder(user, product))
)
)
)
// 或者使用 Do 表示法来更清晰地访问中间值
const processUserOrder = (userId: string, productId: string): E.Either<string, Order> =>
pipe(
E.Do,
E.bind('user', () => getUser(userId)),
E.filterOrElse(
({ user }) => user.isActive,
() => 'User not active'
),
E.bind('product', () => getProduct(productId)),
E.filterOrElse(
({ product }) => product.stock >= 1,
() => 'Out of stock'
),
E.chain(({ user, product }) => createOrder(user, product))
)
type ValidationError = { type: 'validation'; message: string }
type DbError = { type: 'db'; message: string }
const validateInput = (id: string): E.Either<ValidationError, string> => { ... }
const fetchFromDb = (id: string): E.Either<DbError, User> => { ... }
// chainW(W 表示 "更宽")会自动联合错误类型
const process = (id: string): E.Either<ValidationError | DbError, User> =>
pipe(
validateInput(id),
E.chainW(validId => fetchFromDb(validId))
)
有时你想要所有的错误,而不仅仅是第一个错误。表单验证是典型的例子。
// 混乱:手动错误累积
function validateForm(form: FormData): { valid: boolean; errors: string[] } {
const errors: string[] = []
if (!form.email) {
errors.push('Email required')
} else if (!form.email.includes('@')) {
errors.push('Invalid email')
}
if (!form.password) {
errors.push('Password required')
} else if (form.password.length < 8) {
errors.push('Password too short')
}
if (!form.age) {
errors.push('Age required')
} else if (form.age < 18) {
errors.push('Must be 18+')
}
return { valid: errors.length === 0, errors }
}
import * as E from 'fp-ts/Either'
import * as NEA from 'fp-ts/NonEmptyArray'
import { sequenceS } from 'fp-ts/Apply'
import { pipe } from 'fp-ts/function'
// 错误作为 NonEmptyArray(至少有一个)
type Errors = NEA.NonEmptyArray<string>
// 创建累积错误的 applicative
const validation = E.getApplicativeValidation(NEA.getSemigroup<string>())
// 返回 Either<Errors, T> 的验证器
const validateEmail = (email: string): E.Either<Errors, string> =>
!email ? E.left(NEA.of('Email required'))
: !email.includes('@') ? E.left(NEA.of('Invalid email'))
: E.right(email)
const validatePassword = (password: string): E.Either<Errors, string> =>
!password ? E.left(NEA.of('Password required'))
: password.length < 8 ? E.left(NEA.of('Password too short'))
: E.right(password)
const validateAge = (age: number | undefined): E.Either<Errors, number> =>
age === undefined ? E.left(NEA.of('Age required'))
: age < 18 ? E.left(NEA.of('Must be 18+'))
: E.right(age)
// 组合所有验证 - 收集所有错误
const validateForm = (form: FormData) =>
sequenceS(validation)({
email: validateEmail(form.email),
password: validatePassword(form.password),
age: validateAge(form.age)
})
// 用法
validateForm({ email: '', password: '123', age: 15 })
// Left(['Email required', 'Password too short', 'Must be 18+'])
validateForm({ email: 'a@b.com', password: 'longpassword', age: 25 })
// Right({ email: 'a@b.com', password: 'longpassword', age: 25 })
interface FieldError {
field: string
message: string
}
type FormErrors = NEA.NonEmptyArray<FieldError>
const fieldError = (field: string, message: string): FormErrors =>
NEA.of({ field, message })
const formValidation = E.getApplicativeValidation(NEA.getSemigroup<FieldError>())
// 现在错误知道它们属于哪个字段
const validateEmail = (email: string): E.Either<FormErrors, string> =>
!email ? E.left(fieldError('email', 'Required'))
: !email.includes('@') ? E.left(fieldError('email', 'Invalid format'))
: E.right(email)
// 易于在 UI 中显示
const getFieldError = (errors: FormErrors, field: string): string | undefined =>
errors.find(e => e.field === field)?.message
对于可能失败的异步操作,使用 TaskEither。它类似于 Either,但用于 Promise。
TaskEither<E, A> = 返回 Promise<Either<E, A>> 的函数
惰性:在执行之前不会运行任何操作
import * as TE from 'fp-ts/TaskEither' import { pipe } from 'fp-ts/function'
// 包装任何异步操作
const fetchUser = (id: string): TE.TaskEither<Error, User> =>
TE.tryCatch(
() => fetch(/api/users/${id}).then(r => r.json()),
(e) => (e instanceof Error ? e : new Error(String(e)))
)
// 链接异步操作 - 就像 Either 一样 const getUserPosts = (userId: string): TE.TaskEither<Error, Post[]> => pipe( fetchUser(userId), TE.chain(user => fetchPosts(user.id)) )
// 准备就绪时执行 const result = await getUserPosts('123')() // 返回 Either<Error, Post[]>
// 混乱:try/catch 与 promise 链混合
async function loadDashboard(userId: string) {
try {
const user = await fetchUser(userId)
if (!user) throw new Error('User not found')
let posts, notifications, settings
try {
[posts, notifications, settings] = await Promise.all([
fetchPosts(user.id),
fetchNotifications(user.id),
fetchSettings(user.id)
])
} catch (e) {
// 哪个失败了?谁知道!
console.error('Failed to load data', e)
return null
}
return { user, posts, notifications, settings }
} catch (e) {
console.error('Failed to load user', e)
return null
}
}
import * as TE from 'fp-ts/TaskEither'
import { sequenceS } from 'fp-ts/Apply'
import { pipe } from 'fp-ts/function'
const loadDashboard = (userId: string) =>
pipe(
fetchUser(userId),
TE.chain(user =>
pipe(
// 使用 sequenceS 并行获取
sequenceS(TE.ApplyPar)({
posts: fetchPosts(user.id),
notifications: fetchNotifications(user.id),
settings: fetchSettings(user.id)
}),
TE.map(data => ({ user, ...data }))
)
)
)
// 执行并处理两种情况
pipe(
loadDashboard('123'),
TE.fold(
(error) => T.of(renderError(error)),
(data) => T.of(renderDashboard(data))
)
)()
import * as T from 'fp-ts/Task'
import * as TE from 'fp-ts/TaskEither'
import { pipe } from 'fp-ts/function'
const retry = <E, A>(
task: TE.TaskEither<E, A>,
attempts: number,
delayMs: number
): TE.TaskEither<E, A> =>
pipe(
task,
TE.orElse((error) =>
attempts > 1
? pipe(
T.delay(delayMs)(T.of(undefined)),
T.chain(() => retry(task, attempts - 1, delayMs * 2))
)
: TE.left(error)
)
)
// 重试最多 3 次,使用指数退避
const fetchWithRetry = retry(fetchUser('123'), 3, 1000)
// 先尝试缓存,回退到 API
const getUserData = (id: string) =>
pipe(
fetchFromCache(id),
TE.orElse(() => fetchFromApi(id)),
TE.orElse(() => TE.right(defaultUser)) // 最后的默认值
)
真实的代码库有抛出错误的函数、可为空的值和 Promise。以下是如何处理它们。
import * as E from 'fp-ts/Either'
import * as O from 'fp-ts/Option'
// 直接转换
const user = users.find(u => u.id === id) // User | undefined
const result = E.fromNullable('User not found')(user)
// 从 Option 转换
const maybeUser: O.Option<User> = O.fromNullable(user)
const eitherUser = pipe(
maybeUser,
E.fromOption(() => 'User not found')
)
// 在边界处包装
const safeParse = <T>(schema: ZodSchema<T>) => (data: unknown): E.Either<ZodError, T> =>
E.tryCatch(
() => schema.parse(data),
(e) => e as ZodError
)
// 在整个代码中使用
const parseUser = safeParse(UserSchema)
const result = parseUser(rawData) // Either<ZodError, User>
import * as TE from 'fp-ts/TaskEither'
// 包装外部异步函数
const fetchJson = <T>(url: string): TE.TaskEither<Error, T> =>
TE.tryCatch(
() => fetch(url).then(r => r.json()),
(e) => new Error(`Fetch failed: ${e}`)
)
// 包装 axios、prisma 或任何异步库
const getUserFromDb = (id: string): TE.TaskEither<DbError, User> =>
TE.tryCatch(
() => prisma.user.findUniqueOrThrow({ where: { id } }),
(e) => ({ code: 'DB_ERROR', cause: e })
)
有时你需要一个普通的 Promise 用于外部 API。
import * as TE from 'fp-ts/TaskEither'
import * as E from 'fp-ts/Either'
const myTaskEither: TE.TaskEither<Error, User> = fetchUser('123')
// 选项 1:获取 Either(保留两种情况)
const either: E.Either<Error, User> = await myTaskEither()
// 选项 2:出错时抛出(用于遗留代码)
const toThrowingPromise = <E, A>(te: TE.TaskEither<E, A>): Promise<A> =>
te().then(E.fold(
(error) => Promise.reject(error),
(value) => Promise.resolve(value)
))
const user = await toThrowingPromise(fetchUser('123')) // 如果为 Left 则抛出
// 选项 3:出错时使用默认值
const user = await pipe(
fetchUser('123'),
TE.getOrElse(() => T.of(defaultUser))
)()
interface ParsedInput {
id: number
name: string
tags: string[]
}
const parseInput = (raw: unknown): E.Either<string, ParsedInput> =>
pipe(
E.Do,
E.bind('obj', () =>
typeof raw === 'object' && raw !== null
? E.right(raw as Record<string, unknown>)
: E.left('Input must be an object')
),
E.bind('id', ({ obj }) =>
typeof obj.id === 'number'
? E.right(obj.id)
: E.left('id must be a number')
),
E.bind('name', ({ obj }) =>
typeof obj.name === 'string' && obj.name.length > 0
? E.right(obj.name)
: E.left('name must be a non-empty string')
),
E.bind('tags', ({ obj }) =>
Array.isArray(obj.tags) && obj.tags.every(t => typeof t === 'string')
? E.right(obj.tags as string[])
: E.left('tags must be an array of strings')
),
E.map(({ id, name, tags }) => ({ id, name, tags }))
)
// 用法
parseInput({ id: 1, name: 'test', tags: ['a', 'b'] })
// Right({ id: 1, name: 'test', tags: ['a', 'b'] })
parseInput({ id: 'wrong', name: '', tags: null })
// Left('id must be a number')
interface ApiError {
code: string
message: string
status?: number
}
const createApiError = (message: string, code = 'UNKNOWN', status?: number): ApiError =>
({ code, message, status })
const fetchWithErrorHandling = <T>(url: string): TE.TaskEither<ApiError, T> =>
pipe(
TE.tryCatch(
() => fetch(url),
() => createApiError('Network error', 'NETWORK')
),
TE.chain(response =>
response.ok
? TE.tryCatch(
() => response.json() as Promise<T>,
() => createApiError('Invalid JSON', 'PARSE')
)
: TE.left(createApiError(
`HTTP ${response.status}`,
response.status === 404 ? 'NOT_FOUND' : 'HTTP_ERROR',
response.status
))
)
)
// 根据错误代码进行模式匹配的用法
const handleUserFetch = (userId: string) =>
pipe(
fetchWithErrorHandling<User>(`/api/users/${userId}`),
TE.fold(
(error) => {
switch (error.code) {
case 'NOT_FOUND': return T.of(showNotFoundPage())
case 'NETWORK': return T.of(showOfflineMessage())
default: return T.of(showGenericError(error.message))
}
},
(user) => T.of(showUserProfile(user))
)
)
import * as A from 'fp-ts/Array'
import * as E from 'fp-ts/Either'
import { pipe } from 'fp-ts/function'
interface ProcessResult<T> {
successes: T[]
failures: Array<{ item: unknown; error: string }>
}
// 处理所有项目,分别收集成功和失败
const processAllCollectErrors = <T, R>(
items: T[],
process: (item: T) => E.Either<string, R>
): ProcessResult<R> => {
const results = items.map((item, index) =>
pipe(
process(item),
E.mapLeft(error => ({ item, error, index }))
)
)
return {
successes: pipe(results, A.filterMap(E.toOption)),
failures: pipe(
results,
A.filterMap(r => E.isLeft(r) ? O.some(r.left) : O.none)
)
}
}
// 用法
const parseNumbers = (inputs: string[]) =>
processAllCollectErrors(inputs, input => {
const n = parseInt(input, 10)
return isNaN(n) ? E.left(`Invalid number: ${input}`) : E.right(n)
})
parseNumbers(['1', 'abc', '3', 'def'])
// {
// successes: [1, 3],
// failures: [
// { item: 'abc', error: 'Invalid number: abc', index: 1 },
// { item: 'def', error: 'Invalid number: def', index: 3 }
// ]
// }
import * as TE from 'fp-ts/TaskEither'
import * as T from 'fp-ts/Task'
import { pipe } from 'fp-ts/function'
interface BulkResult<T> {
succeeded: T[]
failed: Array<{ id: string; error: string }
}
const bulkProcess = <T>(
ids: string[],
process: (id: string) => TE.TaskEither<string, T>
): T.Task<BulkResult<T>> =>
pipe(
ids,
A.map(id =>
pipe(
process(id),
TE.fold(
(error) => T.of({ type: 'failed' as const, id, error }),
(result) => T.of({ type: 'succeeded' as const, result })
)
)
),
T.sequenceArray,
T.map(results => ({
succeeded: results
.filter((r): r is { type: 'succeeded'; result: T } => r.type === 'succeeded')
.map(r => r.result),
failed: results
.filter((r): r is { type: 'failed'; id: string; error: string } => r.type === 'failed')
.map(({ id, error }) => ({ id, error }))
}))
)
// 用法
const deleteUsers = (userIds: string[]) =>
bulkProcess(userIds, id =>
pipe(
deleteUser(id),
TE.mapLeft(e => e.message)
)
)
// 所有操作都会运行,你会得到一份关于哪些成功哪些失败的报告
| 模式 | 使用场景 | 示例 |
|---|---|---|
E.right(value) | 创建成功 | E.right(42) |
E.left(error) | 创建失败 | E.left('not found') |
E.tryCatch(fn, onError) | 包装抛出错误的代码 | E.tryCatch(() => JSON.parse(s), toError) |
E.fromNullable(error) | 转换可为空的值 | E.fromNullable('missing')(maybeValue) |
E.map(fn) | 转换成功值 | pipe(result, E.map(x => x * 2)) |
E.mapLeft(fn) | 转换错误 | pipe(result, E.mapLeft(addContext)) |
E.chain(fn) | 链接操作 | pipe(getA(), E.chain(a => getB(a.id))) |
E.chainW(fn) | 链接不同错误类型的操作 | pipe(validate(), E.chainW(save)) |
E.fold(onError, onSuccess) | 处理两种情况 | E.fold(showError, showData) |
E.getOrElse(onError) | 提取并附带默认值 | E.getOrElse(() => 0) |
E.filterOrElse(pred, onFalse) | 验证并附带错误 | E.filterOrElse(x => x > 0, () => 'must be positive') |
sequenceS(validation)({...}) | 收集所有错误 | 表单验证 |
所有 Either 操作都有对应的 TaskEither 等价操作:
TE.right, TE.left, TE.tryCatchTE.map, TE.mapLeft, TE.chain, TE.chainWTE.fold, TE.getOrElse, TE.filterOrElseTE.orElse 用于回退chain 会在第一个错误处自动停止fold 在准备行动时处理两种情况回报:TypeScript 跟踪你的错误,不再有遗忘的 try/catch,清晰的控制流,以及可组合的错误处理。
每周安装次数
–
代码仓库
GitHub 星标数
4
首次出现时间
–
安全审计
This skill teaches you how to handle errors without try/catch spaghetti. No academic jargon - just practical patterns for real problems.
The core idea: Errors are just data. Instead of throwing them into the void and hoping someone catches them, return them as values that TypeScript can track.
Exceptions are invisible in your types. They break the contract between functions.
// What this function signature promises:
function getUser(id: string): User
// What it actually does:
function getUser(id: string): User {
if (!id) throw new Error('ID required')
const user = db.find(id)
if (!user) throw new Error('User not found')
return user
}
// The caller has no idea this can fail
const user = getUser(id) // Might explode!
You end up with code like this:
// MESSY: try/catch everywhere
function processOrder(orderId: string) {
let order
try {
order = getOrder(orderId)
} catch (e) {
console.error('Failed to get order')
return null
}
let user
try {
user = getUser(order.userId)
} catch (e) {
console.error('Failed to get user')
return null
}
let payment
try {
payment = chargeCard(user.cardId, order.total)
} catch (e) {
console.error('Payment failed')
return null
}
return { order, user, payment }
}
import * as E from 'fp-ts/Either'
import { pipe } from 'fp-ts/function'
// Now TypeScript KNOWS this can fail
function getUser(id: string): E.Either<string, User> {
if (!id) return E.left('ID required')
const user = db.find(id)
if (!user) return E.left('User not found')
return E.right(user)
}
// The caller is forced to handle both cases
const result = getUser(id)
// result is Either<string, User> - error OR success, never both
Either<E, A> is simple: it holds either an error (E) or a value (A).
Left = error case
Right = success case (think "right" as in "correct")
import * as E from 'fp-ts/Either'
// Creating values const success = E.right(42) // Right(42) const failure = E.left('Oops') // Left('Oops')
// Checking what you have if (E.isRight(result)) { console.log(result.right) // The success value } else { console.log(result.left) // The error }
// Better: pattern match with fold
const message = pipe(
result,
E.fold(
(error) => Failed: ${error},
(value) => Got: ${value}
)
)
// Wrap any throwing function with tryCatch
const parseJSON = (json: string): E.Either<Error, unknown> =>
E.tryCatch(
() => JSON.parse(json),
(e) => (e instanceof Error ? e : new Error(String(e)))
)
parseJSON('{"valid": true}') // Right({ valid: true })
parseJSON('not json') // Left(SyntaxError: ...)
// For functions you'll reuse, use tryCatchK
const safeParseJSON = E.tryCatchK(
JSON.parse,
(e) => (e instanceof Error ? e : new Error(String(e)))
)
import * as E from 'fp-ts/Either'
import { pipe } from 'fp-ts/function'
// Transform the success value
const doubled = pipe(
E.right(21),
E.map(n => n * 2)
) // Right(42)
// Transform the error
const betterError = pipe(
E.left('bad'),
E.mapLeft(e => `Error: ${e}`)
) // Left('Error: bad')
// Provide a default for errors
const value = pipe(
E.left('failed'),
E.getOrElse(() => 0)
) // 0
// Convert nullable to Either
const fromNullable = E.fromNullable('not found')
fromNullable(user) // Right(user) if exists, Left('not found') if null/undefined
The real power comes from chaining. Each step can fail, but you write it as a clean pipeline.
// MESSY: Each step can fail, nested try/catch everywhere
function processUserOrder(userId: string, productId: string): Result | null {
let user
try {
user = getUser(userId)
} catch (e) {
logError('User fetch failed', e)
return null
}
if (!user.isActive) {
logError('User not active')
return null
}
let product
try {
product = getProduct(productId)
} catch (e) {
logError('Product fetch failed', e)
return null
}
if (product.stock < 1) {
logError('Out of stock')
return null
}
let order
try {
order = createOrder(user, product)
} catch (e) {
logError('Order creation failed', e)
return null
}
return order
}
import * as E from 'fp-ts/Either'
import { pipe } from 'fp-ts/function'
// Each function returns Either<Error, T>
const getUser = (id: string): E.Either<string, User> => { ... }
const getProduct = (id: string): E.Either<string, Product> => { ... }
const createOrder = (user: User, product: Product): E.Either<string, Order> => { ... }
// Chain them together - first error stops the chain
const processUserOrder = (userId: string, productId: string): E.Either<string, Order> =>
pipe(
getUser(userId),
E.filterOrElse(
user => user.isActive,
() => 'User not active'
),
E.chain(user =>
pipe(
getProduct(productId),
E.filterOrElse(
product => product.stock >= 1,
() => 'Out of stock'
),
E.chain(product => createOrder(user, product))
)
)
)
// Or use Do notation for cleaner access to intermediate values
const processUserOrder = (userId: string, productId: string): E.Either<string, Order> =>
pipe(
E.Do,
E.bind('user', () => getUser(userId)),
E.filterOrElse(
({ user }) => user.isActive,
() => 'User not active'
),
E.bind('product', () => getProduct(productId)),
E.filterOrElse(
({ product }) => product.stock >= 1,
() => 'Out of stock'
),
E.chain(({ user, product }) => createOrder(user, product))
)
type ValidationError = { type: 'validation'; message: string }
type DbError = { type: 'db'; message: string }
const validateInput = (id: string): E.Either<ValidationError, string> => { ... }
const fetchFromDb = (id: string): E.Either<DbError, User> => { ... }
// chainW (W = "wider") automatically unions the error types
const process = (id: string): E.Either<ValidationError | DbError, User> =>
pipe(
validateInput(id),
E.chainW(validId => fetchFromDb(validId))
)
Sometimes you want ALL errors, not just the first one. Form validation is the classic example.
// MESSY: Manual error accumulation
function validateForm(form: FormData): { valid: boolean; errors: string[] } {
const errors: string[] = []
if (!form.email) {
errors.push('Email required')
} else if (!form.email.includes('@')) {
errors.push('Invalid email')
}
if (!form.password) {
errors.push('Password required')
} else if (form.password.length < 8) {
errors.push('Password too short')
}
if (!form.age) {
errors.push('Age required')
} else if (form.age < 18) {
errors.push('Must be 18+')
}
return { valid: errors.length === 0, errors }
}
import * as E from 'fp-ts/Either'
import * as NEA from 'fp-ts/NonEmptyArray'
import { sequenceS } from 'fp-ts/Apply'
import { pipe } from 'fp-ts/function'
// Errors as a NonEmptyArray (always at least one)
type Errors = NEA.NonEmptyArray<string>
// Create the applicative that accumulates errors
const validation = E.getApplicativeValidation(NEA.getSemigroup<string>())
// Validators that return Either<Errors, T>
const validateEmail = (email: string): E.Either<Errors, string> =>
!email ? E.left(NEA.of('Email required'))
: !email.includes('@') ? E.left(NEA.of('Invalid email'))
: E.right(email)
const validatePassword = (password: string): E.Either<Errors, string> =>
!password ? E.left(NEA.of('Password required'))
: password.length < 8 ? E.left(NEA.of('Password too short'))
: E.right(password)
const validateAge = (age: number | undefined): E.Either<Errors, number> =>
age === undefined ? E.left(NEA.of('Age required'))
: age < 18 ? E.left(NEA.of('Must be 18+'))
: E.right(age)
// Combine all validations - collects ALL errors
const validateForm = (form: FormData) =>
sequenceS(validation)({
email: validateEmail(form.email),
password: validatePassword(form.password),
age: validateAge(form.age)
})
// Usage
validateForm({ email: '', password: '123', age: 15 })
// Left(['Email required', 'Password too short', 'Must be 18+'])
validateForm({ email: 'a@b.com', password: 'longpassword', age: 25 })
// Right({ email: 'a@b.com', password: 'longpassword', age: 25 })
interface FieldError {
field: string
message: string
}
type FormErrors = NEA.NonEmptyArray<FieldError>
const fieldError = (field: string, message: string): FormErrors =>
NEA.of({ field, message })
const formValidation = E.getApplicativeValidation(NEA.getSemigroup<FieldError>())
// Now errors know which field they belong to
const validateEmail = (email: string): E.Either<FormErrors, string> =>
!email ? E.left(fieldError('email', 'Required'))
: !email.includes('@') ? E.left(fieldError('email', 'Invalid format'))
: E.right(email)
// Easy to display in UI
const getFieldError = (errors: FormErrors, field: string): string | undefined =>
errors.find(e => e.field === field)?.message
For async operations that can fail, use TaskEither. It's like Either but for promises.
TaskEither<E, A> = a function that returns Promise<Either<E, A>>
Lazy: nothing runs until you execute it
import * as TE from 'fp-ts/TaskEither' import { pipe } from 'fp-ts/function'
// Wrap any async operation
const fetchUser = (id: string): TE.TaskEither<Error, User> =>
TE.tryCatch(
() => fetch(/api/users/${id}).then(r => r.json()),
(e) => (e instanceof Error ? e : new Error(String(e)))
)
// Chain async operations - just like Either const getUserPosts = (userId: string): TE.TaskEither<Error, Post[]> => pipe( fetchUser(userId), TE.chain(user => fetchPosts(user.id)) )
// Execute when ready const result = await getUserPosts('123')() // Returns Either<Error, Post[]>
// MESSY: try/catch mixed with promise chains
async function loadDashboard(userId: string) {
try {
const user = await fetchUser(userId)
if (!user) throw new Error('User not found')
let posts, notifications, settings
try {
[posts, notifications, settings] = await Promise.all([
fetchPosts(user.id),
fetchNotifications(user.id),
fetchSettings(user.id)
])
} catch (e) {
// Which one failed? Who knows!
console.error('Failed to load data', e)
return null
}
return { user, posts, notifications, settings }
} catch (e) {
console.error('Failed to load user', e)
return null
}
}
import * as TE from 'fp-ts/TaskEither'
import { sequenceS } from 'fp-ts/Apply'
import { pipe } from 'fp-ts/function'
const loadDashboard = (userId: string) =>
pipe(
fetchUser(userId),
TE.chain(user =>
pipe(
// Parallel fetch with sequenceS
sequenceS(TE.ApplyPar)({
posts: fetchPosts(user.id),
notifications: fetchNotifications(user.id),
settings: fetchSettings(user.id)
}),
TE.map(data => ({ user, ...data }))
)
)
)
// Execute and handle both cases
pipe(
loadDashboard('123'),
TE.fold(
(error) => T.of(renderError(error)),
(data) => T.of(renderDashboard(data))
)
)()
import * as T from 'fp-ts/Task'
import * as TE from 'fp-ts/TaskEither'
import { pipe } from 'fp-ts/function'
const retry = <E, A>(
task: TE.TaskEither<E, A>,
attempts: number,
delayMs: number
): TE.TaskEither<E, A> =>
pipe(
task,
TE.orElse((error) =>
attempts > 1
? pipe(
T.delay(delayMs)(T.of(undefined)),
T.chain(() => retry(task, attempts - 1, delayMs * 2))
)
: TE.left(error)
)
)
// Retry up to 3 times with exponential backoff
const fetchWithRetry = retry(fetchUser('123'), 3, 1000)
// Try cache first, fall back to API
const getUserData = (id: string) =>
pipe(
fetchFromCache(id),
TE.orElse(() => fetchFromApi(id)),
TE.orElse(() => TE.right(defaultUser)) // Last resort default
)
Real codebases have throwing functions, nullable values, and promises. Here's how to work with them.
import * as E from 'fp-ts/Either'
import * as O from 'fp-ts/Option'
// Direct conversion
const user = users.find(u => u.id === id) // User | undefined
const result = E.fromNullable('User not found')(user)
// From Option
const maybeUser: O.Option<User> = O.fromNullable(user)
const eitherUser = pipe(
maybeUser,
E.fromOption(() => 'User not found')
)
// Wrap at the boundary
const safeParse = <T>(schema: ZodSchema<T>) => (data: unknown): E.Either<ZodError, T> =>
E.tryCatch(
() => schema.parse(data),
(e) => e as ZodError
)
// Use throughout your code
const parseUser = safeParse(UserSchema)
const result = parseUser(rawData) // Either<ZodError, User>
import * as TE from 'fp-ts/TaskEither'
// Wrap external async functions
const fetchJson = <T>(url: string): TE.TaskEither<Error, T> =>
TE.tryCatch(
() => fetch(url).then(r => r.json()),
(e) => new Error(`Fetch failed: ${e}`)
)
// Wrap axios, prisma, any async library
const getUserFromDb = (id: string): TE.TaskEither<DbError, User> =>
TE.tryCatch(
() => prisma.user.findUniqueOrThrow({ where: { id } }),
(e) => ({ code: 'DB_ERROR', cause: e })
)
Sometimes you need a plain Promise for external APIs.
import * as TE from 'fp-ts/TaskEither'
import * as E from 'fp-ts/Either'
const myTaskEither: TE.TaskEither<Error, User> = fetchUser('123')
// Option 1: Get the Either (preserves both cases)
const either: E.Either<Error, User> = await myTaskEither()
// Option 2: Throw on error (for legacy code)
const toThrowingPromise = <E, A>(te: TE.TaskEither<E, A>): Promise<A> =>
te().then(E.fold(
(error) => Promise.reject(error),
(value) => Promise.resolve(value)
))
const user = await toThrowingPromise(fetchUser('123')) // Throws if Left
// Option 3: Default on error
const user = await pipe(
fetchUser('123'),
TE.getOrElse(() => T.of(defaultUser))
)()
interface ParsedInput {
id: number
name: string
tags: string[]
}
const parseInput = (raw: unknown): E.Either<string, ParsedInput> =>
pipe(
E.Do,
E.bind('obj', () =>
typeof raw === 'object' && raw !== null
? E.right(raw as Record<string, unknown>)
: E.left('Input must be an object')
),
E.bind('id', ({ obj }) =>
typeof obj.id === 'number'
? E.right(obj.id)
: E.left('id must be a number')
),
E.bind('name', ({ obj }) =>
typeof obj.name === 'string' && obj.name.length > 0
? E.right(obj.name)
: E.left('name must be a non-empty string')
),
E.bind('tags', ({ obj }) =>
Array.isArray(obj.tags) && obj.tags.every(t => typeof t === 'string')
? E.right(obj.tags as string[])
: E.left('tags must be an array of strings')
),
E.map(({ id, name, tags }) => ({ id, name, tags }))
)
// Usage
parseInput({ id: 1, name: 'test', tags: ['a', 'b'] })
// Right({ id: 1, name: 'test', tags: ['a', 'b'] })
parseInput({ id: 'wrong', name: '', tags: null })
// Left('id must be a number')
interface ApiError {
code: string
message: string
status?: number
}
const createApiError = (message: string, code = 'UNKNOWN', status?: number): ApiError =>
({ code, message, status })
const fetchWithErrorHandling = <T>(url: string): TE.TaskEither<ApiError, T> =>
pipe(
TE.tryCatch(
() => fetch(url),
() => createApiError('Network error', 'NETWORK')
),
TE.chain(response =>
response.ok
? TE.tryCatch(
() => response.json() as Promise<T>,
() => createApiError('Invalid JSON', 'PARSE')
)
: TE.left(createApiError(
`HTTP ${response.status}`,
response.status === 404 ? 'NOT_FOUND' : 'HTTP_ERROR',
response.status
))
)
)
// Usage with pattern matching on error codes
const handleUserFetch = (userId: string) =>
pipe(
fetchWithErrorHandling<User>(`/api/users/${userId}`),
TE.fold(
(error) => {
switch (error.code) {
case 'NOT_FOUND': return T.of(showNotFoundPage())
case 'NETWORK': return T.of(showOfflineMessage())
default: return T.of(showGenericError(error.message))
}
},
(user) => T.of(showUserProfile(user))
)
)
import * as A from 'fp-ts/Array'
import * as E from 'fp-ts/Either'
import { pipe } from 'fp-ts/function'
interface ProcessResult<T> {
successes: T[]
failures: Array<{ item: unknown; error: string }>
}
// Process all, collect successes and failures separately
const processAllCollectErrors = <T, R>(
items: T[],
process: (item: T) => E.Either<string, R>
): ProcessResult<R> => {
const results = items.map((item, index) =>
pipe(
process(item),
E.mapLeft(error => ({ item, error, index }))
)
)
return {
successes: pipe(results, A.filterMap(E.toOption)),
failures: pipe(
results,
A.filterMap(r => E.isLeft(r) ? O.some(r.left) : O.none)
)
}
}
// Usage
const parseNumbers = (inputs: string[]) =>
processAllCollectErrors(inputs, input => {
const n = parseInt(input, 10)
return isNaN(n) ? E.left(`Invalid number: ${input}`) : E.right(n)
})
parseNumbers(['1', 'abc', '3', 'def'])
// {
// successes: [1, 3],
// failures: [
// { item: 'abc', error: 'Invalid number: abc', index: 1 },
// { item: 'def', error: 'Invalid number: def', index: 3 }
// ]
// }
import * as TE from 'fp-ts/TaskEither'
import * as T from 'fp-ts/Task'
import { pipe } from 'fp-ts/function'
interface BulkResult<T> {
succeeded: T[]
failed: Array<{ id: string; error: string }>
}
const bulkProcess = <T>(
ids: string[],
process: (id: string) => TE.TaskEither<string, T>
): T.Task<BulkResult<T>> =>
pipe(
ids,
A.map(id =>
pipe(
process(id),
TE.fold(
(error) => T.of({ type: 'failed' as const, id, error }),
(result) => T.of({ type: 'succeeded' as const, result })
)
)
),
T.sequenceArray,
T.map(results => ({
succeeded: results
.filter((r): r is { type: 'succeeded'; result: T } => r.type === 'succeeded')
.map(r => r.result),
failed: results
.filter((r): r is { type: 'failed'; id: string; error: string } => r.type === 'failed')
.map(({ id, error }) => ({ id, error }))
}))
)
// Usage
const deleteUsers = (userIds: string[]) =>
bulkProcess(userIds, id =>
pipe(
deleteUser(id),
TE.mapLeft(e => e.message)
)
)
// All operations run, you get a report of what worked and what didn't
| Pattern | Use When | Example |
|---|---|---|
E.right(value) | Creating a success | E.right(42) |
E.left(error) | Creating a failure | E.left('not found') |
E.tryCatch(fn, onError) | Wrapping throwing code | E.tryCatch(() => JSON.parse(s), toError) |
E.fromNullable(error) |
All Either operations have TaskEither equivalents:
TE.right, TE.left, TE.tryCatchTE.map, TE.mapLeft, TE.chain, TE.chainWTE.fold, TE.getOrElse, TE.filterOrElseTE.orElse for fallbackschain stops at first error automaticallyfold to handle both cases when you're ready to actThe payoff: TypeScript tracks your errors, no more forgotten try/catch, clear control flow, and composable error handling.
Weekly Installs
–
Repository
GitHub Stars
4
First Seen
–
Security Audits
Tailwind CSS v4 + shadcn/ui 生产级技术栈配置指南与最佳实践
2,600 周安装
| Converting nullable |
E.fromNullable('missing')(maybeValue) |
E.map(fn) | Transform success | pipe(result, E.map(x => x * 2)) |
E.mapLeft(fn) | Transform error | pipe(result, E.mapLeft(addContext)) |
E.chain(fn) | Chain operations | pipe(getA(), E.chain(a => getB(a.id))) |
E.chainW(fn) | Chain with different error type | pipe(validate(), E.chainW(save)) |
E.fold(onError, onSuccess) | Handle both cases | E.fold(showError, showData) |
E.getOrElse(onError) | Extract with default | E.getOrElse(() => 0) |
E.filterOrElse(pred, onFalse) | Validate with error | E.filterOrElse(x => x > 0, () => 'must be positive') |
sequenceS(validation)({...}) | Collect all errors | Form validation |