Refactor TypeScript to fp-ts

Provides a migration guide for converting imperative TypeScript to fp-ts, organized around six conversion patterns: try/catch to Either/TaskEither (via E.tryCatch/TE.tryCatch, preserving the original error rather than discarding it), null or undefined checks to Option (O.fromNullable, chained with O.flatMap), Node-style callbacks to Task, class-based dependency injection to Reader with a dedicated "Testing with Reader" pattern for injecting mocks, imperative for/while loops to map/filter/reduce/unfold, and Promise chains - .then, Promise.all, Promise.race - to pipe-based TaskEither, A.traverse(TE.ApplicativePar), and alternative-selection combinators respectively. A closing Quick Reference table maps eighteen imperative idioms directly to their fp-ts equivalent, such as array.find() to A.findFirst() and new Class(deps) to R.asks()/RTE.ask().

// CORRECT: Execute the Task
const result = await fetchData()(); // Note the double invocation

Use it when actively refactoring an existing imperative TypeScript codebase toward fp-ts and need migration strategy and trade-offs, not isolated pattern examples. It documents six pitfalls with wrong/right code: forgetting that a Task must be invoked twice to actually run (fetchData()()), breaking out of the fp-ts ecosystem by throwing inside an otherwise-functional pipeline, using map where flatMap is needed and producing a nested Either, discarding the original error cause inside TE.tryCatch's second argument, overusing fromNullable for a single one-off null check where ?? would do, and unsafely casting an Either to its Right variant instead of handling the Left case. It is equally explicit about when NOT to refactor: simple synchronous code with no benefit from the wrapping, performance-critical hot-path loops since fp-ts operations allocate intermediate arrays, interfaces dictated by a third-party library like Express middleware that should stay imperative and only convert at the boundary, code a non-FP-fluent team will maintain, trivial null checks, error handling that just logs and rethrows without needing composed error types, and test code, which should stay readable over "functional."

Input is an existing imperative function or module; output is its fp-ts equivalent plus, for larger migrations, a staged plan. Five gradual-adoption strategies are given as the actual migration methodology: start converting at system boundaries (API responses, DB results, file I/O, user input) while leaving internals imperative; build small bridge functions (unsafeUnwrap, catchSync, fromPromise, toPromise) to cross between the two styles during transition; migrate module-by-module, keeping a module's external API unchanged while its internals adopt fp-ts types, then flip the public API once internals are stable; let the TypeScript compiler drive the migration by changing a function's type signature first and following the resulting call-site errors; and write tests asserting on E.isRight/E.isLeft as living documentation of the new contract.

Built entirely on fp-ts modules - Either/TaskEither (E, TE), Option (O), Array (A), Reader/ReaderTaskEither (R, RTE) - with no other dependency; the loop and Promise-chain conversions also reference pipe and Task (T) directly. It assumes standard TypeScript/Node tooling, using Express as the third-party-boundary example, with no other framework integration.

TypeScript developers actively migrating an imperative codebase to fp-ts who need a staged, low-risk adoption strategy and a list of the specific mistakes that trip up that migration, rather than a from-scratch fp-ts tutorial.