Fp Ts React

1---
2name: fp-ts-react
3description: Practical patterns for using fp-ts with React - hooks, state, forms, data fetching. Use when building React apps with functional programming patterns. Works with React 18/19, Next.js 14/15.
4risk: safe
5source: https://github.com/whatiskadudoing/fp-ts-skills
6---
7 
8# Functional Programming in React
9 
10Practical patterns for React apps. No jargon, just code that works.
11 
12## When to Use This Skill
13 
14- When building React apps with fp-ts for type-safe state management
15- When handling loading/error/success states in data fetching
16- When implementing form validation with error accumulation
17- When using React 18/19 or Next.js 14/15 with functional patterns
18 
19---
20 
21## Quick Reference
22 
23| Pattern | Use When |
24|---------|----------|
25| `Option` | Value might be missing (user not loaded yet) |
26| `Either` | Operation might fail (form validation) |
27| `TaskEither` | Async operation might fail (API calls) |
28| `RemoteData` | Need to show loading/error/success states |
29| `pipe` | Chaining multiple transformations |
30 
31---
32 
33## 1. State with Option (Maybe It's There, Maybe Not)
34 
35Use `Option` instead of `null | undefined` for clearer intent.
36 
37### Basic Pattern
38 
39```typescript
40import { useState } from 'react'
41import * as O from 'fp-ts/Option'
42import { pipe } from 'fp-ts/function'
43 
44interface User {
45  id: string
46  name: string
47  email: string
48}
49 
50function UserProfile() {
51  // Option says "this might not exist yet"
52  const [user, setUser] = useState<O.Option<User>>(O.none)
53 
54  const handleLogin = (userData: User) => {
55    setUser(O.some(userData))
56  }
57 
58  const handleLogout = () => {
59    setUser(O.none)
60  }
61 
62  return pipe(
63    user,
64    O.match(
65      // When there's no user
66      () => <button onClick={() => handleLogin({ id: '1', name: 'Alice', email: 'alice@example.com' })}>
67        Log In
68      </button>,
69      // When there's a user
70      (u) => (
71        <div>
72          <p>Welcome, {u.name}!</p>
73          <button onClick={handleLogout}>Log Out</button>
74        </div>
75      )
76    )
77  )
78}
79```
80 
81### Chaining Optional Values
82 
83```typescript
84import * as O from 'fp-ts/Option'
85import { pipe } from 'fp-ts/function'
86 
87interface Profile {
88  user: O.Option<{
89    name: string
90    settings: O.Option<{
91      theme: string
92    }>
93  }>
94}
95 
96function getTheme(profile: Profile): string {
97  return pipe(
98    profile.user,
99    O.flatMap(u => u.settings),
100    O.map(s => s.theme),
101    O.getOrElse(() => 'light') // default
102  )
103}
104```
105 
106---
107 
108## 2. Form Validation with Either
109 
110Either is perfect for validation: `Left` = errors, `Right` = valid data.
111 
112### Simple Form Validation
113 
114```typescript
115import * as E from 'fp-ts/Either'
116import * as A from 'fp-ts/Array'
117import { pipe } from 'fp-ts/function'
118 
119// Validation functions return Either<ErrorMessage, ValidValue>
120const validateEmail = (email: string): E.Either<string, string> =>
121  email.includes('@')
122    ? E.right(email)
123    : E.left('Invalid email address')
124 
125const validatePassword = (password: string): E.Either<string, string> =>
126  password.length >= 8
127    ? E.right(password)
128    : E.left('Password must be at least 8 characters')
129 
130const validateName = (name: string): E.Either<string, string> =>
131  name.trim().length > 0
132    ? E.right(name.trim())
133    : E.left('Name is required')
134```
135 
136### Collecting All Errors (Not Just First One)
137 
138```typescript
139import * as E from 'fp-ts/Either'
140import { sequenceS } from 'fp-ts/Apply'
141import { getSemigroup } from 'fp-ts/NonEmptyArray'
142import { pipe } from 'fp-ts/function'
143 
144// This collects ALL errors, not just the first one
145const validateAll = sequenceS(E.getApplicativeValidation(getSemigroup<string>()))
146 
147interface SignupForm {
148  name: string
149  email: string
150  password: string
151}
152 
153interface ValidatedForm {
154  name: string
155  email: string
156  password: string
157}
158 
159function validateForm(form: SignupForm): E.Either<string[], ValidatedForm> {
160  return pipe(
161    validateAll({
162      name: pipe(validateName(form.name), E.mapLeft(e => [e])),
163      email: pipe(validateEmail(form.email), E.mapLeft(e => [e])),
164      password: pipe(validatePassword(form.password), E.mapLeft(e => [e])),
165    })
166  )
167}
168 
169// Usage in component
170function SignupForm() {
171  const [form, setForm] = useState({ name: '', email: '', password: '' })
172  const [errors, setErrors] = useState<string[]>([])
173 
174  const handleSubmit = () => {
175    pipe(
176      validateForm(form),
177      E.match(
178        (errs) => setErrors(errs),     // Show all errors
179        (valid) => {
180          setErrors([])
181          submitToServer(valid)         // Submit valid data
182        }
183      )
184    )
185  }
186 
187  return (
188    <form onSubmit={e => { e.preventDefault(); handleSubmit() }}>
189      <input
190        value={form.name}
191        onChange={e => setForm(f => ({ ...f, name: e.target.value }))}
192        placeholder="Name"
193      />
194      <input
195        value={form.email}
196        onChange={e => setForm(f => ({ ...f, email: e.target.value }))}
197        placeholder="Email"
198      />
199      <input
200        type="password"
201        value={form.password}
202        onChange={e => setForm(f => ({ ...f, password: e.target.value }))}
203        placeholder="Password"
204      />
205 
206      {errors.length > 0 && (
207        <ul style={{ color: 'red' }}>
208          {errors.map((err, i) => <li key={i}>{err}</li>)}
209        </ul>
210      )}
211 
212      <button type="submit">Sign Up</button>
213    </form>
214  )
215}
216```
217 
218### Field-Level Errors (Better UX)
219 
220```typescript
221type FieldErrors = Partial<Record<keyof SignupForm, string>>
222 
223function validateFormWithFieldErrors(form: SignupForm): E.Either<FieldErrors, ValidatedForm> {
224  const errors: FieldErrors = {}
225 
226  pipe(validateName(form.name), E.mapLeft(e => { errors.name = e }))
227  pipe(validateEmail(form.email), E.mapLeft(e => { errors.email = e }))
228  pipe(validatePassword(form.password), E.mapLeft(e => { errors.password = e }))
229 
230  return Object.keys(errors).length > 0
231    ? E.left(errors)
232    : E.right({ name: form.name.trim(), email: form.email, password: form.password })
233}
234 
235// In component
236{errors.email && <span className="error">{errors.email}</span>}
237```
238 
239---
240 
241## 3. Data Fetching with TaskEither
242 
243TaskEither = async operation that might fail. Perfect for API calls.
244 
245### Basic Fetch Hook
246 
247```typescript
248import { useState, useEffect } from 'react'
249import * as TE from 'fp-ts/TaskEither'
250import * as E from 'fp-ts/Either'
251import { pipe } from 'fp-ts/function'
252 
253// Wrap fetch in TaskEither
254const fetchJson = <T>(url: string): TE.TaskEither<Error, T> =>
255  TE.tryCatch(
256    async () => {
257      const res = await fetch(url)
258      if (!res.ok) throw new Error(`HTTP ${res.status}`)
259      return res.json()
260    },
261    (err) => err instanceof Error ? err : new Error(String(err))
262  )
263 
264// Custom hook
265function useFetch<T>(url: string) {
266  const [data, setData] = useState<T | null>(null)
267  const [error, setError] = useState<Error | null>(null)
268  const [loading, setLoading] = useState(true)
269 
270  useEffect(() => {
271    setLoading(true)
272    setError(null)
273 
274    pipe(
275      fetchJson<T>(url),
276      TE.match(
277        (err) => {
278          setError(err)
279          setLoading(false)
280        },
281        (result) => {
282          setData(result)
283          setLoading(false)
284        }
285      )
286    )()
287  }, [url])
288 
289  return { data, error, loading }
290}
291 
292// Usage
293function UserList() {
294  const { data, error, loading } = useFetch<User[]>('/api/users')
295 
296  if (loading) return <div>Loading...</div>
297  if (error) return <div>Error: {error.message}</div>
298  return (
299    <ul>
300      {data?.map(user => <li key={user.id}>{user.name}</li>)}
301    </ul>
302  )
303}
304```
305 
306### Chaining API Calls
307 
308```typescript
309// Fetch user, then fetch their posts
310const fetchUserWithPosts = (userId: string) => pipe(
311  fetchJson<User>(`/api/users/${userId}`),
312  TE.flatMap(user => pipe(
313    fetchJson<Post[]>(`/api/users/${userId}/posts`),
314    TE.map(posts => ({ ...user, posts }))
315  ))
316)
317```
318 
319### Parallel API Calls
320 
321```typescript
322import { sequenceT } from 'fp-ts/Apply'
323 
324// Fetch multiple things at once
325const fetchDashboardData = () => pipe(
326  sequenceT(TE.ApplyPar)(
327    fetchJson<User>('/api/user'),
328    fetchJson<Stats>('/api/stats'),
329    fetchJson<Notifications[]>('/api/notifications')
330  ),
331  TE.map(([user, stats, notifications]) => ({
332    user,
333    stats,
334    notifications
335  }))
336)
337```
338 
339---
340 
341## 4. RemoteData Pattern (The Right Way to Handle Async State)
342 
343Stop using `{ data, loading, error }` booleans. Use a proper state machine.
344 
345### The Pattern
346 
347```typescript
348// RemoteData has exactly 4 states - no impossible combinations
349type RemoteData<E, A> =
350  | { _tag: 'NotAsked' }                    // Haven't started yet
351  | { _tag: 'Loading' }                     // In progress
352  | { _tag: 'Failure'; error: E }           // Failed
353  | { _tag: 'Success'; data: A }            // Got it!
354 
355// Constructors
356const notAsked = <E, A>(): RemoteData<E, A> => ({ _tag: 'NotAsked' })
357const loading = <E, A>(): RemoteData<E, A> => ({ _tag: 'Loading' })
358const failure = <E, A>(error: E): RemoteData<E, A> => ({ _tag: 'Failure', error })
359const success = <E, A>(data: A): RemoteData<E, A> => ({ _tag: 'Success', data })
360 
361// Pattern match all states
362function fold<E, A, R>(
363  rd: RemoteData<E, A>,
364  onNotAsked: () => R,
365  onLoading: () => R,
366  onFailure: (e: E) => R,
367  onSuccess: (a: A) => R
368): R {
369  switch (rd._tag) {
370    case 'NotAsked': return onNotAsked()
371    case 'Loading': return onLoading()
372    case 'Failure': return onFailure(rd.error)
373    case 'Success': return onSuccess(rd.data)
374  }
375}
376```
377 
378### Hook with RemoteData
379 
380```typescript
381function useRemoteData<T>(fetchFn: () => Promise<T>) {
382  const [state, setState] = useState<RemoteData<Error, T>>(notAsked())
383 
384  const execute = async () => {
385    setState(loading())
386    try {
387      const data = await fetchFn()
388      setState(success(data))
389    } catch (err) {
390      setState(failure(err instanceof Error ? err : new Error(String(err))))
391    }
392  }
393 
394  return { state, execute }
395}
396 
397// Usage
398function UserProfile({ userId }: { userId: string }) {
399  const { state, execute } = useRemoteData(() =>
400    fetch(`/api/users/${userId}`).then(r => r.json())
401  )
402 
403  useEffect(() => { execute() }, [userId])
404 
405  return fold(
406    state,
407    () => <button onClick={execute}>Load User</button>,
408    () => <Spinner />,
409    (err) => <ErrorMessage message={err.message} onRetry={execute} />,
410    (user) => <UserCard user={user} />
411  )
412}
413```
414 
415### Why RemoteData Beats Booleans
416 
417```typescript
418// ❌ BAD: Impossible states are possible
419interface BadState {
420  data: User | null
421  loading: boolean
422  error: Error | null
423}
424// Can have: { data: user, loading: true, error: someError } - what does that mean?!
425 
426// ✅ GOOD: Only valid states exist
427type GoodState = RemoteData<Error, User>
428// Can only be: NotAsked | Loading | Failure | Success
429```
430 
431---
432 
433## 5. Referential Stability (Preventing Re-renders)
434 
435fp-ts values like `O.some(1)` create new objects each render. React sees them as "changed".
436 
437### The Problem
438 
439```typescript
440// ❌ BAD: Creates new Option every render
441function BadComponent() {
442  const [value, setValue] = useState(O.some(1))
443 
444  useEffect(() => {
445    // This runs EVERY render because O.some(1) !== O.some(1)
446    console.log('value changed')
447  }, [value])
448}
449```
450 
451### Solution 1: useMemo
452 
453```typescript
454// ✅ GOOD: Memoize Option creation
455function GoodComponent() {
456  const [rawValue, setRawValue] = useState<number | null>(1)
457 
458  const value = useMemo(
459    () => O.fromNullable(rawValue),
460    [rawValue]  // Only recreate when rawValue changes
461  )
462 
463  useEffect(() => {
464    // Now this only runs when rawValue actually changes
465    console.log('value changed')
466  }, [rawValue])  // Depend on raw value, not Option
467}
468```
469 
470### Solution 2: fp-ts-react-stable-hooks
471 
472```bash
473npm install fp-ts-react-stable-hooks
474```
475 
476```typescript
477import { useStableO, useStableEffect } from 'fp-ts-react-stable-hooks'
478import * as O from 'fp-ts/Option'
479import * as Eq from 'fp-ts/Eq'
480 
481function StableComponent() {
482  // Uses fp-ts equality instead of reference equality
483  const [value, setValue] = useStableO(O.some(1))
484 
485  // Effect that understands Option equality
486  useStableEffect(
487    () => { console.log('value changed') },
488    [value],
489    Eq.tuple(O.getEq(Eq.eqNumber))  // Custom equality
490  )
491}
492```
493 
494---
495 
496## 6. Dependency Injection with Context
497 
498Use ReaderTaskEither for testable components with injected dependencies.
499 
500### Setup Dependencies
501 
502```typescript
503import * as RTE from 'fp-ts/ReaderTaskEither'
504import { pipe } from 'fp-ts/function'
505import { createContext, useContext, ReactNode } from 'react'
506 
507// Define what services your app needs
508interface AppDependencies {
509  api: {
510    getUser: (id: string) => Promise<User>
511    updateUser: (id: string, data: Partial<User>) => Promise<User>
512  }
513  analytics: {
514    track: (event: string, data?: object) => void
515  }
516}
517 
518// Create context
519const DepsContext = createContext<AppDependencies | null>(null)
520 
521// Provider
522function AppProvider({ deps, children }: { deps: AppDependencies; children: ReactNode }) {
523  return <DepsContext.Provider value={deps}>{children}</DepsContext.Provider>
524}
525 
526// Hook to use dependencies
527function useDeps(): AppDependencies {
528  const deps = useContext(DepsContext)
529  if (!deps) throw new Error('Missing AppProvider')
530  return deps
531}
532```
533 
534### Use in Components
535 
536```typescript
537function UserProfile({ userId }: { userId: string }) {
538  const { api, analytics } = useDeps()
539  const [user, setUser] = useState<RemoteData<Error, User>>(notAsked())
540 
541  useEffect(() => {
542    setUser(loading())
543    api.getUser(userId)
544      .then(u => {
545        setUser(success(u))
546        analytics.track('user_viewed', { userId })
547      })
548      .catch(e => setUser(failure(e)))
549  }, [userId, api, analytics])
550 
551  // render...
552}
553```
554 
555### Testing with Mock Dependencies
556 
557```typescript
558const mockDeps: AppDependencies = {
559  api: {
560    getUser: jest.fn().mockResolvedValue({ id: '1', name: 'Test User' }),
561    updateUser: jest.fn().mockResolvedValue({ id: '1', name: 'Updated' }),
562  },
563  analytics: {
564    track: jest.fn(),
565  },
566}
567 
568test('loads user on mount', async () => {
569  render(
570    <AppProvider deps={mockDeps}>
571      <UserProfile userId="1" />
572    </AppProvider>
573  )
574 
575  await screen.findByText('Test User')
576  expect(mockDeps.api.getUser).toHaveBeenCalledWith('1')
577})
578```
579 
580---
581 
582## 7. React 19 Patterns
583 
584### use() for Promises (React 19+)
585 
586```typescript
587import { use, Suspense } from 'react'
588 
589// Instead of useEffect + useState for data fetching
590function UserProfile({ userPromise }: { userPromise: Promise<User> }) {
591  const user = use(userPromise)  // Suspends until resolved
592  return <div>{user.name}</div>
593}
594 
595// Parent provides the promise
596function App() {
597  const userPromise = fetchUser('1')  // Start fetching immediately
598 
599  return (
600    <Suspense fallback={<Spinner />}>
601      <UserProfile userPromise={userPromise} />
602    </Suspense>
603  )
604}
605```
606 
607### useActionState for Forms (React 19+)
608 
609```typescript
610import { useActionState } from 'react'
611import * as E from 'fp-ts/Either'
612 
613interface FormState {
614  errors: string[]
615  success: boolean
616}
617 
618async function submitForm(
619  prevState: FormState,
620  formData: FormData
621): Promise<FormState> {
622  const data = {
623    email: formData.get('email') as string,
624    password: formData.get('password') as string,
625  }
626 
627  // Use Either for validation
628  const result = pipe(
629    validateForm(data),
630    E.match(
631      (errors) => ({ errors, success: false }),
632      async (valid) => {
633        await saveToServer(valid)
634        return { errors: [], success: true }
635      }
636    )
637  )
638 
639  return result
640}
641 
642function SignupForm() {
643  const [state, formAction, isPending] = useActionState(submitForm, {
644    errors: [],
645    success: false
646  })
647 
648  return (
649    <form action={formAction}>
650      <input name="email" type="email" />
651      <input name="password" type="password" />
652 
653      {state.errors.map(e => <p key={e} className="error">{e}</p>)}
654 
655      <button disabled={isPending}>
656        {isPending ? 'Submitting...' : 'Sign Up'}
657      </button>
658    </form>
659  )
660}
661```
662 
663### useOptimistic for Instant Feedback (React 19+)
664 
665```typescript
666import { useOptimistic } from 'react'
667 
668function TodoList({ todos }: { todos: Todo[] }) {
669  const [optimisticTodos, addOptimisticTodo] = useOptimistic(
670    todos,
671    (state, newTodo: Todo) => [...state, { ...newTodo, pending: true }]
672  )
673 
674  const addTodo = async (text: string) => {
675    const newTodo = { id: crypto.randomUUID(), text, done: false }
676 
677    // Immediately show in UI
678    addOptimisticTodo(newTodo)
679 
680    // Actually save (will reconcile when done)
681    await saveTodo(newTodo)
682  }
683 
684  return (
685    <ul>
686      {optimisticTodos.map(todo => (
687        <li key={todo.id} style={{ opacity: todo.pending ? 0.5 : 1 }}>
688          {todo.text}
689        </li>
690      ))}
691    </ul>
692  )
693}
694```
695 
696---
697 
698## 8. Common Patterns Cheat Sheet
699 
700### Render Based on Option
701 
702```typescript
703// Pattern 1: match
704pipe(
705  maybeUser,
706  O.match(
707    () => <LoginButton />,
708    (user) => <UserMenu user={user} />
709  )
710)
711 
712// Pattern 2: fold (same as match)
713O.fold(
714  () => <LoginButton />,
715  (user) => <UserMenu user={user} />
716)(maybeUser)
717 
718// Pattern 3: getOrElse for simple defaults
719const name = pipe(
720  maybeUser,
721  O.map(u => u.name),
722  O.getOrElse(() => 'Guest')
723)
724```
725 
726### Render Based on Either
727 
728```typescript
729pipe(
730  validationResult,
731  E.match(
732    (errors) => <ErrorList errors={errors} />,
733    (data) => <SuccessMessage data={data} />
734  )
735)
736```
737 
738### Safe Array Rendering
739 
740```typescript
741import * as A from 'fp-ts/Array'
742 
743// Get first item safely
744const firstUser = pipe(
745  users,
746  A.head,
747  O.map(user => <Featured user={user} />),
748  O.getOrElse(() => <NoFeaturedUser />)
749)
750 
751// Find specific item
752const adminUser = pipe(
753  users,
754  A.findFirst(u => u.role === 'admin'),
755  O.map(admin => <AdminBadge user={admin} />),
756  O.toNullable  // or O.getOrElse(() => null)
757)
758```
759 
760### Conditional Props
761 
762```typescript
763// Add props only if value exists
764const modalProps = {
765  isOpen: true,
766  ...pipe(
767    maybeTitle,
768    O.map(title => ({ title })),
769    O.getOrElse(() => ({}))
770  )
771}
772```
773 
774---
775 
776## When to Use What
777 
778| Situation | Use |
779|-----------|-----|
780| Value might not exist | `Option<T>` |
781| Operation might fail (sync) | `Either<E, A>` |
782| Async operation might fail | `TaskEither<E, A>` |
783| Need loading/error/success UI | `RemoteData<E, A>` |
784| Form with multiple validations | `Either` with validation applicative |
785| Dependency injection | Context + `ReaderTaskEither` |
786| Prevent re-renders with fp-ts | `useMemo` or `fp-ts-react-stable-hooks` |
787 
788---
789 
790## Libraries
791 
792- **[fp-ts](https://github.com/gcanti/fp-ts)** - Core library
793- **[fp-ts-react-stable-hooks](https://github.com/mblink/fp-ts-react-stable-hooks)** - Stable hooks
794- **[@devexperts/remote-data-ts](https://github.com/devexperts/remote-data-ts)** - RemoteData
795- **[io-ts](https://github.com/gcanti/io-ts)** - Runtime type validation
796- **[zod](https://github.com/colinhacks/zod)** - Schema validation (works great with fp-ts)
797