DEV Community: Ryan Lee

Leveraged Yield Farming on Alpha Homora Explained

Ryan Lee — Fri, 05 Mar 2021 04:26:11 +0000

Introduction

For the past couple of months, I've been getting my head deep inside of Alpha Homora V1, a platform for leveraged yield farming on Ethereum. Alpha Homora is a game changer for the Decentralized Finance (DeFi) ecosystem because you can leverage an undercollaterized position to earn high yields in a liquidity pool.

In this post, I'll provide a brief overview of yield farming, and then I'll go into the mechanics of how Alpha Homora works, what the quirks are, and how you can use Alpha Homora to maximize your position.

Be warned none of this should be considered financial advice. Do this at your own risk!

What are Liquidity Pools?

Before we get into Alpha Homora, lets get into the basics about yield farming, and more specifically, liquidity pools.

Liquidity pools are smart contracts that allow people to swap one token for another with a small fee attached. Liquidity pools are core components of DeFi because they are permissionless and do not require a centralized exchange to operate.

For liquidity pools to operate, they need well... liquidity! For example, if you want to swap Bitcoin (BTC) for Ethereum (ETH), the pool must have enough Ethereum to give you for that Bitcoin.

Hence, when we talk liquidity pools, we must also talk about the liquidity providers (LPs).

Who are Liquidity Providers?

LPs are those who supply tokens to a liquidity pool. For example, a LP provides liquidity to a ETH-WBTC pool by depositing an equal amount (based on market price) of Ethereum and Wrapped Bitcoin into the pool. In return, liquidity providers are given LP tokens that represents their ownership of the pool.

The benefits of being an LP are the fees that you earn for every swap. In a protocol like Uniswap, the pool takes a 0.30% cut; if you owned 1% of the tokens in the pool, then you would receive 1% of the 0.30% cut, i.e. 0.003%.

In addition, LPs benefit from farming pools that are incentivized by DeFi governance tokens issued by DeFi protocols and platforms. For example, if you farm an incentized pool on Sushiswap, you earn a fixed amount of SUSHI per day (based on your position), regardless of the number of swaps that occur.

A common strategy for liquidity providers is once they have accumulated a certain amount of a governance token, is to dump it on the market and trade it for more tokens to increase their position. However there is a tradeoff; the cost of gas for multiple transactions to makes it expensive to reinvest:

One Txn to claim the governance token
Two Txns to swap the governance token for the tokens in your pool
One Txn to swap the tokens for an LP token
One Txn to stake the LP token into the pool

In today's high gas fee world, compounding your position on platforms like Sushiswap or Uniswap are only worth it if you're position is so large that the amount of yield you earn makes the gas insignificant. High gas costs is whats causing people to other L1 chains like Binance Smart Chain (BSC) or L2 Decentralized Exchanges (DEXs) like Loopring due to their low fees.

The Risks of Yield Farming

If yield farming was free money, then everybody would be doing it right? Obviously there must be risks; one such being the smart contract being hacked but the other being what is known as impermanent loss or divergence loss.

Divergence loss is the loss you incur relative to if you had simply held your tokens. It occurs when an arbitrager takes advantage of the change in the price ratio of the assets in the pool. The more the price ratio diverges from the ratio at which you put your assets in, the worse your loss will be; this loss increases exponentially rather than linearly. Divergence loss is also referred to as impermanent loss because the loss can be reserved if the original price ratio is restored.

This post isn't about divergence loss, so if you want a deeper understanding of divergence loss, check out the Binance Academy article on it.

Yield Farming on Alpha Homora

Now that you understand the basics of yield farming, lets talk about yield farming on Alpha Homora!

The problem Alpha Homora solves is the lack of leveraged yield farming opportunities in today's DeFi market. If you wanted to take a leveraged position on ETH/WBTC on Sushiswap, you would first need to deposit some collateral in another platform like Aave, Compound, or the Iron Bank (CREAM Finance) and then borrow the token(s) you want to farm with. Then make another set of transactions to farm it. Alpha Homora makes it easy for you by bundling this all of this into a single transaction while also more efficient gas-wise.

Another benefit Alpha Homora provides is single-sided liquidity. Previously, I mentioned that if you wanted to farm an ETH/WBTC pool, you would need to hold 50% ETH and 50% WBTC to deposit. Alpha Homora gives the option to enter and exit a position with only ETH; the swap for WBTC happens inside of the contract.

But the best part about Alpha Homora V1 (not V2 since they removed it), is the gas-free compounding of the governance token you receive from farming. The way it works is you need to get one person (or bot) to reinvest on behalf of everyone else in the pool. That person will need to pay the gas fee but they will get a greater cut of the reinvestment as an incentive to do it. Usually, the pool will need to accumulate a large amount of the governance token before it beocmes profitable for somebody to reinvest; however the reality is there are a lot of stupid bots out there that do it at a loss. So in other words, its free money for you; QED.

Choosing a Leverage Ratio

Alpha Homora offers different leverage ratios for different pools. For example, you can take at most 1.75x leverage on an ETH/DPI pool and 2.5x leverage on a WBTC/ETH pool. Each pool also has a maximum debt ratio; if your position reaches this debt ratio, you will be liquidated. Likewise for ETH/DPI, the maximum debt ratio is 60% and for WBTC/ETH, the maximum debt ratio is 80%.

If you want to compute your initial debt ratio based on your leverage, its easy. The formula is (LEVERAGE-1.0)/LEVERAGE. So for example, if I take 1.75x leverage, my debt ratio will be 0.75/1.75 = ~0.4286. Similarity, if I take 2.5x leverage, that means my debt ratio will be 1.5/2.5 = 0.6.

The most important thing to understand when choosing a debt ratio is that your debt is dominated in ETH. This means you are shorting ETH relative to the other token in the pool. But the impact ETH going up relative to the other token in the pool on your debt ratio changes depending on your current leverage; this is due to the mechanics of liquidity pools.

The Mechanics and Dangers of Leveraged Yield Farming

To understand the mechanics of leverage yield farming, I will outline a basic example.

Lets assume you opened an ETH/DPI position at 1.75x leverage with 10 ETH and we will also assume there were no gas or slippage costs to keep the numbers nice. Lets also assume the price ratio between ETH:DPI is 1:4.

Your debt will be 7.5 ETH since you took 1.75x leverage. You will have 8.75 ETH (17.5/2) and you will have 35 DPI (8.75*4). Which means your real ETH is actually 1.25.

So although the pool is a 50/50 pool, your ETH/DPI exposure is actually 12.5/87.5, which looks more like a Balancer pool.

Lets assume the price of ETH goes up 10% relative to DPI. Naively, you would think this would bring our debt ratio up to 47% from the initial 42%, based on this computation: (0.75*1.10)/1.75. But you also need to consider what happens to your assets when there is a price fluctuation (i.e impermanent loss); when the price of ETH goes up relative to DPI, your position in the pool will sell ETH and buy DPI to restore the 50/50 ratio. This means you debt ratio will rise even higher because you:

Own less ETH (you receive less benefit from ETH going up)
Have more DPI (which devalued against ETH)
Have a debt stayed the same (the value of your debt increased)

If the price of ETH were to continue going up, you can reach the point where you have net negative ETH (which is what you start with when you take on 2.5x leverage on the ETH/WBTC pool). Having negative ETH isn't necessarily a bad thing but you need to be careful because even though your position compounds based on trading fees and dumping governance tokens, your debt will also compound based on the borrow interest rate. Luckily, Alpha Homora gives you the ability to refill ETH in order lower your debt ratio when it gets too high.

Maximizing Exposure

Alpha Homora V1 is the perfect yield farming platform if you want to expose yourself heavily to one type of asset. This is not financial advice, but lets say you want to follow this guy's advice (I don't know this guy, nor do I follow him), and divide your portfolio into 50% ETH, 20% BTC, 30% DPI.

// Detect dark theme var iframe = document.getElementById('tweet-1352674884976078854-209'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1352674884976078854&theme=dark" }

A normal yield farm allocation for this portfolio would be 20/20 ETH/WBTC and 30/30 ETH/DPI. If ETH/BTC and ETH/DPI performs relatively the same, you suffer minimal impermanent loss and make excellent gains! But we don't know what will happen so you can look at some alternative strategies.

For example, you can put 20% of your portfolio into a ETH/WBTC position and 30% into a ETH/DPI position, both at maximum leverage. You get basically get full exposure to both assets while earning high yields at the same time. The rest of your portfolio is just ETH which you can deposit as Interest Bearing ETH (IbETH) on Alpha Homora and savour it if you ever need to refill.

This strategy is pretty noob friendly and you can also rebalance your positions every month if you so please. Whether it will outperform the former strategy or is even a good strategy at all, is beyond me.

Conclusion

Leveraged Yield Farming on Alpha Homora is a great product for maximizing your exposure to one asset. It comes with many risks especially because you are shorting ETH, but as long as you don't get liquidated, you should receive some handsome returns.

But please remember this is not financial advice. I'm just a software engineer exploring cool tech. I actually have no idea what I'm doing. Listen to me at your own peril.

Also if you're looking for a software engineer to join your crypto startup, DMs on Twitter and my email are open!

Happy Yield Farming!

Rust Pattern Matching Examples for Typescript Developers

Ryan Lee — Tue, 19 Jan 2021 16:05:11 +0000

Introduction

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.

Practical Guide to Fp-ts P6: The Do Notation

Ryan Lee — Fri, 13 Nov 2020 16:57:26 +0000

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:

of
map
chain (flatmap)
ap

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

Left Identity: of(x).chain(f) == of(f(x))
Right Identity: of(x).chain(of) = of(x)
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.

Monads are like "ships in a bottle". Taken from the Mostly Adequate Guide to Functional Programming

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,
}

Our new Option is still a monad but it certainly doesn't look like a container anymore because it always returns None.

If this trivial example passes the test for a monad, then what if we add a
console.log to each invocation? Is it still a monad?



const option = {
  of: <A>(a: A) => {
    console.log('of')
    return none
  },
  map: <A, B>(fa: Option<A>, f: (a: A) => B) => {
    console.log('map')
    return none
  },
  chain: <A, B>(fa: Option<A>, f: (a: A) => Option<B>) => {
    console.log('chain')
    return none
  },
  ap: <A, B>(fab: Option<(a: A) => B>, fa: Option<A>) => {
    console.log('ap')
    return none
  },
}

By definition, this still obeys all monadic laws, so its still a monad. But now that I've introduced a side effect, it doesn't look like a container anymore. These side effects are reminiscent of the IO monad; IO represents a synchronous side effect.

The point I'm trying to make here is: monads are not containers over values. Rather, monads are descriptions of effects. Monads allow you to describe where in your program you have side effects (IO, Task, etc...) and where you have effects that are pure and deterministic.

What does this mean for you as a programmer?

You should strive to push all side effects to the very exterior of your program and keep your core domain logic pure. For example, if you're building a webserver, isolate your web controller and database layer as much as possible because thats where the side effects occur.

In the advanced FP world this is accomplished through the use of Free Monads or Tagless Final, but that is out of the scope for this post.

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



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



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.

Note this comes from the fp-ts-contrib package. ↩
Note chainFirst is the equivalent of doL. ↩

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

Ryan Lee — Fri, 02 Oct 2020 03:03:38 +0000

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:

We have to awkwardly name our variables with a number suffix because we don't want to shadow the outer variable.
It doesn't scale if we have more parameters.
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.¹

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

Sequences and traversals use ap internally. ↩

Practical Guide to Fp-ts: P4 — Arrays, Semigroups, Monoid

Ryan Lee — Tue, 15 Sep 2020 01:58:08 +0000

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

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

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!

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. ↩
Note I imported monoidSum which is just a monoid for addition. ↩

Practical Guide to Fp-ts: P3 — Task, Either, TaskEither

Ryan Lee — Thu, 20 Aug 2020 13:42:13 +0000

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

async function someTask(id: string) {
  if (id.length > 36) {
    throw new Error('id must have length greater than 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.

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.

Declare the Password Type

// password.ts

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

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

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.

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,
  })
}

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'),
    ),
  ),
)

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

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.

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,
      })),
    )
}

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.

Practical Guide to Fp-ts P2: Option, Map, Flatten, Chain

Ryan Lee — Fri, 19 Jun 2020 03:41:41 +0000

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.

Practical Guide to Fp-ts P1: Pipe and Flow

Ryan Lee — Tue, 16 Jun 2020 00:14:12 +0000

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.

We start with the value of 1.
1 is piped into the first argument of add1 and add1 is evaluated to 2 by adding 1.
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. ¹

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

(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']

Pipe Typescript Definition ↩
Flow Typescript Definition ↩