Practical Async Patterns with fp-ts
Stop writing nested try/catch blocks. Stop losing error context. Start building clean async pipelines that handle errors properly.
TaskEither is simply an async operation that tracks success or failure. That's it. No fancy terminology needed.
typescript
// TaskEither<Error, User> means:
// "An async operation that either fails with Error or succeeds with User"
1. Wrapping Promises Safely
The Problem: Try/Catch Everywhere
typescript
// BEFORE: Try/catch hell
async function getUserData(userId: string) {
try {
const response = await fetch(`/api/users/${userId}`)
if (!response.ok) {
throw new Error(`HTTP ${response.status}`)
}
const user = await response.json()
try {
const posts = await fetch(`/api/users/${userId}/posts`)
if (!posts.ok) {
throw new Error(`HTTP ${posts.status}`)
}
const postsData = await posts.json()
return { user, posts: postsData }
} catch (postsError) {
// Now what? Return partial data? Rethrow? Log?
console.error('Failed to fetch posts:', postsError)
return { user, posts: [] }
}
} catch (error) {
// Lost all context about what failed
console.error('Something failed:', error)
throw error
}
}
The Solution: Wrap Once, Handle Cleanly
typescript
import * as TE from 'fp-ts/TaskEither'
import * as E from 'fp-ts/Either'
import { pipe } from 'fp-ts/function'
// One wrapper function - reuse everywhere
const fetchJson = <T>(url: string): TE.TaskEither<Error, T> =>
TE.tryCatch(
async () => {
const response = await fetch(url)
if (!response.ok) {
throw new Error(`HTTP ${response.status}: ${response.statusText}`)
}
return response.json()
},
(error) => error instanceof Error ? error : new Error(String(error))
)
// AFTER: Clean and composable
const getUser = (userId: string) => fetchJson<User>(`/api/users/${userId}`)
const getPosts = (userId: string) => fetchJson<Post[]>(
`/api/users/${userId}/posts`)
tryCatch Explained
TE.tryCatch takes two things:
- An async function that might throw
- A function to convert the thrown value into your error type
typescript
TE.tryCatch(
() => somePromise, // The async work
(thrown) => toError(thrown) // Convert failures to your error type
)
Creating Success and Failure Values
typescript
// Wrap a value as success
const success = TE.right<Error, number>(42)
// Wrap a value as failure
const failure = TE.left<Error, number>(new Error('Nope'))
// From a nullable value (null/undefined becomes error)
const fromNullable = TE.fromNullable(new Error('Value was null'))
const result = fromNullable(maybeUser) // TaskEither<Error, User>
// From a condition
const mustBePositive = TE.fromPredicate(
(n: number) => n > 0,
(n) => new Error(`Expected positive, got ${n}`)
)
2. Chaining Async Operations
The Problem: Callback Hell / Nested Awaits
typescript
// BEFORE: Deeply nested, hard to follow
async function processOrder(orderId: string) {
try {
const order = await fetchOrder(orderId)
if (!order) throw new Error('Order not found')
try {
const user = await fetchUser(order.userId)
if (!user) throw new Error('User not found')
try {
const inventory = await checkInventory(order.items)
if (!inventory.available) throw new Error('Out of stock')
try {
const payment = await chargePayment(user, order.total)
if (!payment.success) throw new Error('Payment failed')
try {
const shipment = await createShipment(order, user)
return { order, shipment, payment }
} catch (e) {
// Refund payment? Log? What's the state now?
await refundPayment(payment.id)
throw e
}
} catch (e) {
throw e
}
} catch (e) {
throw e
}
} catch (e) {
throw e
}
} catch (e) {
console.error('Order processing failed', e)
throw e
}
}
The Solution: Clean Pipelines with chain
typescript
// AFTER: Flat, readable pipeline
const processOrder = (orderId: string) =>
pipe(
fetchOrder(orderId),
TE.chain(order => fetchUser(order.userId)),
TE.chain(user =>
pipe(
checkInventory(order.items),
TE.chain(inventory => chargePayment(user, order.total))
)
),
TE.chain(payment => createShipment(order, user, payment))
)
chain vs map
Use map when your transformation is synchronous and can't fail:
typescript
pipe(
fetchUser(userId),
TE.map(user => user.name.toUpperCase()) // Just transforms the value
)
Use chain (or flatMap) when your transformation is async or can fail:
typescript
pipe(
fetchUser(userId),
TE.chain(user => fetchOrders(user.id)) // Returns another TaskEither
)
Building Context with Do Notation
When you need values from multiple steps:
typescript
// BEFORE: Have to thread values through manually
const processOrderManual = (orderId: string) =>
pipe(
fetchOrder(orderId),
TE.chain(order =>
pipe(
fetchUser(order.userId),
TE.chain(user =>
pipe(
chargePayment(user, order.total),
TE.map(payment => ({ order, user, payment }))
)
)
)
)
)
// AFTER: Do notation keeps everything accessible
const processOrder = (orderId: string) =>
pipe(
TE.Do,
TE.bind('order', () => fetchOrder(orderId)),
TE.bind('user', ({ order }) => fetchUser(order.userId)),
TE.bind('payment', ({ user, order }) => chargePayment(user, order.total)),
TE.bind('shipment', ({ order, user }) => createShipment(order, user)),
TE.map(({ order, payment, shipment }) => ({
orderId: order.id,
paymentId: payment.id,
trackingNumber: shipment.tracking
}))
)
3. Parallel vs Sequential Execution
When to Use Each
Sequential (one after another):
- When each operation depends on the previous result
- When you need to respect rate limits
- When order matters
Parallel (all at once):
- When operations are independent
- When you want speed
- When fetching multiple resources by ID
Sequential Chaining
typescript
// Operations depend on each other - must be sequential
const getUserWithOrg = (userId: string) =>
pipe(
fetchUser(userId), // First: get user
TE.chain(user => fetchTeam(user.teamId)), // Then: get their team
TE.chain(team => fetchOrganization(team.orgId)) // Finally: get org
)
Parallel Execution
typescript
import { sequenceT } from 'fp-ts/Apply'
// Independent operations - run in parallel
const getDashboardData = (userId: string) =>
sequenceT(TE.ApplyPar)(
fetchUser(userId),
fetchNotifications(userId),
fetchRecentActivity(userId)
) // Returns TaskEither<Error, [User, Notification[], Activity[]]>
// With destructuring:
const getDashboard = (userId: string) =>
pipe(
sequenceT(TE.ApplyPar)(
fetchUser(userId),
fetchNotifications(userId),
fetchRecentActivity(userId)
),
TE.map(([user, notifications, activities]) => ({
user,
notifications,
activities,
unreadCount: notifications.filter(n => !n.read).length
}))
)
Parallel Array Operations
typescript
// Fetch multiple users in parallel
const userIds = ['1', '2', '3', '4', '5']
// TE.traverseArray runs all fetches in parallel
const fetchAllUsers = pipe(
userIds,
TE.traverseArray(fetchUser)
) // TaskEither<Error, readonly User[]>
// Note: Fails fast - if ANY request fails, the whole thing fails
// All errors after the first are lost
Parallel with Batch Control
When you need to limit concurrent requests:
typescript
const chunk = <T>(arr: T[], size: number): T[][] => {
const chunks: T[][] = []
for (let i = 0; i < arr.length; i += size) {
chunks.push(arr.slice(i, i + size))
}
return chunks
}
// Process in batches of 5 concurrent requests
const fetchUsersWithLimit = (userIds: string[]) => {
const batches = chunk(userIds, 5)
return pipe(
batches,
// Process batches sequentially
TE.traverseArray(batch =>
// But within each batch, run in parallel
pipe(batch, TE.traverseArray(fetchUser))
),
TE.map(results => results.flat())
)
}
Sequential When Parallel Looks Tempting
typescript
// WRONG: This looks parallel but order might matter for DB operations
const createUserAndProfile = (userData: UserData) =>
sequenceT(TE.ApplyPar)(
createUser(userData), // Creates user with ID
createProfile(userData.profile) // Needs user ID - race condition!
)
// RIGHT: Sequential when there's a dependency
const createUserAndProfile = (userData: UserData) =>
pipe(
createUser(userData),
TE.chain(user =>
pipe(
createProfile(user.id, userData.profile),
TE.map(profile => ({ user, profile }))
)
)
)
4. Error Recovery Patterns
Fallback to Alternative
typescript
// Try primary API, fall back to cache
const getUserWithFallback = (userId: string) =>
pipe(
fetchUserFromApi(userId),
TE.orElse(() => fetchUserFromCache(userId))
)
// Chain multiple fallbacks
const getConfigRobust = () =>
pipe(
fetchRemoteConfig(),
TE.orElse(() => loadLocalConfig()),
TE.orElse(() => TE.right(defaultConfig))
)
Conditional Recovery
typescript
// Only recover from specific errors
const fetchUserOrCreate = (userId: string) =>
pipe(
fetchUser(userId),
TE.orElse(error =>
error.message.includes('404') || error.message.includes('not found')
? createDefaultUser(userId)
: TE.left(error) // Re-throw other errors
)
)
Typed Error Recovery
typescript
type ApiError =
| { _tag: 'NotFound'; id: string }
| { _tag: 'NetworkError'; cause: Error }
| { _tag: 'Unauthorized' }
const fetchUser = (id: string): TE.TaskEither<ApiError, User> =>
TE.tryCatch(
async () => {
const res = await fetch(`/api/users/${id}`)
if (res.status === 404) throw { _tag: 'NotFound', id }
if (res.status === 401) throw { _tag: 'Unauthorized' }
if (!res.ok) throw { _tag: 'NetworkError', cause: new Error(`HTTP ${res.status}`) }
return res.json()
},
(e): ApiError =>
typeof e === 'object' && e !== null && '_tag' in e
? e as ApiError
: { _tag: 'NetworkError', cause: e instanceof Error ? e : new Error(String(e)) }
)
// Handle specific errors differently
const getUserOrGuest = (userId: string) =>
pipe(
fetchUser(userId),
TE.orElse(error => {
switch (error._tag) {
case 'NotFound':
return TE.right(createGuestUser())
case 'Unauthorized':
return TE.left(error) // Propagate auth errors
case 'NetworkError':
return fetchUserFromCache(userId) // Try cache on network issues
}
})
)
Retry with Exponential Backoff
typescript
import * as T from 'fp-ts/Task'
const wait = (ms: number): T.Task<void> =>
() => new Promise(resolve => setTimeout(resolve, ms))
const retry = <E, A>(
operation: TE.TaskEither<E, A>,
maxAttempts: number,
baseDelayMs: number = 1000
): TE.TaskEither<E, A> => {
const attempt = (remaining: number, delay: number): TE.TaskEither<E, A> =>
pipe(
operation,
TE.orElse(error =>
remaining <= 1
? TE.left(error)
: pipe(
TE.fromTask(wait(delay)),
TE.chain(() => attempt(remaining - 1, delay * 2))
)
)
)
return attempt(maxAttempts, baseDelayMs)
}
// Usage
const fetchUserWithRetry = (userId: string) =>
retry(fetchUser(userId), 3, 1000)
// Attempts: immediate, 1s, 2s delays between retries
Default Values