https://dev.to/gcanti/interoperability-with-non-functional-code-using-fp-ts-432e

Act Zero: 10:15 Saturday Night

In which we will see how to use the type system to handle failure with the Either type and the Validation type.

Here we define some checks that all nightclubs make.

The checks can be specialised by providing a function that creates the error case. For Either this is left and for Validation this is failure.

Act One

First we can perform some checks using the monadic chain methods.

In fp-ts the Validation type does not implement the Monad class required for chaining but we can use the Either type with Left signifying failure.

Because we are using Monad the checks are fail-fast. That is, any failed check shortcircuits subsequent checks so even though we are returning the error as an Array<String> we will only ever get one error.

Act Two

An ideal nightclub would instead tell us everything that is wrong.

Applicative functors and Validation to the rescue!

This time we can use the Validation type to accumulate all errors via a Semigroup structure such as Array.

Act Three

As you can see above, collecting results from a large number of checks can get messy.

To make a large number of checks we can traverse over the checks.

There’s no specific support for immutability in the current (0.36) version of Flow (think of the readonly keyword in TypeScript), however let’s see how we can leverage some other features in order to get immutability for our data structures.

Objects

Objects are mutable by default

type Person = { name: string };

const person: Person = { name: 'Giulio' }

person.name = 'Guido' // ok

Starting from version 0.34 we can annotate properties with variance modifiers (see here for a detailed post about property variance). In short, if we annotate a property as covariant (+ symbol), we can read from but we can’t write to

type Person = { +name: string }; // <= covariance

const person: Person = { name: 'Giulio' }

person.name = 'Guido' // error (*)

(*) Covariant property `name` incompatible with contravariant use

Classes

Can we use the same trick to make class instances immutable?

class Person {
  name: string;
  constructor(name: string) {
    this.name = name
  }
}

new Person('Giulio').name = 'Guido' // <= no error

Of course but there’s a problem, Flow complains for the assignment of the property name in the constructor

class Person {
  +name: string; // <= covariance
  constructor(name: string) {
    this.name = name // error (*)
  }
}

(*) Covariant property `name` incompatible with contravariant use

Here’s a workaround

class Person {
  +name: string;
  constructor(name: string) {
    (this: any).name = name // ok
  }
}

new Person('Giulio').name = 'Guido' // error (*)

(*) Covariant property `name` incompatible with contravariant use

Arrays

Immutable arrays are tricky since we can’t leverage variance annotations. One option is to define a custom ReadonlyArray interface and two converting functions with (almost) zero cost abstraction

type ReadonlyArray<+A> = {
  '@@iterator()': Iterator<A>, // <= handy for..of
  +length: number,
  +[key: number]: void | A, // safe access by index
  map<B>(f: (a: A, ...rest: Array<empty>) => B): ReadonlyArray<B>
  // other non mutating methods...
};

function toReadonlyArray<T>(xs: Array<T>): ReadonlyArray<T> {
  return ((xs: any): ReadonlyArray<T>)
}

function toArray<T>(xs: ReadonlyArray<T>): Array<T> {
  return ((xs: any): Array<T>)
}

Usage

const xs = toReadonlyArray([1, 2, 3])

xs[0] = 4 // error (*)

(*) Covariant computed property incompatible with contravariant use

Alas Flow will complain about each individual usage of this interface when an array is expected

declare function f(xs: Array<any>): void;

f(xs) // error (*)

(*) This type is incompatible with the expected param type of array type

Ideally we should just have covariant interfaces, there’s an open feature request here and here.

EDIT: There’s $ReadOnlyArray<T> in version 0.38

The problem

This tutorial assumes that our data structures are immutable. To see why we might want to consider optics, we’ll look at a simple example. We’ll define two object types

type Street = { num: number, name: string };
type Address = { city: string, street: Street };

Given an instance of Address, getting the street name is quite simple

const a1: Address = 
  { city: 'london', street: { num: 23, name: 'high street' } }

const name = a1.street.name

Setting it to a new value is less so

const a2: Address = {
  ...a1,
  street: {
    ...a1.street,
    name: 'main street'
  }
}

As we can see working with values deep within the data structure starts to get awkward.

Lenses

A lens is a first-class reference to a subpart of some data type. Given a lens there are essentially three things you might want to do

• view the subpart
• modify the whole by changing the subpart
• combine this lens with another lens to look even deeper

A lens is nothing more than a pair of functions, a getter and a setter. The type S represents the whole, A the subpart

interface Lens<S, A> {
  get(s: S): A,
  set(a: A, s: S): S
}

Let’s define a lens for the type Address with focus on the street field

const address: Lens<Address, Street> = {
  get: address => address.street,
  set: (street, address) => ({ ...address, street })
}

address.get(a1)
// => {num: 23, name: "high street"}
address.set({num: 23, name: 'main street'}, a1)
// => {city: "london", street: {num: 23, name: "main street"}}

Now let’s define a lens for the type Street with focus on the name field

const street: Lens<Street, string> = {
  get: street => street.name,
  set: (name, street) => ({ ...street, name })
}

Is there a way to get a lens for the type Address with focus on the inner name field?

Composition

The great thing about lenses is that they compose

function composeLens<A, B, C>(ab: Lens<A, B>, bc: Lens<B, C>): Lens<A, C> {
  
  return {
    get: a => bc.get(ab.get(a)),
    set: (c, a) => ab.set(bc.set(c, ab.get(a)), a)
  }
}

Now handling the inner name is trivial

const streetName = composeLens(address, street)

streetName.get(a1)
// => "high street"
streetName.set('main street', a1)
// => {city: "london", street: {num: 23, name: "main street"}}

Note that our lenses can be composed of any number of other lenses.

Modify

Let’s say we need to set the first character of the address street name in upper case. Mapping a function over a part of a data structure given a lens is as simple as get the value, apply the function to the value, set the new value to be the result

function overLens<S, A>(lens: Lens<S, A>, f: (a: A) => A, s: S): S {
  return lens.set(f(lens.get(s)), s)
}

function capitalize(s: string): string {
  return s.substring(0, 1).toUpperCase() + s.substring(1)
}

overLens(streetName, capitalize, a1)
// => {city: "london", street: {num: 23, name: "High street"}}

Prisms

In the above example, we used capitalize to upper case the first letter of a string. It works but it would be clearer if we could use Lens to zoom into the first character of a string. However, we cannot write such a Lens because a Lens defines how to focus from an object S into a mandatory object A and in our case, the first character of a string is optional as a string might be empty. For this we need a sort of partial Lens.

Prisms work with cases like this. A simple way to put it is that a prism is like a lens, but to something which is or is not there.

Note: sometimes this kind of optics is named Optional.

interface Prism<S, A> {
  get(s: S): ?A,
  set(a: A, s: S): S
}

As you can see lenses and prisms are very similar, except that the getter in the prism returns a maybe type. Let’s write a prism for the first letter of a string

const first: Prism<string, string> = {
  get: s => s ? s.substring(0, 1) : null,
  set: (a, s) => s.length ? a + s.substring(1) : ''
}

Similarly to composeLens we can compose prisms obtaining again a prism

function composePrism<A, B, C>(ab: Prism<A, B>, bc: Prism<B, C>): Prism<A, C> {

  return {
    get: a => {
      const b = ab.get(a)
      return b == null ? null : bc.get(b)
    },
    set: (c, a) => {
      const b = ab.get(a)
      return b == null ? a : ab.set(bc.set(c, b), a)
    }
  }
}

All Lens can be seen as Prism where the optional element to zoom to is always present

function overPrism<S, A>
(prism: Prism<S, A>, f: (a: A) => A, s: S): S {
  const a = prism.get(s)
  return a ? prism.set(f(a), s) : s
}

function toUpper(s: string): string {
  return s.toUpperCase()
}

overPrism(composePrism(streetName, first), toUpper, a1)
// => {city: "london", street: {num: 23, name: "High street"}}

Union types

Prisms are applicable to all union types. How would we write a prism for a custom union type of our own?

type Domicile
  = { type: 'office', address: Address }
  | { type: 'personal', address: string };

Here’s a prism to the address of Domicile when the case is office

const office: Prism<Domicile, Address> = {
  get: d => d.type === 'office' ? d.address : null,
  set: (address, d) => d.type === 'office' ? 
       { type: 'office', address } : d
}

const d1 = { type: 'office', address: a1 }
const d2 = { type: 'personal', address: '23 high street' }

office.get(d1)
// => {city: "london", street: {num: 23, name: "high street"}}
office.get(d2)
// => null

We now have (in the combination of lenses and prisms) some powerful, general and predicatable tools with which to work on data.

Mathematicians love to study objects abstractly. When the object is a set of elements that is equipped with some operation(s) (and some laws!) we call it an algebra. In this post we’ll see how algebras can be encoded as interfaces and then some important algebras are presented.

Let’s start with the simplest algebra we can think of: magmas. A magma is a pair (M, *) in which M is a non-empty set and * is a binary operation on M, i.e. a function that takes two elements of M as input and returns an element of M as output

*: (M, M) -> M;

A semigroup (S, *) is a magma in which * is associative, i.e. the equation

(x * y) * z = x * (y * z)

holds for all x, y, z ∈ S.

Associativity simply tells us that we do not have to worry about parenthesizing an expression and can write x * y * z.

Semigroups capture the essence of parallelizable operations

There are plenty of examples of semigroups

• (number, *) where * is the usual multiplication of numbers
• (string, +) where + is the usual concatenation of strings
• (boolean, &&) where && is the usual conjunction

and many more.

Implementation

How do we translate these ideas into JavaScript? We can implement the concept of a semigroup on a type A as an interface (using Flow or TypeScript), where the operation * is named concat (see static-land specification)

interface Semigroup<A> {
  concat(x: A, y: A): A;
}

The following law must hold

• Associativity concat(concat(x, y), z) = concat(x, concat(y, z))

This is how we can implement the semigroup instance (number, *)

const multiplicationSemigroup: Semigroup<number> = {
  concat: (x, y) => x * y
}

Note that you can define different semigroup instances for the same type. Here’s the implementation of the semigroup instance (number, +) where + is the usual addition of numbers

const additionSemigroup: Semigroup<number> = {
  concat: (x, y) => x + y
}

Another example, with strings this time

const stringSemigroup: Semigroup<string> = {
  concat: (x, y) => x + y
}

I can’t find an instance!

What if, given a type A, you can’t find an associative operation on A? You can create a (trivial) semigroup instance for every type just using the following constructions

// always return the first argument
const leftZeroSemigroup = {
  concat: (x, y) => x
}

// always return the second argument
const rightZeroSemigroup = {
  concat: (x, y) => y
}

// always return the same value a ∈ A
const fixedSemigroup = {
  concat: (x, y) => a
}

Another technique is to define a semigroup instance for Array<A> (called the free semigroup of A)

function getFreeSemigroup<A>(): Semigroup<Array<A>> {
  return {
    // here concat is the native array method
    concat: (x, y) => x.concat(y)
  }
}

and map the elements of A to the singleton elements of Array<A>

function of<A>(a: A): Array<A> {
  return [a]
}

The free semigroup of A is the semigroup whose elements are all possible finite sequences of elements of A.

Semigroups for type constructors

In order to build a sensible semigroup instance for a type constructor, for example Maybe<A> or Promise<A>, we first need a semigroup instance for A

type Maybe<A> = null | A;

function getMaybeSemigroup<A>(
  semigroup: Semigroup<A>):   Semigroup<Maybe<A>> {

  return {
    concat: (x, y) => {
      if (x === null) {
        return y
      }
      if (y === null) {
        return x
      }
      // here we need a semigroup instance for A
      return semigroup.concat(x, y)
    }
  }
}

function getPromiseSemigroup<A>(
  semigroup: Semigroup<A>): Semigroup<Promise<A>> {

return {
    concat: (x, y) => Promise.all([x, y])
      // again, here we need a semigroup instance for A
      .then(([ax, ay]) => semigroup.concat(ax, ay))
  }
}

The product semigroup

Given two semigroup instances, one for A and one for B we can build the semigroup instance of their product, i.e. the tuple [A, B]

function getProductSemigroup<A, B>(
  a: Semigroup<A>, b: Semigroup<B>): Semigroup<[A, B]> {

  return {
    concat: ([ax, bx], [ay, by]) => 
      [a.concat(ax, ay), b.concat(bx, by)]
  }
}

Ordered sets

If A is sortable, then you can define a semigroup on A using min (or max) as operation

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

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

We can try to capture the notion of “sortable”, but before that we need to capture the notion of “being equal”. Mathematicians talk about equivalence relations. Let’s introduce another interface for that: Setoid

interface Setoid<A> {
  equals(x: A, y: A): boolean
}

The following laws must hold

• Reflexivity equals(x, x) = true for all x ∈ A
• Symmetry equal(x, y) = true if and only if equals(y, x) = true for all x, y ∈ A
• Transitivity if equal(x, y) = true and equal(y, z) = true then equal(x, z) = true

We can now capture the notion of “sortable”. Mathematicians talk about order relations. Let’s introduce the interface Ord

type Ordering = 'LT' | 'EQ' | 'GT';

interface Ord<A> extends Setoid<A> {
  compare(x: A, y: A): Ordering
}

// less than or equal
function leq<A>(ord: Ord<A>, x: A, y: A): boolean {
  return ord.compare(x, y) !== 'GT'
}

We write x <= y if and only if leq(ord, x, y) = true.

The following laws must hold

• Reflexivity x <= x for all x ∈ A
• Antisymmetry if x <= y and y <= x then x = y
• Transitivity if x <= y and y <= z then x <= z

In order to be compatible with Setoid, the following additional property must hold

• compare(x, y) = ‘EQ’ if and only if equals(x, y) = true

We can now define min and max in a generic way

function min<A>(ord: Ord<A>, x: A, y: A): A {
  return ord.compare(x, y) === 'LT' ? x : y
}

function max<A>(ord: Ord<A>, x: A, y: A): A {
  return ord.compare(x, y) === 'GT' ? x : y
}

Appendix

Other examples and implementations of semigroups in JavaScript

const everySemigroup: Semigroup<boolean> = {
  concat: (x, y) => x && y
}

const someSemigroup: Semigroup<boolean> = {
  concat: (x, y) => x || y
}

const mergeSemigroup: Semigroup<Object> = {
  concat: (x, y) => Object.assign({}, x, y)
}

// an endomorphism of a set A is a function f: A -> A
function getEndomorphismSemigroup<A>(): Semigroup<(a: A) => A> {
  return {
    concat: (x, y) => ( a => x(y(a)) )
  }
}

If we define a generic fold function

function fold<A>(semigroup: Semigroup<A>, a: A, as: Array<A>): A {
  return as.reduce(semigroup.concat, a)
}

we can re-implement some well known functions using the semigroups defined above

// Array.prototype.every
function every(as: Array<boolean>): boolean {
  return fold(everySemigroup, true, as)
}

// Array.prototype.some
function some(as: Array<boolean>): boolean {
  return fold(someSemigroup, false, as)
}

// Object.assign
function assign(as: Array<Object>): Object {
  return fold(mergeSemigroup, {}, as)
}

The problem

This problem is presented in Slaying a UI Antipattern in Fantasyland by Stefan Oestreicher which in turn is based on How Elm Slays a UI Antipattern by Kris Jenkins.

The problem they present is a very common one. You are loading a list of things but instead of showing a loading indicator you just see zero items. In JavaScript your data model may look like this

{ loading: true, items: [] }

But of course it’s easy to forget to check the loading flag. What about using null in order to represent the “not loaded” case? Both Stefan and Kris wisely discourage it

Long experience will have taught you that setting a property to null may be correct, but it’s just asking for runtime exceptions

Fortunately, this concern evaporates when using Flow and its maybe types

type Model = {
  things: ?Array<Thing>
};

Now if you try to use an instance of this model incorrectly

const SomeView = ({ things }: Model) => {
  return <div>
    { things.map(thing => { ... }) }
  </div>
}

Flow will complain

{model.things.map(thing => {})}
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ call of method `map`. Method cannot be called on possibly null value

{model.things.map(thing => {})}
 ^^^^^^^^^^^^ null

If you want to be more explicit, just define a type alias

type Maybe<A> = ?A;

type Model = {
  things: Maybe<Array<Thing>>
};

However we can go even further, as Kris says “we can be much more sophisticated”.

The solution

HTTP requests have one of four states

• we haven’t asked yet
• we’ve asked, but we haven’t got a response yet
• we got a response, but it was an error
• we got a response, and it was the data we wanted

With Flow we can easily define a type that represents these four states

type RemoteData<E, D>
  = { type: 'NotAsked' }
  | { type: 'Loading' }
  | { type: 'Failure', error: E }
  | { type: 'Success', data: D };

type Model = {
  things: RemoteData<HttpError, Array<Thing>>
};

As Kris observes

The nice thing about this data model is, the type checker will now force you to write the correct UI code. It will keep track of the possibility of “things not loaded” and errors, and force you to handle them all in the UI.

// will raise: property `data`. Property not found in object type
const SomeView = ({ things }: Model) => {
  return <div>
    { things.data.map(thing => {}) }
  </div>
}

Flow will force you to handle all cases

const SomeView = ({ things }: Model) => {
  if (things.type === 'NotAsked') {
    return <div>Please press the button to load the things</div>
  }
  else if (things.type === 'Loading') {
    return <div>Loading things...</div>
  }
  else if (things.type === 'Failure') {
    return <div>An error has occurred { things.error }</div>
  }
  return <div>
    { things.data.map(thing => { ... }) }
  </div>
}

Or, using a more functional style, let’s define a fold function that can be re-utilised in more use cases

function fold<R>(
  notAsked: () => R,
  loading: () => R,
  failure: (error: HttpError) => R,
  success: (data: Array<Thing>) => R
): (model: Model) => R {
  return ({ things }) => {
    return things.type === 'NotAsked' ? notAsked() :
      things.type === 'Loading' ? loading() :
      things.type === 'Failure' ? failure(things.error) :
      success(things.data)  }
}

Now SomeView can be defined as

const SomeView = fold(
  () => <div>Please press the button to load the things</div>,
  () => <div>Loading things...</div>,
  (error) => <div>An error has occurred { error }</div>,
  (data) => <div>{ data.map(thing => {}) }</div>
)

Note. Elm, folktale and daggy are definitely useful and they have their specific use cases, this post just shows you that you can go a long way with vanilla JavaScript and Flow.

“Type driven development” is a technique used to split a problem into a set of smaller problems, letting the type checker suggest the concrete implementation, or at least helping us getting there. Here’s a practical example

The Problem

Say for instance that we like to reimplement the function Promise.all, we’ll name it sequence. Let’s start with its signature

declare function sequence<T>(promises: Array<Promise<T>>): Promise<Array<T>>;

Notice that a declared function, even if not implemented yet, is immediately available and can concur to type check the rest of our code. If we are running a build system though, we’ll get an error because there’s no such function at runtime, it only exists in the “world of types” for now.

However, the goal of this technique is working in the editor for as long as possible without the need to run our code. We’ll rely entirely on the type checker making sure it doesn’t raise any errors as we go through.

Back to our problem, we need to transform (or “reduce”) an array of values of type A to a value of type B.

The transformation we’re looking for is likely reduce, which in fact has the following signature

this: Array<A> ~> reduce<A, B>(f: (acc: B, x: A) => B, init: B): B

We don’t know how to implement neither f nor init yet, but we can skip the concrete implementation as we did before. For now it’s enough to simply declare the missing bits and replace the type parameters A and B with the corresponding types we’re working with:

A = Promise<T>

B = Promise<Array<T>>

This is what we get

function sequence<T>(promises: Array<Promise<T>>): Promise<Array<T>> {
  // declaration
  declare function f(
    acc: Promise<Array<T>>, 
    x: Promise<T>): Promise<Array<T>>;

  // declaration
  declare var init: Promise<Array<T>>;

  // implementation
  return promises.reduce(f, init)
}

init is straightforward, we can put an empty array into the Promise “container”

function sequence<T>(promises: Array<Promise<T>>): Promise<Array<T>> {
  declare function f(
    acc: Promise<Array<T>>, 
    x: Promise<T>): Promise<Array<T>>;

  // implementation
  const init: Promise<Array<T>> = Promise.resolve([])

  return promises.reduce(f, init)
}

Implementing f is more complicated, we know how to concat a value of type Array<T> with a value of type T to get another value of type Array<T>

function push<T>(x: Array<T>, y: T): Array<T> {
  return x.concat(y)
}

but how do we concat acc and x given that they are both promises? What we’d like to have is a procedure, let’s name it liftA2, which can “lift” the function push producing a new function which can work on the values “inside” the promises. Again we just declare the expected result without any implementation

// declaration 
declare function liftA2<A, B, C>(f: (a: A, b: B) => C): 
  (a: Promise<A>, b: Promise<B>) => Promise<C>;

function sequence<T>(promises: Array<Promise<T>>): Promise<Array<T>> {
  // implementation
  function f(
    acc: Promise<Array<T>>, 
    x: Promise<T>): Promise<Array<T>> {

    return liftA2(push)(acc, x)
  }

  const init: Promise<Array<T>> = Promise.resolve([])
  return promises.reduce(f, init)
}

Now we only need to implement liftA2

function liftA2<A, B, C>(f: (a: A, b: B) => C): 
  (a: Promise<A>, b: Promise<B>) => Promise<C> {

  return (a, b) => a.then(aa => b.then(bb => f(aa, bb)))
}

and test the whole thing

function push<T>(x: Array<T>, y: T): Array<T> {
  return x.concat(y)
}

function liftA2<A, B, C>(f: (a: A, b: B) => C): 
  (a: Promise<A>, b: Promise<B>) => Promise<C> {
  return (a, b) => a.then(aa => b.then(bb => f(aa, bb)))
}

function sequence<T>(promises: Array<Promise<T>>): Promise<Array<T>> {
  function f(
    acc: Promise<Array<T>>, 
    x: Promise<T>): Promise<Array<T>> {
    return liftA2(push)(acc, x)
  }
  const init: Promise<Array<T>> = Promise.resolve([])
  return promises.reduce(f, init)
}

const promises: Array<Promise<number>> = [
  Promise.resolve(1),
  Promise.resolve(2),
  Promise.resolve(3)
]

sequence(promises).then(x => console.log(x)) // => [1, 2, 3]

As you can see a strong type system can not only prevent errors, but also guide you and provide feedback in your design process.

Flow declaration files, like any other piece of software, must be thoroughly tested. The base technique for doing so, which is also used by the flow-typed repo, relies on the usage of the suppress_comment configuration option of the .flowconfig:

[options]
suppress_comment=\\(.\\|\n\\)*\\$ExpectError
include_warnings=true

The above configuration allows us to use a “magical” flow comment anywhere within our code.

// $ExpectError
const foo: number = 1 + 'a';

The great thing about $ExpectError is its behavior:

• if the line that follows the comment raises a flow error, it will be suppressed
• if the line that follows the comment does not raise a flow error, then flow will raise an error

This provides us with a very useful mechanism of testing our declaration files.

Example

Say for instance that we need to test the following declaration file:

declare module 'mymodule' {
  declare function sum(a: number, b: number): number;
}

Let’s see the four possible cases of using the sum function

import { sum } from 'mymodule'

/*

1) valid usage of sum

*/

sum(1, 2) // ok

/*

2) invalid usage of sum

*/

sum('a', 2) // flow raises an error

/*

3) invalid usage of sum, with magic comment.
We have also used our magic comment to indicate that we expect 
a flow error to occur.

*/

// $ExpectError
sum('a', 2) // the flow error is suppressed

/*

4) valid usage of sum, with magic comment. We have also used our      magic comment to indicate that we expect a flow error to occur.  However, the below usage of the sum function will not produce an error, therefore the usage of our magic comment will result in an error.

*/

// $ExpectError
sum(1, 2) // a flow error is raised
          // => "Error suppressing comment. Unused suppression"

As you can see this is a great way to test your assumptions about your declaration files. It is always really useful to make sure your declaration files will throw errors in the cases you expect them to.