utilfx

README

utilfx

Focused helpers for the Uber Fx wiring patterns that come up in every application built on it.

• An interface without an adapter - Bind hands the container a concrete value under a contract, and says which types did not match when they do not.
• Value groups without repetition - several constructors into one group, as themselves or as an interface, nil entries ignored.
• Tags that are not hand-quoted - where a typo turns into a dependency nobody satisfies.

go get github.com/uchaloop/utilfx

Quick start

fx.Provide(
	makeService,
	utilfx.Bind[Handler, *Service],          // *Service is also still available
)

utilfx.GroupedAs[Handler](                   // both into one group, as Handler
	"http_handlers",
	makeHealthHandler,
	makeMetricsHandler,
)

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

A library exposing one entry point for its default and named instances:

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

Documentation

What each helper does and the reasons behind it are in the package documentation: pkg.go.dev/github.com/uchaloop/utilfx.

Acknowledgements

I am grateful to the authors of Uber Fx. Their work made this library possible.

License

MIT

Documentation

Overview

Package utilfx contains focused helpers for Uber Fx dependency wiring: the few patterns that come up in every application built on it, each of which is otherwise written as an adapter function or a hand-quoted struct tag.

Exposing a service through an interface

Bind hands the container a concrete value under an interface, replacing the adapter every such wiring otherwise needs:

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

The concrete service stays in the graph, so anything that wants *Service still gets it. An implementation that does not satisfy the contract is reported as an Fx constructor error naming both types, rather than failing to compile in an adapter nobody wrote.

Value groups

Grouped provides several constructors into one Fx value group:

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

GroupedAs does the same for constructors whose results are to be consumed through an interface; each result must implement T. GroupedFor composes the group name from a group and an instance name, for an application that wires the same group per named instance:

utilfx.GroupedFor("database_options", "analytics", makeOption)

All three take the group first, and all three ignore a nil constructor, so a list assembled conditionally does not have to be compacted first.

Tags

An Fx tag is a quoted struct tag, and quoting one by hand is where a typo turns into a dependency nobody satisfies. NameTag, OptionalNameTag and GroupTag build them:

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

GroupName builds the group a named instance feeds - the group itself when the name is empty, and "group:name" otherwise. It is the same rule GroupedFor applies, exposed for a module that needs the name without providing anything.

Default and named modules

ModuleFor picks between them by the instance name, so a library exposes one entry point for both:

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

An empty name selects the default module - the single instance an application usually has - and any other name builds the named one.

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(group, name 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 the group a named instance feeds: group itself when name is empty - the single default instance - and "group:name" otherwise. It is the rule GroupedFor applies, exposed for a module that needs the name without providing anything into it.

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(group, name string, ctors ...any) fx.Option

GroupedFor provides constructors in the group a named instance feeds, composed from group and name the way GroupName composes it. Nil constructors are ignored.

The group comes first, as it does in Grouped and GroupedAs and in GroupName: both arguments are strings, so an order that differed between them would swap silently and feed a group nobody consumes.

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.