Upgrade to version 2.x

fp-ts@2.x brings with it some major improvements, but also breaking changes and the removal of deprecated APIs. This document will help you understand what changed and how you can upgrade your existing codebase.

The major changes in fp-ts@2.x are:

  • Requires TypeScript 3.5+
  • fp-ts@1.19.x has been released with backported 2.x features for a gradual upgrade path
  • Data types are no longer implemented as classes, resulting in a new API using pipe
  • The run() method on IO, Task, etc. has been replaced with a thunk
  • Functions accepting fallback values are now always lazy (e.g. getOrElseL is now just getOrElse)
  • Deprecations
    • HKT: Replaced Type<n> with Kind<n>
    • Replaced Setoid with Eq
    • Several modules were removed, e.g. Exception, Free, StrMap, Trace, Validation, …
    • Read the full changelog for all the changes

Upgrading from version 1.x

You can gradually upgrade your existing codebase using the fp-ts@1.19.x release; the new fp-ts@2.x APIs have been backported to this release.

  1. Upgrade TypeScript to version 3.5+
  2. Install fp-ts@1.19.x, which contains the new fp-ts@2.x APIs
  3. Optional: activate the @obsolete rule for tslint to get guidance on what to change
  4. Familiarise yourself with the new API
  5. Gradually replace the existing code with the new API
  6. Upgrade to fp-ts@2.x and make sure to also upgrade all dependencies that rely on fp-ts

tslint rule

In order to make easier to spot all the occurrences of chainable APIs without depending on @deprecated, which would force you to migrate in one shot, a custom tslint rule is provided (@obsolete).

Add the following lines to your tslint.json to turn the @obsolete rule on:

{
+  "rulesDirectory": ["./node_modules/fp-ts/rules"],
   "rules": {
+    "obsolete": true
   }
}

This rule is available in the 1.19.x branch.

Dependencies

Don’t forget to update your dependencies: libraries that use fp-ts like io-ts or monocle-ts have to be upgraded to their fp-ts@2.x compatible versions.

The new API

In fp-ts@2.x data types are no longer implemented with classes; the biggest change resulting from this is that the chainable API has been removed. As an alternative, a pipe function is provided, along with suitable data-last top level functions (one for each deprecated method). This is best shown with an example:

v1 (deprecated)

import * as O from 'fp-ts/Option'

O.some(1)
  .map((n) => n * 2)
  .chain((n) => (n === 0 ? O.none : O.some(1 / n)))
  .filter((n) => n > 1)
  .foldL(
    () => 'ko',
    () => 'ok'
  )

v2 (new)

import * as O from 'fp-ts/Option'
import { pipe } from 'fp-ts/pipeable'

pipe(
  O.some(1),
  O.map((n) => n * 2),
  O.chain((n) => (n === 0 ? O.none : O.some(1 / n))),
  O.filter((n) => n > 1),
  O.fold(
    () => 'ko',
    () => 'ok'
  )
)

We recommend to use pipe even if you work with just one function, as it allows TypeScript to infer the types automatically. It’s also easier to migrate existing code, because the argument order remains the same.

import * as O from 'fp-ts/Option'
import { pipe } from 'fp-ts/function'

pipe(
  O.some(1),
  O.fold(
    () => 'ko',
    (n) => `ok: ${n}`
  )
)

If you are interested, read about the benefits of the new API in the technical discussion leading to fp-ts@2.x.

Replacement of the run() method

The run() method on IO, Task, etc. has been replaced with a thunk:

v1 (deprecated)

import { Task } from 'fp-ts/Task'

const deepThought = new Task<number>(() => Promise.resolve(42))

deepThought.run().then((n) => {
  console.log(`The answer is ${n}.`)
})

v2 (new)

import { Task } from 'fp-ts/Task'

const deepThought: Task<number> = () => Promise.resolve(42)

deepThought().then((n) => {
  console.log(`The answer is ${n}.`)
})

Functions accepting fallback values are now always lazy

In many places fp-ts@1.x provided two versions of methods:

v1 (deprecated)

import * as O from 'fp-ts/Option'

O.some(1).getOrElse(0) // Direct
O.some(1).getOrElseL(() => 0) // Lazy, i.e. only run if needed

v2 (new)

In fp-ts@2.x the API has been simplified, only the lazy variants have been kept with the L suffix removed.

import * as O from 'fp-ts/Option'
import { pipe } from 'fp-ts/function'

pipe(
  O.some(1),
  O.getOrElse(() => 0)
)

Removed modules

  • Exception
  • Free
  • FreeGroup
  • IxIO
  • IxMonad
  • Monoidal
  • Pair
  • StrMap (use Record instead)
  • Trace
  • Validation (use Either’s getValidation)
  • Zipper

References

If you’re interested in reading up on how this release came to be, have a look at the following discussions: