Providers (DI)

Backend functions depend on runtime services (loggers, clocks, DB handles). Providers declare those dependencies with use and wire them at entry points with with. Request data stays separate from shared infrastructure.

Two primitives

Keyword	Role
`use`	Bind a contract type inside a function: “this code depends on X”
`with { … } { … }`	Wire concrete implementations at an entry point (handler, `main`, test)

Parameters carry data (order IDs, request bodies). Providers carry services the host supplies (logger, clock, repo). Keeping them separate clarifies what flows through your API boundary and what is ambient context.

Declare dependencies with `use`

Contracts are ordinary types: shapes with methods, or imported Go interfaces:

Forst
Generated Go

type Logger = {
	info(msg String)
}

type Clock = {
	now(): Int
}

func logExpiry(id String) {
	use logger: Logger
	logger.info("expire " + id)
}

func expireToken(token Token) {
	use clock: Clock
	if token.expiresAt < clock.now() {
		logExpiry(token.id)
	}
}

// forst build
type Logger interface {
	info(msg string)
}

type Clock interface {
	now() int
}

type Token struct {
	expiresAt int
	id        string
}

func logExpiry(providers Providers_logExpiry, id string) {
	providers.Logger.info("expire " + id)
}

func expireToken(providers Providers_expireToken, token Token) {
	clock := providers.Clock
	if token.expiresAt < clock.now() {
		logExpiry(providers, token.id)
	}
}

The compiler aggregates use sites into Providers(f) for each function and propagates requirements transitively through calls. You can see the obligation chain in diagnostics and LSP hovers: which services a handler needs, and which entry point must supply them.

Wire at the boundary

Entry points satisfy every Provider the call graph needs using a with { … } { … } block. Production wiring and test wiring use the same mechanism:

Forst
Generated Go

func main() {
	with {
		Logger: &ProductionLogger{},
		Clock:  &SystemClock {},
	} {
		expireToken(Token { id: "x", expiresAt: 1 })
	}
}

// forst build
func main() {
	providers := Providers_expireToken{
		Logger: &ProductionLogger{},
		Clock:  &SystemClock{},
	}
	expireToken(providers, Token{id: "x", expiresAt: 1})
}

Wiring keys use the root contract name (Logger, Clock). Values must structurally satisfy the contract: plain structs with matching methods, or Go types that implement an imported interface.

Void contract methods

Contract methods without a return type (such as info(msg String)) must stay void on implementations. A trailing fmt.Println(...) in the method body can infer a non-void Result return from Go’s (int, error) signature; the compiler reports that mismatch. Use println for side-effect logging in void provider methods, or declare an explicit return type if you intend to return the call result. See Return inference and implicit returns.

Shadowing

Nested with blocks merge with outer wiring. When the inner block supplies the same contract key, it shadows the outer value for that scope; other keys still forward from outside:

Forst
Generated Go

with {
	Logger: &ProductionLogger {},
	Clock:  &SystemClock {},
} {
	with { Clock: &FakeClock { fixedMs: 2000 } } {
		// Clock shadows outer; Logger still &ProductionLogger
		expireToken(Token { id: "t1", expiresAt: 500 })
	}
}

// forst build
outer := Providers_expireToken{
	Logger: &ProductionLogger{},
	Clock:  &SystemClock{},
}
inner := Providers_expireToken{
	Logger: outer.Logger,
	Clock:  &FakeClock{fixedMs: 2000},
}
expireToken(inner, Token{id: "t1", expiresAt: 500})

Tests

Tests reuse the same with blocks to swap fakes without a separate DI framework:

Forst
Generated Go

func TestExpireToken_expired(t *testing.T) {
	token := Token { id: "t1", expiresAt: 500 }
	with {
		Logger: &NopLogger {},
		Clock:  &FakeClock { fixedMs: 1000 },
	} {
		expireToken(token)
	}
}

// forst build
func TestExpireToken_expired(t *testing.T) {
	token := Token{id: "t1", expiresAt: 500}
	providers := Providers_expireToken{
		Logger: &NopLogger{},
		Clock:  &FakeClock{fixedMs: 1000},
	}
	expireToken(providers, token)
}

Compared to other approaches

The Providers RFC surveyed these patterns before settling on use and with. See the Providers RFC hub for the full prior art writeup.

Approach	Limitation
Per function parameters	Every helper gains extra arguments. Domain input and infrastructure blur together as the call graph grows.
Go service struct	Wiring lives in `main` as interface fields on one struct. A new dependency deep in the tree does not propagate to the compiler as a wiring obligation.
`context.Context`	`WithValue` is untyped. Keys are easy to miss or collide. Nothing tracks who must supply what at compile time.
DI frameworks (Fx, Wire, dig)	These tools rely on runtime containers or codegen indirection. Wiring and failures can be hard to trace in stack traces.
Effect / ZIO Layers	Requirements live in the environment type and runtime. Layer graphs add ceremony compared to one struct literal at the boundary.
Kotlin context parameters	Implicit context in signatures works on the JVM. Go has no native equivalent, and Forst lowers to explicit struct parameters.
Test harness DSLs	Special test-only keywords split production wiring from test wiring. Readers and agents learn two different surfaces.
Mock frameworks (Jest, testify)	Expectations couple tests to framework APIs. Structural fakes wired with the same boundary pattern as production are harder to reuse across integration tests.
Global singletons	Dependencies hide in package state. Tests need globals, init hooks, or monkey patching.
Plain Go test helpers	A hand written `newTestApp(t)` helper drifts from what handlers actually need. Nothing checks completeness when a leaf adds a new service.
Forst `use` / `with`	Obligations are inferred at compile time. Wiring stays explicit at entry points. The compiler emits plain Go struct literals with no runtime container.

Forst treats context.Context separately from Providers. Declare services with use so requirements stay typed and visible. Use context for cancellation and request scoped values. Use with blocks for service wiring. Sidecar and TypeScript exports stay data only. The host wires Providers in Go before exposing a handler.

What gets emitted

Providers lower to a deduped struct parameter at the Go boundary. Production and test wiring compile to ordinary struct literals: readable Go, no runtime container.

Caveats

Providers are experimental. The RFC surface is still evolving. Pin your compiler version and run task example:providers when upgrading.

Host wiring only

Providers lower in Go. They are not exported to TypeScript or sidecar invoke payloads. Functions with unsatisfied Providers(f) are omitted from generated clients. Wire with blocks in Go main before exposing handlers. See Call Forst from Node § Caveats and Generate client types § Caveats.

Void contract methods

A trailing fmt.Println(...) in a void provider method can infer a non-void Result return from Go’s (int, error) signature. Use println for side effect logging, or declare an explicit return type. See Return inference and implicit returns.

`context.Context` is separate

Providers are typed services declared with use. Cancellation and request scoped values stay in context, not in Provider wiring.

Try it

From the Forst repository:

task example:providers
task example:providers-cross_pkg
forst test examples/in/rfc/providers/

Deep dive: Providers RFC hub

Go interop

Import Go interfaces as Provider contracts.

Editor workflow

LSP hovers show Provider obligations and related diagnostics.

Overview

Getting started

Data validation

Behavior

Interop

Workflow

Providers (DI)

Two primitives

Declare dependencies with `use`

Wire at the boundary

Void contract methods

Shadowing

Tests

Compared to other approaches

What gets emitted

Caveats

Host wiring only

Void contract methods

`context.Context` is separate

Try it

Go interop

Editor workflow

​Two primitives

​Declare dependencies with use

​Wire at the boundary

​Void contract methods

​Shadowing

​Tests

​Compared to other approaches

​What gets emitted

​Caveats

​Host wiring only

​Void contract methods

​context.Context is separate

​Try it

​Related

Go interop

Editor workflow

Two primitives

Declare dependencies with `use`

Wire at the boundary

Void contract methods

Shadowing

Tests

Compared to other approaches

What gets emitted

Caveats

Host wiring only

Void contract methods

`context.Context` is separate

Try it

Related