Guiding principles of effect design

[johnhungerford]

I wanted to propose some principles to guide decisions about whether a custom effect should be provided for a given use case. Would love to hear feedback and suggested changes/additions.

• Core effects should be preferred over custom effects
  • As new effects are used, the effect intersection can get really messy
  • Reducing the number of distinct effects reduces the number of kyo-specific patterns to learn, making it easier for new-comers to interpret function signatures
  • Effect "tracking" is not all that useful
  • It is a problem to have more than one way of doing something -- this a big problem for Scala in general. Using a new effect to do something that can easily be done another way adds to this. Anywhere that we can reduce the number of approaches we should do so.
  • Most importantly: introducing new effects forces users to either add those effects throughout their application, create complicated mechanisms for polymorphism (e.g., tagless-final), or handle them locally all over the place
• Assume the service pattern
  • This is an important lesson from the ZIO community, with a lot of community experience behind it
  • When dependencies are tracked in regular function signatures, they add a lot noise to the public API and make it harder to support multiple implementations with different dependencies. To avoid this noise, dependencies end up having to be provided locally, which generally means taking a dependency stored as a field in a class and using provide to satisfy an Env effect in each method. This means you are essentially just using the service pattern but in a more complicated and verbose way.
  • The cleanest way to organize the code base is for Env to be used only in service constructors, which can be abstracted as Layers.
  • Locals should only be used to provide dependencies that are (1) ubiquitous, (2) have very obvious defaults, and (3) users will be angry to have to deal with. Log and Console are the only ones I can think of that really fit this description.
  • All APIs should assume users will use the service pattern and encourage them to do so
• Circumstances where new effect type may be justified
  • Used locally and adds convenience
    • Choice and Var are utilities which will generally be useful for an implementation but will generally not be exposed in the public signatures of the module/class in which they are used. They provide a convenient way of accomplishing certain things that otherwise could not be accomplished easily -- at least not in composition with other kyo-effects.
    • Questions to ask: (1) Can a user easily use this within a single class without exposing the effect type in the public API? (2) Will doing so provide some clear convenience that wouldn't be achieved by other means?
  • Exposed at the level of dependency management, or service constructors, and handled at the edge of the application
    • Unlike Choice and Var, Env will generally be exposed across modules. However, as discussed above, when properly used Env really only shows up in Layers, which means that when module1 depends on module2, module2 will not have to be aware of any Env effects of module1. Furthermore, by pushing the Env effect to constructors (i.e. Layer), it is easy to support variable Env types without having to refactor anything -- each constructor can have its own different dependency types.
    • Questions to ask: (1) Can this effect be confined to constructors/layers? (2) Can it be handled only at the edge of the application? (3) Is it not possible to reduce this effect to Env (most effects of this type could just be rewritten as a dependency).
  • Global or semi-global "base" effects
    • Sync and Async can be understood as fundamental effects -- they indicate that this part of the application includes side-effecting and possibly asynchronous processes. Users will not generally be annoyed by the proliferation of these effects throughout their application.
    • STM is a good example of a less obvious effect of this type. While STM can also fall under "local use with added convenience", it is frequently used as a global/semi-global base effect. Well-designed applications often do include entire modules dealing entirely with transactional memory manipulation. In a traditional OOP codebase, such modules would generally include some transaction class in many or all of the public method signatures. Also, importantly, STM can't be composed with side-effecting types, so it represents a separate "domain" of effects.
    • Questions to ask: (1) Is this an effect that needs to be handled at the boundary of an application or module? (2) Can it not be reduced to another base effect without losing functionality (e.g., composability)? (3) Can this effect compose only with certain other effect types? (4) Will users want to track this effect all over the place?

[fwbrasil]

This is great! It seems these principles work well for both introducing effects in Kyo's codebase itself and user codebases. We might need an even more constrained version with more warnings to discourage uncontrolled proliferation of new effects, especially user-defined ones.

Assume the service pattern

Can you elaborate on this with an example? It's not clear to me.

Used locally and adds convenience

Other good example is if a new effect significantly reduces the number of tracked effects and hides implementation details. An example is Parse. We could have exposed the underlying effects directly instead of introducing a new one.

Exposed at the level of dependency management, or service constructors, and handled at the edge of the application

Can you also elaborate on this?

Circumstances where new effect type may be justified

Another important category is effects that manipulate the control flow via continurations like Poll, Emit, Choice, etc.

What do you think about also documenting the pattern of composite effects via opaque type, ContextEffect for contextual values, and ArrowEffect for custom control flow?

[johnhungerford]

Assume the service pattern

Can you elaborate on this with an example? It's not clear to me.

The service pattern refers to the following approach to structuring a codebase:

trait IOService:
    def write(value: String): Unit < (Abort[DomainError] & Async)
    def read: String < (Abort[DomainError] & Async)

object IOService:
    val live = Layer.from(Live.apply)

    // **Contrived example**: unlikely that `Console` would ever be an explicit dependency...
    final case class Live(console: Console) extends IOService:
        def write(value: String): Unit < (Abort[DomainError] & Async) =
            console.printLine(value)
        def read: String < (Abort[DomainError] & Async) =
            console.readLine

trait SendService:
    def send(value: DomainType): Unit < (Abort[DomainError] & Async)

object SendService:
    val live = Layer.from(Live.apply)
    val test = Layer:
       AtomicRef.init(List.empty[DomainType]).map(ref => TestSendService(ref))

    final case class Live(ioService: IOService)(using Codec[DomainType]):
        def send(value: DomainType): Unit < (Abort[DomainError] & Async) =
            Codec[DomainType].encode(value).map: valueStr =>
                ioService.write(valueStr)

    final case class TestSendService(ref: AtomicRef[List[DomainType]]):
        def send(value: DomainType): Unit < (Abort[DomainError] & Async) =
            ref.update(value :: _)

        def sentValues: List[DomainError] < Sync = ref.get

object MyApp extends KyoApp:
    val consoleLayer = Layer(Console.live)

    run:
        Memo.run:
            Env.runLayer(SendService.live, IOService.live, consoleLayer):
                Env.get[SendService].map: sendService =>
                    sendService.send(???)

Some basic features of this pattern:

1. Dependencies are fields of the implementation classes
2. Env does not show up anywhere in the interface or implementations
3. Env only appears in the Layer which are provided in companion objects
4. Env is handled only in MyApp via automatic wiring of layers

Requests goes against this pattern because it provides the Backend via Local, making it somewhat complicated to use the service pattern to make the Backend available. Here is how a user would have to do it:

final case class HttpSendService(uri: URI, backend: Backend) extends SendService:
    def send(value: DomainType): Unit < (Abort[DomainError] & Async)(using Codec[DomainType]) =
        Codec[DomainType].encode(value).map: valueStr =>
             Requests.let(backend)(Requests(_.post(uri).body(valueStr))

It would be more straightforward for Requests to use Backend directly (note renamed as RequestsClient):

final case class HttpSendService(uri: URI, client: RequestsClient) extends SendService:
    def send(value: DomainType): Unit < (Abort[DomainError] & Async)(using Codec[DomainType]) =
        Codec[DomainType].encode(value).map: valueStr =>
             client.send(_.post(uri).body(valueStr))

More generally, we want to avoid the following pattern, at least in the case where SomeEffect describes a dependency that could be provided via the service pattern via Env:

trait SomeEffect extends ContextEffect[X]
// OR
opaque type SomeEffect <: AnotherContextEffect = ....

object Module:
    def moduleMethod: Value < SomeEffect

Used locally and adds convenience

Other good example is if a new effect significantly reduces the number of tracked effects and hides implementation details. An example is Parse. We could have exposed the underlying effects directly instead of introducing a new one.

Yes this is a good point, and this should be explicitly presented as a pattern for abstracting over some set of existing effects: use an opaque type with the abstracted effects as an upper bound. I think it's safer to expose them this way as you have consistently done.

I would still point out that in the case of Parse, it is primarily justified in terms of the local usage + convenience principle: it is easy to use locally without having it take over signatures everywhere.

Exposed at the level of dependency management, or service constructors, and handled at the edge of the application

Can you also elaborate on this?

The example above with Env is the main one: Env is only introduced in the layers, and is handled in KyoApp. It's been hard for me to think of custom examples that are not reducible to Env or could not be easily accomplished by other means. However, one good example of pushing effects to layers to keep them out of service methods is a pattern with Scope that I used a lot in ZIO. Consider a "receive" variant of the SendService from above:

trait ReceiveService:
    def receive: DomainType <  (Abort[DomainError] & Async)

object ReceiveService:
    val live = Layer:
        Hub.initWith[DomainType](hub => Live(hub))

    final case class Live(hub: Hub[DomainError]) extends ReceiveService:
        def receive: DomainType <  (Abort[DomainError] & Async) =
             Scope.run(hub.listen(1).map(_.take))

In the above example, Hub.initWith introduces Scope in live (the Layer) which means that it does not have to appear anywhere in the trait. The Scope effect introduced in the Live implementation of receive can be handled there, because the listener should be closed each time.

Circumstances where new effect type may be justified

Another important category is effects that manipulate the control flow via continurations like Poll, Emit, Choice, etc.

I guess I wouldn't consider these separate categories from those I discussed. The reason to have them is justified by the local + convenience principle:

• The inconvenience of having to handle Emit is outweighed by the convenience of being able to express incremental computation while also making use of other effects. Thus Emit can be used locally (e.g., within Stream) without really having to expose the Emit effect. Poll is similarly useful in Pipe/Sink and also Actor.
• The inconvenience of having to handle Choice is outweighed by the convenience of being able to explore branches while using other effects

In each of these cases, it's easy to use the effect without it leaking into your public signatures.

I would contrast this with Routes, which I think unnecessarily abstracts the emission of tapir server routes. In the first place, it's probably easier or at least more straightforward to the user to simply generate routes and then use them as he or she wishes. That is, there is already a perfectly convenient way to combine routes that is not substantially improved upon by the Routes effect. Secondly, if we did want to keep this approach, I think it would be better to simply use Emit[ServerRoute] in this case and provide a specialized handler. This would make it clearer to the user what's going and not have to wonder about the meaning of Routes.

This points back to your observation about Parse: Parse combines a bunch of effects (and therefore simplifies the type intersection rather than complicating it) while adding substantial additional convenience that would be difficult for the user to reproduce without it, whereas Routes (I would argue) does neither.

What do you think about also documenting the pattern of composite effects via opaque type, ContextEffect for contextual values, and ArrowEffect for custom control flow?

At a minimum I think documenting "the pattern of composite effects via opaque type" (great way of putting this) is worth doing -- provided we include guidance about when it's worth it. I'm inclined not even to document ArrowEffect and ContextEffect since I'm so hesitant to encourage users to make custom effects!

[fwbrasil]

Thanks for the clarifications, I can see it now.

Yeah, I find it interesting that, while more academic work would at this point favor expressiveness of handlers as the main feature of the library for some ideal of final, most capable effect mechanism, rather than having its main goal being practical. Polluting the well-guarded "pending set" of months of refinement we've done here to then have anything be a part of it is a bit worrisome if the actual design gets lost in pointless custom effects.

Making custom effects pointless I'd say is a main "guiding principle" in Kyo. It's a search for an ergonomic good "slice" of effects that is powerful just enough but not more. Hard agree in trying to contain it as an advanced aspect of the library! I'd say even "composite effects" (not great with names, sorry) should be considered advanced at least initially to explore how well the current build-in effects attend a good number of needs.

I wrote Routes but haven't had much need for it yet and I'd say it's definitely due for a new design and an analysis of its performance, the same for Requests

[johnhungerford]

I suspect that a big reason for favoring "expressiveness of handlers" is that type classes and/or algebraic effects are the primary way to define "interfaces" in non-OO FP languages like Haskell. So each module or "service" would have its own algebra, and different "implementations" would amount to different handlers (for algebraic effects) or different type class instances. In the first case (algebraic effects), effect handlers would interpret the service's effects in terms of other lower-level effects, and in the second, each type class instance of a service would implement the algebra in terms of lower level type classes.

The result is that for algebraic effects dependency resolution is accomplished through the chaining of handlers at the edge of the program, and for type classes it is accomplished through type class instance resolution (implicit resolution in Scala) at the edge of the program. Type class instance resolution seems to me a particularly bad means of dependency resolution because it is done entirely at compile time and I have not seen any good way to combine it with runtime configuration.

Using algerbraic effect handlers to resolve dependencies is an interesting idea though. If there were not a good way of wiring Env dependencies automatically, it would not be obvious to me that this is a bad way to do it. It would end up being slightly simpler than manual OOP application construction: instead of constructing objects and passing them to other constructors/builders, you would just have to apply handlers in the correct sequence. This could probably also be automated in the same way that Env is currently automated in Kyo. In fact, as I recall my first contribution to the project was to suggest Layer understood more broadly as Layer[FromEffect, ToEffect]. I don't see why layers understood as handlers couldn't be wired automatically.

I would not recommend this approach in kyo for a couple reasons:

1. Defining an effect algebra in kyo is substantially more complicated than defining a trait
2. Implementing an effect handler in kyo is substantially more complicated than implementing a trait as a class
3. It would require a greater mental lift for people coming from OOP, who are used to having dependencies available to them as objects in their classes
4. A lot of lower-level dependencies (e.g., functionality coming from Java) or external library dependencies are already organized in the OOP way and therefore fit more gracefully into the wired-Env approach. (It's easy, for instance, to just make a Layer[ComboPooledDataSource, ?] and have that depend on other dependencies.)

[fwbrasil]

I see. Layer paired with the service pattern can be seen as a more flexible module mechanism. I considered something like this in the past:

class Module[+S]:
    type Kyo[A] = A < S

package object myPackage extends Module[Async]

to export a Kyo type to the package and not require fine-grained tracking in the actual code so you'd handle effects at the package boundaries. Something similar to the component model in WASM. Layer provides a similar mechanism but with more flexible scoping, which can be more ergonomic especially with the macro conveniences. The direction makes sense to me, more convenient and isolated effect tracking and handling can be a good UX improvement.

This could probably also be automated in the same way that Env is currently automated in Kyo. In fact, as I recall my first contribution to the project was to suggest Layer understood more broadly as Layer[FromEffect, ToEffect]. I don't see why layers understood as handlers couldn't be wired automatically.

I was taking a look at the previous Layer implementation. At the time, my concern was short-circuiting effects being order sensitive, but I realized something while looking at the code for Options at the time:

def layer[Se](onEmpty: => Nothing < Se): Layer[Options, Se] =
    new Layer[Options, Se]:
        override def run[T, S](effect: T < (Options & S))(implicit
            fl: Flat[T < (Options & S)]
        ): T < (S & Se) =
            Options.run[T, S](effect).map {
                case None    => onEmpty
                case Some(t) => t
            }

Composition of Layers enables handling effects without having to transform the result type of the computation (like in the Isolate.Transform limitation we discussed recently). I agree it seems possible to wire generic effect handling layers, including short-circuiting effects, without ordering issues.

That said, I wonder if we need more than just Env in layers. Other effects will typically be used locally as you mentioned. I'd find strange a Layer that handles a Parse or Pool for example. Would you have applications of more interesting layers in mind?

[johnhungerford]

I considered something like this in the past

The code block you include here indicates a nice possible approach for specifying a "base effect" for a module. However, I think it's dangerous to alias different modules' base effects to the same name -- that would be confusing to new users who would see the same name in different modules and think it's the same type. It's probably good advice though to think about what the base effect of your module is and consider giving it an alias if the module is large and the intersection has more than one type. This would especially be useful if you wanted some bounded polymorphism:

package domain

type DomainKyo[A, E <: DomainError] = A < (Abort[E] & Async & Scope)

That said, I wonder if we need more than just Env in layers

To be clear, for the four stated reasons in my previous post, I don't want Layer to support handling effects in general, only Env. I just brought that up as a thought experiment because I want to be clear about whether we should aggressively promote the service pattern (which I still think we should).

That said, while Layer should only be used to handle Env, it can and should allow non-Env effects in its output intersection. This allows us to use arbitrary effects like Sync, Async, and Scope in our constructors which are very often needed for initializing dependencies (simple example: generate an AtomicRef used for within the service). I could see effects being introduced by constructors for other reasons as well. A user might also want to include Emit or Var to track the order in which dependencies are constructed, for instance.

[johnhungerford]

Quick stab at turning some of these thoughts into a "do/don't" list:

1. Do not use custom effects as a module/service abstraction
   • You should not see the following in your codebase: val res = Response < DatabaseRequest = DatabaseRequest.submit(request)
2. Do use the service pattern
   • Encapsulate functionality as regular classes with dependencies as fields, exposing constructors as Layers to be auto-wired at the edge of the program
   • You should see the following: val res: Response < (Sync & Abort[DomainError]) = databaseService.submit(request)
   • Env should only ever appear in constructors/Layers
3. Do not add custom effects (traits extending ContextEffect or ArrowEffect) to your codebase
   • If you discover some fundamentally new algebra that cannot be described in terms of existing kyo effects, open a PR to the kyo repository
4. Do create "custom composite effects" when one or more implementations require consistently using a specific group of kyo effects that need to be handled in very specific ways
   • Define the composite effect as an opaque alias of the required effect intersection with that intersection as its upper bound: opaque type CustomEffect <: (Abort[SpecialError] & Choice & Poll[Input] & Emit[Output]) = Abort[SpecialError] & Choice & Poll[Input] & Emit[Output]
   • Define all custom handlers within the opaque scope (i.e., where the opaque type is known to the compiler)
5. Do not use custom composite effects a the "base type" of a module
   • opaque type DomainKyo[A] <: Async & Abort[DomainError] = Async & Abort[DomainError] makes it difficult to use the effect because it requires a special handler just to reduce it to the component effects.
6. Do use a simple type alias for the "base effect type" of a module when there are multiple effects
   • type DomainKyo[A] = Async & Abort[DomainError] can reduce a fair amount of boilerplate and make refactoring easier
   • Make sure different modules use different names so they don't confuse users
7. Do not alias aliased effects
   • type DomainKyo[A] = CustomEffect1 & CustomEffect2 makes it much harder for users -- especially but not only new users -- to keep track of what effects they are looking at
8. In the absence of a very compelling reason to do otherwise, the signatures of public methods should include only the following effects: Sync, Async, Abort, and Scope
   • Modules dealing narrowly with domain logic may use STM instead
   • Modules dealing narrowly effect-specific utilities (e.g., Parser) may expose those effects
   • Modules dealing with Emit should probably expose Stream instead
   • Other effects should be considered implementation details, used in private methods and handled