npm package: @nathrach/early-birds
Description: combinator birds for javascript
Author: Robert Brock
Latest version: 1.0.3

# early-birds

early-birds, like [fantasy-birds](https://github.com/fantasyland/fantasy-birds),
is a port of the haskell package [Data.Aviary.Birds](https://hackage.haskell.org/package/data-aviary-0.4.0/docs/Data-Aviary-Birds.html).

## Install
```shell
npm i @nathrach/early-birds
```

## Differences between early-birds and fantasy-birds
For many combinators, the behaviour of early-birds will (modulo bugs)
be identical to that of fantasy-birds. early-birds differs in that
intermediate results are eagerly evaluated, e.g. for the idstarstar bird,
`(a -> b -> c) -> a -> b -> c`, `idstarstar(f)(x)` will evalute `f(x)` as
soon as x is provided. The intermediate results are also "closed over"
so that the evaluation occurs only once.

 Consider the following example
module which demonstrates the differences.
```javascript
import { psi } from "../src/early-birds.mjs"
const F = require ("fantasy-birds")

const psiEarly = psi

const psiFantasy = F.psi

const toLower = string => (
  console.log (`!---- evaluating "${string}".toLowerCase() ----!`),
  string.toLowerCase()
)

const equal3 = x => y => x === y

const tests = [ 'true', 'True', 'TruE', 'false', 'False', 'FalsE' ]

// --- Using early-birds
console.log ('\n !#### Testing with psiEarly ####!\n')

const isTrueEarly = psiEarly (equal3) (toLower) ('TRUE')

tests.map (e => console.log (`Testing isTrueEarly ("${e}"): ${isTrueEarly (e)}\n`))

// --- Using fantasy-birds
console.log ('\n!#### Testing with psiFantasy ####!\n')

const isTrueFantasy = psiFantasy (equal3) (toLower) ('TRUE')

tests.map (e => console.log (`Testing isTrue ("${e}"): ${isTrueFantasy (e)}\n`))
```

When this module is imported into node.js the following is output:
```text
> await import ('./examples/sameLetters.mjs')

 !#### Testing with psiEarly ####!

!---- evaluating "TRUE".toLowerCase() ----!
!---- evaluating "true".toLowerCase() ----!
Testing isTrueEarly ("true"): true

!---- evaluating "True".toLowerCase() ----!
Testing isTrueEarly ("True"): true

!---- evaluating "TruE".toLowerCase() ----!
Testing isTrueEarly ("TruE"): true

!---- evaluating "false".toLowerCase() ----!
Testing isTrueEarly ("false"): false

!---- evaluating "False".toLowerCase() ----!
Testing isTrueEarly ("False"): false

!---- evaluating "FalsE".toLowerCase() ----!
Testing isTrueEarly ("FalsE"): false

!#### Testing with psiFantasy ####!

!---- evaluating "TRUE".toLowerCase() ----!
!---- evaluating "true".toLowerCase() ----!
Testing isTrue ("true"): true

!---- evaluating "TRUE".toLowerCase() ----!
!---- evaluating "True".toLowerCase() ----!
Testing isTrue ("True"): true

!---- evaluating "TRUE".toLowerCase() ----!
!---- evaluating "TruE".toLowerCase() ----!
Testing isTrue ("TruE"): true

!---- evaluating "TRUE".toLowerCase() ----!
!---- evaluating "false".toLowerCase() ----!
Testing isTrue ("false"): false

!---- evaluating "TRUE".toLowerCase() ----!
!---- evaluating "False".toLowerCase() ----!
Testing isTrue ("False"): false

!---- evaluating "TRUE".toLowerCase() ----!
!---- evaluating "FalsE".toLowerCase() ----!
Testing isTrue ("FalsE"): false

[Module: null prototype] {  }
> 
```
In the example, ```"TRUE".toLowerCase``` is evaluted only once for the
early-birds psi and is evaluted for each test for the fantasy-birds psi.
The eager closure can be useful when applying the combinators to pure
functions since the evaluation will always be the same. However, for
applications that rely on the side effects, the fantasy-birds behaviour
is likely what is desired.

## The Aviary
### <a name="applicator" href="https://gitlab.com/Nathrach/early-birds/-/blob/v1.0.3/./early-birds.mjs#L117">`applicator :: (a -⁠> b) -⁠> a -⁠> b`</a>
- I* combinator
- λ abstraction: `λab.ab`

### <a name="becard" href="https://gitlab.com/Nathrach/early-birds/-/blob/v1.0.3/./early-birds.mjs#L123">`becard :: (c -⁠> d) -⁠> (b -⁠> c) -⁠> (a -⁠> b) -⁠> a -⁠> d`</a>
- B3 combinator
- λ abstraction: `λabcd.a(b(cd))`

### <a name="blackbird" href="https://gitlab.com/Nathrach/early-birds/-/blob/v1.0.3/./early-birds.mjs#L129">`blackbird :: (c -⁠> d) -⁠> (a -⁠> b -⁠> c) -⁠> a -⁠> b -⁠> d`</a>
- B1 combinator
- λ abstraction: `λabcd.a(bcd)`

### <a name="bluebird" href="https://gitlab.com/Nathrach/early-birds/-/blob/v1.0.3/./early-birds.mjs#L135">`bluebird :: (b -⁠> c) -⁠> (a -⁠> b) -⁠> a -⁠> c`</a>
- B combinator 
- λ abstraction: `λabc.a(bc)`

### <a name="bluebird_" href="https://gitlab.com/Nathrach/early-birds/-/blob/v1.0.3/./early-birds.mjs#L141">`bluebird_ :: (a -⁠> c -⁠> d) -⁠> a -⁠> (b -⁠> c) -⁠> b -⁠> d`</a>
- B' combinator 
- λ abstraction: `λabcd.ab(cd)`

### <a name="bunting" href="https://gitlab.com/Nathrach/early-birds/-/blob/v1.0.3/./early-birds.mjs#L147">`bunting :: (d -⁠> e) -⁠> (a -⁠> b -⁠> c -⁠> d) -⁠> a -⁠> b -⁠> c -⁠> e`</a>
- B2 combinator 
- λ abstraction: `λabcde.a(bcde)`

### <a name="cardinal" href="https://gitlab.com/Nathrach/early-birds/-/blob/v1.0.3/./early-birds.mjs#L153">`cardinal :: (a -⁠> b -⁠> c) -⁠> b -⁠> a -⁠> c`</a>
- C combinator 
- λ abstraction: `λabc.acb`

### <a name="cardinal_" href="https://gitlab.com/Nathrach/early-birds/-/blob/v1.0.3/./early-birds.mjs#L159">`cardinal_ :: (c -⁠> a -⁠> d) -⁠> (b -⁠> c) -⁠> a -⁠> b -⁠> d`</a>
- C' combinator 
- λ abstraction: `λabcd.a(bd)c`

### <a name="cardinalstar" href="https://gitlab.com/Nathrach/early-birds/-/blob/v1.0.3/./early-birds.mjs#L165">`cardinalstar :: (a -⁠> c -⁠> b -⁠> d) -⁠> a -⁠> b -⁠> c -⁠> d`</a>
- C* combinator 
- λ abstraction: `λabcd.abdc`

### <a name="cardinalstarstar" href="https://gitlab.com/Nathrach/early-birds/-/blob/v1.0.3/./early-birds.mjs#L171">`cardinalstarstar :: (a -⁠> b -⁠> d -⁠> c -⁠> e) -⁠> a -⁠> b -⁠> c -⁠> d -⁠> e`</a>
- C** combinator 
- λ abstraction: `λabcde.abced`

### <a name="dickcissel" href="https://gitlab.com/Nathrach/early-birds/-/blob/v1.0.3/./early-birds.mjs#L177">`dickcissel :: (a -⁠> b -⁠> d -⁠> e) -⁠> a -⁠> b -⁠> (c -⁠> d) -⁠> c -⁠> e`</a>
- D1 combinator 
- λ abstraction: `λabcde.abc(de)`

### <a name="dove" href="https://gitlab.com/Nathrach/early-birds/-/blob/v1.0.3/./early-birds.mjs#L183">`dove :: (a -⁠> c -⁠> d) -⁠> a -⁠> (b -⁠> c) -⁠> b -⁠> d`</a>
- D combinator 
- λ abstraction: `λabcd.ab(cd)`

### <a name="dovekie" href="https://gitlab.com/Nathrach/early-birds/-/blob/v1.0.3/./early-birds.mjs#L189">`dovekie :: (c -⁠> d -⁠> e) -⁠> (a -⁠> c) -⁠> a -⁠> (b -⁠> d) -⁠> b -⁠> e`</a>
- D2 combinator 
- λ abstraction: `λabcde.a(bc)(de)`

### <a name="eagle" href="https://gitlab.com/Nathrach/early-birds/-/blob/v1.0.3/./early-birds.mjs#L195">`eagle :: (a -⁠> d -⁠> e) -⁠> a -⁠> (b -⁠> c -⁠> d) -⁠> b -⁠> c -⁠> e`</a>
- E combinator 
- λ abstraction: `λabcde.ab(cde)`

### <a name="eaglebald" href="https://gitlab.com/Nathrach/early-birds/-/blob/v1.0.3/./early-birds.mjs#L201">`eaglebald :: (e -⁠> f -⁠> g) -⁠> (a -⁠> b -⁠> e) -⁠> a -⁠> b -⁠> (c -⁠> d -⁠> f) -⁠> c -⁠> d -⁠> g`</a>
- E^ combinator 
- λ abstraction: `λabcdefg.a(bcd)(efg)`

### <a name="finch" href="https://gitlab.com/Nathrach/early-birds/-/blob/v1.0.3/./early-birds.mjs#L207">`finch :: a -⁠> b -⁠> (b -⁠> a -⁠> c) -⁠> c`</a>
- F combinator 
- λ abstraction: `λabc.cba`

### <a name="finchstar" href="https://gitlab.com/Nathrach/early-birds/-/blob/v1.0.3/./early-birds.mjs#L213">`finchstar :: (c -⁠> b -⁠> a -⁠> d) -⁠> a -⁠> b -⁠> c -⁠> d`</a>
- F* combinator 
- λ abstraction: `λabcd.adcb`

### <a name="finchstarstar" href="https://gitlab.com/Nathrach/early-birds/-/blob/v1.0.3/./early-birds.mjs#L219">`finchstarstar :: (a -⁠> d -⁠> c -⁠> b -⁠> e) -⁠> a -⁠> b -⁠> c -⁠> d -⁠> e`</a>
- F** combinator 
- λ abstraction: `λabcde.abedc`

### <a name="goldfinch" href="https://gitlab.com/Nathrach/early-birds/-/blob/v1.0.3/./early-birds.mjs#L225">`goldfinch :: (b -⁠> c -⁠> d) -⁠> (a -⁠> c) -⁠> a -⁠> b -⁠> d`</a>
- G combinator 
- λ abstraction: `λabcd.ad(bc)`

### <a name="hummingbird" href="https://gitlab.com/Nathrach/early-birds/-/blob/v1.0.3/./early-birds.mjs#L231">`hummingbird :: (a -⁠> b -⁠> a -⁠> c) -⁠> a -⁠> b -⁠> c`</a>
- H combinator 
- λ abstraction: `λabc.abcb`

### <a name="idiot" href="https://gitlab.com/Nathrach/early-birds/-/blob/v1.0.3/./early-birds.mjs#L237">`idiot :: a -⁠> a`</a>
- I combinator 
- λ abstraction: `λa.a`

### <a name="idstar" href="https://gitlab.com/Nathrach/early-birds/-/blob/v1.0.3/./early-birds.mjs#L243">`idstar :: (a -⁠> b) -⁠> a -⁠> b`</a>
- I* combinator 
- λ abstraction: `λab.ab`

### <a name="idstarstar" href="https://gitlab.com/Nathrach/early-birds/-/blob/v1.0.3/./early-birds.mjs#L249">`idstarstar :: (a -⁠> b -⁠> c) -⁠> a -⁠> b -⁠> c`</a>
- I** combinator 
- λ abstraction: `λabc.abc`

### <a name="jalt" href="https://gitlab.com/Nathrach/early-birds/-/blob/v1.0.3/./early-birds.mjs#L255">`jalt :: (a -⁠> c) -⁠> a -⁠> b -⁠> c`</a>
- jalt combinator 
- λ abstraction: `λabc.ab`

### <a name="jalt_" href="https://gitlab.com/Nathrach/early-birds/-/blob/v1.0.3/./early-birds.mjs#L261">`jalt_ :: (a -⁠> b -⁠> d) -⁠> a -⁠> b -⁠> c -⁠> d`</a>
- jalt' combinator 
- λ abstraction: `λabcd.abc`

### <a name="jay" href="https://gitlab.com/Nathrach/early-birds/-/blob/v1.0.3/./early-birds.mjs#L267">`jay :: (a -⁠> b -⁠> b) -⁠> a -⁠> b -⁠> a -⁠> b`</a>
- J combinator 
- λ abstraction: `λabcd.ab(adc)`

### <a name="kestrel" href="https://gitlab.com/Nathrach/early-birds/-/blob/v1.0.3/./early-birds.mjs#L273">`kestrel :: a -⁠> b -⁠> a`</a>
- K combinator 
- λ abstraction: `λab.a`

### <a name="kite" href="https://gitlab.com/Nathrach/early-birds/-/blob/v1.0.3/./early-birds.mjs#L279">`kite :: a -⁠> b -⁠> b`</a>
- Ki combinator 
- λ abstraction: `λab.b`

### <a name="owl" href="https://gitlab.com/Nathrach/early-birds/-/blob/v1.0.3/./early-birds.mjs#L285">`owl :: ((a -⁠> b) -⁠> a) -⁠> (a -⁠> b) -⁠> b`</a>
- O combinator 
- λ abstraction: `λab.b(ab)`

### <a name="phoenix" href="https://gitlab.com/Nathrach/early-birds/-/blob/v1.0.3/./early-birds.mjs#L291">`phoenix :: (b -⁠> c -⁠> d) -⁠> (a -⁠> b) -⁠> (a -⁠> c) -⁠> a -⁠> d`</a>
- S' combinator 
- λ abstraction: `λabcd.a(bd)(cd)`

- same as [`starling_`](#starling_)

### <a name="psi" href="https://gitlab.com/Nathrach/early-birds/-/blob/v1.0.3/./early-birds.mjs#L299">`psi :: (b -⁠> b -⁠> c) -⁠> (a -⁠> b) -⁠> a -⁠> a -⁠> c`</a>
- Psi combinator 
- λ abstraction: `λabcd.a(bc)(bd)`

### <a name="quacky" href="https://gitlab.com/Nathrach/early-birds/-/blob/v1.0.3/./early-birds.mjs#L305">`quacky :: a -⁠> (a -⁠> b) -⁠> (b -⁠> c) -⁠> c`</a>
- Q4 combinator 
- λ abstraction: `λabc.c(ba)`

### <a name="queer" href="https://gitlab.com/Nathrach/early-birds/-/blob/v1.0.3/./early-birds.mjs#L311">`queer :: (a -⁠> b) -⁠> (b -⁠> c) -⁠> a -⁠> c`</a>
- Q combinator 
- λ abstraction: `λabc.b(ac)`

### <a name="quirky" href="https://gitlab.com/Nathrach/early-birds/-/blob/v1.0.3/./early-birds.mjs#L317">`quirky :: (a -⁠> b) -⁠> a -⁠> (b -⁠> c) -⁠> c`</a>
- Q3 combinator 
- λ abstraction: `λabc.c(ab)`

### <a name="quixotic" href="https://gitlab.com/Nathrach/early-birds/-/blob/v1.0.3/./early-birds.mjs#L323">`quixotic :: (b -⁠> c) -⁠> a -⁠> (a -⁠> b) -⁠> c`</a>
- Q1 combinator 
- λ abstraction: `λabc.a(cb)`

### <a name="quizzical" href="https://gitlab.com/Nathrach/early-birds/-/blob/v1.0.3/./early-birds.mjs#L329">`quizzical :: a -⁠> (b -⁠> c) -⁠> (a -⁠> b) -⁠> c`</a>
- Q2 combinator 
- λ abstraction: `λabc.b(ca)`

### <a name="robin" href="https://gitlab.com/Nathrach/early-birds/-/blob/v1.0.3/./early-birds.mjs#L335">`robin :: a -⁠> (b -⁠> a -⁠> c) -⁠> b -⁠> c`</a>
- R combinator 
- λ abstraction: `λabc.bca`

### <a name="robinstar" href="https://gitlab.com/Nathrach/early-birds/-/blob/v1.0.3/./early-birds.mjs#L341">`robinstar :: (b -⁠> c -⁠> a -⁠> d) -⁠> a -⁠> b -⁠> c -⁠> d`</a>
- R* combinator 
- λ abstraction: `λabcd.acdb`

### <a name="robinstarstar" href="https://gitlab.com/Nathrach/early-birds/-/blob/v1.0.3/./early-birds.mjs#L347">`robinstarstar :: (a -⁠> c -⁠> d -⁠> b -⁠> e) -⁠> a -⁠> b -⁠> c -⁠> d -⁠> e`</a>
- R** combinator 
- λ abstraction: `λabcde.abdec`

### <a name="starling" href="https://gitlab.com/Nathrach/early-birds/-/blob/v1.0.3/./early-birds.mjs#L353">`starling :: (a -⁠> b -⁠> c) -⁠> (a -⁠> b) -⁠> a -⁠> c`</a>
- S combinator 
- λ abstraction: `λabc.ac(bc)`

### <a name="starling_" href="https://gitlab.com/Nathrach/early-birds/-/blob/v1.0.3/./early-birds.mjs#L359">`starling_ :: (b -⁠> c -⁠> d) -⁠> (a -⁠> b) -⁠> (a -⁠> c) -⁠> a -⁠> d`</a>
- S' combinator 
- λ abstraction: `λabcd.a(bd)(cd)`

- same as [`phoenix`](#phoenix)

### <a name="thrush" href="https://gitlab.com/Nathrach/early-birds/-/blob/v1.0.3/./early-birds.mjs#L367">`thrush :: a -⁠> (a -⁠> b) -⁠> b`</a>
- T combinator 
- λ abstraction: `λab.ba`

### <a name="vireo" href="https://gitlab.com/Nathrach/early-birds/-/blob/v1.0.3/./early-birds.mjs#L373">`vireo :: a -⁠> b -⁠> (a -⁠> b -⁠> c) -⁠> c`</a>
- V combinator 
- λ abstraction: `λabc.cab`

### <a name="vireostar" href="https://gitlab.com/Nathrach/early-birds/-/blob/v1.0.3/./early-birds.mjs#L379">`vireostar :: (b -⁠> a -⁠> b -⁠> d) -⁠> a -⁠> b -⁠> b -⁠> d`</a>
- V* combinator 
- λ abstraction: `λabcd.acbd`

### <a name="vireostarstar" href="https://gitlab.com/Nathrach/early-birds/-/blob/v1.0.3/./early-birds.mjs#L385">`vireostarstar :: (a -⁠> c -⁠> b -⁠> c -⁠> e) -⁠> a -⁠> b -⁠> c -⁠> c -⁠> e`</a>
- V** combinator 
- λ abstraction: `λabcde.abecd`

### <a name="warbler" href="https://gitlab.com/Nathrach/early-birds/-/blob/v1.0.3/./early-birds.mjs#L391">`warbler :: (a -⁠> a -⁠> b) -⁠> a -⁠> b`</a>
- W combinator 
- λ abstraction: `λab.abb`

### <a name="warbler1" href="https://gitlab.com/Nathrach/early-birds/-/blob/v1.0.3/./early-birds.mjs#L397">`warbler1 :: a -⁠> (a -⁠> a -⁠> b) -⁠> b`</a>
- W1 combinator 
- λ abstraction: `λab.baa`

### <a name="warblerstar" href="https://gitlab.com/Nathrach/early-birds/-/blob/v1.0.3/./early-birds.mjs#L403">`warblerstar :: (a -⁠> b -⁠> b -⁠> c) -⁠> a -⁠> b -⁠> c`</a>
- W* combinator 
- λ abstraction: `λabc.abcc`

### <a name="warblerstarstar" href="https://gitlab.com/Nathrach/early-birds/-/blob/v1.0.3/./early-birds.mjs#L409">`warblerstarstar :: (a -⁠> b -⁠> c -⁠> c -⁠> d) -⁠> a -⁠> b -⁠> c -⁠> d`</a>
- W** combinator 
- λ abstraction: `λabcd.abcdd`