utilfx

README

utilfx

Small helpers for recurring Uber Fx dependency wiring.

Install

go get github.com/uchaloop/utilfx@latest

Bind

Bind exposes an existing concrete service under an interface while preserving the concrete dependency in the graph.

Without utilfx:

func makeHandler(service *Service) Handler {
	return service
}

fx.Provide(
	makeService,
	makeHandler,
)

With utilfx:

fx.Provide(
	makeService,
	utilfx.Bind[Handler, *Service],
)

An incompatible binding is returned as an Fx constructor error.

Grouped

Grouped registers one or more constructors in the same value group. Nil constructors are ignored.

Without utilfx:

fx.Provide(
	fx.Annotate(makeHealthHandler, fx.ResultTags(`group:"http_handlers"`)),
	fx.Annotate(makeMetricsHandler, fx.ResultTags(`group:"http_handlers"`)),
)

With utilfx:

utilfx.Grouped("http_handlers", makeHealthHandler, makeMetricsHandler)

GroupedAs

GroupedAs provides multiple implementations of one interface in a value group.

Without utilfx:

fx.Provide(
	fx.Annotate(
		makeHealthHandler,
		fx.As(new(Handler)),
		fx.ResultTags(`group:"http_handlers"`),
	),
	fx.Annotate(
		makeMetricsHandler,
		fx.As(new(Handler)),
		fx.ResultTags(`group:"http_handlers"`),
	),
)

With utilfx:

utilfx.GroupedAs[Handler](
	"http_handlers",
	makeHealthHandler,
	makeMetricsHandler,
)

GroupedFor

GroupName builds a group from a group name and an optional Fx name. GroupedFor uses that group to register constructors.

Without utilfx:

group := "database_options"
if len(name) > 0 {
	group += ":" + name
}

option := fx.Provide(
	fx.Annotate(makeOption, fx.ResultTags(`group:"`+group+`"`)),
)

With utilfx:

group := utilfx.GroupName("database_options", name)
option := utilfx.GroupedFor(name, "database_options", makeOption)

Tags

NameTag, OptionalNameTag, and GroupTag keep manual Fx annotations readable.

Without utilfx:

fx.Annotate(
	makeClient,
	fx.ParamTags(`name:"analytics" optional:"true"`),
	fx.ResultTags(`name:"analytics"`),
)

With utilfx:

fx.Annotate(
	makeClient,
	fx.ParamTags(utilfx.OptionalNameTag("analytics")),
	fx.ResultTags(utilfx.NameTag("analytics")),
)

For a value group, without utilfx:

fx.Annotate(
	makeHandler,
	fx.ResultTags(`group:"http_handlers"`),
)

With GroupTag:

fx.Annotate(
	makeHandler,
	fx.ResultTags(utilfx.GroupTag("http_handlers")),
)

ModuleFor

ModuleFor selects a default module for an empty name and otherwise builds a named variant.

Without utilfx:

func moduleFor(name string) fx.Option {
	if len(name) == 0 {
		return Module
	}

	return makeNamedModule(name)
}

With utilfx:

func moduleFor(name string) fx.Option {
	return utilfx.ModuleFor(name, Module, makeNamedModule)
}

Acknowledgements

Thanks to the creators and maintainers of Uber Fx for building the dependency injection framework that makes this package useful.

Documentation

Overview

Package utilfx contains focused helpers for Fx dependency wiring.

Index

• func Bind[Contract any, Impl any](impl Impl) (Contract, error)
• func GroupName(group, name string) string
• func GroupTag(group string) string
• func Grouped(group string, ctors ...any) fx.Option
• func GroupedAs[T any](group string, ctors ...any) fx.Option
• func GroupedFor(name, group string, ctors ...any) fx.Option
• func ModuleFor(name string, def fx.Option, mk func(string) fx.Option) fx.Option
• func NameTag(name string) string
• func OptionalNameTag(name string) string

Functions

func Bind

func Bind[Contract any, Impl any](impl Impl) (Contract, error)

Bind exposes implementation as contract. It can be passed directly to fx.Provide and replaces adapters of the form:

func(service *Service) Handler { return service }

An incompatible implementation is reported as an Fx constructor error.

func GroupName

func GroupName(group, name string) string

GroupName returns group when name is empty. Otherwise it returns a group name in the form "group:name".

func GroupTag

func GroupTag(group string) string

GroupTag returns an Fx tag for a value group.

func Grouped

func Grouped(group string, ctors ...any) fx.Option

Grouped provides constructors whose results belong to the same Fx value group. Nil constructors are ignored.

func GroupedAs

func GroupedAs[T any](group string, ctors ...any) fx.Option

GroupedAs provides constructors as T in the same Fx value group. Each constructor result must implement T. Nil constructors are ignored.

func GroupedFor

func GroupedFor(name, group string, ctors ...any) fx.Option

GroupedFor provides constructors in a group composed from group and name. Nil constructors are ignored.

func ModuleFor

func ModuleFor(name string, def fx.Option, mk func(string) fx.Option) fx.Option

ModuleFor returns the default module when name is empty. Otherwise it builds the named module.

func NameTag

func NameTag(name string) string

NameTag returns an Fx tag for a named dependency or result.

func OptionalNameTag

func OptionalNameTag(name string) string

OptionalNameTag returns an Fx tag for an optional named dependency.