Effect Essentials
The Effect Type

The Effect Type

The Effect<Requirements, Error, Value> type represents an immutable value that lazily describes a workflow or job.

It encapsulates the logic of a program that requires a collection of contextual data Context<Requirements> to execute. This program can either fail, produce an error of type Error, or succeed, yielding a value of type Value.

Conceptually, you can think of Effect<Requirements, Error, Value> as an effectful version of the following function type:

type Effect<Requirements, Error, Value> = (
  context: Context<Requirements>
) => Error | Value

Effects are not actually functions, of course, they can model synchronous, asynchronous, concurrent, and resourceful computations.

Type Parameters

The Effect type has three type parameters with the following meanings:

  • Requirements. Represents the contextual data required by the effect to be executed. This data is stored in a collection named Context. If this type parameter is never, it means the effect has no requirements and the Context collection is empty.
  • Error. Represents the expected errors that can occur when executing an effect. If this type parameter is never, it means the effect cannot fail, because there are no values of type never.
  • Value. Represents the type of value that an effect can succeed with when executed. If this type parameter is void, it means the effect produces no useful information, while if it is never, it means the effect runs forever (or until failure).

In the Effect ecosystem, you may often encounter the type parameters of Effect abbreviated as R, E, and A respectively. This is just shorthand for Requirements, Error, and the success value of type A.

Effect values are immutable, and all Effect functions produce new Effect values.

Effect values do not actually do anything, they are just values that model or describe effectful interactions.

An Effect can be interpreted by the Effect Runtime System into effectful interactions with the external world. Ideally, this occurs at a single time, in our application's main function.