Skip to content

Latest commit

 

History

History
403 lines (289 loc) · 15.4 KB

README.md

File metadata and controls

403 lines (289 loc) · 15.4 KB
Raw

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: