DEV Community: Anthony G

Simple Immutable Data w/ Spectacles 👓

Anthony G — Wed, 25 Aug 2021 04:04:46 +0000

Do you want to love immutable data but think it's a drag?

Are you perplexed by the syntax of immutability-helper? Repulsed by immer.js's use of assignment? Alarmed by lodash's lack of type safety?

Looking for something a little more intuitive, powerful & flexible? Clear up your data w/ spectacles-ts (github repo)!

Installation

yarn add fp-ts spectacles-ts

Syntax (featuring auto-complete!)

import { pipe } from 'fp-ts/function'
import { set } from 'spectacles-ts'

const oldObj = { a: { b: 123 } }
const newObj = pipe(oldObj, set('a.b', 999))
// oldObj = { a: { b: 123 } }
// newObj = { a: { b: 999 } }

It's that simple!

Try it out here!

(For more info on pipe and fp-ts, check out the appendix)

Nullables

You can set a nullable value using a ?, similar to optional chaining syntax in native js:

interface Obj { a?: { b: number } }
const obj: Obj = { a: { b: 123 } }
const obj2: Obj = {}
const x = pipe(obj, set('a?.b', 456))
const y = pipe(obj2, set('a?.b', 456))
// x = { a: { b: 456 } }
// y = {}

Tuples

You can change at an index of a tuple:

const tup = [123, 'abc'] as const
const x = pipe(tup, set('[0]', 456))
// x = [456, 'abc']

(Here are quick guides if you're unfamiliar with tuples or as const assertions)

Discriminated Union

You can refine a discriminated union:

type Shape = { shape: "circle"; radius: number } | { shape: "rectangle"; width: number; height: number }
const circle: Shape = { shape: "circle"; radius: 123 }
const rect: Shape = { shape: "rectangle"; width: 123, height: 123 }
const x = pipe(circle, set('shape:circle.radius', 456))
const y = pipe(rect, set('shape:circle.radius', 456))
// x = { shape: "circle"; radius: 456 }
// y = { shape: "rectangle"; width: 123, height: 123 }

(If you're not sure what a discriminated union is, here's a quick intro)

Traversals

We can traverse an Array to change its nested data

const x = pipe(
  [{ a: 123 }, { a: 456 }],
  set('[]>.a', 999)
)

// equivalent to:
const y = [{ a: 123 }, { a: 456 }].map(set('a', 999))

// x = y = [{ a: 999 }, { a: 999 }]

We can also traverse a Record

const rec: Record<string, { a: number }> = 
  { two: { a: 456 }, one: { a: 123 } }
const x = pipe(rec, set('{}>.a', 999))
// x = { one: { a: 999 }, two: { a: 999 } }

Indexed Arrays

We can change the value of an Array at a particular index using [number]. To preserve auto-complete, we have to pass in the index number as a separate argument:

const array: { a: number }[] = [{ a: 123 }]
const x = pipe(array, set('[number].a', 0, 456))
//                                       ^
//              The index '0' comes after the path string '[number].a'
// x = [{ a: 456 }]

const y = pipe(array, set('[number].a', 1, 456))
// y = [{ a: 123 }]

Each 'index' in a path gets its own value argument

const nestedArray = [[], [{ a: 123 }]]
const x = pipe(nestedArray, set('[number].[number].a', 1, 0, 456))
//                                                     ^  ^
//                              Similar to nestedArray[1][0].a
// x = [[], [{ a: 456 }]]

You can set the value at an index of a Record in a similar way

const rec: Record<string, number> = { a: 123 }
const x = pipe(rec, set('[string]', 'a', 456))
// x = { a: 456 }

Modification

You can modify a value in relation to its old value:

import { modify } from 'spectacles-ts'

const x =
  pipe({ a: { b: 123 } }, modify('a.b', b => b + 4))
// x = { a: { b: 127 } }

You can use this to e.g. append to an array

import * as A from 'fp-ts/ReadonlyArray'

const x = pipe(
  { a: [123] },
  modify('a', A.append(456))
)
// x = { a: [123, 456] }

(For more on fp-ts, check out the appendix)

You can even change a value's type this way:

import { modifyW } from 'spectacles-ts'
//             ^
//             |
// The 'W' stands for 'widen'
// as in 'widen the type'

const x =
  pipe([{ a: 123 }, { a: 456 }], modifyW('[number].a', 0, a => `${a + 4}`))
// x: { a: string | number }[]
// x = [{ a: "127" }, { a: 456 }]

And there are convenience operations for working with Option and Either types

Change Object types

You can change an existing key:

import { upsert } from 'spectacles-ts'

const x = pipe(
  { a: { b: 123 } }, 
  upsert('a', 'b', 'abc')
)
// x: { a: { b: string } }
// x = { a: { b: 'abc' } }

Or add a new one:

const x = pipe(
  { a: { b: 123 } }, 
  upsert('a', 'c', 'abc')
)
// x: { a: { b: number; c: string } }
// x = { a: { b: 123, c: 'abc' } }

Or remove one of them:

import { remove } from 'spectacles-ts'

const x = pipe(
  { nest: { a: 123, b: 'abc', c: false } }, 
  remove('nest.a')
)
// x: { nest: { b: string, c: boolean } }
// x = { nest: { b: 'abc', c: false } }

Or rename a key:

import { rename } from 'spectacles-ts'

const x = pipe(
  { nest: { a: 123 } }, 
  rename('nest', 'a', 'a2')
)
// x: { nest: { a2: number } }
// x = { nest: { a2: 123 } }

get

You can also get a value

import { get } from 'spectacles-ts'

const x = pipe({ a: { b: 123 } }, get('a.b'))
// x: number
// x = 123

// equivalent to
const y = { a: { b: 123 } }.a.b
// y: number
// y = 123

The curried functions from spectacles-ts fit in nicely w/ a functional style

That's one reason you might want to use a function like get:

const x = [{ a: 123 }].map(get('a'))
// x: number[]
// x = [123]

Option

Since Array access at a given index might fail, we use fp-ts's Option type

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

//           |
//           v
const x: O.Option<number> = pipe(array, get('[number].a', 0))
// x = O.some(123)

This also gives us a way to know when a 'set' call has failed, using setOption:

import { set, setOption } from 'spectacles-ts'

const silentSuccess = pipe([123], set('[number]', 0, 999))
const silentFailure = pipe([123], set('[number]', 1, 999))
// silentSuccess: number[]
// silentFailure: number[]
// silentSuccess = [999]
// silentFailure = [123]

const noisySuccess = pipe([123], setOption('[number]', 0, 999))
const noisyFailure: O.Option<number[]> = pipe([123], setOption('[number]', 1, 999))
// noisySuccess: O.Option<number[]>
// noisyFailure: O.Option<number[]>
// noisySuccess = O.some([999])
// noisyFailure = O.none

(In case the Option type is unfamiliar, check out the appendix for a bit more info)

Also featuring modifyOption and modifyOptionW

Conclusion

I hope spectacles-ts can help you modify data both immutably & ergonomically!

Follow me on twitter! @typesafeFE

Appendix: functional programming

Whats fp-ts

You might have noticed a few references to the npm package called fp-ts. It's the latest in the line of successon of data utility libraries for javascript

underscore.js -> lodash -> ramda -> fantasy land -> fp-ts

fp-ts stands for 'functional programming in typescript'. 'Functional programming' is just a style that emphasizes data transformations and type-safety

Usually functions from fp-ts and its libraries (including spectacles-ts) rely on pipe

pipe

You might be wondering what that function called pipe is for

It can simplify the use of many nested functions

import { pipe } from 'fp-ts/function'

const manyfuncs = String(Math.floor(Number.parseFloat("123.456")));
const samething = pipe(
  "123.456",
  Number.parseFloat,
  Math.round,
  String
);

It's a bit easier to read in this format. We start with a string, then it's parsed into a number, then rounded, and then converted back into a string. It almost looks like a bulleted list!

Why use pipe for spectacles

Let's see what libraries that don't use pipe look like

import { mapValues, filter } from 'lodash'

const data: Record<string, number> = { a: 1, b: 2, c: 3 }

const ugly = filter(
  mapValues(data, (x) => x * 2),
  (x) => x > 2
)
// ugly = { b: 4, c: 6 }

This is a bit difficult to read. mapValues is nested inside filter - this could get messy if we add more functions. We can imagine that this might look much nicer if our data were an array - something like data.map(x => ..).filter(x => ..). Is this possible with an object?

import _ from 'lodash'

const chained = _.chain(data)
  .mapValues(x => x * 2)
  .filter(x => x > 1)
  .values()
// chained = { b: 4, c: 6 }

Much nicer! But this comes with a caveat - now we are importing all 600KB of lodash for two simple functions

pipe gives us the best of both worlds:

import { pipe } from 'fp-ts/function'
import { map, filter } from 'fp-ts/ReadonlyRecord'

const piped = pipe(
  data,
  map(x => x * 2),
  filter(x => x > 1)
)
// piped = { b: 4, c: 6 }

Legibility and economy - that's why we use pipe as much as possible

Here's a more in-depth article about how pipe-able functions work. Here's one of the original articles motivating their use

Whats Option

The Option type is a useful alternative to undefined because it can nest

Consider the following problem:

const usernames: (string | undefined)[] = ["anthony", undefined, "stu"]
const atindex = usernames[4]
// atindex = undefined

We know that atindex is undefined, but we don't know what that means

It could be undefined because the user chose to remain anonymous. In this case, though, it's undefined because the user doesn't exist at all

Option gives us a way to represent both of these cases

import { Option } from 'fp-ts/Option'
import { lookup } from 'fp-ts/ReadonlyArray' 
const usernames: Option<string>[] = [O.some("anthony"), O.none, O.some("stu")]
const atindex: Option<Option<string>> = pipe(usernames, lookup(1))
// atindex = O.some(O.none)

atindex = O.some(O.none) means that the user exists and is anonymous. atindex = O.none means that the user never existed in the first place

For this reason Option should generally be used instead of undefined

The Option type is more powerful than undefined. Options can map and flatten, just like arrays and objects, and much more

Option can be a great, simple intro into the joys of fp-ts

`spectacles-ts` vs `monocle-ts`

spectacles-ts is built on top of monocle-ts, which is more powerful and flexible but a little less ergonomic.

Here's a side-by-side comparison between the two.

import { pipe } from 'fp-ts/lib/function'
import * as O from 'fp-ts/lib/Option'
import * as Op from 'monocle-ts/lib/Optional'

const optional = pipe(
  Op.id<{ a: { b: readonly string[] } }>(),
  Op.prop('a'),
  Op.prop('b'),
  Op.index(0),
)

const nestedMonocle =
  optional.getOption({ a: { b: ['abc', 'def'] } })
// nestedMonocle: O.Option<string>

import { pipe } from 'fp-ts/function'
import { get } from 'spectacles-ts'

const nestedSpectacles = 
  pipe({ a : { b: ['abc', 'def'] } }, get('a.b.[number]', 0))
// nestedSpectacles: O.Option<string>

You can see the simplicity that spectacles-ts offers

monocle-ts has these advantages:

spectacles-ts only works in piped contexts (except for get)
No limitation on object size
can filter (similar to es6's filter)
can traverse on any arbitrary traversable object (aka Zippers or Rose Trees)
Can define an isomorphism between two objects
works with the Map type

Note

An earlier version of spectacles used tuples for pathnames instead of string literals. This document has been updated to reflect the changes

CREDITS:
Logo - Stuart Leach

TaskEither vs Fluture

Anthony G — Sun, 25 Oct 2020 08:20:51 +0000

tl;dr

Task is actually a form of IO. Like Fluture's Future, this makes Task lazy, but unlike Future, IO is never meant to be invoked directly.

Future Rocks
Type Safety
fork is Missing
- What is Invocation
- Advantage of Laziness
- Short Circuit Evaluation
- What is fork
- Why is it Missing
- What is IO
- Wait What
- Forgetting to Invoke IO
- IO Entry Point
- hyper-ts
- redux-observable
Conclusion

Future Rocks

Much like TaskEither, Fluture's Future is a fully monadic, lazy, asynchronous, failable operation. While TaskEither is obviously based on fp-ts, Future is based on the older fantasy land functional programming library.

Unlike Promise, Future has some important advantages over TaskEither - it's ensures error handling at compile time, it's able to cancel asynchronous operations, and it has a broader array of combinators.

So why would we ever use TaskEither? Is it getting warm in here? Is anyone else sweating?

This paper aims to prove that TaskEither is in fact more powerful than Future in two ways: purity and type-safety.

Type Safety

This argument in favor of TaskEither is the easiest to make. fp-ts was designed with Typescript in mind, whereas fantasy land was created before Typescript existed.

The crown jewel of fp-ts and what sets it apart from other fp libraries is its static higher kinded types. Fluture's author, Aldwin Vlasblom, discusses this in the issue tracker for fantasy land.

This means that it's not possible using fantasy land to ensure at compile time that any given typeclass instance properly conforms to its typeclass - monad, functor, applicative functor, any of them.

For example, we can be sure that TaskEither works with sequenceT, just like any other arbitrary Applicative implementation. In my eyes, this makes fp-ts a more powerful library than fantasy land, although fantasy land is a great solution for developers who aren't able to use Typescript.

There are other reasons fp-ts is more powerful - static combinators and tree shaking come to mind - but those are outside the scope of this article.

fork is Missing

This one is a bit trickier to explain. Earlier, I mentioned that Future ensures error handling at compile time. As we have seen in Should I Use fp-ts Task, TaskEither can make no such guarantees. So how is Future able to do this?

The answer is in Future's invocation function - fork, which accepts a handler for both the error case and the resolution case. Now let's back it up and see what all that actually means.

What is Invocation

Task is 'lazy' and it must be 'invoked' or else it won't run. Future is the same way. What does this mean?

Let's take a look at a type defintion for TaskEither:

type TaskEither<E, A> = () => Promise<Either<E, A>>

TaskEither is simply an anonymous function returning a Promise. When we call that function, we say that we have 'invoked' that Task.

const a: TaskEither<string, number> = () => Promise.resolve(E.right<string, number>(4))
a() // invoking 'a', causing the Promise to execute

Future is similar. Why would we do this?

Advantage of Laziness

Vlasblom said about laziness with regard to his Future:

This means is that whoever gave us a Future didn’t only give us control over what happens with the result of its operation, but also over if and when the operation will happen.

This enables us to have better reasoning about exactly when our asynchronous operations are performed.

Short Circuit Evaluation

Another advantage of laziness is something called 'short-circuit evaluation'.

You might already be familiar with this concept from boolean arithmetic:

const first = (): boolean => {console.log('first'); return true }
const second = (): boolean => {console.log('second'); return true }
if (first() || second()) {
  // output:
  // first
}

second() is never invoked, because the || (logical 'or') operator evaluates from left to right, and once it reaches a true value, it stops looking.

This is also relevant for the new nullish coalescing operator '??='

What does this have to do with laziness? Well, since they both return from an anonymous function, first and second are lazy values!

What if we wanted to execute several TaskEithers in sequence, and if any of them returns Left, stops evaluating the other TaskEithers?

import { flow } from 'fp-ts/function'
import { pipe } from "fp-ts/pipeable"
import * as A from 'fp-ts/Array'
import * as T from 'fp-ts/Task'
import * as E from 'fp-ts/Either'
import * as TE from 'fp-ts/TaskEither'

const delayPromise = (millis: number) =>
<V>(value: V): Promise<V> => new Promise(
    resolve => setTimeout(() => {
      console.log(`evaluating ${value}`)
      resolve(value)
    }, millis)
  )

const delayTask = (millis: number) =>
  <V>(value: V): TE.TaskEither<string, V> => TE.tryCatch(
    () => delayPromise(millis)(value),
    () => 'error',
  )

const completed = flow(
  A.map(String),
  ss => ss.join(),
  console.log,
)
const taskArray = [
  delayTask(1000)(1),
  delayTask(2000)(2),
  TE.left<string, number>('short circuit'),
  delayTask(3000)(3),
  delayTask(4000)(4),
]

const result: Promise<void> = pipe(
  taskArray,
  A.sequence(TE.taskEitherSeq),
  TE.map(completed),
  T.map(E.getOrElse(console.error)),
  invokeTask => invokeTask(),
)
// output:
// evaluating 1
// evaluating 2
// short circuit

What if we try to do the same thing with Promise.all?

const promArray = [
  delayPromise(1000)(1),
  delayPromise(2000)(2),
  Promise.reject('short circuit'),
  delayPromise(3000)(3),
  delayPromise(4000)(4),
]

const result: Promise<void> = Promise.all(promArray)
  .then(completed)
  .catch(console.error)
// output:
// short circuit
// evaluating 1
// evaluating 2
// evaluating 3
// evaluating 4

Every Promise is run. Promise is 'eagerly' evaluated (the opposite of 'lazy'), so they're all invoked when they're created inside promArray

To be honest, it's not an accurate comparison, since it's impossible to chain Promises in sequence without using then

If we want to invoke an Array of TaskEither in parallel, we just use the other monad instance for TaskEither like this: A.sequence(TE.taskEither). This will output

// evaluating 1
// evaluating 2
// evaluating 3
// evaluating 4
// short circuit

A.sequence(TE.taskEither) awaits the output of every TaskEither before coalescing their outputs, which is why it prints 'short circuit' after all the evaluation. This makes it closer to Promise.allSettled than Promise.all. I mention this to show that the lazy nature of TaskEither makes it simpler, more intuitive and more flexible than Promise.

Lazy evaluation as a whole is not without disadvantages. Here is a great video by tsoding showing how a traversal of a lazy linked list can become tricky and expensive. However, I argue that in the context of asynchronous operations, laziness is a benefit.

What is fork

We have a major problem with TaskEither. If we invoke a TaskEither directly, we're able to discard our error value without doing anything about it.

const a: TE.TaskEither<string, void> = TE.left('failure')
a()

Type signatures aside, this is no better than an unchecked exception, and we've discussed the problems with those. How can we ensure that we handle our errors at compile time?

The same problem is mentioned in Duncan McGregor's Failure is not and Option, in the context of functions that return an Either type:

We could return Either in these cases, but as the caller is not processing a return value, it is easy to ignore the error as well ... [this only works] for functions where the caller is relying on using the result.

Fluture solves this problem with fork. fork accepts two (curried) arguments - an error handler and a resolution handler. fork is powerful because it's the only way to invoke a Future - meaning that it's required at compile time to handle both the rejection and resolution cases.

import * as F from 'fluture'

const a: F.FutureInstance<string, number> = F.Future<string, number>(
  (reject, resolve) => {
    resolve(3)
    // return function is a callback invoked on cancellation
    return (): void => {}
  }
)
const invoked: F.Cancel = pipe(
  a,
  F.fork(
    (err: string) => `error: ${err}`
  )(
    (val: number) => `resolved: ${val}`
  ),
)

A similar idea was proposed as part of the Promise/A+ spec back when it was being decided upon.

Why is it Missing

TaskEither has no equivalent of fork. You must invoke it unsafely.

In my article Should I Use fp-ts Task, I propose a self-imposed 'rule' as a solution to the problem. But why don't we just make a pull request to fp-ts and add a fork operation to TaskEither?

Because Task is actually a kind of IO. Here's a quote from Giulio Canti's (the creator of fp-ts) Introduction to Functional Programming (english translation)

Type constructor	Effect (interpretation)
`Option<A>`	a computation that may fail
`IO<A>`	a synchronous computation with side effects
`Task<A>`	an asynchronous computation

interface Task<A> extends IO<Promise<A>> {}

This is an interesting type definition of Task - it's actually a form of IO.

What is IO

As we can see from the table above, IO is

a synchronous computation with side effects

IO is fundamental concept to pure functional programming. It stands for Input and Output.

IO is defined in fp-ts like so:

type IO<A> = () => A

This is familiar! IO is just a lazy value. This is why Task is IO - Task is just a lazy promise.

The important thing about IO is that it wraps values obtained through 'side-effects' - meaning an effect that cannot be represented in the type system.

import * as IO from 'fp-ts/IO'

const getInput: (numLines: number): IO.IO<string> => ...
const printOutput: (lineBreaks: boolean): IO.IO<void> => ...

Referential transparency, an important asset for code, means that all possible outcomes of a function are represented in its type signature. This is the meaning of a pure function - a function that has no side effects unrepresented in its type signature.

In react, Component is called Pure if it's stateless - theoretically meaning there are no side effects to it's render logic. The JSX element it output was a pure function of it's input (props), and it given the same input it will always have the same output. The name Pure comes from this same idea of referential transparency. IO helps us maintain purity by representing a side-effect in the type system - it tells us exactly which parts of the program are impure, allowing us to keep a clear separation of the two.

IO is lazy for the reasons listed above - short-circuit evaluation and reasoning about when the operation is invoked, as well as a reason discussed in the previous post - it allows IO to nest (aka conform to the monad laws).

fp-ts has modules for the console and the browser canvas, that wrap effectful operations in IO. This is useful because once an IO value has been introduced, we always know that an effect has taken place beyond what our other types are able to represent. IO can be thought of as representing a change to the universe as a whole.

IO is valueable because it demarcates a value as having been the result of some side effect. This means that for IO to be useful, it can never be unwrapped (read: invoked).

Wait What

Hold up. Does this mean that we can't ever invoke Task? Strictly speaking, yes. The developer themself is never meant to invoke Task - the wrapper is too valuable. Having a value wrapped in Task ensures that we know that the value exists sometime in the future, and that we affected some kind of change on the outside world by the time we have it.

Rather than invoking Task, or any IO for that matter, we're meant to compress all of our IO down into one value and hand it off to an entry point that can handle it. I'll explain what this means in a minute, but for now, I feel like I should explain the big reason why we might want to avoid invoking IO. Purity's nice and all, but there's a killer feature here, hiding just under the surface.

Forgetting to Invoke IO

The major unaddressed problem in the room is this:

const onClick = (): Task<void> => pipe(
  fetchValue,
  T.map(E.fold(
    displayError,
    updateState,
  ))
)

Can you see the problem? It's a little hard to spot. We forgot to invoke Task!

Fluture's fork handles error cases at compile time, but doesn't do anything about this other huge problem - what if you forget to use fork at all?

We addressed this in Should I use fp-ts Task with a self-imposed 'rule' that we always explicitly type our invoked Task as Promise:

const onClick = (): Promise<void> => pipe(
  fetchValue,
  T.map(E.fold(
    displayError,
    updateState,
  )),
  invokeTask => invokeTask(),
)

But this is even easier to forget than fork. How can we solve this? And how are we meant to use IO if we can never invoke it? It turns out that these questions answer each other.

IO Entry Point

What we want is something like the haskell main entry point - a single entry point that evaluates a single IO value. Then, we can combine all of our IOs together (sequentially if we want - IO is a monad after all) and output them all from that point.

main :: IO ()
main = do putStrLn "What is 2 + 2?"
          x <- readLn
          if x == 4
              then putStrLn "You're right!"
              else putStrLn "You're wrong!"

(example stolen from Learn Haskell in 10 minutes)

This idea, originating from haskell, is common across pure functional languages. Purescript and Elm also have main, and Scala cats has IOApp which operates similarly.

Scala uses an interesting terminology - it's said that IO is not evaluated until the "end of the world". The metaphor being that our lazy evaluator procrastinates so bad that the only kind of event that could possibly cause it to run would be cataclysmic. The epitome of true laziness. Practically speaking, "the end of the world" happens when you run your program.

Here are a couple examples of IO entry points that work with fp-ts IO - hyper-ts on the backend and redux-observable on the frontend.

hyper-ts

hyper-ts is a library that allows type-safe connection handling for an express server. You can be sure at compile-time that you are responding to each request with a single response, with a parsed request body and with the head and body written in the correct order.

It's a remarkable library that prevents behavior that shouldn't be allowed in the first place and provides powerful integrations like runtime type validation out of the box.

The Middleware type is the core of the library. It's used to translate Connection values into the correct state.

export interface Middleware<I, O, E, A> {
  (c: Connection<I>): TE.TaskEither<E, [A, Connection<O>]>
}

The type is too complicated to go into, but notice that it's built around the TaskEither type. Naturally, Middleware has both fromTaskEither and fromIOEither functions (and ones for plain IO and Task as well) that upconvert from TaskEither and IOEither.

While a chain of Middlewares isn't exacly a single 'entry point' for the entire server, it is an 'entry point' for a single endpoint.

Notable fp blogger Tim Ecklund's hyper-ts is My Cyborg Brain has a detailed explanation and example application for hyper-ts, including a usage of the fromTaskEither function.

It's worth mentioning that if left unhandled, the error case in TaskEither is passed into the next function of the express route. This is standard default behavior for express applications. The error will be written to the client with the stack trace. The stack trace is not included in the production environment.

redux-observable

If you use react or vue.js, redux-observable can be a great IO entry point. The basic idea is very simple, though a little tricky to explain - every side effect in the app is represented as a sum type called an 'Action', and these 'Actions' are represented as an rxjs stream called an Observable.

Since an Observable represents a potentially infinite stream of asynchronous operations, Task can easily be converted into a stream. fp-ts-rxjs, a library created to bind rxjs and fp-ts together, has a function called fromTask, as well as a fromIO.

Check out my article Should I Use redux-observable? Also What is it? Also Let's be Honest what's Redux? for a thorough yet hopefully simple explanation with examples.

I also recommend using Observable if you need cancellation and you'd rather use TaskEither than Fluture (which I think you probably should)

Conclusion

This is the diciest topic yet. Properly using IO for Typescript is a tricky proposition, especially since it can feel unnecessary, even arbitrary.

When describing what a Functor is, tsoding made a great point about pure functional programming more broadly:

Rust developers like to unwrap everything ... they cannot work with values unless they unwrap them ... In haskell world, we inject functions into things, and modify them from within.

Properly using IO isn't about unwrapping it's value, it's about leaving the value where it is and changing it from within. It's a powerful paradigm shift, and one whose benefits we've explored.

Of course, it's not always worth the added complexity. Like with many of these articles about fp-ts, it ends up being a shade of grey in the end. And as usual, it's probably not worth retrofitting an entire existing application to use redux-observable if it doesn't already - the pros just don't outweigh the cons. And for a simple application, or one that just doesn't need streams, simply following some arbitrary rules for TaskEither can be plenty.

There's a great discussion in the fp-ts issue tracker that brings up the topic of 'bubbles of purity'. I'll quote Toni Ruottu's comment in its entirety:

Essentially, what you have at the moment is a tiny bit of functional code inside an imperative React app. There is strictly speaking nothing wrong about that. It just means you are using fp-ts in a rather limited scope. You could proceed to create other such functional "bubbles" inside your app. This just means that your overall architecture will remain imperative.

Having only one Task or IO means you have managed to defined your application architecture in a functional manner. Your functional React app would then contain imperative bubbles. However, the imperative bubbles would never be executed in the functional context. Instead your code would simply combine the imperative bubbles and return them towards the application root.

The benefit of going 100% functional is that reasoning about the code becomes easier since the imperative bubbles that create unexpected consequences are executed "outside" your application. However, this also means less control over what the computer is doing since you are describing ideas rather than actions.

Ultimately you need to decide what parts of your app are functional or imperative. Functional parts will have more clarity while the imperative parts give you more precise control over execution.

I think it's profound that the very nature of IO is to create an 'imperative bubble'. We can extend this to say that any implementation in any language, from haskell to C, exists along a kind of 'purity' spectrum, and that proper or improper usage of 'IO' is only one facet of this. Total purity is not an end in and of itself; it's not even possible, let alone realistic.

True to its name, fp-ts does its best to provide a pure functional programming experience. Unlike fantasy land's Fluture which is designed for today's more imperative environment, fp-ts actually does inhabit a kind of 'typed-language fantasy land' where IO is universally referentially transparent. This is why, originally, fp-ts stood for 'fantasy problem - terribly strict' [citation needed].

However, with the right tooling, we can work towards a fantastical Future (quite a Task). With time we might see a shift in paradigm among web developers all over. fp-ts can take us to new heights, show us broader horizons, and in time maybe people will take the leap. Someday we can live in a world of purescript integration

TaskEither vs Promise

Anthony G — Sun, 25 Oct 2020 08:11:59 +0000

tl;dr

TaskEither extends the powerful railway-oriented paradigm implemented by Promise, and makes it more referentially transparent.

Promises Rock

Promise as a concept dates back to at latest 1976 when the term was proposed by Daniel P. Friedman and David Wise. The idea started catching on in the javascript community in the late 2000s.

In July of this year (2020), Sam Saccone published a remarkable article outlining in detail the history of javascript's Promise. It's a fun read, I consider it definitive and I recommend it. I will summarize it here.

Before Promise, there was XMLHttpRequest, which used continuation passing style (we'll explain this later). Then, there was MochiKit in 2005, the first implementation of Promise in javascript. This was followed by Dojo's deferredRequest in 2006 (Dojo was the predecessor to jQuery), which was decoupled into Deferred in 2007, followed by Promise in Waterken Q in 2009, which that same year became Q, which influenced Dojo to adopt Promise, followed by jQuery's deferred in 2010.

If that all sounds like a mess, that's because it was. There was no clear way forward - new implementations kept being released and no one knew which one would win out and become standard. Then, in 2010, many important foundational asynchronous web apis began shipping (Webcrypto, fetch, IndexedDB, localStorage). This raised the stakes on what was already a serious vhs/beta situation.

A year earlier, in 2009, Kris Zyp proposed a unified interface that would cover most of these implementations and allow them to inter-operate. This would later became known as the 'Promises/A' spec. Paul Chavard wrote a test suite for it in the Ember.js library, though it was flawed - it didn't correctly describe the 'Promises/A' spec. Domenic Denicola fixed it up and thereby created the 'Promises/A+' spec, which he described in his talk Boom, Promises/A+ Was Born.

In 2015, 'Promises/A+' became officially codified into ECMAScript 2015 (also known as es6). To quote Saccone:

The meta win here was the fact that having multiple agreeing implementations showed the TC39 that there was community consensus around the idea of Promises… an idea that a few years earlier was thought to be too esoteric for common use.

Because of this, Promise is now supported natively by 96% of browsers worldwide. 'Promises/A+' eventually would unify over 70 promise implementations, massively reducing complexity and confusion.

Though the A+ spec had to make serious compromises that we'll discuss later, I think it's worth mentioning the tremendous accomplishment that the compromises allowed: a unified Promise spec that saved us all from having to learn several different standards, and maybe saved the very idea of a javascript Promise.

Promises are Callback Heaven

Before promises, asynchronous operations had to be done using callbacks. Here's an example stolen from Arfat Salman

queryDatabase({ username: 'Arfat' }, (err, user) => {
  // handle errors database querying failure
  const image_url = user.profile_img_url;
  getImageByURL(`someServer.com/q=${image_url}`, (err, image) => {
    // handle errors fetching failure
    transformImage(image, (err, transformedImage) => {
      // handle errors transformation failure
      sendEmail(user.email, (err) => {
        // handle errors of email failure
        logTaskInFile('transformed the file and sent user an email', (err) => {
          // handle errors of logging failure
        })
      })
    }])
  })
})

The above code uses something called continuation passing style, although it's more often alarmingly referred to as 'callback hell'. According to Colin Toh

Callback Hell, also known as Pyramid of Doom, is an anti-pattern ... It consists of multiple nested callbacks which makes code hard to read and debug.

Here's the same code, written using Promise instead

queryDatabase({ username: 'Arfat' })
  .then((user) => {
    const image_url = user.profile_img_url;
    return getImageByURL(`someServer.com/q=${image_url}`)
      .then(image => transformImage(image))
      .then(() => sendEmail(user.email))
  })
  .then(() => logTaskInFile('...'))
  .catch(() => handleErrors()) // handle all errors

This control flow is improved. The power here is in modelling a callback as a value called a Promise.

Promises are Declarative

From James Coglan's article Callbacks are Imperative, Promises are Functional (emphasis added)

If object-oriented programming treats everything as an object, functional programming treats everything as a value – not just functions, but everything.

... At its best, functional programming is declarative. In imperative programming, we write sequences of instructions that tell the machine how to do what we want. In functional programming, we describe relationships between values that tell the machine what we want to compute, and the machine figures out the instruction sequences to make it happen.

More on that fuzzy word 'declarative' later.

Promises are Kinda Monads

then allows operations to run in sequence. This is a necessary trait for monads, which are also known as 'programmable semicolons'.

Monads are sometimes controversially¹ described as containers or wrappers (burritos). Promise fits this metaphor nicely - a Promise 'wraps' a value in a 'container' that the value can never come out of - it exists in that container forever, only able to be changed from within (unless you are cheating with async/await - more on that later). In the burrito metaphor, the Promise is the tortilla and the value is the beans and cheese².

Promise is not in fact a monad, but it's similar enough to be worth mentioning. We'll get to the differences later, but if you already understand monads, maybe now you understand Promise a little better, and vice-versa.

Control Flow

Here is an example of error handling using async/await syntax

try {
  const val = await getVal()
  try {
    const otherVal = await val.getOtherVal()
  } catch (err: any) {
    console.error('handle getOtherVal error')
  }
} catch (err: any) {
  console.error('handle getVal error')
}

Here is the same code with simpler control flow using vanilla Promise:

const otherVal = getVal()
  .catch(() => console.error('handle getVal error'))
  .then(val => val.getOtherVal())
  .catch(() => console.error('handle getOtherVal error'))

Here's an example from Jake Archibald's JavaScript Promises: an Introduction

Here's the implementation using Promise

asyncThing1()
  .then(asyncThing2)
  .then(asyncThing3)
  .catch(asyncRecovery1)
  .then(asyncThing4, asyncRecovery2)
  .catch(() => console.log("Don't worry about it"))
  .then(() => console.log("All done!"))

You can imagine that it would be much more complicated to implement this using async/await. Simple promises have more powerful error handling than async/await syntax³.

Promise also allows for expression-oriented programming, which encourages purity and is easier to reason about than statement-oriented async/await.

Railway oriented programming

Promise is able to easily handle this kind of complicated control flow because with one value it models either a rejection or a resolution. This allows combinators like catch to handle values implicitly passed down from earlier operations. Take this example:

const response = validate(request)
  .then(update)
  .then(send)

Here's a picture representing this code visually

That picture is from Scott Wlaschin's influential Railway oriented programming. You can see two separate 'tracks' - a 'resolution' track above, and a 'rejection' track underneath. In the parlance of railfans, we say that catch can 'shunt' our rejection cases back onto the resolution track, while then can shunt them right back onto the rejection track.

TaskEither takes railway oriented programming to the next level with an abundance of operators. They're more specific than then and catch and cover much more potential functionality.

                 reject(x)  resolve(y)
                       \      /
                  :     |    |     :
      TE.map (f)  :     |   f y    :  The 'map' function affects the value in
                  :     |    |     :  the resolution track, but if the train
                  :     |    |     :  would've been on the rejection track,
                  :     |    |     :  nothing would've happened.
                  :     |    |     :
    TE.chain (f)  :     |   f y    :  The 'chain' function affects the value in
                  :     |   /|     :  the resolution track, and allowed the
                  :     |  / |     :  train to change tracks, unless it was
                  :     | /  |     :  already on the rejection track.
                  :     |/   |     :
                  :     |    |     :
                  :          |     :
                  :     -    |     :
                  :     |    |     :
      TE.alt (m)  :     m    |     :  The 'alt' function replaces a train on
                  :     |\   |     :  the rejection track with another one,
                  :     | \  |     :  allowing it to switch tracks.
                  :     |  \ |     :
                  :     |   \|     :
   TE.orElse (f)  :    f y   |     :  The 'orElse' function is the opposite
                  :     |\   |     :  of the 'chain' function, affecting the
                  :     | \  |     :  rejection branch and allowing a change
                  :     |  \ |     :  back to the resolution track.
                  :     |   \|     :
  TE.fold (f, g)  :    f x  g y    :  The 'fold' function affects both
                  :      \   |     :  tracks, but forces the train to switch
                  :       \  |     :  from the rejection track back to the
                  :        \ |     :  resolution track.
                  :         \|     :
                  :          |     :
                             V

(This is an adaptation of a railway diagram from Aldwin Vlasblom's article on his Fluture library, which is similar to fp-ts. We'll explore Fluture more in the next article)

Problems with promises

Model unchecked exceptions

Errors propogated by Promise are typed as any, which is not good

const resource: Promise<Resource> = getResource()
resource
  .then((r: Resource) => ...)
  .catch((error: any) => ...)

It's also legal to completely omit a catch operation

const resource: Promise<Resource> = getResource()
resource
  .then((r: Resource) => ...)
  //.catch((error: any) => {}) <--- this is perfectly legal

This is because Promise models unchecked exceptions, which we covered in our last article, Either vs Exception Handling. The modern solution to this is the Either type, which of course is part of TaskEither

import * as TE from 'fp-ts/TaskEither'

const resource: TE.TaskEither<ResourceError, Resource> = getResourceTaskEither()

You can see right in the type signature of resource that it may return a ResourceError. We know at compile-time exactly which errors are possible, and we can't invoke a Task without handling both of it's Either cases (or at leas we shouldn't).

Then and catch are vague

then and catch are poorly defined functions. They have many different usages that look similar but behave differently. Here, I've noted the equivalent operations for TaskEither, which are more descriptive.

import { pipe } from 'fp-ts/pipeable'
import * as E from 'fp-ts/Either'
import * as T from 'fp-ts/Task'

const transformValueP = Promise.resolve(3)
  .then(n => n + 3)
const transformValueTE = pipe(
  TE.right(3),
  TE.map(n => n + 3)
)

const chainAsyncP = Promise.resolve(3)
  .then(n => Promise.resolve(n + 3))
const chainAsyncTE = pipe(
  TE.right(3),
  TE.chain(n => TE.right(n + 3))
)

const handleAllErrorsP: Promise<number> = Promise.reject(new Error('Illegal'))
  .catch(() => 3)
const handleAllErrorsTE: T.Task<number> = pipe(
  TE.left(new Error('Illegal')),
  T.map(E.getOrElse(() => 3)),
)

const asyncOnErrorP: Promise<number> = Promise.reject(new Error('Illegal'))
  .catch(() => Promise.resolve(3))
const asyncOnErrorTE: TE.TaskEither<Error, number> = pipe(
  TE.left(new Error('Illegal')),
  TE.orElse(() => TE.right(3)),
)

const handleErrorAndValueP: Promise<number> = Promise.resolve(3)
  .then(
    n => n + 3,
    () => 3,
  )
const handleErrorAndValueTE: T.Task<number> = pipe(
  TE.right(3),
  T.map(E.fold(
    () => 3,
    n => n + 3
  )),
)

Also note that the type of handleAllErrorsTE and handleErrorAndValueTE is Task<number>, while the rest are TaskEither - this is more informative than the Promise<number> type that all of the Promise values share.

Non obvious difference btwn catch and then

then can accept an error handling callback.

const example1: Promise<void> = Promise.resolve(3)
  .then(console.log)
  .catch(console.error)

const example2: Promise<void> = Promise.resolve(3)
  .then(
    console.log,
    console.error,
  )

These examples are functionally the same. So what's the difference between using the second parameter of then and catch?

Here's an example where the behavior is different:

const example3: Promise<number> = Promise.resolve(3)
  .then(() => Promise.reject(new Error('Illegal')))
  .catch(() => 13)
// example3 === Promise.resolve(13)

const example4: Promise<number> = Promise.resolve(3)
  .then(
    () => Promise.reject('Illegal'),
    () => 13,
  )
// example4 === Promise.reject(Error('Illegal'))

The difference arises because both callbacks for then can optionally be asynchronous. This means that the catch from example3 can handle rejections from it's then operation, while the error callback in example4 doesn't get the chance to handle the error thrown by it's success callback.

Here's a railway diagram describing the problem (stolen from this article on coding game)

Here's the equivalent using Task - note that example5 and example6 have entirely different types

const example5: T.Task<number> = pipe(
  TE.right(3),
  TE.chain(() => TE.left(new Error('Illegal'))),
  T.map(E.getOrElse(() => 13)),
)
const example6: TE.TaskEither<Error, number> = pipe(
  TE.right(3),
  TE.fold(
    () => TE.right(13),
    () => TE.left(new Error('Illegal'))
  ),
)

Promiselike

Quote from Aldwin Vlasblom's Broken Promises (warning: paywall)

At the time of drafting the Promises/A+ specification, there were already several existing and popular Promise libraries, and it was important for different implementations to inter-operate. Because of this, it was decided that when users return an object with a then-function into their Promise, it should be assimilated as if it's a Promise.

...Automatic assimilation has some drawbacks though:
Firstly, the fact that the mere existence of a then function on an object will make Promises change behaviour, exposes users to the potential danger of accidentally supplying something that looks too much like a Promise, and causing the program to misbehave. Execute the following for an example of Promises misbehaving:

Promise.resolve({ then: () => console.log("Hello!") }).then(() => {
  console.log('this will never be run')
})
// output:
// Hello!

It is also possible, though extremely difficult, to conform to PromiseLike accidentally, as I discovered writing this example code.

Poor Referential Transparency

Here we see a data structure containing two Promises

const twoPrints: [Promise<void>, Promise<void>] = [
  new Promise(res => {
    console.log('vote!')
    res()
  }), 
  new Promise(res => {
    console.log('vote!')
    res()
  })
]
// output
// vote!
// vote!

There is duplicate code here. What if we factor it out?

const print: Promise<void> = new Promise(res => {
  console.log('vote!')
  res()
})
const twoPrints: [Promise<void>, Promise<void>] = [
  print,
  print
]
// output
// vote!

Promise has cached the result of print (which was void), and will therefore not run it again.

We can do with Task.

import * as Task from 'fp-ts/Task'

const print: Task<void> = () => new Promise(res => {
  console.log('vote!')
})
const twoPrintsRefactored: [T.Task<void>, T.Task<void>] = [
  print,
  print
]
twoPrints.map(invoke => invoke())
// output
// vote!
// vote!

(Example adapted from this SO post about Scala's Future)

This property is called 'referential transparency'. If code is referentially transparent, we can always refactor duplicate code without changing the expected behavior. Referential transparency means that any expression can be replaced by its value without changing the behavior of the program. Things are what they look like - our intentions are 'transparent'.

Promise is therefore less referrentially transparent than Task is - although they both execute code that could affect the outside world, so neither of them can ever be fully transparent⁴.

This is an extension of the same idea we discussed in the first section - although Promise mererly represents a callback pattern as a value, Task (due to its laziness) represents an entire asynchronous execution as a value.

Promises aren't Monads

A rigidly defined category theoretical monad conforms to three different laws. Here the one called 'left identity'

const printLine = (line: string): Promise<void> =>
  new Promise(res => setTimeout(res, 0))
    .then(() => console.log(line))

// Left Identity: the following two statements are equivalent
printLine('vote!')
// output
// 'vote!'

Promise.resolve('vote!').then(printLine)
// output
// 'vote!'

However, Promise.resolve flattens & invokes any Promise passed into it, which breaks the left identity.

const printFirstThen = (next: Promise<void>): Promise<void> =>
  new Promise(res => {
    console.log('first')
    res()
  }).then(() => next)

printFirstThen(printLine('second'))
// output:
// first
// second

Promise.resolve(printLine('second')).then(printFirstThen) // type error
// Type 'void' is not assignable to type 'Promise<void>'

It's a type error - it won't even run. But even if we finagle the value to compile, it still has unexpected behavior:

Promise.resolve(printLine('second'))
  .then(output => printFirstThen(Promise.resolve(output)))
// output:
// second
// first

This happens because Promise.resolve invokes the Promise returned by printLine and forces it to resolve before moving on to printFirstThen.

Hopefully this example shows that this is strange behavior that can lead to unexpected results.

Here's how Task is able to pass the left identity:

const printLineT = (line: string): T.Task<void> =>
  () => printLine(line)
const printFirstThenT = (next: T.Task<void>): T.Task<void> => pipe(
  () => new Promise(res => {
    console.log('first')
    res()
  }),
  T.chain(() => next),
)

printFirstThenT(printLineT('second'))
// output:
// first
// second

pipe(
  T.of(printLine('second')),
  T.chain(printFirstThen),
  invoke => invoke()
)
// output:
// first
// second

This is an example of the practical engineering benefit of the monad laws: the broken left identity tangibly makes Promise less consistent & predictable than the behavior of Task.

Promises can't nest

There are times where we might want to nest Promise. For example, let's say we have the following two functions.

const getInput = (): Promise<string> => ...
const query = (input: string): Promise<Response> => ...

This function composing the two would be nice:

const queryFromInput = (): Promise<Promise<Response>> => ...

From the Promise/A+ spec feature request proposing nestable promises (originally posted in 2013):

This type is quite exquisite. It explicitly shows that there are two different threads of execution involved here - three if you include the present thread of execution - and we have access to either one. In fact, we have access to the response thread from within the userInput thread, which is something we lack if Promises are pre-flattened.

Again, although the type signature is legal, this function is impossible to implement due to the strange auto-flattening nature of promises.

Eagerness Complicates Nestability

Even if it could exist, a nested Promise would pose a problem. Since the creation of a Promise immediately invokes its execution, it's difficult to predict how a nested Promise would behave. The inner Promise could execute before the outer Promise, or vice versa - there's no way to know without looking at the implementation details.

// if promises nested, we'd have a 'map' that wouldn't flatten
Promise.prototype.map = <A>(a: A): Promise<A> => ...

//         this one executes first
//                  vvv
const outerFirst: Promise<Promise<void>> = new Promise(res => {
  console.log('outer first')
}).map(() => new Promise(res => {
  console.log('inner next')
}))

const inner = new Promise(res => {
  console.log('inner first')
})
//                 this one executes first
//                          vvv
const innerFirst: Promise<Promise<void>> = new Promise(res => {
  console.log('outer next')
}).map(() => inner)

Eager evaluation does not preclude nestability - Scala's Future unfortunately has both. It has the behavior described above, which is unnessecarily complicated and not very referentially transparent.

Nested Tasks always run from the innermost component outward.

const inner: T.Task<void> = () => new Promise(res => {
  console.log('inner')
})
const outer: T.Task<void> = () => new Promise(res => {
  console.log('outer')
})
const innerFirst: T.Task<T.Task<void>> = pipe(
  outer,
  T.map(() => inner),
)
// output:
// inner
// outer

Once again, the behavior of Task is more consistent than the behavior of Promise. We'll discuss eager vs. lazy evaluation in the next article, TaskEither vs Fluture.

Conclusion

Promise is powerful. It has made javascript into a first class language for asynchronous programming. I hope Domenic Denicola's legacy is his tremendous 'Promises/A+' spec, and not his infamous github comment criticising typed functional programming (the javascript fp library 'fantasy-land' was named after it).

Though I disagree with his statement, I understand where he was coming from. He was carrying the weight of dozens of proposals and the future of asynchronous programming - as javascript becomes more popular outside of the web (nodejs, react native, electron, ink, etc), it becomes clearer that the success of 'Promises/A+' had staggering implications. He must have felt that one wrong move could bring it all toppling down.

Not to give all the credit to Denicola - the idea is 45 years old, and it took many people many ideas and iterations to get to the point of 'Promises/A+'. I just would have felt wrong writing an article about Promise from a functional perspective without mentioning that github thread. If not for the aggressive and cyclical nature of the debate (on both sides), would recommend reading it - it's entirely about the practicality of functional programming & category theory. There's also a similar thread about Promise.resolve here - read at your own peril.

Needless to say, as great as Promise is, TaskEither is even better. It resolves many the pitfalls outlined above, and adds a ton of functionality. With its laziness, referential transparency, type-safety, and advanced yet simple control flow, TaskEither is the culmination of the best asynchronous programming techniques available.

Some people dislike the burrito metaphor - they correctly assert that it only describes a few monads, and only leads to more confusion later when introduced to more. Here are a couple of paradigmatic tweets (1, 2). ↩

However, the paper What we Talk About When we Talk About Monads posits that such metaphors are necessary for complete understanding of the concept, alongside 'formal' and 'implementation'-level knowledge.
Except you can't eat the burrito, because the filling doesn't exist yet. All you can do is tell the burrito that when it eventually does get filled with beans and cheese, you will want to modify them, like mash them up or something. Which of course means that you immediately throw out your first burrito, and now you have a new one, which is still an empty shell but now when it resolves, it'll all be mashed up, just how you like. ↩

Here's where it gets exciting - you can also tell the burrito that when it eventually exists, you've got another entirely different burrito recipe that needs to use your first burrito's filling - it'll take your beans turn them into some kind of new cassoulet burrito. So now you've thrown out the first burrito, and you've got a new tortilla containing a tortilla which is waiting for the beans and then waiting for the cassoulet to finish. I know what you're thinking - I don't want two tortillas in my burrito! But your burrito is so smart, it automatically yanks the middle shell out of there and throws it away so that you only have one shell. And you can go on chaining burritos together as much as you like! And this ability to nest the burritos and yank the tortilla - this is the essence of what it means to be a true burrito.

Sometimes, though, you might want both shells - you might want to be able to tell where the outer burrito ends and the inner one begins. Except it's an unlawful burrito, so it'll yank the middle shell out whether you want it to or not!

It's a little like Chipotle.
async/await syntax is great for asynchronous operations that don't need complex error handling and whose usage relies on many other asynchronous operations, like react-testing-library (although do-notation can help with this as well). ↩
This is part of the criticism some people have of the word 'declarative' - while Promise is the 'declarative' alternative to a callback, a Task is also 'declarative'. Task is more referentially transparent, but is it correct to say that it's 'more' declarative? It's a fuzzy word without a clear definition. ↩

Peter Landin discussed this in his seminal 1966 paper The Next 700 Programming Languages introducing his ISWIM language (apparently this problem is 55 years old). He suggests an alternative word that implies purity - 'denotative', from the realm of mathematics

The commonplace expressions of arithmetic and algebra have a certain simplicity that most communications to computers lack. In particular, (a) each expression has a nesting subexpression structure, (b) each subexpression denotes something (usually a number, truth value or numerical function), (c) the thing an expression denotes, i.e., its “value”, depends only on the values of its subexpressions, not on other properties of them.

...The word “denotative” seems more appropriate than nonprocedural, declarative or functional. The antithesis of denotative is “imperative.”

By this definition, neither Promise nor Task is denotative because they perform side-effects. A truly useful word!

Should I use fp-ts Task?

Anthony G — Mon, 19 Oct 2020 04:45:30 +0000

tl;dr

TaskEither can enforce type-safe error handling. Always convert with tryCatch. Laziness is a mixed blessing. Always return Promise<void> when invoking Task.

Two Problems with Promise
- catch uses any
- catch is optional
Welcome to Task
Task Rules
- Rule Number 1
- Rule Number 2
- Rule Number 3
Why are there rules this is dumb
Should I use Task
Emotional component
Conclusion

Two Problems with Promise

Here's an example of a promise using fetch:

fetch('https://jsonplaceholder.typicode.com/todos/1')
  .then(response => response.json())
  .then(json => console.log(json))
  .catch((err: any) => {
    console.error(error.message)
  })

`catch` uses `any`

We can do this without a compile-time error.

fetch('https://jsonplaceholder.typicode.com/todos/1')
  .then(response => response.json())
  .then(json => console.log(json))
  .catch((err: any) => {
    console.error(error.mesage) // 'message' is misspelled
  })

`catch` is optional

This throws a 'rejected Promise not handled' runtime exception.

fetch('http://jsonplaceholder.net/todos/-1') // wrong url
  .then(response => response.json())
  .then(json => console.log(json))

This is Bad

We never know whether any given Promise could fail, or how it might fail. Anything could go wrong at any time. It's hard to overstate how much damage this can cause. Given that asynchronous operations are often an application's biggest source of potential errors, untyped & optional asynchronous error handling is a recipe for disaster.

Welcome to Task

Here's the definition for Task¹:

export type Task<A> = () => Promise<A>

How does this help us? All we're doing is returning a Promise from an anonymous function.

It's not obvious, but Task will solve both of the problems listed above - it'll allow us to enforce consistent error handling at compile time.

However! It doesn't work unless you play by the rules. There are three Task rules that you must never violate under penalty of bugs.

Task Rules

Rule Number 1

You must always convert Promise to Task using tryCatch.

const safeAsync: Task<Either<Error, Response>> = tryCatch(
  (): Promise<Response> => fetch('https://jsonplaceholder.typicode.com/todos/1'),
  (err: unknown): Error => {
    if (err instanceof Error) {
      return err
    }
    return new Error(String(err))
  }
)

The first parameter is a function that returns a Promise. I'll explain later why this is a function and not just a Promise.

The second parameter forces us to catch the errors from the Promise from the first parameter. The potential error is represented as an unknown instead of an any.

unknown is safer than any because unknown forces us to narrow the type. In this case, we're narrowing with instanceof.

Check out that return type. Our Task will resolve into a value called an Either. An Either value is either an error value or a success value, but never both. We call the error value Left and the success value Right by convention. Here's the definition of Either:

interface Left<E> {
  _tag: 'Left'
  left: E
}
interface Right<A> {
  _tag: 'Right'
  right: A
}
type Either<E, A> = Left<E> | Right<A>

Let's look again at our return value:

Task<Either<Error, Response>>

This means that our Task will return either an Error or a Response (fetch returns a type called Response).

Compare this with the return type of fetch:

Promise<Response>

We can see that fetch will return a Response, but we have no idea what its error type might be. Could it even have an error? Task<Either<Error, Response>> tells us more about what's going on, and holds us to a contract - we must handle both possibilities.

The combination of Task and Either is so common, it has a type alias called TaskEither²:

type TaskEither<E, A> = Task<Either<E, A>>

The TaskEither package is actually where we import tryCatch from:

import * as E from 'fp-ts/Either'
import * as TE from 'fp-ts/TaskEither'

const safeAsync: TE.TaskEither<Error, Response> = TE.tryCatch(
  (): Promise<Response> => fetch('https://jsonplaceholder.typicode.com/todos/1'),
  E.toError,
)

We also have a convenience function called toError from the Either package that converts unknown into Error for us.

However, we still have to convert our Response into a JSON value³:

import { pipe } from 'fp-ts/pipeable'

const safeAsync: TE.TaskEither<Error, any> = pipe(
  TE.tryCatch(
    (): Promise<Response> => fetch('https://jsonplaceholder.typicode.com/todos/1'),
    E.toError,
  ),
  TE.chain(response => TE.tryCatch(
    (): Promise<any> => response.json(),
    E.toError,
  )),
)

If you're unfamiliar with pipe syntax, I recommend Ryan Lee's excellent Practical Guide to fp-ts.

TE.chain is similar to Promise.prototype.then.

We must wrap response.json() in a tryCatch because it's a Promise.

How will we print the result?

import * as T from 'fp-ts/Task'

const safeAsync: T.Task<void> = pipe(
  TE.tryCatch(
    (): Promise<Response> => fetch('https://jsonplaceholder.typicode.com/todos/1'),
    E.toError,
  ),
  TE.chain(response => TE.tryCatch(
    (): Promise<any> => response.json(),
    E.toError,
  )),
  T.map(E.fold(
    console.error,
    console.log,
  )),
)

T.map is also like Promise.prototype.then. While T.chain means what we must return a Task, T.map means that we can return anything we like. In this case, we return void

E.fold lets us do something for both the error case and the success case. It's a bit like using both callbacks of then, except the callbacks' return types have to match. In this example, we print simply print them both out to the console, with appropriate error styling.

Why is it a rule that we have to use tryCatch? Because it's possible to create a Task like this:

const unsafeAsync: Task<Response> = () => fetch('https://jsonplaceholder.typicode.com/todos/1')

However, this obviously doesn't solve our type-safety problem. What type of error could this cause? This might as well be a plain Promise.

Task is only useful if it can never fail.

We do this by representing both failure and success in its return type through Either.

Rule Number 2

You must explicitly type an invoked Task as Promise

Wait, what does 'invoke' mean?

Well it turns out that this will never run:

const safeAsync: T.Task<void> = ...

Until you invoke it like this:

// invoking the task
safeAsync()

Let's go back to our definition of a Task:

export type Task<A> = () => Promise<A>

Since a Task is actually a function, "invoking" simply means calling the function.

Wait, when is a Promise run anyway? Which of these Promises will be run?

const a: Promise<void> = new Promise(() => console.log('running a'))
new Promise(() => console.log('running b'))
function later() {
  return new Promise(() => console.log('running c'))
}

// output:
// running a
// running b

Promises are 'eagerly' evaluated, meaning that they're run as soon as they're constructed. The Promise returned by the function later has not yet been constructed because later has not been called yet.

later represents a 'lazy' evaluation, meaning that the Promise will not be run until later is called.

Since Task is a function, it represents a 'lazy' evaluation of its return value⁴. In fact, later could be typed as a Task

const later: T.Task<void> = () => {
  return new Promise(() => console.log('running c'))
}

Why do this? Well, the main benefit is that it can be easier to reason about what's actually happening. I'll quote an article about Scala (warning: paywall) that talks about this:

"With [Promise], our code acts differently according to where we write our code...A [Promise] doesn’t describe an execution, it executes."

By contrast, Task describes an execution rather than executing it. This means that we can manipulate a Task with chain and map as much as we want and pass it around the program secure in the knowledge that it hasn't been invoked yet. We can also invoke the same Task multiple times.

The problem is that sometimes, we forget to invoke Task! We can solve this by following rule # 2:

const onClick = (): Promise<void> => ...

We have explicitly typed onClick so that it must return a Promise. If we forget to return a promise, we'll get a compile-time error:

const onClick = (): Promise<void> => {
  const safeAsync: T.Task<void> = ...
  // this won't compile:
  // return safeAsync
  //
  // this will:
  // return safeAsync()
}

I actually prefer to write it this way because I think it's cleaner:

const safeAsync: T.Task<void> = ...
const onClick = (): Promise<void> => pipe(
  safeAsync,
  invokeTask => invokeTask(),
)

Rule Number 3

You may only ever invoke Task<void>. You can never invoke Task<string> or Task<number> etc.

You should especially avoid invoking a TaskEither.

This forces you to handle all of your cases before you run them.

const safeAsync: TE.TaskEither<Error, any> = ...
const onlyLogCorrect: TE.TaskEither<Error, void> = pipe(
  safeAsync,
  TE.map(console.log),
)
onlyLogCorrect() // we never handled the error case!
const logAll: T.Task<void> = pipe(
  safeAsync,
  T.map(E.fold(
    console.error,
    console.log,
  ))
)
logAll() // we handled all possibilities

We can follow rule #2 and rule #3 by returning Promise<void> whenever we invoke a Task.

const logAll: Promise<void> = pipe(
  safeAsync,
  T.map(E.fold(
    console.error,
    console.log,
  )),
  invokeTask => invokeTask(),
)

Why are there rules this is dumb

We could come up with a similar set of rules that would make Promise safer to use as well. Why go through the trouble of converting everything to Task and back again?

As I said earlier, the advantage is type-safety. Promise sacrifices a lot of safety by using any to represent error values. By converting to Task and back, we hold ourselves to the contract of whichever type we decide our error should be.

For even more power and specificity, you can use a union type or sum type to represent all of your different possible errors. This can strengthen a project that handles more than one possible kind of error (probably most projects). If this sounds interesting, check out my next article, Even More Beautiful API Calls with Sum Types

I'll tell you a secret - pure functional programmers don't have to follow rules #2 and #3. They have a rule of their own - they can never invoke Task at all! Sounds impossible, right? If you're curious about this and you have some time on your hands, check out my relevant article Why is fp-ts TaskEither Like that? - TaskEither vs Fluture

Should I use Task

As with Option, I advocate always using Task as much as possible if the project is new and you are building it from the ground up.

On the flip side, if a project is old and has lots of Promises in it already, it's probably best to store Promises in state and return them from functions, but Task can still be useful behind the scenes.

Although the main benefit is error handling, there's also a small benefit of operator readability. Promise.prototype.then can return either a Promise or some other generic value. The map and chain operators are separate - chain is for returning a Task, while map is for some other generic value. fold is also more specific than then - both callbacks must must return the same type. This makes your code easier to read: you can tell a lot about what's happening simply by reading the name of each operator.

Emotional component

It can feel oppressive at first to use compiler-enforced error handling. Error cases can pile up quickly and it might not be obvious what to do about all of them, or which ones are ok to ignore. On the flip side, TaskEither can help you discover errors you hadn't realized were possible. It can be demoralizing to realize that you had been letting errors slip through the cracks.

It can be difficult to have conversations about potential errors with product engineers/ux designers. Although it may seem like a trivial workplace conversation, sometimes it can feel like admitting defeat or failure, or worse, an accusation, to tell them that the product can fail in a way neither of you had expected. It's worth having some self-compassion in those moments.

Or maybe you're your own product person because you're working for a small company, or you're working on a solo project, or things just worked out that way. If that's the case and you find yourself overwhelmed by Task, it might be helpful to research some UX patterns for inspiration:

It's important to have these conversations so you can recognize which errors are worth keeping track of separately, and which can be smushed together and handled the same way. Maybe most problems can be handled with a simple error popup. This is the advantage of using sum types, which you can read about in the article I mentioned earlier. Sum types can relieve a lot of the burden. The idea is to set what granularity you need early on and to hold yourself to that as you go, modifying when necessary.

Conclusion

Task can be cumbersome compared to Promise - conversion is a pain, you have to remember to invoke it, and you have to remember to handle all of its cases.

However, the benefit is a dramatic decrease in bugs and an increase in readability. I think this makes Task a no-brainer for most projects, whether it's completely integrated, or only used sparingly.

The rules above can help you use Task to its fullest advantage and without fear. Remember:

Always convert Promise to Task using tryCatch
Explicitly type an invoked Task as Promise
Only ever invoke Task<void>

I hope Task leads you toward a bright future of asynchronous safety and security!

Task is actually defined as an interface which is different but weirder looking and basically the same ↩
TaskEither is also defined as an interface ↩
You can get rid of the any type in this code using io-ts. io-ts uses Either for its errors too - it's a match made in heaven! Here's a great tutorial: fp-ts and Beautiful API Calls ↩
Returning a value from a parameterless function to make it lazily evaluated is a common pattern called a 'thunk'. In this example, we would say that later is a thunk. According to Eric Raymond: ↩

[The term] was coined after they realized [...] that the type of an argument in Algol-60 could be figured out in advance with a little compile-time thought [...] In other words, it had 'already been thought of'; thus it was christened a thunk, which is 'the past tense of "think"'

This refers to the fact that the function has no parameters. Stephen Huig:

A zero-argument function has no way to change its behavior based on parameters it is called with, since it has no parameters. Therefore the entire operation of the function is set -- it is just waiting to be executed. No more "thought" is required on the part of the computer, all of the "thinking" has been done -- the action is completely "thunk" through.

Why is redux-observable Like That?

Anthony G — Mon, 19 Oct 2020 04:45:17 +0000

tl;dr

redux approximates the elm architecture w/o async capability. redux-loop and elm-ts both come close to exactly modeling elm, but redux-observable is simplest & most powerful. redux-thunk is naive, but popular enough that it influenced the design of redux

What's up with Redux?

redux is super weird. Why would we architect an application that way? How did someone even think to write it like that?

redux, redux-observable and react itself are the consequences of many concepts that have built on each other and in some cases been discovered in parallel. A couple of them come from backend design. Though each concept is simple, they form a complex web of relations to each other.

I gave up trying to come up with a coherent way to present this information, so I cheated. We're going to start at the present day and work ourselves backwards through the history of what led to redux, redux-observable and react. Hopefully this is a useful way to present information that's not necessarily linear. If you're unclear or confused about a concept, just keep reading, I might explain it later.

This is an opinionated view of what happened. Please let me know if you disagree with anything or if I left out anything important in the comments below!

(I'm also putting this article out against a deadline, so I'll be going back in and fleshing out some parts of this over time)

Timeline Overview

June 2020 - Halogen 5 Released
June 2017 - fp-ts-rxjs Gives Observable a Formal Monad Instance
March 2017 - elm-ts Ports the Elm Architecture to Typescript
November 2016 - redux-pack Released
May 2016 - Elm Abandons Strict FRP
March 2016 - rxjs Version 5 Released
Feb 2016 - redux-observable Released
Jan 2016 - redux-loop released
November 2015 - redux-saga Released
July 2015 - redux-thunk Released
June 2015 - Iterables, Generators Released as Part of ECMAScript 2015 (es6)
May 2015 - redux is released
May 2014 - Facebook open-sources Flux
May 2013 - Facebook open-sources React
March 2012 - Elm released
September 2011 - Facebook Releases FaxJS
Sometime Early 2010 (?) - Microsoft Releases ReactiveX
February 2010 - Facebook Introuces XHP
June 1997 - Conal Elliot and Paul Hudak Introduce FRP
Late 1980s - Haskell Team Invents & Discards redux observable
Sometime 1988 - CQS First Described by Bertrand Meyer
Jan 1987 - Sagas First Described by Garcaa-Molrna and Salem
December 1979 - MVC Architecture Introduced by Trygve Reenskaug

June 2020

Halogen 5 Released

Purescript Halogen gets its latest major release as of October 2020.

Halogen is a project initially created by Phil Freeman (original developer of the PureScript compiler) and funded by SlamData for use in their flagship app. So what is Halogen?

Elm and redux have a problem - they use a single sum type used to effect changes on a single global state. This is a problem because there are conceptual and performance advantages to colocated state (analogous article in react here).

Halogen, which is a pure framework that uses a component architecture similar to react, solved this problem by introducing sum types to handle communications between different components, called Query and Output.

The release of Halogen 5 introduces Action, which handles internal changees to a component's state. Presumably Action was named after redux's Action. This means that each component has its own conceptual redux, with three associated sum types:

Query goes from parent -> child, e.g. a parent component telling a video component to start playing
Message (AKA Output) goes from child -> parent, e.g. a dialog box component might want to invoke a dismissal function specified by its parent
Action goes from child -> child, e.g. a clicked button makes an ajax request

There's also:

Input which is analagous to react props

I mention this because Halogen is a logical extension of the ideas crystallized in redux and react. As such, redux and react can be simple frames through which to understand the complex Halogen architecture.

My theory is that Halogen was so named because of its adjacency to Functional Reactive Programming - in chemistry, the Halogens are characterized by their reactivity.

June 2017

fp-ts-rxjs Gives Observable a Formal Monad Instance

Giulio Canti's fp-ts-rxjs brings rxjs into the fp-ts ecosystem. It gives Observable an official monad instance, which it also transforms with Either for type-safe error handling and with Reader for dependency injection.

Also, it adds fromIO and fromTask operators, effectively turning redux-observable into an IO entry point for fp-ts programs using IO or Task.

March 2017

elm-ts Ports the Elm Architecture to Typescript

Giulio Canti's elm-ts proves that the Elm architecture can be represented in terms of react and rxjs. This makes it a saner alternative to redux + redux-loop.

The type signature of Cmd reveals it's strange frankenstein nature:

export interface Cmd<Msg> extends Observable<Task<Option<Msg>>> {}

I view this as proof that redux-observable is simpler and more powerful than the Elm architecture.

In fact, since elm can't represent higher-kinded types (typescript can by way of fp-ts)), elm-ts is more powerful than elm itself.

November 2016

redux-pack Released

Only worth mentioning as an interesting approach to redux async middleware. Though it came out after redux-saga and redux-observable, it's interesting to think of a Promise of Action as a stepping stone to the idea of a stream of Action.

It was conceived because redux-saga was seen as unwieldy. I would say that the type safety and simplicity of redux-observable solves this problem without sacrificing any power.

May 2016

Elm Abandons Strict FRP

Elm gets rid of Signal, favoring Sub instead (short for 'Subscription'). Sub is similar to Observable, except with fewer combinators and operators. For more complex usage of Msg, Elm keeps Cmd, which it still uses at the time of writing.

In my opinion, by the very nature of the fact that Elm tries to model events, it was never truly FRP in the first place.

March 2016

rxjs Version 5 Released

rxjs version 5, spearheaded by Netflix's Ben Lesh, is released. It's goals are to increase performance and stack safety.

Lesh collaborates with Microsoft, and has the type system in Typescript had to be changed to accomodate rxjs. He also collaborates with Google, who make rxjs fundamental to Angular in their release of Angular 2.

Source

Feb 2016

redux-observable Released

Netflix releases redux-observable, which updates redux-saga's pull-based Iterable streams to more appropriate push-based Observable streams.

While pull-based streams are great for handling back-presure, they make less sense for event handling. To paraphrase Ben Lesh (a principal maintainer of rxjs), "imagine every individual mouse event was represented as a js promise".

Since redux is a front-end tool that handles events of one kind or another, a push-based architecture makes more sense.

It also provides a lush library of stream operators and combinators by way of Observable and rxjs. However, later this same month ixjs will be released, providing similar operators and combinators for Iterables.

The name epic is chosen to sound similar to yet different from saga.

redux-observable's logo is a circling loop colored similar to the ReactiveX electric eel. It loops because of the recursive nature of epics. They are three ducks because the Netflix team thought the word 'redux' sounded like 'three ducks'.

Jan 2016

redux-loop released

redux-loop ports the Elm architecture to redux as an async middleware.

While a noble effort, it's a bit of a mess. Check out the type signature for Cmd (it's too complicated and involved to reprint here.) redux-observable's Epic is far simpler.

November 2015

redux-saga Released

redux-saga is an async middleware for redux that uses the 'saga' pattern. From the home page:

The mental model is that a saga is like a separate thread in your application that's solely responsible for side effects.

Earlier this year in July, Caitie McCaffrey gave a talk about her usage of the Saga pattern to develop Halo 4 at Microsoft. This was the inspiration, in part, for redux-saga.

July 2015

redux-thunk Released

The original async middleware for redux, cited in its documentation.

redux is so closely tied to redux-thunk that it changed its type signatures to accommodate it.

Let's examine the useDispatch hook in react-redux. Here's how you might expect it to work:

import { useDispatch } from 'react-redux'

const Comp = () => {
  const dispatch: (a: AppAction) => void = useDispatch<AppAction>()
  return (...)
}

But here's how it actually works:

const dispatch: (a: AppAction) => void = useDispatch<(a: AppAction) => void>()

What's up with that type signature? Why don't we just have to prove our Action type? Why do we have to provide the type signature for the dispatcher itself?

This is because with redux-thunk, it's possible to dispatch a function, so the type system has to be flexible enough to accomodate this. Here's an example of a function that might get dispatched (taken from the redux docs):

export function fetchPostsIfNeeded(subreddit) {
  // Note that the function also receives getState()
  // which lets you choose what to dispatch next.

  // This is useful for avoiding a network request if
  // a cached value is already available.

  return (dispatch, getState) => {
    if (shouldFetchPosts(getState(), subreddit)) {
      // Dispatch a thunk from thunk!
      return dispatch(fetchPosts(subreddit))
    } else {
      // Let the calling code know there's nothing to wait for.
      return Promise.resolve()
    }
  }
}

dispatch(fetchPostsIfNeeded('reactjs'))

The anonymous function returned by fetchPostsIfNeeded is the titular 'thunk', although this is a misuse of the word - a 'thunk' is necessarily parameterless, since it represents a value that has already been 'thought through' and has no potential for change.

This is where redux starts to show its age. Though it was developed to bring functional concepts to javascript, it existed in a time before static typing with Typescript became popular. Some of its behavior is weird, and the type system has trouble keeping up with it.

Similarly, the type for store is

June 2015

Iterables, Generators Released as Part of ECMAScript 2015 (es6)

es6 saw an expansion on es4's Iterators with Iterables. An Iterable is a generalization of any pull based stream, pulled with the yeild keyword.

Iterables are not necessarily asynchronous: Arrays are Iterables too. This is part of the reason that reactive streams are not part of Functional Reactive Programming (FRP). A stream is by nature a sequence of discrete values, while FRP models continuous values as they relate to continuous time.

May 2015

redux is released

redux comes into being as a way to reconcile Dan Abramov's package react-hot-loader with Facebook's Flux architecture. It is explicitly based on the Elm architecture. It's introduced a couple months later in a popular talk titled "Live React: Hot Reloading with Time Travel"

At the time, Elm used something called a Signal. Signals composed together using a function called foldp:

foldp : (a -> s -> s) -> s -> Signal a -> Signal s

This has three parts: the a -> s -> s is a function that takes an Action 'a' and the current state 's', and returns a new state 's'. The -> s after that represents the initial state. This is all then used convert a signal from its Action to new state.

Abramov, seeing this first part a -> s -> s recognized this as the function signature of es6 reduce. fold, when used on a product type in javascript, is called reduce. This word reduce, is the namesake of the reducer, which has a similar function signature.

The word reducer, combined with Flux, is the namesake of redux. The word 'redux' in English also means 'brought back, or revisited' - presumably, redux brings Flux back into the mainstream (?)

Part of the concept of reducers was that they'd be composable - a classically functional goal to be sure. Given that state is normally represented as a javascript object, each key of the object was to be given it's own reducer

import { combineReducers } from 'redux'

interface AppState {
  user: User
  current: Current
  settings: Settings
}
const userReducer: (u: User | undefined, a: Action) => User = ...
const currentReducer: (c: Current | undefined, a: Action) => Current = ...
const settingsReducer: (s: Settings | undefined, a: Action) => Settings = ...

const reducer: (s: AppState | undefined, a: Action) => AppState = combineReducers({
  user: userReducer,
  current: currentReducer,
  settings: settingsReducer
})

Notice that each sub-reducer can be passed in an undefined state, but must always return a value. This is because, in keeping with the compositionality theme, each reducer is responsible for initializing its own data.

Unintuitively, redux will propagate an action called @@INIT through its reducer to collect this initialized state. In my opinion, this is a design flaw that can lead to unexpected behavior.

Despite all this, redux is a beautiful system. In the talk, redux is framed as bringing functional architecture to the mainstream. To quote:

These are not new things. I did not invent them. Some people will tell you that they existed 30 years ago, and maybe they'll be right, but we'll never find out if nobody talks about bringing cool functional techniques to javascript.

Because if you learn a cool programming language like Elm or Clojurescript, you stay there. It doesn't have to be this way.

You know, you can share your knowledge, please do. Because you can do functional in javascript. You can bring functional programming to the mainstream and do really cool stuff with it.

May 2014

Facebook open-sources Flux

Flux is facebook's implementation of MVC & CQRS on the client side. It's introduced in a talk called "Rethinking Web App Development at Facebook"

May 2013

Facebook open-sources React

In a surprisingly unpopular talk called "JS Apps at Facebook", Jordan Walke introduces react to the public.

Given its name, it seems that react came from 'Functional Reactive Programming'. However, the developers deny this:

The control over scheduling would be harder for us to gain if we let the user directly compose views with a “push” based paradigm common in some variations of Functional Reactive Programming ... There is an internal joke in the team that React should have been called “Schedule” because React does not want to be fully “reactive”.

March 2012

Elm released

Evan Czaplicki's Harvard undergrad thesis, named Elm, is released. The idea is to model a web UI using FRP in an accessible way.

The original paper documents different approaches to FRP & functional UI design through the 2010s. It's interesting to see how the ideas evolved over time.

It's easy to think that react took major inspiration from Elm. Here's a passage in the introduction from Elm's original paper:

Functional reactive programming is a declarative approach to GUI design ... With functional reactive programming, many of the irrelevant details are left to the compiler ... The term declarative is important because most current frameworks for graphical user interfaces are not declarative ... FRP also encourages a greatly simplified approach to graphical layout.

Sound familiar? Here's a quote from the react.js homepage:

React makes it painless to create interactive UIs. Design simple views for each state in your application, and React will efficiently update and render just the right components when your data changes ... Declarative views make your code more predictable and easier to debug.

Even if the name react was never meant to refer to FRP, clearly the ideas here are similar, yet both radical departures from the norm.

It is not clear, however, that react is at all based on Elm, as FaxJS and XHP have been in development for some time by now. I choose to believe that Elm and react were unaware of each other.

The two projects came to denotative design through radically different means: React from syntactic sugar by way of XHP, and Elm through academic rigor by way of frp. Like Hindley-Milner or Leibniz-Newton, the same concept was discovered twice. Phil Wadler, who brought monads into Haskell (building on Eugenio Moggi's work), often speaks of discovery as opposed to invention in mathematics in a similar way.

September 2011

Facebook Releases FaxJS

FaxJS is an early prototype of React.

var MainComponent = exports.MainComponent = F.Componentize({
  structure : function() {
    return Div({
      firstPerson: PersonDisplayer({
        name: 'Joe Johnson', age: 31,
        interests: 'hacking, eating, sleeping'
      }),

      secondPerson: PersonDisplayer({
        name: 'Sally Smith', age: 29,
        interests: 'biking, cooking swiming'
      }),

      thirdPerson: PersonDisplayer({
        name: 'Greg Winston', age: 25,
        interests: 'design and technology'
      })
    });
  }
});

You can see the denotative nature of the component architecture here.

Sometime Early 2010 (?)

Microsoft Releases ReactiveX

ReactiveX, originally developed by Microsoft for their .NET system, models a stream called an Observable and gives it combinators and operations inspired by their own LINQ library. LINQ handles communications with databases. From their homepage:

Rx = Observables + LINQ + Schedulers

(Schedulers also exist in rxjs. They control the nature of the concurrency of an Observable)

Uses the same electric eel logo as the 2007 Microsoft project Volta because they were created by the same team.

Date inferred from here. Earliest doc found here, in June 2011.

February 2010

Facebook Introuces XHP

XHP allows the direct usage of xml inside of php files.

if ($_POST['name']) {
  echo Hello, {$_POST['name']};
} else {
  echo
    <form method="post">
      What is your name?
      <input type="text" name="name" />
      <input type="submit" />
    </form>;
}

This syntactic sugar is the precursor to JSX, whose denoatative nature will eventually make react so powerful.

June 1997

Conal Elliot and Paul Hudak Introduce FRP

At the International Conference on Functional Programming in the Netherlands, Conal Elliot and Paul Hudak introduce their paper titled "Functional Reactive Animation" (Fran for short). This idea will later be renamed Functional Reactive Programming (FRP).

Conal Elliot discusses the difference between FRP vs Reactive Programming in this SO post. FRP is by definition:

(a) denotative
(b) temporally continuous

Elliot also wrote a great post titled Why Program with Continuous Time, which is about pushing compromises to the boundaries of your system.

ReactiveX and FRP are fundamentally at odds: FRP's Behavior is by definition continuous while Observable is by definition discrete. FRP's Behavior is by definition pure (implied by denotative) while Observable is by definition effectful (thus fp-ts-rxjs's fromIO). They both model streams, but in their intentions they are exact opposites.

In the same SO post, Elliot talks about FRP as it relates to rxjs specifically:

As far as I can tell, Rx and Bacon.js lack both of the two fundamental properties on which I based the original FRP. In that sense, they're not what FRP set out to be. Which is fine with me, as I love to see a multitude of abstractions explored. Using a single term to describe them all, however, creates more confusion about what each means and how they differ. I think an accurate description of Rx and Bacon.js is "compositional event systems inspired by FRP".

It's a (really) bad example, but FRP as originally envisioned is closer to React Native's Animated library than to rxjs, Sagas or redux-observable. Continuous time is represented by an Animated.Value, and denotative transformations like Delay and Spring are applied before it's interpolated into actual positions at each frame. It doesn't look much like the Behaviors and Events described in the formal papers, but its continuous nature is closer in spirit than the discrete events output by Observable.

Elliot has said that hearing people refer incorrectly refer to non-FRP systems as FRP is 'heartbreaking for me personally'.

The terms 'Functional Reactive Programming' and 'ReactiveX' are confusingly similar - 'ReactiveX' debatably uses a functional paradigm ('functional' is a poorly defined term), and they're both technically Reactive Programming. They are antonyms masquerading as synonyms!

Ben Lesh (lead maintainer of rxjs) tweeted about this confusion - Elliot's reply:

Then perhaps better to discuss content first and names later.

Late 1980s

Haskell Team Invents & Discards redux observable

From Simon Peyton Jones's "Escape from the Ivory Tower"

A haskell program was simply a program from string to string ... This was a bit embarrassing. So after a bit we thought, maybe instead of producing a string, we'll produce a sequence of commands like "print hello," or "delete this file," which we can execute. So you can imagine, to run the program you call a program passing in some input and you get back a string of commands which some external command execution engine would - the evil operating system - the functional program is very good and pure and produces only a data structure, and the evil side-effecting operating system consumes these commands and executes them.

Well that's not very good if you want to read a file, because if you open a file and want to read it's contents, how does a program get access to it's contents? Ah! Maybe we can apply the function to the result of the evil external thing doing its work. So now there's this sort of loop between the pure functional program and the evil external operating system.

It didn't work very well at all. It was very embarrassing for a number of years.

Eventually, the solution that the Haskell team came to was the IO monad, as described in 1993's Imperative Functional Programming

Sometime 1988

CQS First Described by Bertrand Meyer

Command query responsibility segregation (CQRS) is a continuation of the principle proposed by Bertrand Meyer (1988) called command query separation (CQS)

2014 paper on CQRS

Earliest doc I could find on CQRS is from Greg Young's November 2011 CQRS Documents

Greg Young says CQRS is basically MVC

Jan 1987

Sagas First Described by Garcaa-Molrna and Salem

paper

Sagas relate to CQRS

December 1979

MVC Architecture Introduced by Trygve Reenskaug

paper

Conclusion

From an engineering standpoint, short of implementing an undo history, redux-observable is really a solution in search of a problem - it makes little sense. However, from a historical perspective, redux-observable is the logical conclusion of attempts at a purely functional frontend architecture, achieved by way of streams, CQRS and the Saga pattern. Hopefully it's easier to understand where and when redux-observable is an appropriate solution given a more whole understanding of its history.

I think deep understanding is a common difficulty in programming. React hooks are difficult to understand for many new developers. I would contend that it's easier to understand them if you have experience using setState, and have a concept for react components as fundamentally object-oriented (unfortunately).

However, even given this understanding, it was initially difficult for me to truly wrap my head around hooks. Why are there 'rules' that are impossible to enforce at compile time? Why do we need an entirely separate library to test them? Why is that weird one called useEffect? And how do they actually work?

It helped to learn that react hooks are actually a vastly simplified implementation of algebraic effects. This explains so much to me - hooks are an extreme approximation, so by definition flawed and strange. Indeed, Dan Abramov of the react team has written candidly that for him 'much discussion about algebraic effects is incomprehensible'. I don't mean to advocate against hooks or criticize Abramov - I think some hooks can be super useful, and I don't fully understand algebraic effects either. I only mean to say that a wholesale understanding of hooks and the complexity of its origins helps understand how best to use them (minimally).

The point is that often, mere documentation is not enough. Interfaces are abstractions, and all non-trivial abstractions leak to some degree.

This is true on the backend especially. For example, Apache Kafka is almost impossible to understand without first understanding the solutions that preceded it.

A similar idea is explored in the paper What we Talk About When We Talk About Monads They discuss this in context of monadic solutions that ended up not being useful. The paper posits that programming concepts ought to be thought of across three different levels

... treating monads in a more comprehensive way and considering the formal, implementation and metaphorical level could have prevented the undesirable use of monads

The paper suggests that developers often eschew metaphorical explanations of monads as 'kludges', but such an understanding is crucial and fundamental. I would argue that most redux-observable pedagogy is missing a different level of explanation.

In the spirit of the paper, we might say that the 'implementation' level of understanding redux-observable is its interface - the type signatures for reducer, dispatch, and epic. The 'metaphorical' level is the common understanding of redux-observable as a 'state management' library - something that can help wrangle complex state. These explanations are not incorrect, but they miss the crucial third level - 'formal'.

Formally, redux-observable is a referentially transparent functional architecture - an IO entry point. Its history is edifying because it took the long way to get there (as opposed to something like Elm). Understanding that journey can help understand some of the stranger points about it and some of the documentation and opinion pieces surrounding it.

Should I use redux-observable? Also what is it? Also let's be honest what's redux?

Anthony G — Mon, 19 Oct 2020 04:38:44 +0000

tl;dr

Use redux if you need a global undo function, you need to work with streams, or if referential transparency is important.

What's up with redux?
General Tradeoffs
- redux
- recoil
- react-query
- mobx
What's redux?
What's redux-observable?
Wait What's an Observable?
Ok so what's redux-observable agian?
Advantages of Global State
Sum Type Utility

What's up with redux?

At the time of writing in 2020, redux and redux-observable appear frequently on job descriptions (although more often they ask for experience with redux-saga, which is similar but less powerful). State management is a popular buzzword. What are these things and why would you use them?

Since I consider redux almost useless without redux-observable, I'll refer to them interchangeably through this article, although they are in fact separate.

For simplicity's sake, we'll be talking about redux as it relates to react for this post. react is a goot fit, since redux is meant to model elm, which it does most effectively when paired with react.

General Tradeoffs

redux is not the only popular state management library. Here's an overview of redux as compared to its major alternatives

redux

Pros:

implementing global undo is trivial
natural solution for global event handling (aka routing)
seamlessly integrates with timers, progress indicators, websockets, any kind of "streaming" data source
sophisticated debug system
global state = illegal states become unrepresentable. Reduce or eliminate null checking
nearly total referential transparency
decoupled side effects enable dependency injection which aids testing

Cons:

colocated state is faster (though React.memo can solve this)
colocated state can be simpler to reason about
colocated state is kinda the whole point of react (though you're certainly still allowed to use hooks for textfield input etc)
adding new behavior is cumbersome
applications with many different behaviors can become unwieldy
the debug system is a bit arbitrary unless paired with a hot reloader

recoil

Pros:

variably memoized changes of shared state across deeply nested components
good for projects that render many expensive & memoiz-able components, e.g. spreadsheets or flowcharts

Cons:

no compile time guarantees about application state as a whole

react-query

Pros:

logical separation of "server cache", which models async data as a cache, and "client state", which more directly affectts the ui
polls a server with periodic refetching

Cons:

tight coupling of render logic and fetching logic
no compile-time guarantees about application state as a whole

mobx

Pros:

Cons:

mutable state
run imperative code based on derived state

My general take is that state management is often a solution in search of a problem. redux became popular as a solution to prop drilling, which can now be solved with simple react context. Unless you need some of the benefits outlined above, I would advise against using a state management library at all. react itself is a fantastic state management libary.

Full disclosure: I have zero production experience with any of these besides redux. The rest of the pros and cons are from cursory research, so take them with a big grain of salt. If you have any relevant experience, ideas or corrections please let me know in the comments!

What's redux?

redux models the elm architecture. The application keeps all its state in one object at the root level ('state' in redux, 'model' in elm). All possible state changes are represented as a sum type ('Action'¹ in redux, 'Msg' in elm). There's a function that takes the old state and an action as inputs, and outputs a new state ('reducer' in redux, 'update' in elm)

const reducer: (state: State, action: Action) => State = ...

It's so simple, we can easily implement it ourselves:

import React, { useState } from 'react'

type State = number

enum Action {
  Increment,
  Decrement
}

const reducer = (state: State, action: Action): State => {
  switch(action) {
    case Action.Increment:
      return state + 1
    case Action.Decrement:
      return state - 1
  }
}

const Root = () => {
  const [state, setState] = useState<State>(0)
  const dispatch = (action: Action) => setState(reducer(state, action))
  return (
    <>
      <div>
        Count: {state} 
      </div>
      <button
        onClick={() => dispatch(Action.Increment)}
      >
        +
      </button>
      <button
        onClick={() => dispatch(Action.Decrement)}
      >
        -
      </button>
    </>
  )
}

That's the basic idea!

In react-redux, the root State and the dispatch function are both wrapped in react context so they can be accessed by every component.

While there's a little more to it, this is enough to move on (and enough for ~80% of your work with redux)

What's redux-observable?

What if we need to change the state asynchronously?

type Data = ...
const fetchAsyncData: () => Promise<Data> = ...

const reducer = (state: State, action: Action): State => {
  switch(action.type) {
    case 'FetchData':
      const newState: Promise<State> = fetchAsyncData()
        .then((asyncData: Data): State => ({
          ...state,
          asyncData,
        }))
      return ???
  }
}

We can't return newState because reducers are synchronous. We'll need an async middleware to handle this case. What does that mean?

redux uses middleware, just like express does. This means that you can add additional functionality to your dispatcher. This is how you use the sophisticated debug system I mentioned earlier.

redux-observable is the most powerful async middleware. It combines an Observable with the dispatcher.

Wait What's an Observable?

Observable comes from the library rxjs. It represents a stream of data.

What's a stream? Where Promise represents an asynchronous value with one single output, an Observable represents an asynchronous value with many.

The same way you would model the callback in setTimeout as a Promise, you would model the callback in setInterval as an Observable

import { Observable } from 'rxjs'

const output: Promise<string> = new Promise(res => {
  setTimeout(() => res('output'), 1000)
})
const output$: Observable<string> = new Observable(sub => {
  setInterval(() => sub.next('output'), 1000)
})

output.then(console.log)
// output

output$.subscribe(console.log)
// output
// output
// output
// ...

By convention, we use the '$' character as a suffix for Observable values.

rxjs is powerful because Observable has many combinators and operations

A quick note: like Promise, Observable models unchecked exceptions with optional error handling. If these concepts are unfamiliar, check out my article Either vs Exception Handling. I recommend using an Either type to model errors with more type safety. fp-ts-rxjs provides a great type alias called ObservableEither that's similar to TaskEither for this purpose.

Ok so what's redux-observable agian?

redux-observable adds a function called an Epic, which takes an Observable<Action> and returns an Observable<Action>

const epic: (action$: r.Observable<Action>) => r.Observable<Action> = ...

Let's revisit our earlier example, this time with redux-observable:

import { pipe } from 'fp-ts/pipeable'
import * as r from 'rxjs'
import * as ro from 'rxjs/operators'

interface FetchData { type: 'FetchData' }
interface UpdateData { type: 'UpdateData'; data: Data }
type Action = FetchData | UpdateData

const epic = (action$: r.Observable<Action>): r.Observable<Action> => pipe(
  action$,
  ro.filter((action: Action): action is FetchData => action.type === 'FetchData'),
  ro.map((_: FetchData): Promise<Data> => fetchAsyncData()),
  ro.switchMap((resp: Promise<Data>): r.Observable<Data> => r.from(resp)),
  ro.map((asyncData: Data): Action => ({ type: 'UpdateData', asyncData })),
)

const reducer = (state: State, action: Action): State => {
  switch(action.type) {
    case 'UpdateData':
      return {
        ...state,
        action.data,
      }
    default:
      return state
  }
}

If you're unfamiliar with pipe syntax, check out Ryan Lee's excellent Practical Guide to fp-ts part 1 (the whole series is excellent but part 1 deals specifically with pipe).

This may seem like a complex way to update state asynchronously, and it is. Here's comparable code using vanilla react:

import React, { useState } from 'react'

const AsyncData = () => {
  const [asyncData, setAsyncData] = useState<Data | undefined>(undefined)
  const onClick = () => fetchAsyncData().then(setAsyncData)
  ...
}

Why would we use redux-observable? As I mentioned earlier, Observable has many operators and combinators. We can easily compose multiple streams together. If this was all the functionality we needed, I would say that redux-observable is a bad fit.

What if we also wanted to delete our async data whenever the delete key is pressed? We would simply merge the streams

const epic = (action$: r.Observable<Action>): r.Observable<Action> => pipe(
  r.merge(
    pipe(
      action$,
      ro.filter((action: Action): action is FetchData => action.type === 'FetchData'),
      ro.map((fetchData: FetchData): Promise<Data> => fetchAsyncData()),
      ro.flatMap((promResponse: Promise<Data>): r.Observable<Data> => r.from(promResponse)),
    ),
    pipe(
      r.fromEvent<KeyboardEvent>(window, 'keydown'),
      ro.filter(e => e.which === 8), // 8 is the key code for 'delete'
      ro.map(() => undefined),
    ),
  ),
  ro.map((asyncData: Data): Action => ({ type: 'UpdateData', asyncData })),
)

redux-observable is great for global event handling because we have access to the global state. Here, we're able to keep our code naturally DRY because our FetchData action and our key event both trigger the UpdateData action.

Anyway, it always feels wrong to add an event handler like this to some componentDidMount function. Why would we wait for a component to mount to start handling the event? What does a key press have to do with a component at all? redux-observable provides a more natural place for this.

Here's the full code, in case you want to see how to properly set up the redux-observable middleware.

Advantages of Global State

Like elm, redux manages global state. There are well-documented disadvantages to using global state.

However, whether or not you end up using redux, global state is often the best way to model data. It has a major advantage often overlooked: type safety.

Let's say we need to implement authentication in a web app. Certain routes and data can only be accessed after we've been logged in. Here's how that might look with vanilla react:

import { Route } from 'react-router-dom'

interface AppState {
  user?: User
  data?: SecureData
}

const Routes = ({ state }: { state: AppState }) => (
  <>
    <Route
      path="/authenticated"
    >
      <Authenticated
        user={state.user}
        data={state.data}
      />
    </Route>
    <Route
      path="/unauthenticated"
    >
      <Unauthenticated/>
    </Route>
  </>
)

We have a few potential errors here:

What do we display we're at '/authenticated' but we have no user or no data?
What if we have a user but no data, or vice versa?

We could solve this with null checking.

const Routes = ({ state }: { state: AppState }) => (
  <>
    <Route
      path="/authenticated"
    >
      {state.user && state.data && (
        <Authenticated
          user={state.user}
          data={state.data}
        />
      )}
    </Route>
    <Route
      path="/unauthenticated"
    >
      <Unauthenticated/>
    </Route>
  </>
)

This is a bad solution. What if we have no user or data and we're at the /authenticated route? This should never be possible, but at compile time it could be. We have introduced a possible error that exists solely due to a weakness in our system.

We can fix all of this using a sum type:

interface Authenticated {
  type: 'Authenticated'
  user: User
  data: SecureData
}
interface Unauthenticated { type: 'Unuthenticated' }
type AppState = Authenticated | Unauthenticated

const Routes = ({ state }: { state: AppState }) => {
  switch(state.type) {
    case 'Authenticated':
      return (
        <Authenticated
          user={state.user}
          data={state.data}
        />
      )
    case 'Unauthenticated':
      return (
        <Unauthenticated/>
      )
  }
}

We know at compile time that we can't display our 'authenticated' route unless we have both a User and SecureData. We can't misspell or forget to handle our routes due to compile-time exhaustiveness checking.

Illegal states are unrepresentable. Errors are pushed to the boundaries of the system. This is the meaning of the mantra "parse, don't validate"

Routing is a great example of event handling that redux-observable handles well.

const epic = (action$: r.Observable<Action>): r.Observable<Action> => pipe(
  r.fromEvent(window, 'popstate'),
  ro.map(() => window.location.href),
  ro.flatMap((route: string): Observable<Authenticated | undefined> => {
    switch(route) {
      case '/authenticated':
        return r.from(loadUserAndData())
      default:
        return r.from({ type: 'Unauthenticated' })
    }
  }),
  ro.map((appState: AppState): Action => ({
    type: 'SetAppState',
    appState,
  }))
)

For more on parsing a route string to a sum type, check out my fp-ts-routing tutorial.

Sum Type Utility

@morphic-ts/adt is a great library that provides predicates and a reducer for free.

Let's check out an earlier example with a morphic upgrade:

import { makeADT, ofType, ADTType } from '@morphic-ts/adt'

interface FetchData { type: 'FetchData' }
interface UpdateData { type: 'UpdateData'; data: Data }
const Action = makeADT('type')({
  FetchData: ofType<FetchData>(),
  UpdateData: ofType<UpdateData>()
})
type Action = ADTType<typeof Action>

const epic = (action$: r.Observable<Action>): r.Observable<Action> => pipe(
  action$,
  ro.filter(Action.is.FetchData),
  ro.map((action: FetchData) => ...),
)

const defaultState: AppState = ...
const reducer = Action.createPartialReducer(defaultState)({
    UpdateData: (action: Action) => (state: AppState) => ...,
})

// there's also a curried pattern match
const AppState = makeADT('type')(...)
type AppState = ADTType<typeof AppState>
const Routes = ({ state }: { state: AppState }) => AppState.matchStrict({
  Authenticated: ({ user, data }) => (
    <Authenticated
      user={user}
      data={data}
    />
  ),
  Unauthenticated: () => (
    <Unauthenticated/>
  )
})(state)

This replaces typesafe-actions, redux-actions, and ofType in both ngrx and redux-observable by solving the more general problem of sum types.

Conclusion

redux-observable is a powerful framework. It effectively decouples the ui of a project from it's behaviors, and guides it toward a more functional style. Though tangibly it mostly just helps implement undo & testing, it has benefits beyond that.

I like to use it if I'm working with streams or a lot of event handling. This is because I know that, especially if I need to mock out certain behaviors for testing, I will eventually end up architecting the project using something similar to redux-observable anyway.

The framework itself is extremely simple and minimal. I use it less for its functionality than for its name - it tells incoming developers a lot about how the project is structured just by reading through its dependencies in package.json.

redux-observable can also be used to bring a pure functional framework to react. For more on how redux-observable can be used as an IO entry point, check out my article about it. For more on the history of frontend functional frameworks, check out my article Why is redux-observable like that?

Hopefully this article gives a deep enough overview to decide whether or not redux and redux-observable is right for you!

This example's a bit misleading. We can't use enum with redux because Action has to be an object conforming to this interface: interface Action<T> { type: T } ↩

enum can't conform to that, since it's represented with number values. I used enum for our example simply because I imagine more devs are familiar with enum than with 'sum type' or 'union type', which are mostly the same thing.

fp-ts and Even More Beautiful API Calls (w/ sum types!)

Anthony G — Mon, 19 Oct 2020 04:37:14 +0000

The Prompt
Union types to the rescue!
- Benefits
Unions of Complex Types - Sum Types
Even more features with @morphic-ts/adt
- Other advantages of @morphic-ts/adt
Is it Actually Boilerplate
How far we've come
Conclusion

The Prompt

Let's build on the application outlined in fp-ts and Beautiful API Calls (a lovely application to be sure).

We want to be able to customize error messages based on their source:

const handleErrors = (error: Error): T.Task<string> => {
  const message: string = ...
  if (/* error is from parsing */) {
    return T.of(`Parse error: ${message}`)
  } else if (/* error is from networking */) {
    return T.of(`Network error: ${message}`)
  }
}
const runProgram = pipe(
  sequenceT(TE.taskEither)(
    getAnswer, 
    getFromUrl(apiUrl(1), users), 
    getFromUrl(apiUrl(2), users)
  ),
  TE.fold(
    handleErrors,
    ([ans, users1, users2]) => T.of(
      smashUsersTogether(users1, users2).join(", ") 
        + `\nThe answer was ${ans.ans} for all of you`
    ),
  )
)();

As it stands, implementing handleErrors is difficult, since its input is of type Error. This means that we'll have to parse the string at error.message.

const handleErrors = (error: Error): T.Task<string> => {
  const message: string = ...
  if (error.message.includes('parse')) {
    return T.of(`Parse error: ${message}`)
  } else if (error.message.includes('network')) {
    return T.of(`Network error: ${message}`)
  }
  return T.of('can never happen')
}

This is a brittle solution. What if we forget to handle a case or misspell something? And why should we have to handle a case that can never happen?

Union types to the rescue!

const enum ErrorType {
  Network,
  Parse,
}
interface AppError {
  type: ErrorType
  message: string
}

Here, ErrorType is a union type. A union type encodes an 'or' relationship, meaning that an ErrorType is either Network or Parse, but never both. Right now we're using a simple typescript enumerator to implement our union type, but there are other ways of doing it¹.

We'll need to rewrite our networking code to conform to our new AppError interface:

const decodeWith = <A>(decoder: t.Decoder<unknown, A>) =>
  flow(
    decoder.decode,
    E.mapLeft((errors): AppError => ({
      type: ErrorType.Parse,
      message: failure(errors).join('\n')
    })),
    TE.fromEither
  )

const getFromUrl = <A>(url:string, codec:t.Decoder<unknown, A>) => pipe(
  httpGet(url),
  TE.map(x => x.data),
  TE.mapLeft(({ message }): AppError => ({ type: ErrorType.Network, message })),
  TE.chain(decodeWith(codec))
);

Now implementing handleErrors is a breeze!

const handleErrors = (appError: AppError): T.Task<string> => {
  switch(appError.type) {
    case ErrorType.Network:
      return T.of(`Network error: ${appError.message}`)
    case ErrorType.Parse:
      return T.of(`Parse error: ${appError.message}`)
  }
}

Benefits

We get autocompletion when we type in ErrorType. - our IDE recommends ErrorType.Network and ErrorType.Parse to us.

Furthermore, we get an exhaustiveness check from the switch statement, so this won't compile:

const handleErrors = (appError: AppError): T.Task<string> => {
  switch(appError.type) {
    case ErrorType.Network:
      return T.of(`Network error: ${appError.message}`)
  }
}
// Function lacks ending return statement and return type does not include 'undefined'.

Like anything that adds type-safety, ErrorType helps you make a visible contract for yourself up front and hold yourself to it later on.

Unions of Complex Types - Sum Types

What if we want to display the first three lines of our ErrorType.Parse errors to the user, and log the full error for the developer?

We need an AppError type that can handle both situations.

interface AppError {
  type: ErrorType
  message: string
  firstThreeLines: string | undefined
}

This isn't a great solution. We have duplicate data all over the place. firstThreeLines is just the first three lines of message, and a value of undefined for firstThreeLines is the same as a value of ErrorType.Network for type. There is no SSOT.

It would be simplest if we could keep track of the original t.Errors value returned by io-ts

interface AppError {
  type: ErrorType
  message: string | t.Errors
}

This works, but we'll have to do an ugly typeof check to determine what message is. And once again we have duplicate data: if our message is a string, our type should never be ErrorType.Parse. Our metadata is duplicated. We can do bad stuff like this:

const absurdError: AppError = {
  type: ErrorType.Parse,
  message: 'not an io-ts error' // we can have a 'string' here!
}

Is there a way to prevent these potential mistakes at compile time?

Let's ditch ErrorType and try something radical.

interface NetworkError  {
  type: 'NetworkError'
  message: string
}
interface ParseError {
  type: 'ParseError'
  errors: t.Errors
}
type AppError = NetworkError | ParseError

How does this make our code look?

const handleErrors = (appError: AppError): T.Task<string> => {
  switch(appError.type) {
    case 'NetworkError':
      return T.of(`Network error: ${appError.message}`)
    case 'ParseError':
      return pipe(
        appError.errors,
        failure,
        A.takeLeft(3),
        a => a.join('\n'),
        T.of
      )
  }
}

Like magic, Typescript can infer which data our appError contains depending on which case is being handled. Calling appError.errors outside the scope of case 'ParseError': would be an error, but inside the scope it typechecks.

This is called a tagged union type, or a sum type². Here, our tag is type.

And we have the flexibility to handle ParseErrors differently in different cases:

const logAllParseErrors = (appError: AppError): void => {
  if (appError.type === 'ParseError') {
    console.error(failure(appError.errors).join('\n'))
  }
}

The underlying upgrade here is that AppError is now able to contain completely different data depending on which case it represents.

Even more features with `@morphic-ts/adt`³

If we don't like the switch statement's statement-oriented appearance, we can get a more expression-oriented appearance using matchStrict from @morphic-ts/adt

import { makeADT, ofType, ADT, ADTType } from '@morphic-ts/adt'

// little bit of boilerplate here
const AppError: ADT<NetworkError | ParseError, "type"> = makeADT('type')({
  NetworkError: ofType<NetworkError>(),
  ParseError: ofType<ParseError>(),
})
type AppError = ADTType<typeof AppError>

const handleErrors = AppError.matchStrict<T.Task<string>>({
  NetworkError: ({ message }) => T.of(`Network error: ${message}`),
  ParseError: ({ errors }) => pipe(
    errors,
    failure,
    A.takeLeft(3),
    a => a.join('\n'),
    T.of
  ),
})

makeADT's first parameter is our tagged union's 'tag'. For this example, our tag is 'type'.

You might also notice that we have two entities called AppError: a const and a type. The const is morphic's magical ADT value that gives us fancy type-safe operations like matchStrict. The compiler is able to infer from context which of the two AppError entities to use, and you only have to export & import AppError once to be able to use both entities.

We also get a nice constructor syntax:

const decodeWith = <A>(decoder: t.Decoder<unknown, A>) =>
  flow(
    decoder.decode,
    E.mapLeft((errors) => AppError.of.ParseError({ errors })),
    TE.fromEither
  )
const getFromUrl = <A>(url:string, codec:t.Decoder<unknown, A>) => pipe(
  httpGet(url),
  TE.map(x => x.data),
  TE.mapLeft(({ message }) => AppError.of.NetworkError({ message })),
  TE.chain(decodeWith(codec))
);

In my experience, the curried pattern match provided by matchStrict makes the @morphic-ts/adt boilerplate worth it for most sum types.

Other advantages of `@morphic-ts/adt`

We get many features for free:

type predicates

const error: AppError = ...
let message: string = 'default'
if (AppError.is.NetworkError(error)) {
  // the type is narrowed, so we have access to `message`
  message = error.message
}
// or
import * as O from 'fp-ts/Option'

const message = pipe(
  error,
  O.fromPredicate(AppError.is.NetworkError),
  O.map(e => e.message),
  O.getOrElse(() => 'default'),
)

lenses

// add data to the cases
interface NetworkError {
  type: 'NetworkError'
  message: string
  metaData: {
    errorID: number
  }
}
interface ParseError {
  type: 'ParseError'
  errors: t.Errors
  errorID: number
}

// ...

import * as M from 'monocle-ts'

const errorIDLens: (a: AppError) => number = AppError.matchLens({
  NetworkError: M.Lens.fromPath<NetworkError>()(['metaData', 'errorID']),
  ParseError: M.Lens.fromProp<ParseError>()('errorID'),
})

const error: AppError = ...
const errorID: number = errorIDLens.get(error)

unionADT

interface NoEndpoint ...
interface BadRequestBody ...
interface DatabaseError ...
interface ParseError ...

const NetworkError = makeADT('type')({
  NoEndpoint: ofType<NoEndpoint>(),
  BadRequestBody: ofType<BadRequestBody>(),
  DatabaseError: ofType<DatabaseError>(),
})
type NetworkError = ADTType<typeof NetworkError>

const AppError = unionADT([
  NetworkError,
  makeADT('type')({
    ParseError: ofType<ParseError>(),
  }),
])
type AppError = ADTType<typeof AppError>

exclude

const AppError = makeADT('type')({
  NoEndpoint: ofType<NoEndpoint>(),
  BadRequestBody: ofType<BadRequestBody>(),
  DatabaseError: ofType<DatabaseError>(),
  ParseError: ofType<ParseError>(),
})
type AppError = ADTType<typeof AppError>

const NetworkError = AppError.exclude(['ParseError'])
type NetworkError = ADTType<typeof NetworkError>

select

const NetworkError = AppError.select(['NoEndpoint', 'BadRequestBody', 'DatabaseError'])

default match case

// type widening as well
// handles multiple different return types
const matcher: (a: AppError) => string | number = AppError.match(
  {
    NoEndpoint: ({ endpoint }) => `bad endpoint: ${endpoint}`,
    BadRequestBody: () => 3,
  },
  () => 'other'
)
const error: AppError = ...
const result: string | number = matcher(error)

Verification (narrowing to a subset)

const error: AppError = ...
const a: string = pipe(
  error as NetworkError,
  O.fromPredicate(NetworkError.verified),
  O.map((networkError: NetworkError) => {
    ...
  })
)

The added boilerplate is unfortunate but minimal, and the generated ADT type is powerful. More powerful even than sum type manipulation in Haskell: The equivalent of matchLens requires a Haskell language extension.

Additionally, morphic can solve many of the problems outlined in Matt Parsons's wonderful The Trouble with Typed Errors.

To oversimplify, Parsons makes the correct point that monolithic error types are bad. With morphic, you can:

keep your types small with select or unionADT
pass errors upstream with validate

Is it Actually Boilerplate

Functions like getFromUrl and decodeWith can seem like boilerplate. Shouldn't every application have to write something like this? Surely there must be existing npm packages out there that do this type of thing for you.

There are several out there (like fetch-ts, fp-fetch, & react-fetchable). My current favorite is appy because it accurately models javascript's fetch and composes nicely with io-ts. However, though I normally discourage re-inventing the wheel, I often prefer to write this kind of code on my own.

Most of the work in converting Promise into TaskEither is in deciding how granular your Error type needs to be. This is necessarily tied to each individual project's requirements. Some projects might be simple enough to display an "Error, please try again" message for everything, while some might need to log each error's http status code. It's also worth mentioning that axios has different mocking capabilities than fetch and might not always be appropriate for every project.

How far we've come

Here's a naive implementation of the original program, without type safety (it's a one liner):

const runProgram2 = Promise.all([
  Promise.resolve({ ans: 42 }),
  fetch('https://reqres.in/api/users?page=1').then(a => a.json()),
  fetch('https://reqres.in/api/users?page=2').then(a => a.json()),
]).then(([ans, users1, users2]) =>
  [...users1.data, ...users2.dat]
    .map(item => item.firstName)
    .join(', ')
  + `\nThe answer was ${ans.ans} for all of you`
).catch(error => error.message
  .startsWith('Cannot read property')
    ? console.error('Parse error')
    : console.error('Network error')
})

I must admit, the naive solution is attractive in its simplicity. We didn't even have to import anything. We could have saved some time writing the code like this instead.

What's better about our earlier type-safe solution?

Due to the use of the any type, there are typos in the above code that the compiler wouldn't catch
We aren't relying on the nuances of runtime error messages
We're able to output specific parsing errors
we can differentiate errors at compile time with exactly the granularity we want
our function signatures tells us which specific errors must be handled
we get compile time errors if we fail to handle every case
autocompletion every step of the way

Conclusion

Sum types are worth learning about! They have many applications on the frontend alone:

routing (check out my article!)
loading indicators
radio buttons
representing a day of the week
representing logged in vs anonymous users
redux actions (morphic even provides createReducer)
etc.

And many types you may already know - boolean⁴, Option, Either, These - are sum types. The concept of a sum type (or tagged union) is a fundamental concept in data modeling (and math).

So even if you decide your application's error handling is simple enough that you don't want the added complexity, in the future you'll know how to model 'or' relationships between complex data at the type level.

If you're interested in learning more, here's a comprehensive article by Gabriel Lebec (warning: paywall).

Under the hood, Typescript enum actually maps each case to a number, so this is valid: ↩

const error: ErrorType = 3

Be careful of this! This can lead to unexpected behavior.

They are actually quite flexible in this regard, which makes them less referentially transparent.

In practice, sometimes I prefer to use a union type of string literals to increase referential transparency, although this can be a little less legible.
The name 'sum type' refers to the number of possibilities it can represent. They exist in contrast to product types (e.g. Typescript interfaces and tuples) (they are mathematical duals). Take the following example: ↩

type Vehicle = 'Car' | 'Motorcycle' | 'Truck'
type Color = 'Yellow' | 'Red' | 'Blue'
type BirthdayPartyTheme = Vehicle | Color
interface Ride { wheels: Vehicle; style: Color }

What if we wanted to find out how many different possible BirthdayPartyThemes there are?

A BirthdayPartyTheme can either be a Vehicle or a Color. We would add the number of possible Vehicles to the number of possible Colors.

3 + 3 = 6

How about the number of different possible Rides?

A Ride must have both a Vehicle and a Color. We would multiply the terms instead.

3 * 3 = 9

This is why BirthdayPartyTheme is called a sum type and Ride is called a product type - 'sum' refers to addition and 'product' refers to multiplication.

In fact, both Vehicle and Color are sum types as well.

1 + 1 + 1 = 3

What's counterintuitive is that a Yellow themed birthday party can actually be a lot of fun.
The 'adt' in @morphic-ts/adt stands for 'Algebraic Data Type'. morphic uses the term a bit differently than it's classical definition. ↩

According to wikipedia,

an algebraic data type is a kind of composite type, i.e., a type formed by combining other types

The term is often used in programming to refer to either product types (see above) or sum types, although pi types and sigma types are also technically ADTs (they rely on dependent types which is a whole other can of worms).

In morphic, 'ADT' always refers to sum types.
boolean is technically a union type not a sum type, but it's functionally a sum type. ↩

Either vs Exception Handling

Anthony G — Mon, 19 Oct 2020 04:32:21 +0000

tl;dr

Either solves the problems presented by Exception Handling by adding power and flexibility.

Why use Either
Unchecked Exceptions
- Either Provides Types and Compile Time Safety
Checked Exceptions
Unwanted Information
- Either Can Eject Unneeded Info
Similarity to goto
- Expression Oriented Control Flow
Difficulty with Callbacks
- Streams
- Progression
Other Benefits of Either
- Compositionality
- Validations
Either Drawbacks and Pitfalls
- Leaky abstraction
- Pokemon Anti Pattern
- 'Stringly-typed error handling'
- Solution: Union Types
Conclusion

Why use Either

Why does Task represent both its failure and success cases in data with Either? It seems a bit arbitrary to invent a data type that just represents one thing or another. How did we get here?

Before Either became a common pattern, errors were mainly managed with exception handling. The flaws inherent to exception handling are well documented. In my research, I found that many critical articles pointed to the same few problems.

I've compiled code samples illustrating these problems and alternative code samples showing how Either solves them.

Unchecked Exceptions

Javascript implements exception handling. You've probably seen this kind of thing (adapted from this Joe Fallon article)

let resource: ExampleResource | undefined = undefined;
try {
  resource = new ExampleResource();
  const opened: number = resource.open();
  // use the resource...
} catch (e: any) {
  if (e instanceof Error) {
    // handle error if possible
  } else {
    throw e;
  }
} finally {
  if (resource) {
    resource.close();
  }
}

Javascript exceptions are unchecked. This means that the errors are of the any type (something we normally want to avoid). It also means that exception handling is optional. It's perfectly legal to ignore the possibility of an exception:

const resource = new ExampleResource();
resource.open();
// use the resource...
resource.close();

This is a problem. Users of ExampleResource have no way of knowing whether it could throw an exception other than reading its documentation (assuming it has documentation). They could be in for a surprise runtime error.

`Either` Provides Types and Compile Time Safety

Here's the same problem, solved with Either

interface ExampleResource {
  open: () => E.Either<string, number>
  close: () => void
}

const getExampleResource = (): E.Either<string, ExampleResource> => ...

const handleResource = (): void => pipe(
  getExampleResource(),
  E.chain((resource: ExampleResource) => {
    const result: E.Either<string, number> = pipe(
      resource.open(),
      E.map((opened: number) => {
        // use the resource ...
      })
    )
    resource.close()
    return result
  }),
  E.fold(
    console.error,
    console.log,
  ),
)

The error type is preserved in the type signature Either<string, number> You can see at compile time exactly what can go wrong. No more any types. You are encouraged to deal with the possible errors by the data structure of Either.

Checked Exceptions

Languages that were designed before Either became popular tried to solve this problem by using checked exceptions. We'll use Java for these examples since it was the first mainstream language to implement checked exceptions and remains the canonical example of them.

If a method throws an error, you're forced at compile time to surround it in a try/catch block, or to propagate it yourself.

public void useResource() {
  ExampleResource resource;
  try {
    resource = new ExampleResource();
    resource.open();
    // use the resource...
  } catch (e: IOException) {
     // handle error
  } finally {
    if (resource != null) {
      resource.close();
    }
  }
}

Neglecting an exception is a compile time error:

public void useResource() {
  // Unhandled exception: java.io.IOException
  ExampleResource resource = new ExampleResource();
}

If useResource shouldn't handle the exception, you can choose to propagate it instead using throws

public void useResource() throws IOException {
  ExampleResource resource = new ExampleResource();
}

Checked exceptions are a step in the right direction. They give exceptions type inference and compile-time safety.

However, this approach has a few drawbacks.

Unwanted Information

Although checked exceptions have the advantage of type-safety, often that information is unwanted boilerplate.

catch (IOException e) {
  // 'e' is ignored
  Dialog.alert("Crash when opening resource")
}

This can actually be harmful, as in the case where a low-level method throws a new exception, causing a chain of callers that are now broken at compile time. (Image taken from Checked Exceptions are Evil)

Bill Venners asked Anders Hejlsberg (who would go on to co--found Typescript) about this problem in an interview for artima.com:

Venners: But aren't you breaking their code [by throwing a new exception] anyway?

Hejlsberg: ...No, because in a lot of cases, people don't care. They're not going to handle any of these exceptions. There's a bottom level exception handler around their message loop. That handler is just going to bring up a dialog that says what went wrong and continue.

The programmers protect their code by writing try finally's everywhere, so they'll back out correctly if an exception occurs ... You make sure you protect yourself all the way out by deallocating any resources you've grabbed, and so forth.

...You don't want a program where in 100 different places you handle exceptions and pop up error dialogs. What if you want to change the way you put up that dialog box? That's just terrible. The exception handling should be centralized, and you should just protect yourself as the exceptions propagate out to the handler.

Either Can Eject Unneeded Info

This problem is easily solved by converting Either into Option

const withError: E.Either<string, number> = ...
const errorDoesntMatter: O.Option<number> = pipe(
  withError,
  O.fromEither,
)

Similarity to goto

Cunningham also notes in Don't Use Exceptions for Control Flow that they can be used as a kind of goto statement (goto is considered harmful). Here is his example:

public void search(TreeNode node, Object data) throws ResultException {
  if (node.data.equals(data)) {
    throw new ResultException(node);
  } else {
    search(node.leftChild, data);
    search(node.rightChild, data);
  }
}

The cute trick here is that the exception will break out of the recursion in one step no matter how deep it has got...This makes it harder for programmers to read.

Expression Oriented Control Flow

Since in the above example exception is actually being used to represent optionality, in this case it's actually best replaced by Option

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

interface TreeNode<D> {
  data: D
  leftChild: O.Option<TreeNode<D>>
  rightChild: O.Option<TreeNode<D>>
}
const search = <D>(data: D) => (node: TreeNode<D>): O.Option<TreeNode<D>> => pipe(
  node,
  O.fromPredicate(node => node.data === data),
  O.alt(() => pipe(
    node.leftChild,
    O.chain(search(data)),
  )),
  O.alt(() => pipe(
    node.rightChild,
    O.chain(search(data)),
  )),
)

// we can convert `Option` into `Either` (if we want to)
const searchEither = <D>(data: D) => (node: TreeNode<D>): E.Either<string, TreeNode<D>> => pipe(
  search(data)(node),
  E.fromOption(() => 'data not found'),
)

This is an example of expression-oriented programming, as opposed to the Java example which is statement-oriented.

According to Alvin Alexander:

Statements do not return results and are executed solely for their side effects, while expressions always return a result and often do not have side effects at all.

This makes the code easier to read and to reason about, because each operation is labelled and does exactly what it seems like it does.

Even though this code is a one-liner, reading through it we get a sense of things happening one after another. In this sense, alt and chain can be thought of as programmable semicolons: they are sequential in nature.

Difficulty with Callbacks

Here is an example adapted from Ward Cunningham's The Problem with Checked Exceptions

interface Procedure { public void call(); }
abstract class Context {
  public static callWithContext(Procedure proc);
}
...
Context.callWithContext(new Procedure () {
  public void call() {
    InputStream is = ...
    is.read(); // what if `read` throws an exception?
  }
});

How should we handle this? We can't throw the error because Context doesn't know how to handle it. We could put a try/catch block in our implementation of call, but this often isn't ideal - exceptions are often handled similarly across many different situations (e.g. an error dialog box) so this approach could lead to duplicate code.

Duncan McGregor notes that Java-style checked exceptions don't integrate well with inline (lambda) or higher-order functions. The previous example is essentially a different statement of the same problem.

Streams

A callback like this can often be replaced with a data structure called a Stream. Two common kinds of stream in Typescript are generators and rxjs Observables¹. Here, we'll use Observable.

The advantage of streams is that they compose together easily. Used in confluence with Either, this solves our above problem - we're able to compose together several streams of error-prone operations, DRY-ly handling all errors in the same place.

import { pipe } from 'fp-ts/pipeable'
import * as E from 'fp-ts/Either'
import * as r from 'rxjs'
import * as ro from 'rxjs/operators'

const numberOutput: O.Observable<Either<string, number>> = new r.Observable((subscriber) => {
  Context.callWithContext(() => {
    const err: E.Either<string, number> = readNumber()
    subscriber.next(err)
  })
})
const otherOutput: O.Observable<Either<string, number>> = ...

// unified errors & successes
const combineStreams: r.Observable<void> = pipe(
  r.merge(numberOutput, otherOutput),
  ro.map(E.fold(
    console.error,
    console.log
  )),
)

Progression

The oversimplified history of exception handling went like this (modified from from Duncan McGregor's Failure is not an Option):

Early APIs returned error codes or set global error flags, but it was easy to forget to check these.
[C++-style] Exceptions were introduced [debatably in Algol 68] to force explicit error handling, but it was still hard to know if a function could fail in practice.
Checked exceptions were introduced [in Java] to make expected failure conditions more explicit.
Checked exceptions [have problems], go back 2 spaces [Unchecked exceptions in C# (kinda), Ruby, Python, Scala, Kotlin, Haskell].

Other Benefits of Either

Compositionality

Not all errors come from the same place - for example, there are validation errors that come from email address input, selecting an invalid date for a person's birthday, or of course, asynchronous failures. Either composes quite nicely no matter where the error came from.


const asyncOp: TE.TaskEither<string, Response> = TE.tryCatch(
  fetch('http://google.com'),
  E.toError
)
const syncOp: E.Either<string, number> = validateEmail(...)

const output = pipe(
  asyncOp,
  T.map(resp => pipe(
    sequenceT(E.either)(
      resp,
      syncOp,
    ),
    E.fold(
      console.error,
      ([resp, validated]: [Response, string]) => {
        // use values safely
      }
    ),
  )),
)

Validations

Either only represents one kind of control flow - a series of operations that short-circuit when any one of them fails. What if we want to continue past an individual failure and collect many possible errors?

Validation is the solution - read more about it here

Either Drawbacks and Pitfalls

Leaky abstraction

In his wonderful article on F#, You're better off using Exceptions, Eirik Tsarpalis argues that Either is a leaky abstraction in a language with unchecked exceptions. Since any operation could fail at any time, we can never ensure full coverage.

Indeed, even a rigid language like Haskell that boasts of referential transparency uses unchecked exceptions. They are an ever-present threat.

And necessarily so. At their most useful, exceptions represent errors that are unexpected, like division by zero or array index out of bounds. Well written code avoids these cases, but of course they are often possible and must be accounted for.

Pokemon Anti Pattern

Tsarpalis writes about this in context of the pokemon anti-pattern, named after the catchphrase "Gotta Catch 'em All"

const simpleArithmetic: (nums: number[]) => number = ...

// since any operation could fail, everything becomes an `Either`
const avg: E.Either<string, number> = E.tryCatch(
  () => simpleArithmetic(nums),
  E.toError
) // gotta catch em all!

This is a problem, since it becomes increasingly difficult to handle errors properly when everything is a potential error.

'Stringly-typed error handling'

Tsarpalis mentions another common anti-pattern - "stringly typed" error handling, a pun on "strongly typed". The pattern is every error sharing the same type: string. This is a problem because differentiating between different kinds of errors based on string comparison becomes messy and fragile.

const operation: E.Either<string, number> = ...
const output = pipe(
  operation,
  E.mapLeft((error: string) => {
    if (error.startsWith('Cannot read property')) {
      console.error('Parse error')
    } else {
      console.error('Other error')
    }
  })
)

In this example, we're relying on our error to start with the exactly correct string. This is messy because different errors might share this attribute, and it's fragile because there might be typos. We also have no compile time guarantees that every possible error has been handled.

The examples in this article so far have used this anti-pattern only for the sake of simplicity. I don't recommend using string to represent errors

Using the Error type provided by Typescript leads to the same problems, since often the only relevant information is stored in message, a string. This is of course also a problem with exception handling, except it's worse because we have an any type instead of string.

You can solve all of these problems by representing your errors with union types instead.

Solution: Union Types

With a union type, you decide ahead of time which errors you care about, and you're able to easily simulate a pattern match using a switch statement.

const enum ErrorType {
  Parse,
  Other,
}

const operation: E.Either<ErrorType, number> = ...
const output = pipe(
  operation,
  E.mapLeft((error: ErrorType) => {
    switch (error) {
      case ErrorType.Parse:
        console.error('Parse error')
        break;
      case ErrorType.Other:
        console.error('Other error')
        break;
    }
  })
)

This way, we're able to choose exactly what granularity we want to handle errors with, and hold ourselves to that later. This is better than stringly-typed errors because we're able to easily differentiate between errors at compile time. If we use a sum type library like @morphic-ts/adt, we get a more strict pattern match with exhaustiveness checking to ensure that we've handled every case.

I've written more extensively about about using sum types and @morphic-ts/adt here, and about the difference between union types and sum types here.

Conclusion

Phil Hauer makes the point in Checked Exceptions are Evil that if we're just logging an error and exiting, it's actually more informative to fail at runtime because we have the added benefit of the printed call stack.

Sometimes there's wisdom in forgoing a more comprehensive yet flawed solution. However, rather than throwing the baby out with the bathwater, Either solves all of the specific problems I could find for exceptions, both unchecked and checked.

I would argue that the advantages of Either outweigh the pain of uncertainty. Every non-trivial abstraction leaks, and I think Either is still better than its alternatives.

This is a common refrain when adopting functional paradigms. Since complete purity is basically unattainable, past what point is it worth striving for anyway? In the case of Either, I think almost always.

However, since they are by definition a compile-time solution they cannot take the place of unexpected runtime exception handling. Hopefully the arguments listed above can help explain the resurgence of unchecked exception handling and its benefits.

rxjs is generally used for pushing changes, while generators are used for pulling them. Generators are better for handling backpressure. source ↩

Why is fp-ts Option like that?

Anthony G — Mon, 19 Oct 2020 04:30:01 +0000

tl;dr

Option contains more data when nested than traditional nullable values do.

The problem
Something Option can do that Nullable Can't
- undefined can't nest
- Option saves the day!
- Metadata and Data: Sum Types vs Union Typs
Set Theory
Category Theory
Conclusion

The problem

Option is nice - it's got a monad instance and pipeable helper functions and all that - but it can be inconvenient when you have to also work with null or undefined.

With the Array and Record helper functions & typeclass instances, I'm able to simply input and output standard Typescript Array and Record types:

import * as A from 'fp-ts/Array'
import * as R from 'fp-ts/Record'
import { pipe } from 'fp-ts/pipeable'

const arr: number[] = pipe(
  [1, 2, 3],
  A.map(n => n * 2),
)
const rec: Record<string, number> = pipe(
  {a: 1, b: 2, c: 3},
  R.map(n => n * 2),
)

Option represents a similarly common pattern (nullables), but I have to convert nullable values using O.fromNullable and back again using O.toUndefined:

import * as O from 'fp-ts/Option'
const nullablenum: number | undefined = ...
const opt: number | undefined = pipe(
  nullablenum,
  O.fromNullable,
  O.map(n => n * 2),
  O.toUndefined
)

If you're interested in whether to use 'Nullable' or Option, check out my companion article, Should I Use fp-ts Option

But why do we have to choose? Why isn't Option just defined as type Option<A> = A | undefined? It's trivial to implement a monad instance for that type:

import { identity } from 'fp-ts/function'

type Option<A> = A | undefined
export const OptionMonad = {
  of: identity,
  chain: <A, B>(fa: Option<A>, f: (a: A) => Option<B>): Option<B> => fa !== undefined ? f(fa) : undefined,
}

What gives? Wouldn't that make life much easier? Isn't O.none the same thing as undefined anyway?

Something `Option` can do that `Nullable` Can't

Consider this contrived example:

const firstTerm: number | undefined = 3
const secondTerm: number | undefined = undefined
const sum: number | undefined = firstTerm
  ? secondTerm
    ? firstTerm + secondTerm
    : undefined
  : undefined

Here's how we might use this:

if (sum !== undefined) {
  console.log(`sum: ${sum}`)
} else {
  console.error(`Not enough terms`)
}
// output: Not enough terms

What if we want to print different error output depending on which term is missing?

if (sum === undefined) {
  // does 'firstTerm' exist or not?
}

`undefined` can't nest

Ideally, we might want a type signature that looks like this:

const sum: number | undefined | undefined = firstTerm
  ? secondTerm
    ? firstTerm + secondTerm
    : undefined
  : undefined

Believe it or not, this compiles! But these two undefineds are the same. How would we know which is which?

This works because the compiler unifies these types under the hood. There are three possible return cases: number, undefined, and undefined. Typescript takes the union of these cases, which removes the redundant undefined and flattens to number | undefined

For nullables, flatten is the identity function.

`Option` saves the day!

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

const firstTerm: O.Option<number> = O.some(3)
const secondTerm: O.Option<number> = O.none
const sum: O.Option<O.Option<number>> = pipe(
  firstTerm,
  O.map(firstTerm => pipe(
    secondTerm,
    O.map(secondTerm => firstTerm + secondTerm)
  )),
)
pipe(
  sum,
  O.fold(
    () => console.error(`First term doesn't exist`),
    O.fold(
      () => console.error(`Second term doesn't exist`),
      sum => console.log(`sum: ${sum}`)
    ),
  ),
)
// output: Second term doesn't exist

The magic here is in the type of sum:

const sum: O.Option<O.Option<number>>

Option nests! This means that we're able to track exactly where our operation failed.

Metadata and Data: Sum Types vs Union Types

Gabriel Lebec explained to me on the fp-ts slack channel that Option gives us

separation between meaningful layers (metadata vs. data)

Here, our metadata tells us whether an operation was successful or not.

Option is implemented as a sum type (or tagged union or discriminated union), so under the hood, the metadata and the data are stored separately, like so: { _tag: 'Some', value: 3 }. _tag is the metadata and value is the data. This allows us to nest different data together and keep their associated metadata separate.

On the flip side, a union with undefined combines the metadata and the data.

const separatedMetadata: O.Option<O.Option<number>> = {
  _tag: 'Some',
  value: {
    _tag: 'None'
  }
}
const coupledMetadata: number | undefined = undefined

A value of undefined is both the metadata of 'failure' and the data of 'no result'.

In contrast, a value of 3 is both the metadata of 'success' and the data of '3'.

const separatedMetadata2: O.Option<O.Option<number>> = {
  _tag: 'Some',
  value: {
    _tag: 'Some',
    value: 3
  }
}
const coupledMetadata2: number | undefined = 3

While the types O.None and undefined may seem similar, { _tag: 'None' } has more information encoded into it than undefined. This is because _tag must be one of two values, while undefined has no such context. In the earlier case of sum, undefined smushes two different metadata together inseparably, resulting in information loss.

Set Theory

While union types are simply the union of two sets

A ∪ B

Each element of a sum type necessarily has a label 'l'

A + B = ({l^A} × A) ∪ ({l^B} × B)

This label represents the set the object originated from. It allows each object can 'remember' where it came from.

We can also see in the above equation that a sum type is a union type, but not vice versa.

This is where the term 'tagged union' comes from.

In Option, this label is the _tag field.

When nested, the _tag field helps Option 'remember' whether it has succeeded or failed.

Category Theory

Another way to think about nestabiltiy is through the lens of formal monadic correctness.

Remember our OptionMonad instance defined earlier? Although it's is correctly typed, it is not in fact a proper monad instance - it fails the left identity law

const f = (_: undefined): number => 1
const leftTerm = OptionMonad.chain(OptionMonad.of(undefined), f)
const rightTerm = f(undefined)
const leftIdentity = leftTerm === rightTerm
console.log(`${leftTerm} vs. ${rightTerm}`)
console.log(`left identity passes? ${leftIdentity}`)
// undefined vs. 1
// left identity passes? false

The monadic left identity deals with flattening and wrapping¹ - basically it asks the question "do the flattening from chain and the wrapping from of consistently cancel each other out?"

In our case, the answer is no. Since our of is the identity function, it doesn't really wrap anything. Since our chain function has no wrapper to unwrap, it must short circuit on all undefined values, even if undefined was the value that we wanted it to pass through. Directly invoking f with an undefined value returns a number, so our behavior is shown to be inconsistent.

This proves in a simple way the pragmatic, engineering use of the monad laws (or one of them, anyway). The left identity ensures that monads are meaningfully nest-able.

Remember this the next time you find yourself frustrated by O.fromNullable - you are lifting your unmarked data into a glorious nestable mathematically sound monadically wrapped value!

Conclusion

Hopefully this has provided some insight into why Option was implemented as a sum type, and not just a union type - and as a bonus, provided some insight into the practical benefits of proper category theoretical monads.

A month or two ago, I 'discovered' that a monad instance of Nullable could be valid (it's not) and have a simpler interface than the tagged union. I was excited, and I almost made a pull request to the library to 'fix' the 'problem' I had found.

Before I did that, however, I thought it would be wise to double check that this 'problem' was in fact a mistake. I asked the fp-ts slack channel why Option was implemented as a tagged union. You can click the link above to see the lovely explanations that people provided. Happily, I avoided implementing that pull request, and instead was redirected on a journey of learning that led me to write this article.

I am inspired by public forums where I'm able to ask basic questions and be taken seriously. I recommend joining the fp-ts and typescript slack channels here, especially if you're interested in deeper understanding of functional programming.

The community is supportive and kind, and has helped me become a better developer.

(edit:) The slack community continues to support me! Thanks to Monoid Musician for pointing out that sum types & union types belong to set theory, not category theory, and for pointing out that OptionMonad fails the monad laws.

Some people dislike the wrapper metaphor - they correctly assert that it only describes a few monads, and only leads to more confusion later when introduced to more. Here are a couple of paradigmatic tweets (1, 2). ↩

However, the paper What we Talk About When we Talk About Monads posits that such metaphors are necessary for a complete understanding of the concept, alongside 'formal' and 'implementation'-level knowledge.

Should I use fp-ts Option?

Anthony G — Tue, 15 Sep 2020 19:02:52 +0000

tl;dr

Option is more powerful than nullable but can be cumbersome to work with if you aren’t using it consistently. New apps should use Option everywhere but it can sometimes be a hassle to mix it into existing apps.

What is Option?
The Problem
What Option does well
Trying to get an intuition
Final Thoughts
Appendix: Uses for Option
- Converting to and from Either
- Safe Array Operations
- Array of Option
- Tuple of Option
- Safe Record Operations
- Chaining And Using Several Optional Values In Sequence
- Accessing and Modifying Deeply Nested Data

What is Option?

If you aren't sure, here are links to simple lessons that I like:

pipe (good to understand this before diving into Option)
Option

The Problem

Nullables are simple. (For this article, I'll be using the term 'nullable' to mean 'union type with undefined')

const multiplyNullableByTwo = (
  num: number | undefined
): number | undefined => num ? num * 2 : undefined

Option is even simpler.

import * as O from 'fp-ts/Option'
import { pipe } from 'fp-ts/pipeable'
const multiplyOptionalByTwo: (
  num: O.Option<number>
) => O.Option<number> = O.map(n => n * 2)

But what if we're adding fp-ts to an app that already uses lots of nullables?

const multiplyOptionalByTwo: (
  num: number | undefined
) => O.Option<number> = ????

We have to upconvert using O.fromNullable

import { flow } from 'fp-ts/function'
const multiplyNullableByTwo: (
  num: number | undefined
) => O.Option<number> = flow(
  O.fromNullable,
  O.map(n => n * 2)
)

But should we return an Option? It makes multiplyNullableByTwo less interoperable with the existing code that uses nullables. It might be confusing for other devs who don't know fp-ts, or incoming devs who aren't sure why Option is used in some places and nullable elsewhere.

Should we convert back?

const multiplyNullableByTwo: (
  num: number | undefined
) => number | undefined = flow(
  O.fromNullable,
  O.map(n => n * 2),
  O.toUndefined,
)

In this case, it's definitely not worth the hassle. We should just use the nullable approach from the beginning of this section.

But where's the line? When is Option more appropriate than nullable?

What Option does well

if statements are are nowadays considered brittle and poorly legible, and Option helps simplify control flow.

Let's say you want to write a function called greet that turns certain authors' names lowercase, and refers to everyone else by their last name. The following has already been implemented (Note that lastName returns a nullable):

const lowercase = (a: string): string => a.toLowerCase()
const isAuthor = (a: string): boolean => lowercase(a).includes('bell hooks') || lowercase(a).includes('pattrice jones')
const lastName = (a: string): string | undefined => a.split(' ').length > 1 ? a.split(' ')[1] : undefined

Here is the traditional implementation using plain nullables:

const greet = (name: string | undefined): string => {
  let modifiedName: string | undefined = undefined
  if (name) {
    if (isAuthor(name)) {
      modifiedName = lowercase(name)
    } else {
      const last = lastName(name)
      if (last) {
        modifiedName = last
      }
    }
  }
  if (modifiedName) {
    return `Hello ${modifiedName}`
  }
  return 'Greetings!'
}

This version has mutable state (which we normally want to avoid), convoluted control flow, and multiple exit points, which are controversial at best.

Here's the same function implemented with Option:

const greet = (name: string | undefined): string => pipe(
  O.fromNullable(name),
  O.chain(O.fromPredicate(isAuthor)),
  O.map(lowercase),
  O.alt(() => pipe(
    O.fromNullable(name),
    O.chain(flow(
      lastName,
      O.fromNullable,
    )),
  )),
  O.map(n => `Hello ${n}`),
  O.getOrElse(() => 'Greetings!'),
)

This version is shorter even including the extra conversions with fromNullable.

The Option version is easier to read. Our Option operations give us clues to what's going on:

fromPredicate: isAuthor is a predicate
alt: lastName is applied as an alternative to lowercase
chain: lastName might fail
getOrElse: return 'Greetings!' if anything goes wrong

It's an example of expression-oriented programming. This means that every line of code has a return value as opposed to executing a side effect. This mitigates information loss and discourages unnecessary side effects.

We could do something like this:

const greet = (name: string | undefined): string => {
  const modifiedName = name
    ? isAuthor(name)
      ? lowercase(name)
      : lastName(name)
        ? lastName(name)
        : undefined
    : undefined
  if (modifiedName) {
    return `Hello ${modifiedName}`
  }
  return 'Greetings'
}

This approach, while shortest, is probably the least legible of the three. Related cases are spread far apart, it's not obvious why lastName is called twice, and nested ternaries are often disabled by eslint anyway.

This article's appendix details many useful things that Option can do better than nullable.

Trying to get an intuition

Ok, we get it, Option is more powerful than nullable. But that doesn't change the fact that nullable is a very common pattern and can often lead to simpler, shorter solutions.

How can I know when it will be worth the hassle? Should I store Options in my data model? Even if my old code still uses nullable all over the place?

This is tricky to think about. I think this question gets at a fundamental paradox about functional programming generally: simple problems become hard and hard problems become simple. Maybe in this case, it's better framed as simple problems becoming slightly awkward and not being sure whether your simple problem will eventually become a hard problem that we can turn into an simple problem.

Functional programming represents an intersection of academic research and practical engineering. What's exciting about fp-ts is that it's the functional Typescript library that has made the fewest compromises for engineering's sake. This gives it power, but also rigidity. In this regard, fp-ts is easy, but not simple (as defined by Rich Hickey, the author of Clojure).

Maciej Sikora's wonderful article Maybe just Nullable? posits that Option should be avoided unless the entire application is implemented using functional techniques.

For me, within an application it's often worth the small amount of pain to up-convert into Option. Hopefully you can use the above example and the appendix below as tools to predict whether your data would benefit from being represented as Option in the long run.

However, if you're exposing an interface that many other developers will use, and many of them won't be using fp-ts, it's probably best to save them the hassle and simply expose undefined. This could be an npm module, or just a project where all the devs aren't entirely comfortable with fp concepts.

Final Thoughts

In an impure language like Typescript, your code will never be fully functional. There are necessarily shades of fp gray along the Typescript spectrum. Choosing to use React pushes your project towards the functional side, or at least more so than choosing Angular or Vue. Choosing lodash shifts slightly further, although even vanilla es6 has taken great inspiration from fp paradigms (by way of lodash and underscore). Maybe you'll go crazy and wrap all your side effects in IO for referential transparency (or maybe that's going sane!)

Adding fp-ts to a project will make waves. It can be particular and finicky, more so than a library like lodash which can integrate more seamlessly. Like any restriction, the benefit is more power.

Ultimately, it's up to you how functional you want your code to be. It can be difficult to convince your team to make the switch, and migrating an entire existing project can be beyond reach. In this author's opinion, even in small doses, it's worth the inconvenience, but in any case hopefully this article gives you enough context to make informed decisions.

If you have a specific case where you are still having trouble deciding, please leave a comment or tweet at me about it - sometimes these are difficult questions and I'd love to have longer conversations about them!

Appendix: Uses for Option

Converting to and from Either

Can be useful if error messages are unimportant, or if decide you want to add one later on:

import * as E from 'fp-ts/Either'
const parseIntResult: E.Either<string, number> = E.right(3)

const discardErrorMessage: O.Option<number> = O.fromEither(parseIntResult)

const addErrorMessage: E.Either<string, number> = pipe(
  discardErrorMessage,
  E.fromOption(() => 'could not parse to number'),
)

Safe Array Operations

This PR to Typescript was closed, so this is dangerous:

const names: string[] = ['anthony', 'gabriele']
const unsafeThirdName: string = names[2]

Unfortunately, this won't even crash at runtime. unsafeThirdName will merely be set to 'undefined' even though the type doesn't reflect that. It will run as though nothing is wrong until unsafeThirdName is used.

Option is safer.

import * as A from 'fp-ts/Array'

const safeThirdName: O.Option<string> = pipe(
  names,
  A.lookup(2)
)

There are many safe Array functions that take advantage of Option:

(Edit: Good news! Ryan Lee pointed out in the comments that Typescript 4.1 will fix this issue by providing a new compiler flag, which can be set on the command line like this: tsc --noUncheckedIndexedAccess or by setting "noUncheckedIndexedAccess": true in the compilerOptions of your tsconfig.json (thanks Ryan!). At the time of writing (16/9/2020), it hasn't been folded into a stable build of Typescript yet, but it is in the latest nightly build. You can learn more about the flag in its PR here)

(This leaves us with a bit less justification for using Option in a project where fp-ts usage is not ubiquitous, since A.lookup and R.lookup are now actually slightly more cumbersome to use than the new nullable syntax.)

(However, this assumes that your Typescript version is greater than version 4.1 and that you have noUncheckedIndexedAccess enabled. We will see if and when those things get folded into common use with tools like create-react-app which is still currently using version 3.7.5 (nearly a year old), ng create which uses 3.8.3, etc.)

Array of Option

Let's say we have an array of optional names:

const names: O.Option<string>[] = [O.some('anthony'), O.none, O.some('gabriele')]

If we want to remove all empty values, we can use:

const existingNames: Array<string> = pipe(
  names,
  A.compact
)

// existingNames = ['anthony', 'gabriele']

To ensure the array contains no empty values, we can use:

const allNamesFailure: O.Option<Array<string>> = pipe(
  names,
  A.sequence(O.option)
)
// allNamesFailure = O.none

const allNamesSuccess: O.Option<Array<string>> = pipe(
  [O.some('anthony'), O.some('gabriele')],
  A.sequence(O.option)
)
// allNamesSuccess = O.some(['anthony', 'gabriele'])

sequence is used to 'flip' nested generic types inside out - here, we have gone from Array<O.Option<string>> to O.Option<Array<string>>

Tuple of Option

If we want to ensure a tuple has no empty values, we can't use A.sequence, since the internal types can be different from each other:

const nameAndAge: [O.Option<string>, O.Option<number>] = [O.some('anthony'), O.some(26)]

const bothNameAndAge: O.Option<[string, number]> = pipe(
  nameAndAge,
  A.sequence(O.option),
)
// error: Type '[Option<string>, Option<number>]' is not assignable to type 'Option<string>[]'.

You can use sequenceT in this case:

import { sequenceT } from 'fp-ts/Apply'
const printSelf: string = pipe(
  sequenceT(O.option)(...nameAndAge),
  O.map(
    ([name, age]: [string, number]) =>
      `in five years, ${name} will be ${age + 5}`
  ),
  O.getOrElse(() => 'missing name or age'),
)

Safe Record Operations

There are similar functions for Record as for Array:

import * as R from 'fp-ts/Record'

const block: Record<string, number> = {
  buildings: 5,
  streets: 4
}

const unsafeNumBuildings: number = block.buildings

const safeNumBuildings: O.Option<number> = pipe(
  block,
  R.lookup('buildings')
)

const ingredients: Record<string, O.Option<number>> = {
  onions: O.some(2),
  peppers: O.none,
  eggs: O.some(3),
}

const whateverOmlette: Record<string, number> = pipe(
  ingredients,
  R.compact,
)

const westernOmlette: O.Option<Record<string, number>> = pipe(
  ingredients,
  R.sequence(O.option),
)

Chaining And Using Several Optional Values In Sequence

If you find yourself with the deeply nested chain of doom:

const addFour: number = pipe(
  O.some(6),
  O.chain(first => pipe(
    O.some(1),
    O.chain(second => pipe(
      O.some(first + 7),
      O.chain(third => pipe(
        O.some(4),
        O.map(fourth => first + second + third + fourth),
      ))
    )),
  )),
)

You can approximate Haskell's Do notation like this:

const addFour: number = pipe(
  O.some(6),
  O.bindTo('first'),
  O.bind('second', () => O.some(1)),
  O.bind('third', ({ first }) => O.some(first + 7)),
  O.bind('fourth', () => O.some(4))
  O.map(({ first, second, third, fourth }) => first + second + third + fourth)
)

Much cleaner!

Accessing and Modifying Deeply Nested Data

Option can help you easily access & modify deeply nested data using monocle-ts:

import * as Op from 'monocle-ts/lib/Optional'

interface Employee {
  name: string
  company: {
    name: string
    address: {
      city: string
      street: O.Option<{
        num: number
        name: string
      }>
    }
  }
}

const companyStreetName: Op.Optional<Employee, string> = pipe(
  Op.id<Employee>(),
  Op.prop('company'),
  Op.prop('address'),
  Op.prop('street'),
  Op.some,
  Op.prop('name')
)

const employee: Employee = ...
const employeeCompanyStreetName: O.Option<string> =
  companyStreetName.getOption(employee)
const employeeAfterMove: Employee = pipe(
  employee,
  companyStreetName.set('New Street Name')
)

getOption is Option's version of nullable's optional chaining (which is a confusing name in this context because nullable is not Option), but set has no such equivalent.

Type Safe Routing with fp-ts-routing

Anthony G — Wed, 01 Jul 2020 22:01:47 +0000

tldr;

fp-ts-routing is a typesafe router (an alternative to react-router, @angular/router, vue.js router, etc). video tutorial here (react)

Introduction

fp-ts-routing is a type safe string parsing library inspired by purescript-routing. It's part of the fp-ts (functional programming with type script) ecosystem.

Motivation

Framework Agnostic

fp-ts-routing has no dependence on the browser. This means that it can be used with any framework that has access to the browser window (e.g. react, angular, vue.js).

Prevents typos

react-router, @angular/router and vue.js router use string for matching route paths. They also use string for rerouting (react-router, @angular/router, vue.js router). This invites typos and leads to misbehavior when these strings don't match.

fp-ts-routing parses routes into sum types, which are validated at compile time. This eliminates the possibility of mismatches or misspellings.

Pattern Matching

With routes represented as sum types, it's easy to render according to a pattern match.

This gives users exhaustiveness checking - a helpful compile time error if users fail to render every route.

Parses Route Params to Arbitrary Types

react-router, @angular/router and vue.js router all use string for route params and queries.

fp-ts-routing allows users to parse any type they want for route params and queries - strings, integers, anything really (by way of io-ts)

Accessibility (React)

Because react-router's <Link> composes <a>, eslint-plugin-jsx-a11y (included in create-react-app) is unable to provide <Link> users proper <a> warnings (validity, content). Rather than enforce these warnings statically, the react-router team made the (understandable) decision to ignore them.

Because fp-ts-routing has no dependence on the DOM, users are able to use plain <a> tags, which can give the proper accessibility warnings.

Simplicity & Clarity of Purpose

fp-ts-routing does very little - it can parse a string to a sum type, and back again. In this author's opinion, this makes it easier to learn than, for example, react-router, which has 4 hooks, an HOC, 11 components, esoteric and strange matching logic, and many distinct but similar usages of route params.

Usage of fp-ts-routing requires learning about sum types and the browser window api. It can be an interesting case study for io-ts. These are fundamentals, and in this author's opinion, learning about them is more fruitful than learning a routing framework's arbitrary rules.

Video Tutorial

I've put together an fp-ts-routing video tutorial (38 min). It's for beginners, so don't worry, you don't need to know anything about fp-ts or io-ts. If you know basic typescript and basic react you'll be able to follow along.

The tutorial covers:

window.location.pathname & <a> (video)
window.history.pushState & popstate (video)
union types (video)
tagged union types (video)
fp-ts-routing (video)
@morphic-ts/adt (video)
morphic-ts-routing (video)

There are also bonus videos that cover:

window.location.hash & history state (video)
fp-ts-routing param & query types (video)
@morphic-ts/adt verified (video)
a brief history of typescript adt libraries (video)

The tutorial is free. Please consider donating if you'd like to support future planned tutorials.

If you are an experienced developer and you'd prefer to skip the tutorial, here's code for an example application that mirrors this react-router example app.

DEV Community: Anthony G

Simple Immutable Data w/ Spectacles 👓

Installation

Syntax (featuring auto-complete!)

Nullables

Tuples

Discriminated Union

Traversals

Indexed Arrays

Modification

Change Object types

get

Option

Conclusion

Appendix: functional programming

Whats fp-ts

pipe

Why use pipe for spectacles

Whats Option

spectacles-ts vs monocle-ts

Note

TaskEither vs Fluture

tl;dr

Contents

Future Rocks

Type Safety

fork is Missing

What is Invocation

Advantage of Laziness

Short Circuit Evaluation

What is fork

Why is it Missing

What is IO

Wait What

Forgetting to Invoke IO

IO Entry Point

hyper-ts

redux-observable

Conclusion

TaskEither vs Promise

tl;dr

Promises Rock

Promises are Callback Heaven

Promises are Declarative

Promises are Kinda Monads

Control Flow

Railway oriented programming

Problems with promises

Model unchecked exceptions

Then and catch are vague

Non obvious difference btwn catch and then

Promiselike

Poor Referential Transparency

Promises aren't Monads

Promises can't nest

Eagerness Complicates Nestability

Conclusion

Should I use fp-ts Task?

tl;dr

Contents

Two Problems with Promise

catch uses any

catch is optional

This is Bad

Welcome to Task

Task Rules

Rule Number 1

Rule Number 2

Rule Number 3

Why are there rules this is dumb

Should I use Task

Emotional component

Conclusion

Why is redux-observable Like That?

tl;dr

What's up with Redux?

Timeline Overview

June 2020

Halogen 5 Released

June 2017

`spectacles-ts` vs `monocle-ts`

`catch` uses `any`

`catch` is optional

Even more features with `@morphic-ts/adt`³

Other advantages of `@morphic-ts/adt`