This part covers the ZIO module pattern. ZIO uses a module pattern that a layer depends on the layers imediately below it without knowing their interal implementations. A module consists a set of methods that addresses one oncern. ZIO uses modules to create different application layers depending on each other and allows flexible composition for testing and changing.
0 Common Patterns
There are three common ways to create a ZLayer, the difference is the input type. If the input type is Has[_], use fromFunction. If the input type is the actual service trait, use fromService. Using fromServices to build a layer from multiple services.
|
|
1 The Basic Concepts
ZIO module is implemented using the following types:
1.1 Environment
The ZIO[R, E, A]: represents a type of an immutable value that lazily describes a functional effect (also called ZIO effect, or simply effect). A ZIO effect is a workflow or a job that require an environment of type R and may fail with an error of type E or succeed with a value of type A. An environment can be a generic type of R or a subtype of Has[_].
Environment values are provisioned via provide, provideSome, provideLayer, provideSomeLayer and provideCustomLayer methods.
ZIO.provide:ZIOobject method defined asdef provide[R, E, A](r: => R): ZIO[R, E, A] => IO[E, A] = (zio: ZIO[R, E, A]) => new ZIO.Provide(r, zio). It provides anRto to an effectZIO[R, E, A]to have another effect withoutR, i.e., a type ofIO[E, A].ZIO#provide:ZIOtrait method defined asdef provide(r: R)(implicit ev: NeedsEnv[R]): IO[E, A] = ZIO.provide(r)(self). Eliminate the dependency onR.ZIO#provideSome:ZIOtrait method defined asfinal def provideSome[R0](f: R0 => R)(implicit ev: NeedsEnv[R]): ZIO[R0, E, A] = ZIO.accessM(r0 => self.provide(f(r0))). It provides some of the environment required to run this effect, leaving the remainderR0.ZIO#provideLayer: providers a layer to the ZIO effect to translate it to another layer.ZIO#provideSomeLayer[R0 <: Has[_]](layer: ZLayer[R0, E1, R1]): ZIO[R0, E1, A]: the environment has two parts, provide one part and leaves the reaminderR0.ZIO#provideCustomLayer: defined asfinal def provideCustomLayer[E1 >: E, R1 <: Has[_]](layer: ZLayer[ZEnv, E1, R1])(implicit ev: ZEnv with R1 <:< R, tagged: Tag[R1]): ZIO[ZEnv, E1, A] = provideSomeLayer[ZEnv](layer). It provides an effect with required environment that is not part of theZEnv, leaving the effect that only depends on theZEnv.
Access the environment value using ZIO.access[R](f) or ZIO.accessM[R](f) to perform an opeartion f using R as input. The f can be pure (R => A) or effectful (R => ZIO(R, E, A)).
ZIO.access[R]creates anAccessPartiallyApplied[R]- a class that definesdef apply[A](f: R => A): URIO[R, A] = new ZIO.Read(r => succeedNow(f(r))).ZIO.accessM[R]create anAccessMPartiallyApplied[R]- a class that definesdef apply(f: R => ZIO[R, E, A]) = new ZIO.Read(f).
1.2 Has
The trait Has[A] is used as a ZIO environment to express an effect’s dependency on a service of type A. For example, RIO[Has[Console.Service], Unit] is an effect depedning on Console.Service. It is a pattern to use a type alias for service such as type Console = Has[Console.Service]. Therefore it is hard to tell if an environment has a type of Has[_].
Has[M.Service]: represents an environment of type M.Service, the Has[_] is the R in ZIO[R, E, A]. Usually it is a collection of methods defined in atrait Service or a class Service in a package object or module object M. MultipleHas[A] can be combined.
1.3 ZLayer
A ZLayer[-RIn, +E, ROut <: Has[_]] is a recipe to create an environment of type Rout. It represents an dependecy relationship of a Has[_] type. It describes a layer of an application (onion archtiecture). A layer describes a module’s dependencies and output: a module depends on some servcies (the input RIn) and produces some services (the output ROut is a subtype of Has[_]). Construction of a layer may be effectful.
It utitlizes resources (ZManaged) to manage resources because some resources must acquired and safely released. Layers can be composed horizonally or vertically. ZLayer is used to build the dependency hierarchy in a ZIO application. A ZLayer can be shared, i.e., only one instance is created, or created individually.
In short:
Ris often represented asHas[A]to make it composable.ZLayerrepresents an implementation of a module. It usesZManagedto wrap inputRand outputHas[A].ZLayercan be composed both horizontally and vertically.- Use
ZIO.accessM[Has[A]].(for effectful operation) orZIO.access[Has[A]](for pure operation) to accessHas[A]and then callgetto get an instance ofAand use methods defined inA. - To inject dependency, use
ZIO.provideLayerand related methods to provideRorZLayer.
2 The Module Pattern
A module is an object that defines a set of methods in its Service trait. The service methods are represented by a Has[_] data type and it becomes the output type of an ZLayer value. The module object may define one or more ZLayer implementations of the interface.
ZIO uses ZLayer to deal with the R, the environment parameter, of a ZIO type. A ZIO effect uses the ZIO#provide(r: R) method of an effect to provide a runtime environment for the effect. It eleminates the environment dependency in the resulting effect type, i.e., a value of ZIO[R, E, A] becomes a value of IO[E, A]. The result effect type could also beUIO[A] (no error) or Task[A] (throwable error). The Runtime#unsafeRun method takes an IO[E, A] value. The Runtime#unsafeRunTask method takes a Task[Throwable, A] value.
Thre are three ways to build a module.
2.1 Simple Module
This kind of module is used as a dependency of another module and it is fixed with one implementation – not good for testing. For simple scenarios or business logic module (not changed, only replaced), testing may not be an issue. There are two steps to create a simple module:
- define a class with its constructor depending on a service
- define a companion object to create a
ZLayer.
The following is an example:
|
|
2.2 Module in ZIO docs
Building a module has the following steps:
- Define an object that gives the name to the module, such as
object ModuleName {... }. Define the following fields in the object. Define thetrait Serviceand type alais inside the object. - Define a type alias
type ModualeName = Has[Service]. The type represents a collection of methods defined in the service. - Define a
trait Service { def method1...}that defines the interface methods. - Define an access method for each service method as
def method1(...): ZIO[ModuleName, E, ModuleName] = ZIO.accessM(_.get.method1(...)), theRandEare the method’s input environment type and error type. This allows the business domain logic to use the service methods directly from theobject ModuleName. - Define the different implementations of
ModuleName.Service. It is good idea to define the implementation in a separate file using a class whose constructor uses the dependent service. For example:class implementOne(dep: DepService) extends ModuleName.Service {...}. - Defeine one or more
ZLayerusing the above implementation. UseZLayer.fromFunctionorZLayer.fromServiceto specify dependeent environment.ZLayer.fromFunctiontakes an input of typeRthat is also the environment type of the resultedZLayer. Userr.getto get the service is R isHas[_]. TheZLayer.fromServicetake an input of typeServiceand the enviornemtn type of resultedZLayerisHas[Service].
Following is the commented implementation of zio.system.System:
|
|
2.3 Module with Explict Has (Recommended)
This method use a trait, an object to define a module, not defining an aliase for Has[Service]. In my opinion, this is the recommended styple because it uses consistent name for the trait and object. Also the use of Has making it clear that the type is a Has[_] type.
|
|
3 The Has Date Type
The Has[A] type represents a dependency on a service of type A. Has collects its services in a map. Its get[ModuleName] method accesses the service imlementation. Two Has[_] values can be combined horizontally through + (for a new service) and ++ (for another Has[B]) operators. For example:
|
|
The power of Has is that it can collect and provide all service methods from one place. Below is partial code from the ZEnv.
|
|
4 The ZLayer Data Type
ZIO uses the ZLayer[-RIn, +E, + ROut <: Has[_]] to build an enviornment of Has[], from a value RIn with a possible error type of E during creation. Layer[E, R] is an aliase of ZLayer[Any, E, R]. There are several ways to create a ZLayer:
There are many ways to create a ZLayer:
ZLayer.succeedorZIO.asService: to create a layer from an existing service.ZLayer.succeedMany: to create a layer from a value that is one or more services.ZLayer.fromFunction: to create a lyaer from a fuinction from an enviornmentRto the service.Rcould be an environment or aHas[_]. If it is aHas[_], callR.getto access the service. The result’s enviornment is still the orginalR.ZLayer.fromEffect: to left aZIOeffect to a layer requiring the effect enviornment.ZLayer.fromAquireRelease: create a layer based on resource acquisition/release.ZLayer.fromService: create a layer depends on a specified service. The input is aServiceand the result’s enviornment isHas[Service].ZLayer.fromServices: create a layer depends on the specified services.
There are some variants of creation with different suffixes: build a service effectfully with a suffix of M, resourcefully with a suffix of Managed, or combinately with a suffix of Many.
The ++ composes layers horizontally that includes the requirements of both layers. To build a layer vertically, i.e., one layer is used as the input to another, use layerA >>> layerB, the composed layer has a requirement of the first and the output of the second layer. The first layer’s output is the input of the second layer. It hides the LayerB. To expose both enviornments, use layerA >+> layerB.
Be default, ZIO layers are acquired in parallel and are shared. a non-shared version can be created by ZLayer.fresh.
5 An Example
The following defines a module interface and one implementation:
|
|
The following module depends on another module:
|
|
A sample application uses the above modules:
|
|
6 Summary
The ZLayer has the following patterns:
- Ogranize services into a module that is defined by an object.
- Defining the service interface, the type aliase and access methods is almost the same for each module.
- Each service implementation declares its dependencies.
- Modules can be composed vertically and horizontally, in different places. For example, system-wide dependencies can be provided by a custom runtime.