If you're new to Effect-TS, this is the start of a mini series where we'll explore practical use cases for it. Looking back at fp-ts, Effect-TS is a significant improvement because it enables true functional programming in a concurrent environment.

Let's dive into a real-world example of using Effect-TS in a production setting. Imagine you're developing an application that uses image generation APIs. You need to wait for the images to render before proceeding, but you want to avoid the complexity of implementing webhooks. Instead, you'll use polling.

Here's a simplified diagram of the flow:

And here's the breakdown in plain English:

1. Send a POST request to the API to generate an image based on a text prompt.

2. Receive a generation ID as the response.

3. Spawn a new thread to periodically check the status of the image generation using the provided ID. Keep looping until the status is "Complete" or "Failed".

4. Suspend the main thread until the image generation task completes.

Effect-TS shines in scenarios like this, where you need to perform concurrent operations and handle asynchronous results in a functional way. It provides the tools to write clean, composable code that's easy to reason about, even in the presence of concurrency.

Data Modelling

Lets write some interfaces to model what our AI APIs would look like

export type ImageGeneration = {
  id: string;
} & (
  | {
      status: 'completed';
      url: string;
    }
  | { status: 'failed'; error: string }
  | { status: 'pending' }
);

export type AiImageSDK = {
  generateImage(prompt: string): Promise<string>;
  getGenerationById(id: string): Promise<ImageGeneration>;
};

And now the code

declare const client: AiImageSDK;

const getImageGeneration = (id: string) =>
  Effect.Do.pipe(
    Effect.bind('deferredUrl', () => Deferred.make<string, Error>()),
    Effect.tap(({ deferredUrl }) =>
      Effect.tryPromise(async () => {
        const response = await client.getGenerationById(id);
        if (response.status === 'completed') {
          return response.url;
        }
        if (response.status === 'failed') {
          throw new Error(`Generation ${id} failed.`);
        }
      }).pipe(
        Effect.tap((url) =>
          url ? Deferred.succeed(deferredUrl, url) : Effect.none
        ),
        Effect.catchAllCause((c) => Deferred.failCause(deferredUrl, c)),
        Effect.repeat(Schedule.spaced('5 seconds')),
        Effect.forkScoped
      )
    ),
    Effect.flatMap(({ deferredUrl }) => Deferred.await(deferredUrl))
  ).pipe(Effect.scoped);

await Effect.Do.pipe(
  Effect.bind('id', () =>
    Effect.tryPromise(async () => client.generateImage('shib army'))
  ),
  Effect.bind('url', ({ id }) => getImageGeneration(id)),
  Effect.map(({ url }) => url),
  Effect.tap(Console.log)
).pipe(Effect.runPromise);

Lets break down the getImageGeneration function:

1. We create a Deferred effect called deferredUrl representing the image url of the image that is being created.

2. We create a fork aka spawn a new non-blocking promise, to get the image generation. if the status is "completed" we return the url, if its "failed" we throw an error, if its "pending" we return undefined.

3. Once we reach a state where the status is completed successfully we assign the url to deferredUrl with Deferred.succeed(deferredUrl, url). If the operation fails or encounters a defect, we use Effect.catchAllCause((c) => Deferred.failCause(deferredUrl, c)) to propogate it back to the Deferred object.

4. This process repeats every 5 seconds until the function succeeds or fails. Once the URL is assigned, Deferred.await(deferredUrl) is unblocked and the effect is finished. Also take note of how the fork is scoped. The entire function is wrapped in Effect.scoped, meaning Effect.forkScoped will complete once the Deferred is unblocked.

Conclusion

And thats how you do polling with effect-ts. Hope you leanred something!

If you have any questions or want to discuss this further, feel out to reach out. I'm available on Twitter or you can email me at ryanleecode@gmail.com.

The reason why Typescript and Rust has been steadily gaining adoption is the superiority of their type systems compared to conventional programming languages like Java or Python. One thing that stands out about their type systems is their ability to do pattern matching.

In this post I'll give you an overview of what pattern matching is, how Typescript's switch statement works and its drawbacks. and I'll compare and contrast Rust pattern matching mechanics with Typescript's.

What is Pattern Matching?

Pattern matching is a mechanism that is used to check if a value matches a particular pattern defined within a programming construct. Pattern matching is useful because we can succinctly check if a value has a certain set of properties without having to use multiple if-statements. Multiple if-statements are bad because they are verbose and you have to worry about dealing with nullable nested fields (i.e. checking if the property is null before checking the value).

Pattern matching is also useful for doing state management because it forces you to add a handler all the possible states that your type allows. If your type was a discriminated union, then your handler would handle all variants of the union. This prevents logic errors from creeping up into your programs because you can't accidentally forget to a handle a state.

Pattern matching is also commonly associated with algebraic data types (ADTs) because ADTs can be decomposed into its constituent parts using pattern matching.

Lets look at some examples of pattern matching.

Example 1 — The Switch Statement

The only way to pattern match in Typescript is with the switch statement. Given a type that is a discriminated union, we can narrow the type using its discriminator.

For example in Redux, we use switch statements to match against different types of actions to update the state. The type of action is defined by its discriminator property type.

type Todo = {
  readonly id: string
  readonly title: string
  readonly description: string
}

type AddTodoAction = {
  readonly type: 'ADD_TODO'
  readonly todo: Todo
}

type RemoveTodoAction = {
  readonly type: 'REMOVE_TODO'
  readonly id: string
}

type Action = AddTodoAction | RemoveTodoAction

type State = {
  readonly todos: ReadonlyRecord<string, Todo>
}

function reducer(state: State = { todos: {} }, action: Action): State {
  switch (action.type) {
    case 'ADD_TODO':
      return { todos: { ...state.todos, [action.todo.id]: action.todo } }
    case 'REMOVE_TODO': {
      const { [action.id]: _, ...nextTodos } = state.todos
      return { todos: nextTodos }
    }
  }
}

As evident in the example above, the type of action will be narrowed down to AddTodoAction when the type matches ADD_TODO and similarly narrowed down to RemoveTodoAction when the type matches REMOVE_TODO.

Drawbacks of Switch Statements

1. Switch statements are verbose

When you try to pattern match against nested ADTs, it adds verbosity because each level of nesting requires another switch state.

For example, the code snippet below is verbose because it uses two switch statements to decompose the Option<FooBar> type.

type Option<A> = { _tag: 'Some'; value: A } | { _tag: 'None' }

type Foo = {
  _tag: 'Foo'
}

type Bar = {
  _tag: 'Bar'
}

type FooBar = Foo | Bar

declare const foobar: FooBar

switch (foobar._tag) {
  case 'Some':
    // Double switch! 🤮
    switch (foobar.value._tag) {
      case 'Foo':
        break
      case 'Bar':
        break
    }
    break
  default:
    break
}

Alternatively you can introduce a second function and move the switch statement into it. This removes the nesting but still adds verbosity.

function handleFooBar(foobar: FooBar) {
  switch (foobar._tag) {
    case 'Foo':
      break
    case 'Bar':
      break
  }
}

switch (foobar._tag) {
  case 'Some':
    handleFooBar(foobar.value)
    break
  default:
    break
}

2. Switch Statements Cannot be Assigned to Variables

If you want to assign the result of a switch statement to a variable, you need to wrap into a function, which adds verbosity.

// Very verbose! 😡
const fibonacci = ((n: number) => {
  switch (n) {
    case 0:
      return 0
    case 1:
      return 1
    default:
      return n + n - 1
  }
})(100)

3. Discriminators can only be primitive fields

Third, you can only switch on primitive fields: i.e. string and number. Switching on an object does not work.

const foo = { bar: 'baz' }

switch (foo) {
  case { bar: 'baz' }:
    console.log('foobarbaz') ❌
    break
  default:
    console.log('nope.jpg') 😢
    break
}

From a pattern matching perspective, Typescript is very limited in what it can do. Hence, this makes writing functional code more verbose and requires more boilerplate because you'll need to write your own matchers. See ts-adt as an example.

Example 2 — The Match Statement

In Rust, we don't have switch statements, we have match statements. Match statements are like Typescript switch statements but without all the drawbacks.

1. Match statements are concise

Here's an example of same redux code but written in Rust; written mutably for extra brevity.

use std::collections::HashMap;

struct Todo {
    id: String,
    title: String,
    description: String
}

enum Action {
    AddTodoAction { todo: Todo },
    RemoveTodoAction { id: String }
}

struct State {
    todos: HashMap<String, Todo>
}

impl Default for State {
    fn default() -> State {
        State { todos: HashMap::new() }
    }
}

fn reducer(state: &mut State, action: Action) {
    match action {
        Action::AddTodoAction { todo } => {
            state.todos.insert(todo.id.clone(), todo);
        },
        Action::RemoveTodoAction { id } => {
            state.todos.remove(&id);
        }
    }
}

How is this more concise?

First, because Rust is nominally typed rather than structurally typed, so we don't need a type discriminator field.

Second, we leverage Rust's enum syntax to destructure fields directly in a match statement as demonstrated with Action::AddTodoAction { todo }.

2. No Nested Matches

The same foobar example shown in the Typescript example can be written in Rust like so:

pub enum FooBar {
    Foo,
    Bar
}

fn main() {
    let foobar: Option<FooBar> = Some(FooBar::Foo);
    match foobar {
        Some(FooBar::Foo) => {}
        Some(FooBar::Bar) => {}
        _ => {}
    }
}

You can see how advantageous this is compared to Typescript because you can just construct the values you want to match against directly as demonstrated by Some(FooBar::Foo).

Heres a more complicated example where we match against certain fields and ignore the fields we don't care about using the .. syntax. The .. syntax is analogous to Typescript's ....

struct Cube {
    length: u32,
    width: u32,
    height: u32
}

fn main() {
    let my_cube = Cube {
        length: 10,
        width: 5,
        height: 5
    };

    match my_cube {
        // only match cubes of length 10
        Cube { length: 10, .. } => {},
        _ => {}
    }
}

You can also name the parameters you match.

Cube { length: cube_length @ 10 , .. } => {
    println!("{}", cube_length); // cube length is a variable
},

And if you use an unstable feature, you can match the cube length against a range as well.

#![feature(exclusive_range_pattern)]

// only match cubes of length (10-15]
Cube { length: cube_length @ 10..15 , .. } => {
    println!("{}", cube_length);
},

Example 3 — The If-Let Statement

In the previous example we wrote a full match statement to match against a very specific variant of a cube but we discarded the other variants.

If we don't care about other variants, then a succinct way of pattern matching is using an if-let statement.

if let Cube { length: cube_length @ 10, .. } = my_cube {
    println!("{}", cube_length);
}

This makes writing pattern matching code idiomatic.

There are problems though; you can't chain if-let statements with conditionals.

let my_cond = true;
// ❌ Syntax Error
if (let Cube { length: cube_length @ 10, .. } = my_cube) && my_cond {
    println!("{}", cube_length);
}

But you can just add the conditional into a tuple and pattern match against the tuple.

if let (Cube { length: cube_length @ 10, .. }, true) = (my_cube, my_cond) {
    println!("{}", cube_length);
}

Example 4 — Rust: Matching Slices

In Rust, not only can you match against structs and enums, but you can also match against slices.

Here is a basic example matching against an empty slice.

if let [0,0,0] = [0; 3] {
    println!("woah");
}

A more sophisticated example is matching against a vector with a known size.

let my_vec = vec![1,2,3];
if let &[1, x, 3] = &*my_vec {
    println!("{}", x); // 2
}

Note, dereferencing my_vec with * turns the vector into a slice. The slice on the right then needs to be borrowed and matched against a borrowed slice on the left. This is because an owned slice is not sized and will fail compilation.

For vectors where we don't know the size we can replace the parts we don't care about matching with ...

let my_vec = vec![1,2,3,4,5];
if let &[1, .., 4, 5] = &*v {
    println!("wow!");
}

The caveat is we can only match the head and the tail, we can't use the .. operator more than once. For example, this won't compile.

if let &[1, .., 3, .., 5] = &*v {
    println!("this doesn't compile!");
}

Conclusion

You should now understand the differences between Typescript and Rust pattern matching. Rust lets you do advanced pattern matching while Typescript is limited to basic switch statements and discriminated unions. The takeaway is the more complex your types are, the more you should consider languages like Rust, or even Scala because of their advanced pattern matching techniques.

Thanks for reading! If you enjoyed this post, please consider sharing.

⚠️ Disclaimer Warning

fp-ts is now dead. Please use effect-ts instead.

Update 2024: effect-ts is the recommended library for functional programming in TypeScript.

Introduction

Welcome back to Part 6 of The Practical Guide to fp-ts. So far I've covered the basics of functional programming and fp concepts. Now I will shift to more advanced topics.

In this post, I will formally introduce what a monad is and how we can use the Do Notation to simplify writing monadic code.

What is a Monad?

By now, you may have noticed I haven't said the term monad once in this entire series. This was intentional. The term monad creates a lot of confusion for newcomers to functional programming because there are many interpretations for what a monad is.

But even though I haven't said the term monad, you've been using monads throughout this entire series. Option is a monad. Either is a monad. Task is a monad.

So what is a monad?

A monad is any type that has the following instance methods:

1. of
2. map
3. chain (flatmap)
4. ap

In addition it the implementation of these methods must satisfy the following monadic laws:

1. Left Identity: of(x).chain(f) == of(f(x))
2. Right Identity: of(x).chain(of) = of(x)
3. Associativity: of(x).chain(f).chain(g) = of(x).chain(flow(f, g))

Are Monads Containers?

A common belief about monads is that they are containers. Some might refer to them as "ships in a bottle". Even though there exist some monads that would satisfy the definition of a container, not all monads are containers.

Lets see why.

When we look at the Option monad, its clear that it operates as a container over a nullable type. Its either Some(x) or None. Just like how Either is either Left or Right over some value x.

Can we create a type that satisfies monadic properties but isn't a container? Yes we can. Just change the all the option methods to return None.

export interface None {
  readonly _tag: 'None'
}
export interface Some<A> {
  readonly _tag: 'Some'
  readonly value: A
}
declare type Option<A> = None | Some<A>
export declare const none: Option<never>

// this option "contains" nothing
const option = {
  of: <A>(a: A) => none,
  map: <A, B>(fa: Option<A>, f: (a: A) => B) => none,
  chain: <A, B>(fa: Option<A>, f: (a: A) => Option<B>) => none,
  ap: <A, B>(fab: Option<(a: A) => B>, fa: Option<A>) => none,
}

Now our new "Option" is clearly not a container but it is still a monad. So it is not enough to describe monads as containers.

Instead, I will implore you with @YuriyBogomolov definition of a monad.

The Do Notation

Understanding monads is key to understanding the Do notation. But before we jump in, lets first understand the motivation for the Do notation.

The most common hurdle people run into when using monads is maintaining variable scope when using the chain operator.

Lets build up an example to demonstrate this.

First, lets define 3 functions returning a Task monad.

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

// filler values for brevity
type A = 'A'
type B = 'B'
type C = 'C'

declare const fa: () => T.Task<A>
declare const fb: (a: A) => T.Task<B>
declare const fc: (ab: { a: A; b: B }) => T.Task<C>

In order to call fc we need to have access to the return values of fa and fb. If we want to normally chain these set of function calls, we would need to nest our chain calls to keep previous variables in scope.

Like so.

T.task.chain(fa(), (a) => T.task.chain(fb(a), (b) => fc({ a, b }))) // Task<"C">

This is in contrast to what we would normally write, which looks like this:

flow(fa, T.chain(fb), T.chain(fc)) // ❌ "a" will go out of scope

So how can we achieve something that looks similar to the above? We can use the Do notation!

The Do notation is similar to sequenceT and sequenceS in the sense that you need to provide it an instance. The difference is, sequences require the instance to be of the Apply type (ap + map) while Do requires a Monad type (ap + map + chain + of).

So lets look at the same code but using the Do notation instead.[^1]

import { Do } from 'fp-ts-contrib/lib/Do'

Do(T.task)
  .bind('a', fa()) // task
  .bindL('b', ({ a } /* context */) => fb(a)) // lazy task
  .bindL('c', fc) // lazy task
  .return(({ c }) => c) // Task<"C">

What Do does here is, it lets you keep the bind the result of each task to a context variable. The first parameter in bind is the name of the variable. The second is the value.

You may also notice there are two variants of bind: bind and bindL. The L suffix stands for lazy. In this example, we don't directly provide a Task to bindL, we provide a function where the parameter is the context and the return value is a Task.

And at the very end of the Do notation we add a return call. In the previous example, we went from fa -> fb -> fc to form the Task<"C">. With the Do notation we need to specify what we want to return because just binding variables leaves us in an undefined state.

You can also view this from the imperative lens, where fa, fb, and fc are synchronous functions rather than monads.

declare const fa: () => A
declare const fb: (a: A) => B
declare const fc: (ab: { a: A; b: B }) => C
;() => {
  const a = fa()
  const b = fb(a)
  const c = fc({ a, b })

  return c
}

If we wanted to introduce a side effect, say console.log, its easy in the imperative world.

;() => {
  const a = fa()
  const b = fb(a)

  console.log(b) // 👈 side effect

  const c = fc({ a, b })

  return c
}

With Do notation we can do the same with a do invocation.

import { log } from 'fp-ts/lib/Console'

Do(T.task)
  .bind('a', fa())
  .bindL('b', ({ a }) => fb(a))
  .doL(({ b }) => pipe(log(b), T.fromIO)) // 👈 side effect
  .bindL('c', fc)
  .return(({ c }) => c)

Do is different from bind in the sense that it doesn't take a name as its first argument. This means it won't be added to the context.

If you want a more in-depth post about the Do notation, check our Paul Gray's post where he covers all the Do methods.

The Built-In Do Notation

One of the problems with the Do notation from the fp-ts-contrib package is its inflexibility. Every bind must be a monad representing the instance passed in. This means we can't switch categories from say Task to TaskEither. In our example, we are limited to Task because we used Do(T.task).

If we were to introduce a 4th function that returns a TaskEither, we would need to replace our instance with taskEither and lift each Task into TaskEither, which is not ideal because it becomes more verbose.

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

type D = 'D'
declare const fd: (ab: { a: A; b: B; c: C }) => TE.TaskEither<D, Error>

Do(TE.taskEither)
  .bind('a', TE.fromTask(fa()))
  .bindL('b', ({ a }) => TE.fromTask(fb(a)))
  .doL(({ b }) => pipe(log(b), T.fromIO, TE.fromTask))
  .bindL('c', ({ a, b }) => TE.fromTask(fc({ a, b })))
  .return(({ c }) => c)

Instead, fp-ts has its own notation for binding where we can switch between different monads with ease.[^2]

pipe(
  T.bindTo('a')(fa()),
  T.bind('b', ({ a }) => fb(a)),
  T.chainFirst(({ b }) => pipe(log(b), T.fromIO)),
  T.bind('c', ({ a, b }) => fc({ a, b })),
  TE.fromTask,
  TE.bind('d', ({ a, b, c }) => fd({ a, b, c })),
  TE.map(({ d }) => d),
)

You can see that the advantage of this approach is the ease of switching between different categories of monads. Hence, I strongly recommend you use this notation over the Do notation from the fp-ts-contrib package.

Conclusion

The Do notation is a powerful way of writing monadic code that makes it easy to chain functions while at the same time maintaining variable scope. Its inspired by the Haskell Do notation and Scala's for-yield notation.

In Typescript, we can use the Do notation from the fp-ts-contrib package or the built in bind methods. But there's another notation thats being discussed on the fp-ts Github. It proposes using function generators and along with yield syntax to make monadic code look imperative. Its an interesting approach and definitely worth investigating further.

Lastly, if you're interested in my content, be sure to follow me on Twitter.

Until next time.

[^1]: Note this comes from the fp-ts-contrib package.

[^2]: Note chainFirst is the equivalent of doL.

⚠️ Disclaimer Warning

fp-ts is now dead. Please use effect-ts instead.

Update 2024: effect-ts is the recommended library for functional programming in TypeScript.

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

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. 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.

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

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

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

Trivially we can call the function like this:

writeC('key')('value')(true)

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

// ❌ 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!

// ✅ 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.

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.

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.

// 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.

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.

// 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

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.

// 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.

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 (vararg). The return value is the provided applicative with a tuple as the type parameter.

For example:

//  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.

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.

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.

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 and shoot me a DM if you have questions!.

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

⚠️ Disclaimer Warning

fp-ts is now dead. Please use effect-ts instead.

Update 2024: effect-ts is the recommended library for functional programming in TypeScript.

Introduction

Welcome to the fourth post on learning fp-ts the practical way. This series is dedicated to learning fp-ts and functional programming with no mathematical knowledge required.

In this post, I'm going to introduce how to use arrays effectively in fp-ts and how we can use semigroups and monoids to easily compose operations over arrays.

Array Basics

The most basic data structure you'll encounter on a daily basis is the Array data type. Arrays are useful to us because we can use them to perform computations by traversing over its elements. But before we jump into traversals with fp-ts, lets start with the basics by going back to loops.

For Loop

The traditional way of traversing over an array is to use a loop with an index variable, i.

const foo = [1, 2, 3]

let sum = 0
for (let i = 0; i < foo.length; i++) {
  sum += foo[i]
}
console.log(sum) // 6

For-of Loop

Instead of using an index counter, we can also directly iterate over the elements using the for-of syntax.

const foo = [1, 2, 3]

let sum = 0
for (const x of foo) {
  sum += x
}
console.log(sum) // 6

Functional Loops

But lets be real, all the cool kids these days are using the fancy functional map, reduce, filter syntax.

const foo = [1, 2, 3, 4, 5]

const sum = foo
  .map((x) => x - 1)
  .filter((x) => x % 2 === 0)
  .reduce((prev, next) => prev + next, 0)
console.log(sum) // 6

In fp-ts, we can do the same thing but with different syntax.

import * as A from 'fp-ts/lib/Array'
import { pipe } from 'fp-ts/lib/function'

const foo = [1, 2, 3, 4, 5]

const sum = pipe(
  A.array.map(foo, (x) => x - 1),
  A.filter((x) => x % 2 === 0),
  A.reduce(0, (prev, next) => prev + next),
)
console.log(sum) // 6

However, this just looks like syntactic sugar, so let us digress. Why should you install fp-ts when you can just use the regular array methods?

Array Extensions

If you come from the Python world, you'll be shocked to find that Typescript doesn't have built in array methods like zip. You should use fp-ts because it gives you the additional batteries you need to do fancy array manipulation.

import * as A from 'fp-ts/lib/Array'
import { pipe } from 'fp-ts/lib/function'

const foo = [1, 2, 3]
const bar = ['a', 'b', 'c']

const zipped = pipe(foo, A.zip(bar))
console.log(zipped) // [[1, 'a], [2, 'b], [3, 'c']]

The cool thing about this is that it preserves the type-safety of the elements in the array. The type of zipped is Array<[number, string]> rather than Array<Array<number | string>>. In other words, zipped is an array of tuples.

If you find this cool, then you might also be interested in the unzip, partition, and flatten operators.

Array Type Safety

One of things that's not type-safe safe in Typescript is array access and mutations. If you're coming from the Java world, then you should know in Typescript, there is no such thing as an IndexOutOfBounds exception. Accessing an element that is out of bounds returns undefined. You can also create undefined behaviour when you mutate an array outside of its bounds.

const foo = [1, 2, 3]

const x: number = foo[4] // no compile error
foo[5] = 2 // no runtime error
console.log(foo) // [1, 2, 3, undefined, undefined, 2]

Now just by looking at this code snippet, I can assure you, that we are indeed living in scary times. However, there is light at the end of tunnel; type safe array access is coming in Typescript 4.1. The term they use is for it pedantic index signatures.

In the meantime, in our never ending search for purity, we must look to fp-ts to save us from the gallows of undefined.

Lookup

If we want to be type safe when accessing an element in an array, we should use the lookup function. It takes two parameters, an index and an array and returns an Option type.

import * as A from 'fp-ts/lib/Array'
import { pipe } from 'fp-ts/lib/function'

pipe([1, 2, 3], A.lookup(1)) // { _tag: 'Some', value: 2 }
pipe([1, 2, 3], A.lookup(3)) // { _tag: 'None' }

Because it returns an Option, we are forced to deal with the possible none case.

However, this can become cumbersome when we are interested in the first element, otherwise known as the head of the array and when we know the array is not empty.

const foo = [1, 2, 3]
if (foo.length > 0) {
  // We don't want an Option since we know it will always be some
  const firstElement = A.head(foo) // { _tag: 'Some', value: 1 }
}

To deal with this, fp-ts has another type known as the NonEmptyArray. The NonEmptyArray type also has a head operator but it return the underlying value instead of an Option.

Examine the type definition to see the difference.

// Array
export declare const head: <A>(as: A[]) => Option<A>

// NonEmptyArray
export declare const head: <A>(nea: NonEmptyArray<A>) => A

Now we must answer the question: how do we go from Array<A> 🠂 NonEmptyArray<A>.

In our example, we can do this by replacing our if statement with a isNonEmpty guard.

// Fp-ts Type guard
export declare const isNonEmpty: <A>(as: A[]) => as is NonEmptyArray<A>

import * as A from 'fp-ts/lib/Array'
import * as NEA from 'fp-ts/lib/NonEmptyArray'

const foo = [1, 2, 3]
if (A.isNonEmpty(foo)) {
  const firstElement = NEA.head(foo) // 1
}

Voilà, we have the value instead of an Option.

In short, if you really care about type safety, use lookup to access elements in your array.

Be sure to also checkout the insertAt and updateAt operators.

Partitioning Non-Homogenous Arrays

In Typescript, we can have two types of arrays: homogenous and non-homogeneous. In a homogenous array, every element must be of the same type. Elements in a non-homogenous arrays can take on union of types.

// Homogenous
const foo = [1, 2, 3] // number[]

// Non Homogenous
const bar = [1, '2', 3] // (string | number)[]

When we iterate over a non-homogenous array, we are limited by what is common between the union of types.

type Foo = {
  readonly _tag: 'Foo'
  readonly f: () => number
}

type Bar = {
  readonly _tag: 'Bar'
  readonly g: () => number
}

declare const arr: Array<Foo | Bar>
for (const a of arr) {
  console.log(a._tag) // Ok
  console.log(a.f()) // Error: not assignable to Bar
  console.log(a.g()) // Error: not assignable to Foo
}

But, lets say we had this problem domain. We want to sum all elements belonging to Foo using f() and multiply it by the maximum of all elements belong to Bar using g().

Trivially, we can compute it imperatively.

function compute(arr: Array<Foo | Bar>) {
  let sum = 0
  let max = Number.NEGATIVE_INFINITY

  arr.forEach((a) => {
    switch (a._tag) {
      case 'Foo':
        sum += a.f()
        break
      case 'Bar':
        max = Math.max(max, a.g())
        break
    }
  })

  return sum * max
}

This is great. It gets the job done. And its not too verbose. How does it look in fp-ts?

import * as A from 'fp-ts/lib/Array'
import * as NEA from 'fp-ts/lib/NonEmptyArray'
import * as O from 'fp-ts/lib/Option'
import * as E from 'fp-ts/lib/Either'
import { pipe } from 'fp-ts/lib/function'

const compute = (arr: Array<Foo | Bar>) =>
  pipe(
    A.array.partitionMap(arr, (a) =>
      a._tag === 'Foo' ? E.left(a) : E.right(a),
    ),
    ({ left: foos, right: bars }) => {
      const sum = A.array.reduce(foos, 0, (prev, foo) => prev + foo.f())
      const max = A.array.reduce(bars, Number.NEGATIVE_INFINITY, (max, bar) =>
        Math.max(max, bar.g()),
      )

      return sum * max
    },
  )

You probably think this looks ugly and verbose. And you would be are correct. But however, isn't functional code suppose to be more concise? The problem with this is, we have to write a lot what I called plumbing code to reduce the sum and the max to a single numeric value.

To clean this up, we need to learn about Semigroups and Monoids.

Semigroups

A Semigroup is a type that is able to take two homogenous values and produce a single homogenous value. Semigroups must implement a function known as concat. An example of a concat operation is addition: given two numbers, we can concatenate them together by addition to produce a single number.

The type definition for a Semigroup looks like this.[^1]

export interface Semigroup<A> {
  readonly concat: (x: A, y: A) => A
}

This is useful to us because we can use it to generalize the addition operation prev + foo.f() from our reduce function.

Also important to note is, when implementing a Semigroup, we don't need to literally concat both elements x and y, we just need to produce a number. For example you could have a semigroup that always returns one.

const onlyOne: Semigroup<number> = {
  concat: (_, _) => 1,
}

What this also means is that we can implement a semigroup for finding the max of our bars.

const semigroupMax: Semigroup<number> = {
  concat: (x, y) => Math.max(x, y),
}

Or more concisely.

const semigroupMax: Semigroup<number> = {
  concat: Math.max,
}

Going back to our original problem domain, we can see how this paradigm can be useful for sum and maximum operations. However, we have a problem. The function takes two elements. What happens if our input array is empty?

To solve this problem we need to learn about Monoids.

Monoids

Monoids are an extension of Semigroup but it also includes the empty or default element.

In fp-ts, this is what the type definition looks like

export interface Monoid<A> extends Semigroup<A> {
  readonly empty: A
}

If you go back to the reduce functions we wrote previously, we specified 0 as the empty element for addition and Number.NEGATIVE_INFINITY for Math.max. We would plug in the same values for a monoid.

For example, we can create a monoidMax by extending semigroupMax.

import { Monoid } from 'fp-ts/lib/Monoid'

const monoidMax: Monoid<number> = {
  concat: semigroupMax.concat,
  empty: Number.NEGATIVE_INFINITY,
}

Now we can replace our reduce functions with foldMap functions alleviating the responsibility of the reduction to the monoid.[^2]

import { Monoid, monoidSum } from 'fp-ts/lib/Monoid'

const compute = (arr: Array<Foo | Bar>) =>
  pipe(
    A.array.partitionMap(arr, (a) =>
      a._tag === 'Foo' ? E.left(a) : E.right(a),
    ),
    ({ left: foos, right: bars }) => {
      const sum = A.array.foldMap(monoidSum)(foos, (foo) => foo.f())
      const max = A.array.foldMap(monoidMax)(bars, (bar) => bar.g())

      return sum * max
    },
  )

Hey, that's nice! Its less verbose and its clear what the function does now. Let's extend our usecase and have a condition where we want to swap the operations. That is, Math.max on foos and sum on bars.

With monoids this is very easy, we can create a higher order function and dynamically create the behaviour we want.

const compute = (fooMonoid: Monoid<number>, barMonoid: Monoid<number>) => (
  arr: Array<Foo | Bar>,
) =>
  pipe(
    A.array.partitionMap(arr, (a) =>
      a._tag === 'Foo' ? E.left(a) : E.right(a),
    ),
    ({ left: foos, right: bars }) => {
      const sum = A.array.foldMap(fooMonoid)(foos, (foo) => foo.f())
      const max = A.array.foldMap(barMonoid)(bars, (bar) => bar.g())

      return sum * max
    },
  )

declare const i: number
if (i % 2 === 0) {
  compute(monoidSum, monoidMax)
} else {
  compute(monoidMax, monoidSum)
}

Whereas imperatively it might look something like this.

function compute(arr: Array<Foo | Bar>, invert: boolean) {
  let sum = 0
  let max = Number.NEGATIVE_INFINITY

  arr.forEach((a) => {
    switch (a._tag) {
      case 'Foo':
        if (invert) {
          max = Math.max(max, a.f())
        } else {
          sum += a.f()
        }
        break
      case 'Bar':
        if (invert) {
          sum += a.g()
        } else {
          max = Math.max(max, a.g())
        }
        break
    }
  })

  return sum * max
}

From this you can understand, the imperative approach gets much worse as the cyclomatic complexity increases. Whereas in functional programming, because it so composable, allows use to easily change behaviours of our program without creating additional complexity in the code.

That's all for this post. As always, if you like this kind of content, please give me a follow on Twitter and send me a DM or email for what you want to see next!

[^1]: Actually Semigroup inherits from Magma which is generalization of Semigroup. The difference Semigroups operations are associative. See the fp-ts definitions for Semigroup and Magma.

[^2]: Note I imported monoidSum which is just a monoid for addition.

⚠️ Disclaimer Warning

fp-ts is now dead. Please use effect-ts instead.

Update 2024: effect-ts is the recommended library for functional programming in TypeScript.

Introduction

This is the third post in my series on learning fp-ts the practical way. In my last post, I introduced the Option type and the map, flatten, and chain operators.

This post will introduce two concepts in fp-ts: asynchronous tasks and error handling. Namely we will look at the Task, Either, and TaskEither types.

Task

Every asynchronous operation in modern Typescript is done using a Promise object. A task is a function that returns a promise which is expected to never be rejected.

The type definition for task can be found below.

interface Task<A> {
  (): Promise<A>
}

Another way to define task is using a function type definition.

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

Tasks are expected to always succeed but can fail when an error occurs outside our expectations. In this case, the error is thrown and breaks the functional pipeline. An analogy to this is awaiting a Promise that throws an error without putting a try-catch-finally block in front. Test your assumptions before using Task.

Why use Tasks?

A Task is more than a glorified promise; it is also an expression of intent.

From a client perspective, when you are using a library, all asynchronous functions will have a type definition that returns a Promise<T>. Some of the functions might never fail but are asynchronous out of necessity. A Promise provides no indication about whether the function can fail. As such, in the imperative model, you are forced to handle these errors using a try-catch-finally block.

By using Task<T>, we relieve the burden on the client to handle errors that don't exist.

When can an operation "never fail"?

In the age of distributed computing, errors are the norm. Languages like Go and Rust embrace this model by forcing you to handle errors. To understand when an operation can never fail, we must first understand the most common ways a function can fail in the first place.

Functions commonly fail because of invalid preconditions. Take the function below, where the precondition is the length of id must be less than or equal to 36.

async function someTask(id: string) {
  if (id.length > 36) {
    throw new Error('id must have length less than or equal to 36')
  }

  // do async work here
}

If we knew the exact implementation of the function and we knew all errors stem from pre-condition failing, then we can assume the function will never fail if and only if we know the length of id is <= 36. As such, we can wrap the function into a Task and argue it never fails.

const id = 'abc'
const task: T.Task<void> = () => someTask(id)

In general, we don't make these assumptions because we don't always know the implementation. It's also risky because the implementation can change without us knowing.

Handled Failures Can't Fail

A more real-world example is when you have an operation that can fail, but is handled by reducing both the success and failure outcomes into a single type. Since the error has been handled, the function, although asynchronous, will always return a Promise that is fulfilled.

Take this function that reduces both the success and failure outcomes into a boolean result.

async function boolTask(): Promise<boolean> {
  try {
    await asyncFunction()
    return true
  } catch (err) {
    return false
  }
}

By definition, this function already implements the Task interface, but because the return type is a Promise, the result is still ambiguous to the client. We can remove the ambiguity by adjusting the syntax.

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

const boolTask: Task<boolean> = async () => {
  try {
    await asyncFunction()
    return true
  } catch (err) {
    return false
  }
}

Constructors

Any arbitrary value can become a Task by using the of operator to lift it into the Task world. This is equivalent to calling Promise.resolve.

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

const foo = 'asdf' // string
const bar = T.of(foo) // T.Task<string>

// Same As
const fdsa: T.Task<string> = () => Promise.resolve(foo)

Either

An Either is a type that represents a synchronous operation that can succeed or fail. Much like Option, where it is Some or None, the Either type is either Right or Left. Right represents success and Left represents failure. It is analogous to the Result type in Rust.

As such, we get the following type definitions.

type Either<E, A> = Left<E> | Right<A>

export interface Left<E> {
  readonly _tag: 'Left'
  readonly left: E
}

export interface Right<A> {
  readonly _tag: 'Right'
  readonly right: A
}

The Either type is a union type of Left and Right. The _tag field is used as a discriminator to differentiate between Left and Right.

Why use Eithers

Eithers are essential for capturing error states in functional programming. We need the Eithers because we cannot break pipelines by throwing errors. Error states must either be handled or propagated up the call stack.

Eithers are also advantageous to their try-catch-finally counterparts because the error is always type-safe. When you use a catch block, the error is always of type unknown. This is inconvenient for you as the client because you need to use instanceof to narrow down the error type. Even worse is when you are forced to define your own custom type guards to do the same thing.

With Eithers, we know every possible error state based on the type signature. We can choose to handle them in a switch statement or continue to propagate up the call stack.

Eithers in Action

Let’s contrive an example where we are validating a password for security. The password must be at least 8 characters long and have at least 1 capital letter. If the password is valid, we will hash it using a very insecure md5 hash.

1. Create 2 error classes to represent the two different error states. Join them together into a discriminated union.

// password.ts

export class MinLengthValidationError extends Error {
  public _tag: 'PasswordMinLengthValidationError'

  public minLength: number

  private constructor(minLength: number) {
    super('password fails to meet min length requirement: ${minLength}')
    this._tag = 'PasswordMinLengthValidationError'
    this.minLength = minLength
  }

  public static of(minLength: number): MinLengthValidationError {
    return new MinLengthValidationError(minLength)
  }
}

export class CapitalLetterMissingValidationError extends Error {
  public _tag: 'PasswordCapitalLetterMissingValidationError'

  private constructor() {
    super(`password is missing a capital letter`)
    this._tag = 'PasswordCapitalLetterMissingValidationError'
  }

  public static of(): CapitalLetterMissingValidationError {
    return new CapitalLetterMissingValidationError()
  }
}

export type PasswordValidationError =
  | MinLengthValidationError
  | CapitalLetterMissingValidationError

Note we are using the Error class instead of declaring the error as a plain object because it comes with built-in stack-trace, which is necessary for debugging.

2. Declare the Password Type

// password.ts

export interface Password {
  _tag: 'Password'
  value: string
  isHashed: boolean
}

3. Create the constructors for the Password Type

// password.ts

export function of(value: string): Password {
  return { _tag: 'Password', value, isHashed: false }
}

export function fromHashed(value: string): Password {
  return { _tag: 'Password', value, isHashed: true }
}

4. Validate the password using a Password specification.

// password.ts

export type PasswordSpecification = {
  minLength?: number
  capitalLetterRequired?: boolean
}

export function validate({
  minLength = 0,
  capitalLetterRequired = false,
}: PasswordSpecification = {}) {
  return (password: Password): E.Either<PasswordValidationError, Password> => {
    if (password.value.length < minLength) {
      return E.left(MinLengthValidationError.of(minLength))
    }

    if (capitalLetterRequired && !/[A-Z]/.test(password.value)) {
      return E.left(CapitalLetterMissingValidationError.of())
    }

    return E.right({ ...password, isValidated: true })
  }
}

Notice how validate doesn't return a Password type directly, but a function that returns a Password type. We could have put the PasswordSpecification and Password as parameters to a single function, but the reason why we want to separate them is to make function chaining easier.

When we construct the Password using of or fromHashed, we want to directly pipe the result of that function, Password, into the next function. If our validate function were to take two parameters instead of one, it would break the whole flow. This methodology of splitting function parameters is called currying.

You may also notice we can only propagate a single error upwards. But what if multiple validations fail? It would be better to propagate all of them. We will learn about this in the next post.

5. Define a hash function that takes a curried hash function.

// password.ts

export type HashFn = (value: string) => string

export function hash(hashFn: HashFn) {
  return (password: Password): Password => ({
    ...password,
    value: hashFn(password.value),
    isHashed: true,
  })
}

6. Create a pipeline

// index.ts

import { flow, identity, pipe } from 'fp-ts/lib/function'
import * as Password from './password'
import crypto from 'crypto'
import * as E from 'fp-ts/lib/Either'

const pipeline = flow(
  Password.of,
  Password.validate({ minLength: 8, capitalLetterRequired: true }),
  E.map(
    Password.hash((value) =>
      crypto.createHash('md5').update(value).digest('hex'),
    ),
  ),
)

7. Test using an invalid password

console.log(pipe('pw123', pipeline))

Produces the following:

{
  _tag: 'Left',
  left: Error: password fails to meet min length requirement: 8
      at new MinLengthValidationError (/tmp/either-demo/password.ts:9:5)
      at Function.MinLengthValidationError.of (/tmp/either-demo/password.ts:15:12)
      at /tmp/either-demo/password.ts:61:46
      at /tmp/either-demo/node_modules/fp-ts/lib/function.js:92:27
      at Object.pipe (/tmp/either-demo/node_modules/fp-ts/lib/function.js:190:20)
      at Object.<anonymous> (/tmp/either-demo/index.ts:16:13)
      at Module._compile (internal/modules/cjs/loader.js:1118:30)
      at Module.m._compile (/tmp/either-demo/node_modules/ts-node/src/index.ts:858:23)
      at Module._extensions..js (internal/modules/cjs/loader.js:1138:10)
      at Object.require.extensions.<computed> [as .ts] (/tmp/either-demo/node_modules/ts-node/src/index.ts:861:12) {
    _tag: 'PasswordMinLengthValidationError',
    minLength: 8
  }
}

Due to the way Node prints errors, left doesn't look like a regular typescript object. The underlying object looks like this.

{
  _tag: 'Left',
  left: {
    message: 'password fails to meet min length requirement: 8',
    stack: `Error: password fails to meet min length requirement: 8
      at new MinLengthValidationError (/tmp/either-demo/password.ts:9:5)
      at Function.MinLengthValidationError.of (/tmp/either-demo/password.ts:15:12)
      at /tmp/either-demo/password.ts:61:46
      at /tmp/either-demo/node_modules/fp-ts/lib/function.js:92:27
      at Object.pipe (/tmp/either-demo/node_modules/fp-ts/lib/function.js:190:20)
      at Object.<anonymous> (/tmp/either-demo/index.ts:16:13)
      at Module._compile (internal/modules/cjs/loader.js:1118:30)
      at Module.m._compile (/tmp/either-demo/node_modules/ts-node/src/index.ts:858:23)
      at Module._extensions..js (internal/modules/cjs/loader.js:1138:10)
      at Object.require.extensions.<computed> [as .ts] (/tmp/either-demo/node_modules/ts-node/src/index.ts:861:12)`
    _tag: 'PasswordMinLengthValidationError',
    minLength: 8
  }
}

8. Test using a valid password.

console.log(pipe('Password123', pipeline))

Produces the following:

{
  _tag: 'Right',
  right: {
    _tag: 'Password',
    value: '42f749ade7f9e195bf475f37a44cafcb',
    isHashed: true,
    isValidated: true
  }
}

Chaining Eithers

What if hash was an operation that could also fail and return an Either? We can chainW operator to chain both validate and hash into a single Either type. We'll use the base Error type to represent this error for simplicity's sake.

1. Update the hash function to return an Either

export type HashFn = (value: string) => E.Either<Error, string>

export function hash(hashFn: HashFn) {
  return (password: Password): E.Either<Error, Password> =>
    pipe(
      hashFn(password.value),
      E.map((value) => ({
        ...password,
        value,
        isHashed: true,
      })),
    )
}

2. Update the pipeline using chainW

const pipeline = flow(
  Password.of,
  Password.validate({ minLength: 8, capitalLetterRequired: true }),
  E.chainW(
    Password.hash((value) =>
      E.right(crypto.createHash('md5').update(value).digest('hex')),
    ),
  ),
)

The reason why we use chainW instead of chain because we want to widen the final type to include both errors from validate and hash. If you hover over pipeline to inspect the type, this is what you would get.

E.Either<
  MinLengthValidationError | CapitalLetterMissingValidationError | Error,
  Password
>

But if we swap chainW with chain, we would only get the final error type in the chain.

E.Either<Error, Password.Password>

But note, chain only works here because Error is a superclass of all 3 of our errors. If the left side of the generic to the function hash was not an Error, we would be forced to use chainW to cover the two Errors from validate.

You can run the source code here.

TaskEither

We know a Task is an asynchronous operation that can't fail. We also know an Either is a synchronous operation that can fail. Putting the two together, a TaskEither is an asynchronous operation that can fail.

Performing an HTTP request is a good demonstration of this functionality.

import axios from 'axios'
import { pipe } from 'fp-ts/lib/function'
import * as TE from 'fp-ts/lib/TaskEither'
;(async () => {
  const ok = await pipe(
    TE.tryCatch(
      () => axios.get('https://httpstat.us/200'),
      (reason) => new Error(`${reason}`),
    ),
    TE.map((resp) => resp.data),
  )()

  console.log(ok)
  // { _tag: 'Right', right: { code: 200, description: 'OK' } }
})()

Here we are making an http request using axios to httpstat which returns status code 200. An error will not occur because the http response is 200 –⁠ Ok. The right side gets printed out.

We can do the same thing for a 500 status code.

type Resp = { code: number; description: string }
;(async () => {
  const result = await pipe(
    TE.tryCatch(
      () => axios.get('https://httpstat.us/500'),
      (reason) => new Error(`${reason}`),
    ),
    TE.map((resp) => resp.data),
  )()

  console.log(result)
  /**
   * {
   *   _tag: 'Left',
   *   left: Error: Error: Request failed with status code 500
   *       at /tmp/either-demo/taskeither.ts:19:19
   *       at /tmp/either-demo/node_modules/fp-ts/lib/TaskEither.js:94:85
   *       at processTicksAndRejections (internal/process/task_queues.js:97:5)
   * }
   */
})()

Folding

If we're hitting the https://httpstat.us/200 endpoint, we can assume the operation will succeed and use the fold operator to convert the output into a Task.

import { absurd, constVoid, pipe, unsafeCoerce } from 'fp-ts/lib/function'

const result = pipe(
  TE.tryCatch(
    () => axios.get('https://httpstat.us/200'),
    () => constVoid() as never,
  ),
  TE.map((resp) => unsafeCoerce<unknown, Resp>(resp.data)),
  TE.fold(absurd, T.of),
) // Not executing the promise

// Result is of type:
// T.Task<Resp>

Notice how I'm passing T.of directly instead of creating an anonymous function that calls T.of. i.e. (a) => T.of(a).

Absurd is a function that takes a never and casts it to a generic type A, which in this case is Resp.

Asynchronously Error Handling

Sometimes your error handling is also asynchronous and this is common if you're doing a 2 Phase Commit. A good example is when you are processing a database transaction.

import { pipe } from 'fp-ts/lib/function'
import * as TE from 'fp-ts/lib/TaskEither'

declare function begin(): Promise<void>
declare function commit(): Promise<void>
declare function rollback(): Promise<void>

const result = pipe(
  TE.tryCatch(
    () => begin(),
    (err) => new Error(`begin txn failed: ${err}`),
  ),
  TE.chain(() =>
    TE.tryCatch(
      () => commit(),
      (err) => new Error(`commit txn failed: ${err}`),
    ),
  ),
  TE.orElse((originalError) =>
    pipe(
      TE.tryCatch(
        () => rollback(),
        (err) => new Error(`rollback txn failed: ${err}`),
      ),
      TE.fold(TE.left, () => TE.left(originalError)),
    ),
  ),
)

In this example, we try to rollback if the begin or commit operations fail and return the original error. If rollback also fails, we return the rollback error.

Conclusion

Error handling and asynchronous operations are core components of any application. By understanding Task, Either, and TaskEither, you now have the building blocks you need to develop a simple application.

If you found this post helpful, be sure to also follow me on Twitter.

⚠️ Disclaimer Warning

fp-ts is now dead. Please use effect-ts instead.

Update 2024: effect-ts is the recommended library for functional programming in TypeScript.

Introduction

This is the second post in my series on learning fp-ts the practical way. In my first post, I introduced the building blocks of fp-ts: pipe and flow. In this post, I will introduce the Option type.

Options

Options are containers that wrap values that could be either undefined or null. If the value exists, we say the Option is of the Some type. If the value is undefined or null, we say it has the None type.

In fp-ts, the Option type is a discriminated union of None and Some.

type Option<A> = None | Some<A>

Why should we use Option types in the first place? Typescript already has good ways to deal with undefined or null values. For example, we can use optional chaining or nullish coalescing.

Option types are useful because it gives us superpowers. The first superpower is the map operator.

Map

The map operator allows you to transform or intuitively map one value to another. Here is an example of a map function using the pipe operator and an anonymous function.

const foo = {
  bar: 'hello',
}

pipe(foo, (f) => f.bar) // hello

In this example, foo is mapped to foo.bar and we get the result 'hello'. Let's extend this further to handle the case where foo is possibly undefined using optional chaining.

interface Foo {
  bar: string
}

const foo = {
  bar: 'hello',
} as Foo | undefined

pipe(foo, (f) => f?.bar) // hello

As expected, we get 'hello' again. But we can do better here. We have a named variable f in our anonymous function. In general, we want to avoid this. This is because it puts us at risk of shadowing an outer variable. Another reason is the difficulty of naming the variable. It is named f, but you could name it nullableFoo. Bottom line is, there is no good name for this variable.

Let's use object destructuring to solve this problem.

pipe(foo, ({ bar }) => bar) // Property 'bar' does not exist on type 'Foo | undefined'.ts (2339)

Property 'bar' does not exist on type 'Foo | undefined'.ts (2339)

Oops. The compiler can't destructure an object that is possibly undefined.

Enter the Option type.

pipe(
  foo,
  O.fromNullable,
  O.map(({ bar }) => bar),
) // { _tag: 'Some', value: 'hello' }
pipe(
  undefined,
  O.fromNullable,
  O.map(({ bar }) => bar),
) // { _tag: 'None' }

After replacing the anonymous function with a map function from the Option module, the compiler no longer complains. Why is this?

Let's start by looking at the output of both pipes. In the first pipe, we have { _tag: 'Some', value: 'hello' }. This is in comparison to the original output, 'hello'. Likewise, the second pipe does not output undefined but instead, outputs { _tag: 'None' }.

Intuitively, this must imply our map function is not operating over the raw values: 'hello' or undefined but rather, over a container object.

The second operation in our pipe function, O.fromNullable creates this container object. It lifts the nullable value into the container by adding a _tag property to discriminate whether the Option is Some or None. The value is dropped if the _tag is None.

Going back to our map function. How does O.map work over the Option container? It works by performing a comparison over the _tag property. If the _tag is Some, it transforms the value using the function passed into map. In this case, we transformed it using ({ bar }) => bar. However, if the _tag is None, no operation is performed. The container remains in the None state.

Flatten

How would we handle a situation where the object has sequentially nested nullable properties? Let's extend the example we had above.

interface Fizz {
  buzz: string
}

interface Foo {
  bar?: Fizz
}

const foo = { bar: undefined } as Foo | undefined

pipe(foo, (f) => f?.bar?.buzz) // undefined

To make this work with optional chaining, we only needed to add another question mark. How would this look like using the Option type?

pipe(
  foo,
  O.fromNullable,
  O.map(({ bar: { buzz } }) => buzz),
)

Property 'buzz' does not exist on type 'Fizz | undefined'.ts (2339)

Sadly, we run in the same problem we had before. That is, object destructuring cannot be used over a type that is possibly undefined.

What we can do is lift both foo and bar into Option types using O.fromNullable twice.

pipe(
  foo,
  O.fromNullable,
  O.map(({ bar }) =>
    pipe(
      bar,
      O.fromNullable,
      O.map(({ buzz }) => buzz),
    ),
  ),
) // { _tag: 'Some', value: { _tag: 'None' } }

But now we've created two new problems. First, it's horribly verbose. Second, we have a nested Option. Look at the _tag of both the outer and inner Option. The first one is Some, which we expect because foo.bar is defined. The second one is None because foo.bar.buzz is undefined. If you only cared about the result of the final Option, you would need to traverse the Option's nested list of tags every time.

Given that we only care about the final Option, could we flatten this nested Option into a single Option?

Introducing the O.flatten operator.

pipe(
  foo,
  O.fromNullable,
  O.map(({ bar }) =>
    pipe(
      bar,
      O.fromNullable,
      O.map(({ buzz }) => buzz),
    ),
  ),
  O.flatten,
) // { _tag: 'None' }

We now have a single Option, { _tag: 'None' } that represents the last Option in the pipeline. If we wanted to check whether this Option was Some or None, we can pipe the result into O.some or O.none.

However, we still have the problem of verbosity. It would be beneficial if we could both map and flatten the nested option with a single operator. Intuitively, this is often called a flatmap operator.

Chain (Flatmap)

In fp-ts, the flatmap operator is called chain. We can refactor the above code into the following.

pipe(
  foo,
  O.fromNullable,
  O.map(({ bar }) => bar),
  O.chain(
    flow(
      O.fromNullable,
      O.map(({ buzz }) => buzz),
    ),
  ),
) // { _tag: 'None' }

In short, we achieve the same result with less.

Conclusion

In most cases, you won't need to use Option; optional chaining is less verbose. But the Option type is more than just checking for null. Options can be used to represent failing operations. And just like how you can lift undefined into an Option, you can also lift an Option into another fp-ts container, like Either.

Checkout the official Option documentation for more info.

⚠️ Disclaimer Warning

fp-ts is now dead. Please use effect-ts instead.

Update 2024: effect-ts is the recommended library for functional programming in TypeScript.

Introduction

This post is an introduction to fp-ts, a functional programming library for Typescript. Why should you be learning fp-ts? The first reason is better type safety. Fp‑ts allows you to make assertions about your data structures without writing user-defined type guards or using the as operator. The second reason is expressiveness and readability. Fp-ts gives you the tools necessary to elegantly model a sequence of operations that can fail. All in all, you should add fp-ts to your repertoire of tools because it will help you write better Typescript programs.

Contrary to popular opinion, you don’t need to understand complex mathematics to learn functional programming. In truth, you just need to get a feel for how each operator works. Once you get a handle on the basic operators, you can go back and review the mathematics. With this in mind, this post and the ones that follow, I will introduce functional programming from a practical perspective, avoiding mathematical jargon unless necessary.

The Pipe Operator

The basic building block of fp-ts is the Pipe operator. Intuitively, you can use the operator to chain a sequence of functions from left-to-right. The type definition of pipe takes an arbitrary number of arguments. The first argument can be any arbitrary value and subsequent arguments must be functions of arity one. The return type of a preceding function in the pipeline must match the input type of the subsequent function.

Let's look at how to pipe simple addition and multiplication functions.

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

function add1(num: number): number {
  return num + 1
}

function multiply2(num: number): number {
  return num * 2
}

pipe(1, add1, multiply2) // 4

The result of this operation is 4. How did we arrive at this result? Let’s look at the steps.

1. We start with the value of 1.
2. 1 is piped into the first argument of add1 and add1 is evaluated to 2 by adding 1.
3. The return value of add1, 2 is piped into the first argument multiply2 and is evaluated to 4 by multiplying by 2.

Currently our pipeline inputs a number and outputs a new number. Is it possible to transform the input type to another type, like a string? The answer is yes. Let’s add a toString function at the end of the pipeline.

function toString(num: number): string {
  return `${num}`
}

pipe(1, add1, multiply2, toString) // '4'

Now our pipeline evaluates to ’4’. What happens if we were to put toString between add1 and multiply2? We get a compile error because the output type of toString, string does not match the input type of multiply2, number.

pipe(1, add1, toString, multiply2)

Argument of type '(num: number) => string' is not assignable to parameter of type '(b: number) => number'. Type 'string' is not assignable to type 'number'.ts (2345)

In short, you can use the pipe operator to transform any value using a sequence of functions. The flow of control can be modelled as follows. [^1]

A -> (A->B) -> (B->C) -> (C->D)

The Flow Operator

The flow operator is almost analogous to the pipe operator. The difference being the first argument must be a function, rather than any arbitrary value, say a number. The first function is also allowed to have an arity of more than one.

For example, we could wrap our three functions inside of the flow operator.

import { flow } from 'fp-ts/lib/function'

pipe(1, flow(add1, multiply2, toString))
flow(add1, multiply2, toString)(1) // this is equivalent

In comparison, to the pipe operator, this is what the "flow" of control looks like for the flow operator. [^2]

(A->B) -> (B->C) -> (C->D) -> (D->E)

What is a good use case for the flow operator? When should you use it over the pipe operator? A general rule of thumb is when you want to avoid using an anonymous function. In Typescript, a good example of an anonymous function are callbacks.

Lets declare a function, concat with arity of 2. The first argument will be a number. The second argument is a callback that takes a number as its first argument and transforms it into a string. The function returns the first value and the transformed second value as a two dimensional tuple.

function concat(
  a: number,
  transformer: (a: number) => string,
): [number, string] {
  return [a, transformer(a)]
}

Using our previous repertoire of functions, we can compose a callback for this function. Here is an example using the pipe operator.

concat(1, (n) => pipe(n, add1, multiply2, toString)) // [1, '4']

What’s the problem with this? The problem is we have to declare n as part of an anonymous function to use it with the pipe operator. You should avoid this because it puts you at risk of shadowing a variable in the outer scope. It is also more verbose.

The solution is to use the flow operator and remove the anonymous function. This works because the return value of flow is a function itself. The signature of this function is number -> string which is exactly the same as the callback signature.

concat(1, flow(add1, multiply2, toString)) // [1, '4']

Appendix

• Pipe Typescript Definition
• Flow Typescript Definition

The first step to becoming a good developer is to understand your text editor. Like many, I use VSCode and over the years I have discovered features that I failed to realize even existed. These features have improved my productivity and my confidence as a developer. As such, I am obliged to share, in this post, the hotkeys that have improved my editing experience the most.

The first two categories of hotkeys I will introduce are Command and Navigation. The command palette is an important tool because it allows you to explore the full range of possibilities that exist in the editor. Likewise, navigation is important because it helps you dig into a codebase and follow links between dependencies easily. However, the deeper you go, the more important it is to know how to navigate back to where you came from. The Editing category is all about maximizing keyboard usage efficiency and avoiding unnecessary usage of the mouse. Getting your cursor in the right position or selecting blocks of text are examples of keyboard usage efficiency.

Command Palette

Keyboard Shortcut: Ctrl+Shift+P

The command palette is like Google in your browser; it lets you discover what is possible in your editor. When you open the command palette, you will notice the search bar is prefixed with >. This is how VSCode knows you are inputting a command. If you remove the >, it becomes a search engine for any files in your current working directory.

Reload Window

The first command I will introduce is Reload Window. This handy when your terminal freezes or when an extension that requires a reload is updated; Its less work than manually closing VSCode and reopening it. Another reason is the interoperability between Linux machines and NVIDIA graphics cards. From my experience, whenever my computer wakes up from sleep, the integrated terminal becomes corrupted with visual artifacts. There are two ways of fixing this: kill all your terminals or reload the window; I choose the latter option.

Format Document

The second command is Format Document. I rarely use this command when I'm programming because I have Format on Save turned on. When trying to debug, it comes in handy. The most common use-case is when I want to read the minified JSON printed in terminal. To do this, I create a new file, paste the minified JSON, set the language to JSON, and run the Format Document.

Save Without Formatting

Similarly, the third command is Save without Formatting. This command is useful when you are working on a team with a repository that is riddled with linter and formatting errors. Assuming you have Format on Save turned on, saving any file in this repository would create a large Git diff; its courtesy for small changes to have small diffs. Leave the formatting for a separate, isolated PR.

Navigation

Go to Definition

Keyboard Shortcut: F12

Go to Definition is your bread and butter for navigation. Use this when you are integrating with third party libraries. Being able to inspect the function definition and type declaration is essential because it gives you a better understanding about how the library was designed to be used. My biggest qualm with Go To Defintion is getting stuck in a ditch because I'm using the command recursively. Its easy to get lost because its so hard to retrace through all the new files that were opened. The key discovery to overcome this is the Go Back operation.

Go Back/Forward

Keyboard Shortcut: CTRL+ALT+➖/CTRL+ALT+➕

Go Back is self explanatory, it lets you go back after a navigation command. What I despise about Go Back is when you have the same file opened in two split panes, the Go Back operation refocuses the window on the wrong pane. What I expect is for it to go back to the pane I called Go To Definition in. Go Forward is the same story but in reverse.

Control Arrow Keys / Home / End

Keyboard Shortcuts: CTRL+ALT+LEFT_ARROW,CTRL+ALT+RIGHT_ARROW, HOME, END

I'm sure you've seen somebody who just holds down the arrow key on their keyboard and waits for the cursor to move to the right spot. That is extremely inefficient and wasteful. Jump between words and delimiters using Control Arrow Keys. If the distance is too far, use the Home and End buttons to your advantage.

Editing

Cut

Keyboard Shortcut: Ctrl+X

I use the cut hotkey to delete lines more often than to actually cut and paste text. This is because you can cut a line if you have nothing selected under your cursor. I find this to be more effective than the delete line hotkey because there are less bindings I need to remember, CTRL+X is simple to build into muscle memory, and you always have the option of repasting the line.

Column Select

Keyboard Shortcut: ALT+DOWN_ARROW/ALT+UP_ARROW

Column select is necessary when you are trying to select lines that have the same column delimiter or prefix. This video shows how I column selected in front of import, used Control Arrow Keys to select it all and replaced it with a require statement.

Add Current Word To Selection

Keyboard Shortcut: Ctrl+W

Add Current Word To Selection is useful when you want to select the word thats under your cursor quickly. Often times I use this to delete the word or use it to pre-fill a Find (CTRL+F) command.

Conclusion

These are all the hotkeys you need to be an effective and quick developer. Checkout the video below for a combination of most of them. 😉

String enums were a feature that was introduced in version 2.4. Since then, we have preferred using string enums over numeric enums because it better demonstrate the developer's intent. However, there a severe drawbacks to the usage of string enums; strong-typing being one of them. This has been detrimental to the Typescript developer experience because tools outside of an individual developer control such as software development kits and code generation tools are filled with string enums.

In this post I will teach you about the problems enums were meant to solve and its drawbacks. I will demonstrate how constant objects and discriminated unions work and how they can be used as an alternative to string enums.

The Problem Enums Were Meant to Solve

Imagine you had two sets of values. One for credit card type: VISA, Mastercard, AMEX and one for shipping type: Standard, Express, Next-Day. Logically, we can group these sets in two separate enums.

enum CreditCardType {
  VISA,
  MASTERCARD,
  AMEX
}

enum ShippingType {
  STANDARD,
  EXPRESS,
  NEXTDAY
}

Each enum member has an underlying sequential value. In this case, it ranges from 0-2. Hence, what would happen if we were to compare VISA to STANDARD? Both have an underlying value of 0. It must follow that they are equal. Or so we may think.

In a statically typed language, the compiler would prevent this comparison. It would be illogical to compare a credit card type with a shipping type. Hence, every enum must have its own unique type. From an object-oriented perspective, you can consider every enum to be a class.

String Enums

String enums are a considerable upgrade from numerical enums. This is because it gives the underlying data type a comprehensible value. It also makes debugging easier because it is identifiable in a print statement.

Here is what the two enums above would look like as string enums.

enum CreditCardType {
  VISA = 'VISA',
  MASTERCARD = 'MASTERCARD',
  AMEX = 'AMEX'
}


enum ShippingType {
  STANDARD = 'STANDARD',
  EXPRESS = 'EXPRESS',
  NEXTDAY = 'NEXTDAY'
}

If we were to compare VISA to STANDARD again, they would not be equal because the underlying values are different. However, a statically typed compiler will still enforce the enum invariant. The comparison remains impossible. The illogical nature of comparing a credit card type to a shipping type has not changed.

Drawbacks of String Enums

If strong typing was a benefit for numeric enums, it is huge drawback for string enums.

Imagine you are using an SDK provided by a third party for their shipping service. They provide an interface using the ShippingType enum above. For business reasons, you only want your customers to specify standard or express shipping. You decide to create you own enum for your web application controller. Because your enum is narrower than the SDK's enum, you expect there to be no problem passing it straight the SDK.

namespace FastShippersCo {
  export enum ShippingType {
    STANDARD = 'STANDARD',
    EXPRESS = 'EXPRESS',
    NEXTDAY = 'NEXTDAY',
  }

  export interface ShippingService {
    ship(type: ShippingType): void
  }
}

namespace TShirtsOnline {
  enum OrderShippingType {
    STANDARD = 'STANDARD',
    EXPRESS = 'EXPRESS',
  }

  class ShippingDetailsDTO {
    type!: OrderShippingType
  }

  declare const shippingService: FastShippersCo.ShippingService
  declare const shippingDetails: ShippingDetailsDTO

  // Argument of type 'OrderShippingType' is not assignable to parameter of type 'ShippingType'. ts(2345)
  // highlight-next-line
  shippingService.ship(shippingDetails.type)
}

Argument of type OrderShippingType is not assignable to parameter of type ShippingType.

The purpose of strong typing was to prevent accidents when comparing numeric enums. There are no accidents for string enums. The developer's intent is always clear. The compiler error here is a real pain to deal with because it causes unnecessary obstruction. Compounded with the fact that there are no easy ways around it.

Casting is not a solution.

shippingService.ship(shippingDetails.type as FastShippersCo.ShippingType)

Conversion of type OrderShippingType to type ShippingType may be a mistake because neither type sufficiently overlaps with the other. If this was intentional, convert the expression to unknown first. ts(2352)

Mapping works, but it is highly verbose.

switch (shippingDetails.type) {
  case OrderShippingType.STANDARD:
    shippingService.ship(FastShippersCo.ShippingType.STANDARD)
  case OrderShippingType.EXPRESS:
    shippingService.ship(FastShippersCo.ShippingType.EXPRESS)
}

Discriminated Unions

A great alternative to string enums are discriminated unions. The primary difference between a string enum and a discriminated union is the lack of strong typing. This is exactly what we want.

export type ShippingType = 'STANDARD' | 'EXPRESS' | 'NEXT_DAY'

There is a problem with this approach. We cannot directly reference the type without using a string literal. We want to preserve the ability to do this:

const shippingType = FastShippersCo.ShippingType.STANDARD

What we could also do is also export an object containing the enums values and extract the type based on the enum's values. Remember we can export a type and an object with the same name because types are erased after transpilation.

export const ShippingType = {
  STANDARD: 'STANDARD' as 'STANDARD',
  EXPRESS: 'EXPRESS' as 'EXPRESS',
  NEXTDAY: 'NEXTDAY' as 'NEXTDAY',
}

export type ShippingType =
  | typeof ShippingType.STANDARD
  | typeof ShippingType.EXPRESS
  | typeof ShippingType.NEXTDAY

We can make a minor adjustment using as const to prevent code duplication.

export const ShippingType = {
  STANDARD: 'STANDARD',
  EXPRESS: 'EXPRESS',
  NEXTDAY: 'NEXTDAY',
} as const

export type ShippingType =
  | typeof ShippingType.STANDARD
  | typeof ShippingType.EXPRESS
  | typeof ShippingType.NEXTDAY

Finally, we can leverage keyof and typeof to turn our type into a one liner.

export const ShippingType = {
  STANDARD: 'STANDARD',
  EXPRESS: 'EXPRESS',
  NEXTDAY: 'NEXTDAY',
} as const

export type ShippingType = typeof ShippingType[keyof typeof ShippingType]

To understand how this works, first evaluate keyof typeof ShippingType. This is an expansion of all the keys in ShippingType.

'STANDARD' | 'EXPRESS' | 'NEXTDAY'

For each one of these values, it indexes the ShippingType object to get the following.

typeof ShippingType['STANDARD'] | typeof ShippingType['EXPRESS'] | typeof ShippingType['NEXTDAY']

This is what the final type looks like when we hover our mouse over it.

type FastShippersCo.ShippingType = 'STANDARD' | 'EXPRESS' | 'NEXTDAY'

Conclusion

Never use string enums. Always favour discriminated unions. Code generation tools, especially those written in other programming languages must be aware of this fact. Adoption of these tools will increase as more developers adopt OpenAPI standards. SDK designers and library designers must also take notice.