ZIO Prelude Documentation

ZIO Prelude is a lightweight library providing functional abstractions and data types with tight ZIO integration. It focuses on three main areas:

1. Data structures and traversal: Extends Scala standard library collections with new instances and useful additions.
2. Patterns of composition for types: Provides binary operators for combining two values of the same type, named after algebraic laws like Associative, Commutative, and Identity.
3. Patterns of composition for type constructors: Provides binary operators for type constructors (e.g., Future, Option, ZIO) that produce structures like tuples or Eithers.

Key features include:

• Functional Data Types: Types like NonEmptyList, NonEmptySet, ZSet, ZNonEmptySet, Validation, and ZValidation for accurate domain modeling.
• Functional Abstractions: Ways to combine data in a principled manner.
• New Types: Zero-overhead Subtype wrappers to increase type safety in domain modeling.
• ZPure: A high-performance alternative to monad transformers that supports logging, context, state, and errors.
• zio.prelude.fx: A research-stage package providing abstractions over expressive effect types like ZIO and ZPure.

Ord[A] describes a total ordering on values of type A. It allows you to compare any two values and determine if the left value is LessThan, GreaterThan, or Equals the right value.

Key Differences from scala.math.Ordering

1. Variance and Type Inference: Unlike the invariant scala.math.Ordering, Ord is contravariant (Ord[-A]). This means if you have an Ord[CustomerAccount], you can automatically use it to compare ConsumerAccount or BusinessAccount subtypes without manual type widening. This solves common type inference failures in Scala when comparing subtypes.
2. Result Type: Instead of returning an Int (where negative/positive/zero is used), Ord returns a sealed trait Ordering (LessThan, GreaterThan, or Equals), which is more expressive and type-safe.
3. Integration: Ord integrates with other ZIO Prelude abstractions and provides operators like =?= and <> for easier composition.

Interoperability

import zio.prelude.Ord

// Convert Scala Ordering to Ord
val toScala: scala.math.Ordering[Int] =
  Ord[Int].toScala

// Convert Ord to Scala Ordering
val fromScala: Ord[Int] =
  Ord.fromScala(scala.math.Ordering[Int])

NonEmptyList is a data type representing a List that is guaranteed to contain at least one element. It is defined by two cases: Single[A](head: A) and Cons[A](head: A, tail: NonEmptyList[A]).

Why use it?

• Accurate Domain Modeling: Use it when your business logic dictates a collection cannot be empty (e.g., a collection of errors that only exists if an error occurred).
• Type-Level Safety: Unlike Scala's standard List, NonEmptyList allows you to call methods like head, reduceLeft, or reduceRight without fear of exceptions or having to handle empty cases.
• Preserving Information: Many operations on NonEmptyList (like map) return a NonEmptyList, preserving the knowledge that the collection is not empty, whereas standard library operations often revert to a standard List to account for potential emptiness.

sealed trait NonEmptyList[+A]
object NonEmptyList {
  case class Single[A](head: A)                      extends NonEmptyList[A]
  case class Cons[A](head: A, tail: NonEmptyList[A]) extends NonEmptyList[A]
}

An Invariant[F] describes a parameterized type F[A] that both consumes and produces A values. It provides the invmap operator, which allows you to "lift" an Equivalence[A, B] (an A <=> B relationship) into an equivalence relationship between F[A] and F[B].

Core Concepts

• Equivalence (<=>): A data type representing a bidirectional transformation between two types A and B without losing information. It consists of a to: A => B function and a from: B => A function.
• Lifting with invmap: If you have a way to convert A to B and back, invmap provides a way to convert a container/context of As into a container/context of Bs.

Laws

To be a valid Invariant, the implementation must follow these laws:

1. Identity: fa.invmap(Equivalence.identity) === fa
2. Composition: fa.invmap(f).invmap(g) === fa.invmap(f.andThen(g))

Common Invariant Types

• JsonCodec[A] (where A is both encoded and decoded)
• Scala's Set[A]
• ZIO's Ref[A], Queue[A], and Hub[A]

// Using invmap in infix form (requires importing zio.prelude._)
val codecB: JsonCodec[B] = codecA.invmap(equivalenceAB)

A ZPure[W, S1, S2, R, E, A] is a description of a pure computation that provides four specific capabilities in a single, high-performance data type:

• Errors (E): Can fail with an error of type E (similar to Either).
• Context (R): Requires an environment of type R (similar to Reader).
• State (S1, S2): Can transition from an initial state S1 to an updated state S2 (similar to State).
• Logging (W): Produces a log of type W (similar to Writer).

When to use ZPure vs ZIO: Use ZPure when you want to model computations that use these four capabilities without embedding arbitrary side-effecting code. If your computation requires managing IO or concurrency, use ZIO instead. ZPure is designed for high performance and better ergonomics than traditional monad transformer stacks.

// The type signature represents:
// W: Log type
// S1: Initial state type
// S2: Updated state type
// R: Environment type
// E: Error type
// A: Success value type
case class ZPure[+W, -S1, +S2, -R, +E, +A](run: (R, S1) => (Chunk[W], Either[E, (S2, A)]))

The AssociativeFlatten[F] abstraction describes a way to combine two layers of a nested value F[F[A]] into a single layer F[A] in an associative manner.

Conceptually, flatten represents running an outer value to produce an inner value, and then running that inner value to produce a final result. This allows for dynamic workflows where the next step depends on the result of the previous step.

Associative Law

The flatten operator must satisfy the following law:

fffa.flatten.flatten == fffa.map(_.flatten).flatten

Common Interpretations

Different data types interpret flatten differently based on their semantics:

• ZIO: Runs the first workflow, and if successful, runs the resulting workflow.
• ZStream: Concatenates the inner streams into a single stream.
• Either / Option: If the outer layer is a success, returns the inner value; otherwise, returns the failure/none.
• Collections (e.g., Chunk): Concatenates the inner collections into a single collection.

trait AssociativeFlatten[F[+_]] {
  def flatten[A](ffa: F[F[A]]): F[A]
}