Introduction

Welcome to the documentation for @effect/typeclass, a collection of re-usable typeclasses for the Effect ecosystem.

The functional abstractions in @effect/typeclass can be broadly divided into two categories.

- Abstractions For Concrete Types - These abstractions define properties of concrete types, such as number and string, as well as ways of combining those values.
- Abstractions For Parameterized Types - These abstractions define properties of parameterized types such as ReadonlyArray and Option and ways of combining them.

Concrete Types

Members and derived functions

Note: members are in bold.

$3

A type class used to name the lower limit and the upper limit of a type.

Extends:

- Order

| Name | Given | To |
| ------------ | ------------ | ------------ |
| maxBound | | A |
| minBound | | A |
| reverse | Bounded | Bounded |
| clamp | A | A |

$3

A Monoid is a Semigroup with an identity. A Monoid is a specialization of a
Semigroup, so its operation must be associative. Additionally,
x |> combine(empty) == empty |> combine(x) == x. For example, if we have Monoid,
with combine as string concatenation, then empty = "".

Extends:

- Semigroup

| Name | Given | To |
| -------------- | ------------------------------------- | ----------------------------- |
| empty | | A |
| combineAll | Iterable | A |
| reverse | Monoid | Monoid |
| tuple | [Monoid, Monoid, ...] | Monoid<[A, B, ...]> |
| struct | { a: Monoid, b: Monoid, ... } | Monoid<{ a: A, b: B, ... }> |
| min | Bounded | Monoid |
| max | Bounded | Monoid |

$3

A Semigroup is any set A with an associative operation (combine):

x |> combine(y) |> combine(z) == x |> combine(y |> combine(z))

| Name | Given | To |
| --------------- | ------------------------------------------- | -------------------------------- |
| combine | A, A | A |
| combineMany | A, Iterable | A |
| reverse | Semigroup | Semigroup |
| tuple | [Semigroup, Semigroup, ...] | Semigroup<[A, B, ...]> |
| struct | { a: Semigroup, b: Semigroup, ... } | Semigroup<{ a: A, b: B, ... }> |
| min | Order | Semigroup |
| max | Order | Semigroup |
| constant | A | Semigroup |
| intercalate | A, Semigroup | Semigroup |
| first | | Semigroup |
| last | | Semigroup |

Parameterized Types

Parameterized Types Hierarchy

``mermaid
flowchart TD
Alternative --> SemiAlternative
Alternative --> Coproduct
Applicative --> Product
Coproduct --> SemiCoproduct
SemiAlternative --> Covariant
SemiAlternative --> SemiCoproduct
SemiApplicative --> SemiProduct
SemiApplicative --> Covariant
Applicative --> SemiApplicative
Chainable --> FlatMap
Chainable ---> Covariant
Monad --> FlatMap
Monad --> Pointed
Pointed --> Of
Pointed --> Covariant
Product --> SemiProduct
Product --> Of
SemiProduct --> Invariant
Covariant --> Invariant
SemiCoproduct --> Invariant
`

Members and derived functions

Note: members are in bold.

$3

Extends:

- SemiAlternative
- Coproduct

$3

Extends:

- SemiApplicative
- Product

| Name | Given | To |
| ---------- | ----------- | -------------- |
| liftMonoid | Monoid | Monoid> |

$3

A type class of types which give rise to two independent, covariant
functors.

| Name | Given | To |
| --------- | -------------------------------- | ---------- |
| bimap | F, E1 => E2, A => B | F |
| mapLeft | F, E1 => E2 | F |
| map | F, A => B | F |

$3

Extends:

- FlatMap
- Covariant

| Name | Given | To |
| -------------- | ----------------------------------- | ---------------------- |
| tap | F, A => F | F |
| andThenDiscard | F, F | F |
| bind | F, name: string, A => F | F |

$3

Contravariant functors.

Extends:

- Invariant

| Name | Given | To |
| -------------------- | ------------------- | --------- |
| contramap | F, B => A | F |
| contramapComposition | F>, A => B | F> |
| imap | contramap | imap |

$3

Coproduct is a universal monoid which operates on kinds.

This type class is useful when its type parameter F<_> has a
structure that can be combined for any particular type, and which
also has a "zero" representation. Thus, Coproduct is like a Monoid
for kinds (i.e. parametrized types).

A Coproduct can produce a Monoid> for any type A.

Here's how to distinguish Monoid and Coproduct:

- Monoid allows A values to be combined, and also means there
is an "empty" A value that functions as an identity.

- Coproduct allows two F values to be combined, for any A. It
also means that for any A, there is an "zero" F value. The
combination operation and zero value just depend on the
structure of F, but not on the structure of A.

Extends:

- SemiCoproduct

| Name | Given | To |
| ---------------- | ---------------- | -------------- |
| zero | | F |
| coproductAll | Iterable> | F |
| getMonoid | | Monoid> |

$3

Covariant functors.

Extends:

- Invariant

| Name | Given | To |
| -------------- | ------------------- | --------- |
| map | F, A => B | F |
| mapComposition | F>, A => B | F> |
| imap | map | imap |
| flap | A, F B> | F |
| as | F, B | F |
| asUnit | F | F |

$3

Filterable allows you to map and filter out elements simultaneously.

| Name | Given | To |
| ----------------------- | ------------------------------ | -------------------- |
| partitionMap | F, A => Either | [F, F] |
| filterMap | F, A => Option | F |
| compact | F> | F |
| separate | F> | [F, F] |
| filter | F, A => boolean | F |
| partition | F, A => boolean | [F, F] |
| partitionMapComposition | F>, A => Either | [F>, F>] |
| filterMapComposition | F>, A => Option | F> |

$3

| Name | Given | To |
| ------------------- | ------------------------ | ----------- |
| flatMap | F, A => F | F |
| flatten | F> | F |
| andThen | F, F | F |
| composeKleisliArrow | A => F, B => F | A => F |

$3

Data structures that can be folded to a summary value.

In the case of a collection (such as ReadonlyArray), these
methods will fold together (combine) the values contained in the
collection to produce a single result. Most collection types have
reduce methods, which will usually be used by the associated
Foldable instance.

| Name | Given | To |
| ------------------- | ----------------------------------------- | ------------------ |
| reduce | F, B, (B, A) => B | B |
| reduceComposition | F>, B, (B, A) => B | B |
| reduceRight | F, B, (B, A) => B | B |
| foldMap | F, Monoid, A => M | M |
| toReadonlyArray | F | ReadonlyArray |
| toReadonlyArrayWith | F, A => B | ReadonlyArray |
| reduceKind | Monad, F, B, (B, A) => G | G |
| reduceRightKind | Monad, F, B, (B, A) => G | G |
| foldMapKind | Coproduct, F, (A) => G | G |

$3

Invariant functors.

| Name | Given | To |
| --------------- | ----------------------------- | ------------------ |
| imap | F, A => B, B => A | F |
| imapComposition | F>, A => B, B => A | F> |
| bindTo | F, name: string | F<{ [name]: A }> |
| tupled | F | F<[A]> |

$3

Allows composition of dependent effectful functions.

Extends:

- FlatMap
- Pointed

$3

| Name | Given | To |
| ------------- | ----- | --------- |
| of | A | F |
| ofComposition | A | F> |
| unit | | F |
| Do | | F<{}> |

$3

Extends:

- Covariant
- Of

$3

Extends:

- SemiProduct
- Of

| Name | Given | To |
| -------------- | --------------------------- | ------------------------ |
| productAll | Iterable> | F> |
| tuple | [F, F, ...] | F<[A, B, ...]> |
| struct | { a: F, b: F, ... } | F<{ a: A, b: B, ... }> |

$3

Extends:

- SemiCoproduct
- Covariant

$3

Extends:

- SemiProduct
- Covariant

| Name | Given | To |
| -------------- | ------------------- | ---------------------------- |
| liftSemigroup | Semigroup | Semigroup> |
| ap | F B>, F | F |
| andThenDiscard | F, F | F |
| andThen | F, F | F |
| lift2 | (A, B) => C | (F, F) => F |
| lift3 | (A, B, C) => D | (F, F, F) => F |

$3

SemiCoproduct is a universal semigroup which operates on kinds.

This type class is useful when its type parameter F<_> has a
structure that can be combined for any particular type. Thus,
SemiCoproduct is like a Semigroup for kinds (i.e. parametrized
types).

A SemiCoproduct can produce a Semigroup> for any type A.

Here's how to distinguish Semigroup and SemiCoproduct:

- Semigroup allows two A values to be combined.

- SemiCoproduct allows two F values to be combined, for any A.
The combination operation just depends on the structure of F,
but not the structure of A.

Extends:

- Invariant

| Name | Given | To |
| ----------------- | ---------------- | ----------------- |
| coproduct | F, F | F |
| coproductMany | Iterable> | F |
| getSemigroup | | Semigroup> |
| coproductEither | F, F | F> |

$3

Extends:

- Invariant

| Name | Given | To |
| ---------------------- | ------------------------------ | -------------------------------- |
| product | F, F | F<[A, B]> |
| productMany | F, Iterable> | F<[A, ...ReadonlyArray]> |
| productComposition | F>, F> | F> |
| productManyComposition | F>, Iterable>> | F]>> |
| nonEmptyTuple | [F, F, ...] | F<[A, B, ...]> |
| nonEmptyStruct | { a: F, b: F, ... } | F<{ a: A, b: B, ... }> |
| andThenBind | F, name: string, F | F |
| productFlatten | F, F | F<[...A, B]> |

$3

Traversal over a structure with an effect.

| Name | Given | To |
| ------------------- | ---------------------------------------- | ------------ |
| traverse | Applicative, T, A => F | F> |
| traverseComposition | Applicative, T>, A => F | F>> |
| sequence | Applicative, T> | F> |
| traverseTap | Applicative, T, A => F | F> |

$3

TraversableFilterable, also known as Witherable, represents list-like structures
that can essentially have a traverse and a filter applied as a single
combined operation (traverseFilter).

| Name | Given | To |
| ------------------------ | ------------------------------------------------ | ----------------- |
| traversePartitionMap | Applicative, T, A => F> | F<[T, T]> |
| traverseFilterMap | Applicative, T, A => F> | F> |
| traverseFilter | Applicative, T, A => F | F> |
| traversePartition | Applicative, T, A => F | F<[T, T]>` |

---

Adapted from:

- cats
- zio-prelude
- zio-cheatsheet