# Introduction

In addition to abstractions for concrete types, ZIO Prelude provides a set of functional abstractions to describe the common structure of *parameterized types*.

A parameterized type is a type that is parameterized on one or more other types. For example, a `List[A]`

is parameterized on the element type `A`

.

When we are describing the common structure of parameterized types we are talking about the structure of the parameterized type without knowing about the type it is parameterized on. For example, consider the following two abstractions to describe associative ways of combining two values of a data type.

```
trait Associative[A] {
def combine(left: => A, right: => A): A
}
trait AssociativeBoth[F[_]] {
def both[A, B](left: => F[A], right: => F[B]): F[(A, B)]
}
```

The `Associative`

abstraction describes a way of associatively combining two concrete data types.

The syntax is relatively straightforward here. The `Associative`

is parameterized on a type `A`

that has an associative `combine`

operator.

When we define an instance of `Associative`

we know the type of the values we are combining and can use that information in implementing the `combine`

operator. For example we know we have two `Int`

values and can combine them by adding them together.

```
implicit val IntAssociative: Associative[Int] =
new Associative[Int] {
def combine(left: => Int, right: => Int): Int =
left + right
}
// IntAssociative: Associative[Int] = repl.MdocSession$MdocApp$$anon$1@16d6b35a
```

In contrast, the `AssociativeBoth`

abstraction describes a way of associatively combining two parameterized types.

The syntax here may look a little new. Instead of being parameterized on an `A`

, `AssociativeBoth`

is parameterized on an `F[_]`

.

There is nothing special about the `F`

here, just like the `A`

in `Associative`

it is just a placeholder for some type. By convention we start with `A`

for concrete types and `F`

for parameterized types but we can call these types whatever we want.

What is important is the `[_]`

after `F`

. This tells the Scala compiler that this is a parameterized type, such as a `List`

rather than a `List[Int]`

.

The importance of this becomes clear when we define an instance of `AssociativeBoth`

because we do not know anything about the types `A`

and `B`

that the `left`

and `right`

values are parameterized on. This prevents us from doing anything with the `A`

and `B`

values that requires knowledge of their types and so essentially forces us to work exclusively at the level of the `F`

structure.

To see this, consider how we would implement an instance of `AssociativeBoth`

for `List`

.

```
implicit val ListAssociativeBoth: AssociativeBoth[List] =
new AssociativeBoth[List] {
def both[A, B](left: => List[A], right: => List[B]): List[(A, B)] =
left.flatMap(a => right.map(b => (a, b)))
}
// ListAssociativeBoth: AssociativeBoth[List] = repl.MdocSession$MdocApp$$anon$2@415104a7
```

Notice how the `AssociativeBoth`

instance is parameterized on `List`

rather than a list of any specific type. This is important because it says the `ListAssociativeBoth`

instance knows how to combine any two lists in an associative way, not just two lists of some specific type.

What would the implementation of such a way of combining look like? It would not be able to use any information about the `A`

or `B`

values, because they could be anything, so it would have to combine them in a way that worked for any `A`

and `B`

values.

The `AssociativeBoth`

abstraction does this by combining the `A`

and `B`

values into a tuple. We will see later that this is one of two fundamental ways that we can combine two values in a generic way.

In our implementation for `List`

we return the Cartesian product of the two lists, which is an associative operation after reassociating nested tuples.

We'll talk more about `AssociativeBoth`

in the section on that abstraction. For now the goal of this discussion is not to discuss `AssociativeBoth`

in detail but to get a sense of what it means to describe the structure of a parameterized type instead of a concrete one.

Just like for concrete types, the abstractions for parameterized types fall into two categories.

## Properties Of Parameterized Types

The first set of abstractions define properties of single values of a parameterized type `F[A]`

. All of them describe the fundamental nature of the `A`

parameter with respect to `F`

.

### Invariant

The first relationship that `A`

can have to `F`

is that `F`

both produces and consumes `A`

values. For example, a `JsonCodec[A]`

both produces `A`

values by turning JSON into `A`

values and consumes `A`

values by turning `A`

values into JSON.

Parameterized types that both produce and consume `A`

values are *invariant* in the `A`

type parameter and we describe them with the `Invariant`

abstraction.

An invariant type `F[A]`

can be transformed into an `F[B]`

with an `Equivalence[A, B]`

using the `invmap`

operator. Conceptually, if we have a data type that produces and consumes `A`

values we can always turn it into a data type that produces and consumes `B`

values by transforming all inputs into `A`

values and all outputs back to `B`

values with the equivalence relationship.

This is useful to "lift" equivalence relationships into the context of a parameterized type. For example, if we have defined an equivalence between new and old versions of our data model we can use `Invariant`

to convert the `JsonCodec`

for the old data model into a `JsonCodec`

for the new data model.

### Covariant

The second relationship that `A`

can have to `F`

is that `F`

produces `A`

values but does not consume them. Data types that produce `A`

values may either just contain existing `A`

values, like a `Chunk`

, or potentially produce `A`

values at some point in the future, like a `ZIO`

.

Parameterized types that produce but do not consume `A`

values are *covariant* in the `A`

type parameter and we describe them with the `Covariant`

abstraction.

A covariant type `F[A]`

can be transformed into an `F[B]`

with a function `A => B`

using the `map`

operator. Conceptually, if we have a data type that produces `A`

values then we can create a data type that produces `B`

values simply by taking each output and transforming it with the function.

This is useful to allow us to transform the output of a covariant type to build richer data pipelines. For example, if we had a function that decrypted some data and a `ZIO`

effect that loaded the encrypted data from a file we could return a new `ZIO`

effect that produced the decrypted data, which we could then compose with the rest of our program.

### Contravariant

The third relationship that `A`

can have to `F`

is that `F`

consumes `A`

values but does not produce them. Examples of data types that consume values of one or more types include Scala functions with respect to their input, `ZIO`

with respect to its environment type, and `ZSink`

with respect to stream elements.

Parameterized types that consume but do not produce `A`

values are *contravariant* in the `A`

type parameter and we describe them with the `Contravariant`

abstraction.

A contravariant type `F[A]`

can be transformed into an `F[B]`

with a function `B => A`

using the `contramap`

operator. Conceptually, if we have a data type that consumes `A`

values then we can create a data type that consumes `B`

values simply by transforming each `B`

value into an `A`

value with the function before feeding it to the original data type.

This is useful to allow us to transform the input of a contravariant type to build richer data pipelines. For example, if we have a sink that takes chunks of bytes and writes them to a file we could transform it into a sink that takes strings and writes them to a file by providing a function to transform strings into bytes.

### ForEach

The `ForEach`

abstraction builds on the `Covariant`

abstraction by describing a data type that not only produces `A`

values but actually contains zero or more `A`

values as opposed to merely being able to potentially generate them at some point in the future. For example, a `Chunk`

has zero or more existing `A`

values and so has a `ForEach`

instance defined for it whereas a `ZIO`

merely may produce an `A`

value at some point in the future.

A data type with a `ForEach`

instance contains zero or more existing `A`

values so we can iterate over it, potentially transforming its values while maintaining its structure using an operator like `ZIO.foreach`

. We can also tear it down entirely and reduce it to a summary value with an operator like `foldLeft`

.

This ability to get an `A`

value out of the data type only exists because `ForEach`

describes a data type where the `A`

values already exist. If we had a data type like `ZIO`

then we would not be able to get an `A`

value out of it because a `ZIO`

is only a description of a workflow that may produce an `A`

value when it is run.

The `ForEach`

abstraction is one of the most practically useful functional abstractions in ZIO Prelude. Most collection operators can be defined in terms of `ForEach`

and especially in combination with the abstractions for describing ways of combining concrete types it provides very powerful ways of working with collections.

### NonEmptyForEach

The `NonEmptyForEach`

abstraction further builds on `ForEach`

to describe a parameterized type that contains one or more existing `A`

values. For example, a `NonEmptyChunk`

is guaranteed to contain at least one `A`

value.

Because a data type with a `NonEmptyForEach`

instance must always contain at least one existing `A`

value we can define certain operators for it that would not be safe to define for a data type that might not contain any `A`

values. For example, we can define a `reduce`

operator that reduces the collection to a summary value with an associative operator whereas with a `ForEach`

instance we can only define a `fold`

operator that also requires an identity value to handle the empty case.

## Combining Parameterized Types

The second set of abstractions describe ways of combining parameterized types.

Because of the additional structure of parameterized types there are three separate ways that we can combine values of parameterized types, each of which may satisfy properties of associativity, commutativity, and identity.

The first way of combining an `F[A]`

and an `F[B]`

is to return both `A`

and `B`

values. This corresponds to some notion of doing both things, though what exactly this means will depend on the parameterized type and the combining operation.

This way of combining is described by the `AssociativeBoth`

, `CommutativeBoth`

, and `IdentityBoth`

functional abstractions.

The second way of combining an `F[A]`

and an `F[B]`

is to return either an `A`

or a `B`

value. This corresponds to some notion of choosing which value to return, though again what exactly this means and how we choose will depend on the parameterized type and the combining operation.

This way of combining is described by the `AssociativeEither`

, `CommutativeEither`

, and `IdentityEither`

functional abstractions.

The third way of combining actually combines two layers of `F`

values, converting an `F[F[A]]`

into an `F[A]`

. This corresponds to some notion of evaluating the outer layer and then evaluating the inner layer.

This way of combining is described by the `AssociativeFlatten`

and `IdentityFlatten`

functional abstractions.

### AssociativeBoth

The `AssociativeBoth`

abstraction describes a parameterized type `F[A]`

with an associative operator `both`

that can combine a value of type `F[A]`

and a value of type `F[B]`

into a value of type `F[(A, B)]`

. This is described by the `zip`

operator on `ZIO`

and corresponds to running the left value and then running the right value.

### CommutativeBoth

`CommutativeBoth`

describes a way of combining an `F[A]`

and an `F[B]`

to produce an `F[(A, B)]`

that is both associative and commutative.

This is described by the `zipPar`

operator on `ZIO`

and corresponds to running the left value and the right value in parallel, since this is the only way that the order will not matter as required by the commutative property.

### IdentityBoth

The `IdentityBoth`

abstraction describes a way of combining an `F[A]`

and an `F[B]`

to produce an `F[(A, B)]`

that is both associative and has an identity value of type `F[Any]`

. In ZIO the identity value is value is `ZIO.unit`

since zipping any value with unit is equivalent to returning the original value unchanged

### AssociativeEither

The `AssociativeEither`

abstraction describes a parameterized type `F[A]`

with an associative operator `either`

that can combine a value of type `F[A]`

and a value of type `F[B]`

into a value of type `F[Either[A, B]]`

. This is described by the `orElseEither`

operator on `ZIO`

and corresponds to running the left value, but if it fails then running the right value.

### CommutativeEither

`CommutativeEither`

builds on `AssociativeEither`

by describing an operator that combines an `F[A]`

and and `F[B]`

to produce an `F[Either[A, B]]`

in a way that is both associative and commutative. In ZIO this corresponds to the `raceEither`

operator which runs both effects concurrently and returns the first to succeed, since running both effects concurrently is the only way that the order will not matter as required by the commutative property.

### IdentityEither

The `IdentityEither`

abstraction describes a way of combining an `F[A]`

and an `F[B]`

to produce an `F[Either[A, B]]`

that is both associative and has an identity value of type `F[Nothing]`

. `ZIO`

does not have such an identity value since it is not possible to fail without any error but conceptually such an identity would correspond to a failure that did not contain any information.

### AssociativeFlatten

The `AssociativeFlatten`

abstraction describes the ability to flatten two layers of `F`

structure in an associative way. In `ZIO`

this corresponds to the `flatten`

operator, and in combination with the `Covariant`

abstraction the `flatMap`

operator, corresponding to running one `ZIO`

value and using its result to generate another `ZIO`

value and running that value.

### IdentityFlatten

The `IdentityFlatten`

abstraction describes an identity value of type `F[Any]`

with respect to the associative flattening operation defined by `AssociativeFlatten`

. In `ZIO`

this corresponds to `ZIO.unit`

and is the same as the identity value defined by the `IdentityBoth`

instance.