Typed Dependencies with fp-go Effect

fp-go Effect: Typed Dependencies

Core Principle: C Is for Dependencies

// Effect[C, A] = func(C) func(context.Context) func() Result[A]
type Effect[C, A any] = readerreaderioresult.ReaderReaderIOResult[C, A]

An Effect takes three inputs, and each input has its own job:

Rules that follow from this:

1. Every dependency goes into C. Never store it in context.Context (untyped, unchecked, panics on a missing key). Never pass it as a parameter through every layer, and never keep it in a package-level global.
2. C is a type, so the compiler checks the wiring. A function's signature Effect[UserDeps, User] states exactly what it needs. Code that forgets to provide something does not compile.
3. Declare the narrowest C per function. A function that only reads users asks for UserDeps, not for the whole application. Widen it with Local where it is composed.
4. Provide once, run many times. Build the dependency graph at startup, Provide it, and RunSync per request with that request's context.
5. Request-scoped data stays in context.Context (see the fp-go-context skill). If a value differs per request, it is not a dependency.

Before You Generate

fp-go is low-frequency in training data, so signatures are easy to misremember. For any combinator not shown below, look it up via the fp-go MCP server's search_examples / get_example tools (see the fp-go-mcp skill) instead of guessing. After writing code, run go build ./... and go vet ./... and fix any type-parameter or argument-order errors before presenting it.

When to Use Effect

Effect is the recommended top-level monad for service code. Every RIO operator still works inside it (see "Runtime Context Inside an Effect").

Designing the Dependency Type

One Capability Interface per Package

Each package that needs something from outside declares a small capability interface with getter methods, a private implementation, a constructor and a generic upcast helper:

package users

// UserRepo is the port; the adapter (Postgres, in-memory, fake) implements it.
type UserRepo interface {
    FindUser(ctx context.Context, id int) (User, error)
}

// UserDeps is what this package needs from its environment.
type UserDeps interface {
    GetUserRepo() UserRepo
}

type userDeps struct{ repo UserRepo }

func (d *userDeps) GetUserRepo() UserRepo { return d.repo }

// MakeUserDeps is the only way to build the dependency.
func MakeUserDeps(repo UserRepo) UserDeps { return &userDeps{repo} }

// AsUserDeps upcasts any wider dependency that embeds UserDeps.
// It is used with EF.Local to run a UserDeps effect inside a wider C.
func AsUserDeps[R UserDeps](r R) UserDeps { return r }

• Getters, not fields. An interface lets callers supply any implementation and lets tests supply fakes. The implementation stays private.
• Getters may return capabilities as functions, for example GetLookupEnv() IOR.Kleisli[string, string] or GetRequestOptions() EF.Thunk[[]Option]. A capability that is a function is trivial to fake and is only evaluated when the effect runs.
• Keep it small. A XxxDeps interface lists what this package uses, typically one to three getters.

A plain struct of fields (type Deps struct{ DB DB; Config Config }) also works for a small program. Capability interfaces scale better, because every package keeps its own narrow view and the composite is assembled by embedding.

Composite Dependencies by Embedding

Higher layers combine the capabilities of the packages they use. The interface embeds interfaces, and the implementation embeds the implementations:

package app

type AppDeps interface {
    users.UserDeps
    mail.MailDeps
}

type appDeps struct {
    users.UserDeps
    mail.MailDeps
}

func MakeAppDeps(u users.UserDeps, m mail.MailDeps) AppDeps { return &appDeps{u, m} }

Because Go generics are invariant, an Effect[UserDeps, A] is not an Effect[AppDeps, A], even though AppDeps embeds UserDeps. Local performs that conversion (next sections).

Lifting Leaves

The leaves are where Go code meets the effect. Lift, never hand-write the nested closures:

Interface method expressions make the leaves point-free. The receiver becomes the dependency, and Local with the getter fetches it from the capability interface:

func FindUser() EF.Kleisli[UserDeps, int, User] {
    return F.Flow2(
        EF.Eitherize1(UserRepo.FindUser),     // Kleisli[UserRepo, int, User]
        EF.Local[User](UserDeps.GetUserRepo), // run it on UserDeps
    )
}

Asks is for pure projections only. Effect[C, A] is func(C) ReaderIOResult[A], so EF.Asks(func(c C) ReaderIOResult[A] {...}) silently yields the nested Effect[C, ReaderIOResult[A]]. For a getter that returns an effectful capability, use Asks followed by ChainThunkK:

func LookupEnv(key string) EF.Effect[EnvDeps, string] {
    return F.Pipe1(
        EF.Asks(EnvDeps.GetLookupEnv), // Effect[EnvDeps, IOR.Kleisli[string, string]]
        EF.ChainThunkK[EnvDeps](F.Flow2(
            RD.Read[IOR.IOResult[string]](key), // apply the capability to key
            RIO.FromIOResult[string],
        )),
    )
}

Narrowing with Local

EF.Local[A](f) takes f: C1 → C2 (from what you have to what the effect needs) and turns an Effect[C2, A] into an Effect[C1, A]. With the AsXxxDeps helpers this is how a narrow effect runs inside a wide dependency:

func NotifyUser() EF.Kleisli[AppDeps, int, MessageID] {
    findUser := F.Flow2(users.FindUser(), EF.Local[User](users.AsUserDeps[AppDeps]))
    sendMail := F.Flow2(mail.SendMail(), EF.Local[MessageID](mail.AsMailDeps[AppDeps]))

    return F.Flow3(
        findUser,
        EF.Map[AppDeps](F.Flow2(getEmail, welcome)),
        EF.Chain(sendMail),
    )
}

• Local needs only the value type [A]. C1 and C2 are inferred from f, and AsXxxDeps[Wide] fixes the generic helper to the wide type.
• Asks + Map versus Local: build a new effect from a getter and a pure function with EF.Asks(getter) plus EF.Map[C](f). Use Local when you already have an Effect[C2, A] (a Kleisli defined elsewhere) and want to reuse it unchanged under another C.
• EF.ContraMap is an alias of Local.
• Compose with the effect combinators (Asks, Map, Ap, Chain, ChainThunkK, FromThunk, Local). Do not rebuild Effect's nested reader shape by hand with reader / context/readerioresult. That also type-checks, but it depends on the internal representation and is hard to read.

When deriving the inner dependency needs more than a pure function, use the Local*K variants (f goes from the outer to the inner dependency):