Project: Grafana (Observability and Analysis / Observability)
File: guide.md

Wire has two core concepts: providers and injectors. The primary mechanism in Wire is the provider: a function that can produce a value. These functions are ordinary Go code. ```go package foobarbaz type Foo struct { X int } // ProvideFoo returns a Foo. func ProvideFoo() Foo { return Foo{X: 42} } ``` Provider functions must be exported in order to be used from other packages, just like ordinary functions. Providers can specify dependencies with parameters: ```go package foobarbaz // ... type Bar struct { X int } // ProvideBar returns a Bar: a negative Foo. func ProvideBar(foo Foo) Bar { return Bar{X: -foo.X} } ``` Providers can also return errors: ```go package foobarbaz import ( "context" "errors" ) // ... type Baz struct { X int } // ProvideBaz returns a value if Bar is not zero. func ProvideBaz(ctx context.Context, bar Bar) (Baz, error) { if bar.X == 0 { return Baz{}, errors.New("cannot provide baz when bar is zero") } return Baz{X: bar.X}, nil } ``` Providers can be grouped into provider sets. This is useful if several providers will frequently be used together. To add these providers to a new set called `SuperSet`, use the `wire.NewSet` function: ```go package foobarbaz import ( // ... "github.com/google/wire" ) // ... var SuperSet = wire.NewSet(ProvideFoo, ProvideBar, ProvideBaz) ``` You can also add other provider sets into a provider set. ```go package foobarbaz import ( // ... "example.com/some/other/pkg" ) // ... var MegaSet = wire.NewSet(SuperSet, pkg.OtherSet) ``` An application wires up these providers with an injector: a function that calls providers in dependency order. With Wire, you write the injector's signature, then Wire generates the function's body. An injector is declared by writing a function declaration whose body is a call to `wire.Build`. The return values don't matter as long as they are of the correct type. The values themselves will be ignored in the generated code. Let's say that the above providers were defined in a package called `example.com/foobarbaz`. The following would declare an injector to obtain a `Baz`: ```go // +build wireinject // The build tag makes sure the stub is not built in the final build. package main import ( "context" "github.com/google/wire" "example.com/foobarbaz" ) func initializeBaz(ctx context.Context) (foobarbaz.Baz, error) { wire.Build(foobarbaz.MegaSet) return foobarbaz.Baz{}, nil } ``` Like providers, injectors can be parameterized on inputs (which then get sent to providers) and can return errors. Arguments to `wire.Build` are the same as `wire.NewSet`: they form a provider set. This is the provider set that gets used during code generation for that injector. Any non-injector declarations found in a file with injectors will be copied into the generated file. You can generate the injector by invoking Wire in the package directory: ```shell wire ``` Wire will produce an implementation of the injector in a file called `wire_gen.go` that looks something like this: ```go // Code generated by Wire. DO NOT EDIT. //go:generate go run -mod=mod github.com/google/wire/cmd/wire //+build !wireinject package main import ( "example.com/foobarbaz" ) func initializeBaz(ctx context.Context) (foobarbaz.Baz, error) { foo := foobarbaz.ProvideFoo() bar := foobarbaz.ProvideBar(foo) baz, err := foobarbaz.ProvideBaz(ctx, bar) if err != nil { return

err } return baz, nil } ``` As you can see, the output is very close to what a developer would write themselves. Further, there is little dependency on Wire at runtime: all of the written code is just normal Go code, and can be used without Wire. Once `wire_gen.go` is created, you can regenerate it by running [`go generate`]. The following features all build on top of the concepts of providers and injectors. Frequently, dependency injection is used to bind a concrete implementation for an interface. Wire matches inputs to outputs via , so the inclination might be to create a provider that returns an interface type. However, this would not be idiomatic, since the Go best practice is to . Instead, you can declare an interface binding in a provider set: ```go type Fooer interface { Foo() string } type MyFooer string func (b *MyFooer) Foo() string { return string(*b) } func provideMyFooer() *MyFooer { b := new(MyFooer) *b = "Hello, World!" return b } type Bar string func provideBar(f Fooer) string { // f will be a *MyFooer. return f.Foo() } var Set = wire.NewSet( provideMyFooer, wire.Bind(new(Fooer), new(*MyFooer)), provideBar) ``` The first argument to `wire.Bind` is a pointer to a value of the desired interface type and the second argument is a pointer to a value of the type that implements the interface. Any set that includes an interface binding must also have a provider in the same set that provides the concrete type. Structs can be constructed using provided types. Use the `wire.Struct` function to construct a struct type and tell the injector which field(s) should be injected. The injector will fill in each field using the provider for the field's type. For the resulting struct type `S`, `wire.Struct` provides both `S` and `*S`. For example, given the following providers: ```go type Foo int type Bar int func ProvideFoo() Foo {/ ... /} func ProvideBar() Bar {/ ... /} type FooBar struct { MyFoo Foo MyBar Bar } var Set = wire.NewSet( ProvideFoo, ProvideBar, wire.Struct(new(FooBar), "MyFoo", "MyBar")) ``` A generated injector for `FooBar` would look like this: ```go func injectFooBar() FooBar { foo := ProvideFoo() bar := ProvideBar() fooBar := FooBar{ MyFoo: foo, MyBar: bar, } return fooBar } ``` The first argument to `wire.Struct` is a pointer to the desired struct type and the subsequent arguments are the names of fields to be injected. A special string `"*"` can be used as a shortcut to tell the injector to inject all fields. So `wire.Struct(new(FooBar), "*")` produces the same result as above. For the above example, you can specify only injecting `"MyFoo"` by changing the `Set` to: ```go var Set = wire.NewSet( ProvideFoo, wire.Struct(new(FooBar), "MyFoo")) ``` Then the generated injector for `FooBar` would look like this: ```go func injectFooBar() FooBar { foo := ProvideFoo() fooBar := FooBar{ MyFoo: foo, } return fooBar } ``` If the injector returned a `*FooBar` instead of a `FooBar`, the generated injector would look like this: ```go func injectFooBar() *FooBar { foo := ProvideFoo() fooBar := &FooBar{ MyFoo: foo, } return fooBar } ``` It is sometimes useful to prevent certain fields from being filled in by the injector, especially when passing `*` to

You can tag a field with `` `wire:"-"` `` to have Wire ignore such fields. For example: ```go type Foo struct { mu sync.Mutex `wire:"-"` Bar Bar } ``` When you provide the `Foo` type using `wire.Struct(new(Foo), "*")`, Wire will automatically omit the `mu` field. Additionally, it is an error to explicitly specify a prevented field as in `wire.Struct(new(Foo), "mu")`. Occasionally, it is useful to bind a basic value (usually `nil`) to a type. Instead of having injectors depend on a throwaway provider function, you can add a value expression to a provider set. ```go type Foo struct { X int } func injectFoo() Foo { wire.Build(wire.Value(Foo{X: 42})) return Foo{} } ``` The generated injector would look like this: ```go func injectFoo() Foo { foo := _wireFooValue return foo } var ( _wireFooValue = Foo{X: 42} ) ``` It's important to note that the expression will be copied to the injector's package; references to variables will be evaluated during the injector package's initialization. Wire will emit an error if the expression calls any functions or receives from any channels. For interface values, use `InterfaceValue`: ```go func injectReader() io.Reader { wire.Build(wire.InterfaceValue(new(io.Reader), os.Stdin)) return nil } ``` Sometimes the providers the user wants are some fields of a struct. If you find yourself writing a provider like `getS` in the example below to promote struct fields into provided types: ```go type Foo struct { S string N int F float64 } func getS(foo Foo) string { // Bad! Use wire.FieldsOf instead. return foo.S } func provideFoo() Foo { return Foo{ S: "Hello, World!", N: 1, F: 3.14 } } func injectedMessage() string { wire.Build( provideFoo, getS) return "" } ``` You can instead use `wire.FieldsOf` to use those fields directly without writing `getS`: ```go func injectedMessage() string { wire.Build( provideFoo, wire.FieldsOf(new(Foo), "S")) return "" } ``` The generated injector would look like this: ```go func injectedMessage() string { foo := provideFoo() string2 := foo.S return string2 } ``` You can add as many field names to a `wire.FieldsOf` function as you like. For a given field type `T`, `FieldsOf` provides at least `T`; if the struct argument is a pointer to a struct, then `FieldsOf` also provides `*T`. If a provider creates a value that needs to be cleaned up (e.g. closing a file), then it can return a closure to clean up the resource. The injector will use this to either return an aggregated cleanup function to the caller or to clean up the resource if a provider called later in the injector's implementation returns an error. ```go func provideFile(log Logger, path Path) (*os.File, func(), error) { f, err := os.Open(string(path)) if err != nil { return nil, nil, err } cleanup := func() { if err := f.Close(); err != nil { log.Log(err) } } return f, cleanup, nil } ``` A cleanup function is guaranteed to be called before the cleanup function of any of the provider's inputs and must have the signature `func()`. If you grow weary of writing `return foobarbaz.Foo{}, nil` at the end of your injector function declaration, you can instead write it more concisely with a `panic`: ```go func injectFoo() Foo { panic(wire.Build(/ ... /)) } ```