# Practical Guide to Fp-ts P5: Apply, Sequences, and Traversals

<div style="border: 2px solid #FF4136; border-radius: 10px; padding: 20px; background-color: #FEEBEC;">
  <h3 style="color: #FF4136; margin-top: 0;">⚠️ Disclaimer Warning</h3>
  <p style="font-size: 18px; line-height: 1.6;">
    <strong>fp-ts</strong> is now dead. Please use <a href="https://effect.website/" target="_blank" style="color: #FF4136; text-decoration: none;"><strong>effect-ts</strong></a> instead.
  </p>
  <p style="font-size: 16px; line-height: 1.4; color: #333; margin-top: 10px;">
    <em>Update 2024: effect-ts is the recommended library for functional programming in TypeScript.</em>
  </p>
</div>

## Introduction

Welcome to part 5 of this series on learning fp-ts the practical way.

By now you've been introduced to the operators `of`, `map`, `chain`, `flatten`, but there's one operator we haven talked about yet: `ap` or _apply_. The `ap` operator is a greater part of what is called an Applicative. And applicatives form the basis for sequences and traversals.

In this post, I will explain the rationale for `ap`, its usecases, and how we don't actually need it because we have sequences and traversals.

## Apply

<!-- Applicatives are composed of three operators: `of`, `map`, and `ap`. As you can recall, `of` is just a type constructor, and `map` is just a function that transforms a type from one category to another.
 -->

What is the mysterious `ap` operator, otherwise known as Apply?

In many ways, it is like the reverse of `map`. Rather than piping a value into a function, you pipe a function into a value.

To demonstrate this, lets learn about [currying](https://en.wikipedia.org/wiki/Currying). Currying is taking a function with multiple parameters and converting it into a higher order function such that it takes a single argument repeatedly.

For example, we can have a `write` function that takes 3 parameters.

```ts
declare function write(key: string, value: string, flush: boolean): unknown
```

And we can convert it into a curried function like so:

```ts
const writeC = (key: string) => (value: string) => (flush: boolean) =>
  write(key, value, flush)
```

Trivially we can call the function like this:

```ts
writeC('key')('value')(true)
```

And, if we wanted to do the same with our pipe syntax we could try something like this.

```ts
// ❌ Wrong
pipe(true, 'value', 'key', writeC)
```

But unfortunately this doesn't work because pipeline is evaluated from left-to-right; the compiler will complain that `true` cannot be piped into `value` and `value` cannot be piped into `key`. To make this work, we will need to enforce the order of operations (just like in math), with more pipes!

```ts
// ✅ Correct
pipe(true, pipe('value', pipe('key', writeC)))
```

Now the compiler understands because we force the right side to evaluate first. However, this syntax isn't ideal because its annoying to add additional pipes for the sake of ordering.

The solution to this is `ap`.

```ts
import { ap } from 'fp-ts/lib/Identity'

pipe(writeC, ap('key'), ap('value'), ap(true))
```

Remember when I said `ap` is just piping a function into a value? This is exactly what you see here.

`writeC` is piped into `key` which forms the function `(value: string) => (flush: boolean) => write(key, value, flush)`. This function is piped into `value` which forms the function `(flush: boolean) => write(key, value, flush)`. And finally, this last function is piped into `true` which calls our 3 parameter write function: `write(key, value, flush)`.

In essence, `ap` just makes it easier to curry function values while keeping the correct order of operations.

---

Another use case for `ap` is when you have functions and values that don't play well together because one of them is trapped inside an `Option` or an `Either`, etc... `ap` is useful in this scenario because it can lift values or functions into a particular category.

To demonstrate, lets look at an example.

```ts
import * as O from 'fp-ts/lib/Option'
import { Option } from 'fp-ts/lib/Option'

declare const a: Option<number>
declare const b: Option<string>
declare function foo(a: number, b: string): boolean
```

As you can see, we want to call `foo` using our variables `a` and `b`, but the problem is: `a` and `b` are in the Option category while `foo`
takes plain values.

A naive way of executing `foo` is to use `chain` and `map`.

```ts
// Option<boolean>
O.option.chain(a, (a1) => O.option.map(b, (b1) => foo(a1, b1)))
```

But this is terrible because:

1. We have to awkwardly name our variables with a number suffix because we don't want to shadow the outer variable.
2. It doesn't scale if we have more parameters.
3. Its ugly and confusing.

Lets try again.

First we need to convert `foo` into a curried function `fooC`.

```ts
const fooC = (a: number) => (b: string) => foo(a, b)
```

Then it is just the same thing as we did before, BUT we need to _lift_ `fooC` into the `Option` category using `of`, because the `Option` version of `ap` must operate on two options.

```ts
// Option<boolean>
pipe(O.of(fooC), O.ap(a), O.ap(b))
```

Lets extend the example a bit further. Let say we had another function `bar` that takes a boolean (the return value of `foo`) and returns an `object`. Naturally, we want to call `foo` and subsequently `bar` with the return value of `foo`.

We have already computed `foo` as an `Option<boolean>`, so this is nothing more than a simple _lift_ into `ap`

```ts
declare function bar(a: boolean): object

const fooOption = pipe(O.of(fooC), O.ap(a), O.ap(b))

// Option<object>
pipe(O.of(bar), O.ap(fooOption))
```

Cool, `ap` is clearly powerful. But what are the problems with `ap`?

First, its boring to have to curried every function in existence just to use fp.

Second, reversing the order of the input value of a function inside of a pipe from left-to-right to right-to-left breaks the natural `flow` of operations.

In the real world, there's hardly a usecase for `ap` because we can leverage sequences instead.[^1]

## Sequences

So what is a sequence?

In math, we think of a sequence as a sequence of numbers. Similarly, we can apply this to a sequence of Options, a sequence of Eithers, etc...

The most common usecase for a sequence is convert an array of say Options into an Option of an array.

```ts
// How?
Array<Option<A>> => Option<A[]>
```

To do this, you need to provide sequence an instance of `Applicative`. An applicative has 3 methods: `of`, `map`, and `ap`. This applicative defines the type of the objects inside of the collection. For a list of `Options`, we would provide it with `O.option`.

```ts
import * as A from 'fp-ts/lib/Array'
import * as O from 'fp-ts/lib/Option'

const arr = [1, 2, 3].map(O.of)
A.array.sequence(O.option)(arr) // Option<number[]>
```

Now we lets go back to the problem: how do we use sequence such that we don't have to write a curried function and use `ap`?

Enter `sequenceT`.

### SequenceT

`sequenceT` is the same as a regular `sequence` except you pass it a [rest parameter](https://www.typescriptlang.org/docs/handbook/functions.html#rest-parameters) (vararg). The return value is the provided applicative with a tuple as the type parameter.

For example:

```ts
//  Option<[number, string]>
sequenceT(O.option)(O.of(123), O.of('asdf'))
```

Now you see where this is going. We can just pipe this into our original `foo` and `bar` functions.

```ts
declare function foo(a: number, b: string): boolean
declare function bar(a: boolean): object

// Option<object>
pipe(
  sequenceT(O.option)(O.of(123), O.of('asdf')),
  O.map((args) => foo(...args)),
  O.map(bar),
)
```

Note, I had to use the `...` spread syntax to convert the tuple into parameter form.

### SequenceS

Sometime our function takes a single object parameter rather than multiple arguments. To solve this problem we can leverage `sequenceS`.

```ts
import * as E from 'fp-ts/lib/Either'

type RegisterInput = {
  email: string
  password: string
}

declare function validateEmail(email: string): E.Either<Error, string>
declare function validatePassword(password: string): E.Either<Error, string>
declare function register(input: RegisterInput): unknown

declare const input: RegisterInput

pipe(
  input,
  ({ email, password }) =>
    sequenceS(E.either)({
      email: validateEmail(email),
      password: validatePassword(password),
    }),
  E.map(register),
)
```

## Traversals

Sometimes your inputs will not line up nicely and you need to perform some additional computations before applying `sequence`. Traversal is the answer to this. It performs the same thing sequence but lets us transform the intermediate value.

A good example network request to retrieve parts of a file. You either want all the parts or you want none of them.

```ts
import * as TE from 'fp-ts/lib/TaskEither'
import { TaskEither } from 'fp-ts/lib/TaskEither'
import * as A from 'fp-ts/lib/Array'

declare const getPartIds: () => TaskEither<Error, string[]>
declare const getPart: (partId: string) => TaskEither<Error, Blob>

// ✅ TE.TaskEither<Error, Blob[]>
pipe(getPartIds(), TE.chain(A.traverse(TE.taskEither)(getPart)))
```

## Conclusion

In this post we've learned about Apply, its usecases, and how we can _apply_ it to our lives with sequences and traversals.

Thanks for reading and if you like this content, please give me a follow on [Twitter](https://twitter.com/ryanleecode) and shoot me a DM if you have questions!.

---

[^1]: Sequences and traversals use `ap` internally.