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.

Bounded

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<A> | Bounded<A> | | clamp | A | A |

Monoid

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<String>, with combine as string concatenation, then empty = "".

Extends:

• Semigroup

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

Semigroup

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> | A | | reverse | Semigroup<A> | Semigroup<A> | | tuple | [Semigroup<A>, Semigroup<B>, ...] | Semigroup<[A, B, ...]> | | struct | { a: Semigroup<A>, b: Semigroup<B>, ... } | Semigroup<{ a: A, b: B, ... }> | | min | Order<A> | Semigroup<A> | | max | Order<A> | Semigroup<A> | | constant | A | Semigroup<A> | | intercalate | A, Semigroup<A> | Semigroup<A> | | first | | Semigroup<A> | | last | | Semigroup<A> |

Parameterized Types

Parameterized Types Hierarchy

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.

Alternative

Extends:

• SemiAlternative
• Coproduct

Applicative

Extends:

• SemiApplicative
• Product

| Name | Given | To | | ---------- | ----------- | -------------- | | liftMonoid | Monoid<A> | Monoid<F<A>> |

Bicovariant

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

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

Chainable

Extends:

• FlatMap
• Covariant

| Name | Given | To | | -------------- | ----------------------------------- | ---------------------- | | tap | F<A>, A => F<B> | F<A> | | andThenDiscard | F<A>, F<B> | F<A> | | bind | F<A>, name: string, A => F<B> | F<A & { [name]: B }> |

Contravariant

Contravariant functors.

Extends:

• Invariant

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

Coproduct

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<F> can produce a Monoid<F<A>> for any type A.

Here's how to distinguish Monoid and Coproduct:

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

• Coproduct<F> allows two F<A> values to be combined, for any A. It also means that for any A, there is an "zero" F<A> 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<A> | | coproductAll | Iterable<F<A>> | F<A> | | getMonoid | | Monoid<F<A>> |

Covariant

Covariant functors.

Extends:

• Invariant

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

Filterable

Filterable<F> allows you to map and filter out elements simultaneously.

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

FlatMap

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

Foldable

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<F> instance.

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

Invariant

Invariant functors.

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

Monad

Allows composition of dependent effectful functions.

Extends:

• FlatMap
• Pointed

Of

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

Pointed

Extends:

• Covariant
• Of

Product

Extends:

• SemiProduct
• Of

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

SemiAlternative

Extends:

• SemiCoproduct
• Covariant

SemiApplicative

Extends:

• SemiProduct
• Covariant

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

SemiCoproduct

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<F> can produce a Semigroup<F<A>> for any type A.

Here's how to distinguish Semigroup and SemiCoproduct:

• Semigroup<A> allows two A values to be combined.

• SemiCoproduct<F> allows two F<A> 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<A>, F<B> | F<A \| B> | | coproductMany | Iterable<F<A>> | F<A> | | getSemigroup | | Semigroup<F<A>> | | coproductEither | F<A>, F<B> | F<Either<A, B>> |

SemiProduct

Extends:

• Invariant

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

Traversable

Traversal over a structure with an effect.

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

TraversableFilterable

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<F>, T<A>, A => F<Either<B, C>> | F<[T<B>, T<C>]> | | traverseFilterMap | Applicative<F>, T<A>, A => F<Option<B>> | F<T<B>> | | traverseFilter | Applicative<F>, T<A>, A => F<boolean> | F<T<A>> | | traversePartition | Applicative<F>, T<A>, A => F<boolean> | F<[T<A>, T<A>]> |

Adapted from:

• cats
• zio-prelude
• zio-cheatsheet