add pipeable helpers

[gcanti]

Motivation

The pipeable module now exports a series of pipe-able helpers that are useful when you build
a typeclass instance "on the fly".

Example

Here's a simple pipe-line which validates a Person struct

import * as E from 'fp-ts/Either'
import { pipe } from 'fp-ts/function'

const parseString = (u: unknown): E.Either<string, string> =>
  typeof u === 'string' ? E.right(u) : E.left('not a string')

const parseNumber = (u: unknown): E.Either<string, number> =>
  typeof u === 'number' ? E.right(u) : E.left('not a number')

interface Person {
  readonly name: string
  readonly age: number
}

const person = (name: string) => (age: number): Person => ({ name, age })

const parsePerson = (input: Record<string, unknown>): E.Either<string, Person> =>
  pipe(E.of(person), E.ap(parseString(input.name)), E.ap(parseNumber(input.age)))

console.log(parsePerson({})) // => left('not a string')

As you can see the default ap exported by the Either module return only the first validation error.

You probably already know that if you want to get all validation errors you must create an Applicative instance on the fly

import * as S from 'fp-ts/Semigroup'
import * as string from 'fp-ts/string'

const Applicative = E.getApplicativeValidation(pipe(string.Semigroup, S.intercalate(', ')))

The issue here is that Applicative.ap is not pipe-able and can't be used inside a pipe-line

const parsePersonAll = (input: Record<string, unknown>): E.Either<string, Person> =>
  pipe(
    E.of(person),
    Applicative.ap(parseString(input.name)), // <= error
    Applicative.ap(parseNumber(input.age)) // <= error
  )

That's when the new pipe-able helpers come to handy

import * as P from 'fp-ts/pipeable'

//    v--- this is `pipe`-able
const ap = P.ap(Applicative)

const parsePersonAll = (input: Record<string, unknown>): E.Either<string, Person> =>
  pipe(
    E.of(person),
    ap(parseString(input.name)), // <= ok
    ap(parseNumber(input.age)) // <= ok
  )

console.log(parsePersonAll({})) // => left('not a string, not a number')