nject

func Cluster ¶

func Cluster(name string, providers ...interface{}) *Collection

Cluster is a variation on Sequence() with the additional behavior that all of the providers in the in the cluster will be included or excluded as a group. This doesn't apply to providers that cannot be included at all. It also downgrades providers that are in the cluster that would normally be considered desired because they don't return anything and aren't wrappers: they're no longer automatically considered desired because doing so would imply the entire Cluster is is desired.

A "Cluster" with only one member is not really a cluster and will not be treated as a cluster.

package main

import (
	"fmt"

	"github.com/muir/nject"
)

func main() {
	chain := nject.Sequence("overall",
		func() string {
			return "example string"
		},
		nject.Cluster("first-cluster",
			func(s string) int32 {
				return int32(len(s))
			},
			func() int64 {
				fmt.Println("included even though no consumer")
				return 0
			},
			func(i int32) {
				fmt.Println("auto-desired in 1st cluster")
			},
			func(i int32) int64 {
				return int64(i)
			},
		),
		nject.Cluster("second-cluster",
			func(s string) uint32 {
				return uint32(len(s))
			},
			func(i uint32) {
				fmt.Println("auto-desired in 2nd cluster")
			},
			func(i int64, u uint32) uint64 {
				return uint64(uint32(i) + u)
			},
		),
	)
	_ = nject.Run("does not consume uint64",
		chain,
		func(s string) {
			fmt.Println("no need for data from clusters")
		},
	)
	_ = nject.Run("consumes uint64",
		chain,
		func(u uint64) {
			fmt.Println("got value that needed both chains -", u)
		},
	)
}

Output:

no need for data from clusters
included even though no consumer
auto-desired in 1st cluster
auto-desired in 2nd cluster
got value that needed both chains - 28

func Sequence ¶

func Sequence(name string, providers ...interface{}) *Collection

Sequence creates a Collection of providers. Each collection must have a name. The providers can be: functions, variables, literal values, Collections, *Collections, or Providers.

Functions must match one of the expected patterns.

Injectors specified here will be separated into two sets: ones that are run once per bound chain (STATIC); and ones that are run for each invocation (RUN). Memoized functions are in the STATIC chain but they only get run once per input combination. Literal values are inserted before the STATIC chain starts.

Each set will run in the order they were given here. Providers whose output is not consumed are skipped unless they are marked with Required. Providers that produce no output are always run.

Previsously created *Collection objects are considered providers along with *Provider, named functions, anonymous functions, and literal values.

package main

import (
	"fmt"

	"github.com/muir/nject"
)

func main() {
	seq := nject.Sequence("example",
		func() string {
			return "foo"
		},
		func(s string) {
			fmt.Println(s)
		},
	)
	nject.Run("run", seq)
}

Output:

foo

func PostActionByName ¶

func PostActionByName(name string, function interface{}, opts ...PostActionFuncArg) FillerFuncArg

PostActionByName arranges to call a function passing in the field that has a matching name. PostActionByName happens before PostActionByType and after PostActionByTag calls.

EXPERIMENTAL: this is currently considered experimental and could be removed in a future release. If you are using this, please open a pull request to remove this comment.

package main

import (
	"fmt"

	"github.com/muir/nject"
)

func main() {
	type S struct {
		I int32
		J int32
	}
	fmt.Println(nject.Run("example",
		func() int32 {
			return 10
		},
		func() *[]int {
			var x []int
			return &x
		},
		nject.MustMakeStructBuilder(S{},
			nject.PostActionByName("I", func(i int, a *[]int) {
				*a = append(*a, i+1)
			}),
			nject.PostActionByName("J", func(i int64, a *[]int) {
				*a = append(*a, int(i)-1)
			}),
		),
		func(_ S, a *[]int) {
			fmt.Println(*a)
		},
	))
}

Output:

[11 9]
<nil>

func PostActionByTag ¶

func PostActionByTag(tagValue string, function interface{}, opts ...PostActionFuncArg) FillerFuncArg

PostActionByTag establishes a tag value that indicates that after the struct is built or filled, a function should be called passing a pointer to the tagged field to the function. The function must take as an input parameter a pointer to the type of the field or it must take as an input paraemter an interface type that the field implements. interface{} is allowed. This function will be added to the injection chain after the function that builds or fills the struct. If there is also a WithMethodCall, this function will run before that.

EXPERIMENTAL: this is currently considered experimental and could be removed in a future release. If you are using this, please open a pull request to remove this comment.

package main

import (
	"fmt"

	"github.com/muir/nject"
)

func main() {
	type S struct {
		I int `nject:"square-me"`
	}
	nject.Run("example",
		func() int {
			return 4
		},
		nject.MustMakeStructBuilder(&S{}, nject.PostActionByTag("square-me", func(i *int) {
			*i *= *i
		}, nject.WithFill(true))),
		func(s *S) {
			fmt.Println(s.I)
		},
	)
}

Output:

16

package main

import (
	"fmt"

	"github.com/muir/nject"
)

func main() {
	type S struct {
		I int32 `nject:"rollup"`
		J int32 `nject:"rolldown"`
	}
	fmt.Println(nject.Run("example",
		func() int32 {
			return 10
		},
		func() *[]int {
			var x []int
			return &x
		},
		nject.MustMakeStructBuilder(S{},
			nject.PostActionByTag("rollup", func(i int, a *[]int) {
				*a = append(*a, i+1)
			}),
			nject.PostActionByTag("rolldown", func(i int64, a *[]int) {
				*a = append(*a, int(i)-1)
			}),
		),
		func(_ S, a *[]int) {
			fmt.Println(*a)
		},
	))
}

Output:

[11 9]
<nil>

package main

import (
	"fmt"

	"github.com/muir/nject"
)

func main() {
	type S struct {
		I int `nject:"square-me"`
	}
	nject.Run("example",
		func() int {
			return 4
		},
		nject.MustMakeStructBuilder(S{}, nject.PostActionByTag("square-me", func(i int) {
			fmt.Println(i * i)
		})),
		func(s S) {
			fmt.Println(s.I)
		},
	)
}

Output:

16
4

package main

import (
	"fmt"

	"github.com/muir/nject"
)

type Causer interface {
	Unwrap() error
	Error() string
}

type MyError struct {
	err error
}

func (err MyError) Error() string {
	return "MY: " + err.err.Error()
}

func (err MyError) Unwrap() error {
	return err.err
}

var _ Causer = MyError{}

func main() {
	type S struct {
		Error Causer `nject:"print-error,print-cause"`
	}
	fmt.Println(nject.Run("example",
		func() error {
			return fmt.Errorf("an injected error")
		},
		func(err error) Causer {
			return MyError{err: err}
		},
		nject.MustMakeStructBuilder(S{},
			nject.PostActionByTag("print-error", func(err error) {
				fmt.Println(err)
			}),
			nject.PostActionByTag("print-cause", func(err Causer) {
				fmt.Println("Cause:", err.Unwrap())
			}),
		),
		func(s S) {
			fmt.Println("Done")
		},
	))
}

Output:

MY: an injected error
Cause: an injected error
Done
<nil>

func PostActionByType ¶

func PostActionByType(function interface{}, opts ...PostActionFuncArg) FillerFuncArg

PostActionByType arranges to call a function for every field in struct that is being filled where the type of the field in the struct exactly matches the first input parameter of the provided function. PostActionByType calls are made after PostActionByTag calls, but before WithMethodCall invocations.

If there is no match to the type of the function, then the function is not invoked.

EXPERIMENTAL: this is currently considered experimental and could be removed in a future release. If you are using this, please open a pull request to remove this comment.

package main

import (
	"fmt"

	"github.com/muir/nject"
)

func main() {
	type S struct {
		I int32
		J int64
	}
	fmt.Println(nject.Run("example",
		func() int32 {
			return 10
		},
		func() int64 {
			return 20
		},
		func() *[]int {
			var x []int
			return &x
		},
		nject.MustMakeStructBuilder(&S{},
			nject.PostActionByType(func(i int32, a *[]int) {
				*a = append(*a, int(i))
			}, nject.WithFill(true)),
			nject.PostActionByType(func(i *int32, a *[]int) {
				*i += 5
			}, nject.WithFill(true)),
		),
		func(s *S, a *[]int) {
			fmt.Println(*a, s.I, s.J)
		},
	))
}

Output:

[15] 15 20
<nil>

func WithMethodCall ¶

func WithMethodCall(methodName string) FillerFuncArg

WithMethodCall looks up a method on the struct being filled or built and adds a method invocation to the dependency chain. The method can be any kind of function provider (the last function, a wrapper, etc). If there is no method of that name, then MakeStructBuilder will return an error.

EXPERIMENTAL: this is currently considered experimental and could be removed in a future release. If you are using this, please open a pull request to remove this comment.

package main

import (
	"fmt"

	"github.com/muir/nject"
)

type S struct {
	I int
}

func (s *S) Square() {
	s.I *= s.I
}

func (s S) Print() {
	fmt.Println(s.I)
}

func main() {
	nject.Run("example",
		func() int {
			return 4
		},
		nject.MustMakeStructBuilder(&S{},
			nject.WithMethodCall("Square"),
			nject.WithMethodCall("Print")),
		func(s *S) {
			fmt.Println("end")
		},
	)
}

Output:

16
end

func WithTag ¶

func WithTag(tag string) FillerFuncArg

WithTag sets the struct tag to use for per-struct-field directives in MakeStructBuilder. The default tag is "nject"

EXPERIMENTAL: this is currently considered experimental and could be removed in a future release. If you are using this, please open a pull request to remove this comment.

func MatchToOpenInterface ¶

func MatchToOpenInterface(b bool) PostActionFuncArg

MatchToOpenInterface requires that the post action function have exactly one open interface type (interface{}) in its arguments list. A pointer to the field will be passed to the interface parameter.

EXPERIMENTAL: this is currently considered experimental and could be removed in a future release. If you are using this, please open a pull request to remove this comment.

func WithFill ¶

func WithFill(b bool) PostActionFuncArg

WithFill overrides the default behaviors of PostActionByType, PostActionByName, and PostActionByTag with respect to the field being automatically filled. By default, if there is a post-action that that receives a pointer to the field, then the field will not be filled from the injection chain.

EXPERIMENTAL: this is currently considered experimental and could be removed in a future release. If you are using this, please open a pull request to remove this comment.

func Cacheable ¶

func Cacheable(fn interface{}) Provider

Cacheable creates an inject item and annotates it as allowed to be in the STATIC chain. Without this annotation, MustCache, or Memoize, a provider will be in the RUN chain.

When used on an existing Provider, it creates an annotated copy of that provider.

func ConsumptionOptional ¶

func ConsumptionOptional(fn interface{}) Provider

ConsumptionOptional creates a new provider and annotates it as allowed to have some of its return values ignored. Without this annotation, a wrap function will not be included if some of its return values are not consumed.

In the downward direction, optional consumption is the default.

When used on an existing Provider, it creates an annotated copy of that provider.

func Curry ¶ added in v1.2.0

func Curry(originalFunction interface{}, pointerToCurriedFunction interface{}) (Provider, error)

Curry generates a Required Provider that prefills arguments to a function to create a new function that needs fewer args.

Only arguments with a unique (to the function) type can be curried.

The original function and the curried function must have the same outputs.

The first curried input may not be a function.

EXPERIMENTAL: This is currently considered experimental and could be removed or moved to another package. If you're using this, open a pull request to remove this comment.

package main

import (
	"fmt"

	"github.com/muir/nject"
)

func main() {
	lotsOfUnchangingArgs := func(s string, i int, u uint) string {
		return fmt.Sprintf("%s-%d-%d", s, i, u)
	}
	var shorthand func(i int) string
	fmt.Println(nject.Run("example",
		func() string { return "foo" },
		func() uint { return 33 },
		nject.MustCurry(lotsOfUnchangingArgs, &shorthand),
		func() {
			fmt.Println("actual injection goal")
		},
	))
	fmt.Println(shorthand(10))
}

Output:

actual injection goal
<nil>
foo-10-33

func Desired ¶

func Desired(fn interface{}) Provider

Desired creates a new provider and annotates it as desired: it will be included in the provider chain unless doing so creates an un-met dependency.

Injectors and wrappers that have no outputs are automatically considered desired.

When used on an existing Provider, it creates an annotated copy of that provider.

func InsertAfterNamed ¶ added in v1.6.0

func InsertAfterNamed(target string, fn interface{}) Provider

InsertAfterNamed will edit the set of injectors, inserting the provided injector after the target injector, which is identified by the name it was given with Provide(). That injector can be a Collection. This re-arrangement happens very early in the injection chain processing, before Reorder or injector selection. If target does not exist, the injection chain is deemed invalid.

func InsertBeforeNamed ¶ added in v1.6.0

func InsertBeforeNamed(target string, fn interface{}) Provider

InsertBeforeNamed will edit the set of injectors, inserting the provided injector before the target injector, which is identified by the name it was given with Provide(). That injector can be a Collection. This re-arrangement happens very early in the injection chain processing, before Reorder or injector selection. If target does not exist, the injection chain is deemed invalid.

func Loose ¶

func Loose(fn interface{}) Provider

Loose annotates a wrap function to indicate that when trying to match types against the outputs and return values from this provider, an in-exact match is acceptable. This matters when inputs and returned values are specified as interfaces. With the Loose annotation, an interface can be matched to the outputs and/or return values of this provider if the output/return value implements the interface.

By default, an exact match of types is required for all providers.

func MakeStructBuilder ¶

func MakeStructBuilder(model interface{}, optArgs ...FillerFuncArg) (Provider, error)

MakeStructBuilder generates a Provider that wants to receive as arguments all of the fields of the struct and returns the struct as what it provides.

The input model must be a struct: if not MakeStructFiller will panic. Model may be a pointer to a struct or a struct. Unexported fields are always ignored. Passing something other than a struct or pointer to a struct to MakeStructBuilder results is an error. Unknown tag values is an error.

Struct tags can be used to control the behavior: the argument controls the name of the struct tag used.

The following struct tags are pre-defined. User-created struct tags (created with PostActionByTag) may not uses these names:

"whole" & "blob": indicate that an embedded struct should be filled as a blob rather than field-by-field.

"field" & "fields": indicates that an embedded struct should be filled field-by-field. This is the default and the tag exists for clarity.

"-" & "skip": the field should not be filled and it should should ignore a PostActionByType and PostActionByName matches. PostActionByTag would still apply.

"nofill": the field should not be filled, but all PostActions still apply. "nofill" overrides other behviors including defaults set with post-actions.

"fill": normally if there is a PostActionByTag match, then the field will not be filled from the provider chain. "fill" overrides that behavior. "fill" overrides other behaviors including defaults set with post-actions.

If you just want to provide a value variable, use FillVars() instead.

func Memoize ¶

func Memoize(fn interface{}) Provider

Memoize creates a new InjectItem that is tagged as Cacheable further annotated so that it only executes once per input parameter values combination. This cache is global among all Sequences. Memoize can only be used on functions whose inputs are valid map keys (interfaces, arrays (not slices), structs, pointers, and primitive types). It is further restrict that it cannot handle private (not exported) fields inside structs.

Memoized providers will remember every combination of imputs they have ever seen. This can exhaust all memory.

By default, Memozied providers are Cacheable, but that doesn't force the provider into the STATIC set where it runs infrequently. Combine Memoize with MustCache to make sure that Memoize is actually in the STATIC set where it probably won't exhaust all memory.

Use NotCacheable to exclude Memoized providers from the STATIC set. Remember: they'll remember every combination of inputs.

When used on an existing Provider, it creates an annotated copy of that provider.

As long as consistent injection chains are used Memoize + MustCache can guarantee singletons.

package main

import (
	"fmt"

	"github.com/muir/nject"
)

func main() {
	type aStruct struct {
		ValueInStruct int
	}
	structProvider := nject.Memoize(func(ip *int, i int) *aStruct {
		return &aStruct{
			ValueInStruct: i * *ip,
		}
	})
	exampleInt := 7
	ip := &exampleInt
	_ = nject.Run("chain1",
		2,
		ip,
		structProvider,
		func(s *aStruct) {
			fmt.Println("first input", s.ValueInStruct, "value set to 22")
			s.ValueInStruct = 22
		},
	)
	_ = nject.Run("chain2",
		3,
		ip,
		structProvider,
		func(s *aStruct) {
			fmt.Println("different inputs", s.ValueInStruct)
		},
	)
	exampleInt = 33
	_ = nject.Run("chain3",
		2,
		ip,
		structProvider,
		func(s *aStruct) {
			fmt.Println("same object as first", s.ValueInStruct)
		},
	)

}

Output:

first input 14 value set to 22
different inputs 21
same object as first 22

func MustCache ¶

func MustCache(fn interface{}) Provider

MustCache creates an Inject item and annotates it as required to be in the STATIC set. If it cannot be placed in the STATIC set then any collection that includes it is invalid.

func MustConsume ¶

func MustConsume(fn interface{}) Provider

MustConsume creates a new provider and annotates it as needing to have all of its output values consumed. If any of its output values cannot be consumed then the provider will be excluded from the chain even if that renders the chain invalid.

A that is received by a provider and then provided by that same provider is not considered to have been consumed by that provider.

For example:

// All outputs of A must be consumed
Provide("A", MustConsume(func() string) { return "" } ),

// Since B takes a string and provides a string it
// does not count as suming the string that A provided.
Provide("B", func(string) string { return "" }),

// Since C takes a string but does not provide one, it
// counts as consuming the string that A provided.
Provide("C", func(string) int { return 0 }),

MustConsume works only in the downward direction of the provider chain. In the upward direction (return values) all values must be consumed.

When used on an existing Provider, it creates an annotated copy of that provider.

func MustCurry ¶ added in v1.2.0

func MustCurry(originalFunction interface{}, pointerToCurriedFunction interface{}) Provider

MustCurry calls Curry and panics if Curry returns error

func MustMakeStructBuilder ¶

func MustMakeStructBuilder(model interface{}, opts ...FillerFuncArg) Provider

MustMakeStructBuilder wraps a panic around failed MakeStructBuilder calls

EXPERIMENTAL: this is currently considered experimental and could be removed in a future release. If you are using this, please open a pull request to remove this comment.

func MustSaveTo ¶ added in v1.1.0

func MustSaveTo(varPointers ...interface{}) Provider

MustSaveTo calls FillVars and panics if FillVars returns an error

EXPERIMENTAL: This is currently considered experimental and could be removed or moved to another package. If you're using this, open a pull request to remove this comment.

func NonFinal ¶

func NonFinal(fn interface{}) Provider

NonFinal annotates a provider to say that it shouldn't be considered the final provider in a list of providers. This is to make it possible to insert a provider into a list of providers late in the chain without actually being the final provider. It's easy to insert a final at the start of the chain -- you simply list it first. It's easy to insert a final provider. Without NonFinal, it's hard or impossible to insert a provider very late in the chain. If NonFinal providers are invoked, they will be called before the final provider.

package main

import (
	"fmt"

	"github.com/muir/nject"
)

func main() {
	seq := nject.Sequence("example",
		func() string {
			return "some string"
		},
		func(i int, s string) {
			fmt.Println("final", i, s)
		},
	)
	fmt.Println(nject.Run("almost incomplete",
		seq,
		nject.NonFinal(func() int {
			return 20
		}),
	))
}

Output:

final 20 some string
<nil>

func NotCacheable ¶

func NotCacheable(fn interface{}) Provider

NotCacheable creates an inject item and annotates it as not allowed to be in the STATIC chain. With this annotation, Cacheable is ignored and MustCache causes an invalid chain.

When used on an existing Provider, it creates an annotated copy of that provider.

package main

import (
	"database/sql"

	"github.com/muir/nject"
)

type (
	driverName     string
	dataSourceName string
)

// openDBErrorReturnRequired is a provider that opens a database.   Surface it seems
// fine but it has a problem: what if nothing below it returns error?
// nolint:deadcode,unused
func openDBErrorReturnRequired(inner func(*sql.DB) error, driver driverName, name dataSourceName) error {
	db, err := sql.Open(string(driver), string(name))
	if err != nil {
		return err
	}
	defer db.Close()
	return inner(db)
}

// openDBCollection is a collection of providers that open a database but do not
// assume that a something farther down the chain will return error.  Since this collection
// may be used nievely in a context where someone is trying to cache things,
// NotCacheable is used to make sure that we do not cache the open.
// We use MustConsume and a private type on the open to make sure that if the open happens,
// the close will happen too.
type mustCloseDB bool // private type
var openDBCollection = nject.Sequence("open-database",
	nject.NotCacheable(nject.MustConsume(
		func(driver driverName, name dataSourceName) (*sql.DB, mustCloseDB, nject.TerminalError) {
			db, err := sql.Open(string(driver), string(name))
			if err != nil {
				return nil, false, err
			}
			return db, false, nil
		})),
	func(inner func(*sql.DB), db *sql.DB, _ mustCloseDB) {
		defer db.Close()
		inner(db)
	},
)

// ExampleNotCacheable is a function to demonstrate the use of NotCacheable and
// MustConsume.
func main() {
	// If someone tries to make things faster by marking everything as Cacheable,
	// the NotCacheable in openDBCollection() will prevent an inappropriate move to the
	// static chain of the database open.
	_ = nject.Cacheable(nject.Sequence("big collection",
		// Many providers
		driverName("postgres"),
		dataSourceName("postgresql://username:password@host:port/databasename"),
		openDBCollection,
		// Many other providers here
	))
}

Output:

func OverridesError ¶ added in v0.5.0

func OverridesError(fn interface{}) Provider

OverridesError marks a provider that is okay for that provider to override error returns. Without this decorator, a wrapper that returns error but does not expect to receive an error will cause the injection chain compilation to fail.

A common mistake is to have an wrapper that accidentally returns error. It looks like this:

func AutoCloseThing(inner func(someType), param anotherType) error {
	thing, err := getThing(param)
	if err != nil {
		return err
	}
	defer thing.Close()
	inner(thing)
	return nil
}

The above function has two problems. The big problem is that it will override any returned errors coming up from below in the call chain by returning nil. The fix for this is to have the inner function return error. If you aren't sure there will be something below that will definitely return error, then you can inject something to provide a nil error. Put the following at the end of the sequence:

nject.Shun(nject.NotFinal(func () error { return nil }))

The second issue is that thing.Close() probably returns error. A correct wrapper for this looks like this:

func AutoCloseThing(inner func(someType) error, param anotherType) (err error) {
	var thing someType
	thing, err = getThing(param)
	if err != nil {
		return err
	}
	defer func() {
		e := thing.Close()
		if err == nil && e != nil {
			err = e
		}
	}()
	return inner(thing)
}

func Parallel ¶ added in v1.5.0

func Parallel(fn interface{}) Provider

Parallel annotates a wrap function to indicate that the inner function may be invoked in parallel.

At the current time, support for this is very limited. Returned values cannot be propagated across such a call and the resulting lack of initialization can cause a panic.

func Provide ¶

func Provide(name string, fn interface{}) Provider

Provide wraps an individual provider. It allows the provider to be named. The return value is chainable with with annotations like Cacheable() and Required(). It can be included in a collection. When providers are not named, they get their name from their position in their collection combined with the name of the collection they are in.

When used on an existing Provider, it creates an annotated copy of that provider.

package main

import (
	"fmt"

	"github.com/muir/nject"
)

func main() {
	fmt.Println(nject.Run("failure1",
		func(s string) int {
			return 4
		},
	))
	fmt.Println(nject.Run("failure2",
		nject.Provide("create-int", func(s string) int {
			return 4
		}),
	))
}

Output:

final-func: failure1(0) [func(string) int]: required but has no match for its input parameter string
final-func: create-int [func(string) int]: required but has no match for its input parameter string

package main

import (
	"fmt"

	"github.com/muir/nject"
)

func main() {
	fmt.Println(nject.Run("literals",
		nject.Provide("an int", 7),
		"I am a literal string", // naked literal work too
		nject.Provide("I-am-a-final-func", func(s string, i int) {
			fmt.Println("final:", s, i)
		}),
	))
}

Output:

final: I am a literal string 7
<nil>

package main

import (
	"fmt"
	"strconv"

	"github.com/muir/nject"
)

func main() {
	fmt.Println(nject.Run("regular",
		func() int {
			return 7
		},
		nject.Provide("convert-int-to-string",
			func(i int) string {
				return strconv.Itoa(i)
			},
		),
		func(s string) {
			fmt.Println(s)
		},
	))
}

Output:

7
<nil>

package main

import (
	"fmt"

	"github.com/muir/nject"
)

func main() {
	shouldFail := true
	seq := nject.Sequence("fallible",
		nject.Provide("example-wrapper",
			func(inner func() (string, error)) {
				s, err := inner()
				fmt.Println("string:", s, "error:", err)
			}),
		nject.Provide("example-injector",
			func() bool {
				return shouldFail
			}),
		nject.Provide("example-fallible-injector",
			func(b bool) (string, nject.TerminalError) {
				if b {
					return "", fmt.Errorf("oops, failing")
				}
				return "example", nil
			}),
		nject.Provide("example-final-injector",
			func(s string) string {
				return "final: " + s
			}),
	)
	fmt.Println(nject.Run("failure", seq))
	shouldFail = false
	fmt.Println(nject.Run("success", seq))
}

Output:

string:  error: oops, failing
oops, failing
string: final: example error: <nil>
<nil>

func Reorder ¶ added in v0.6.0

func Reorder(fn interface{}) Provider

Reorder annotates a provider to say that its position in the injection chain is not fixed. Such a provider will be placed after it's inputs are available and before it's outputs are consumed.

If there are multiple pass-through providers (that is to say, ones that both consume and provide the same type) that pass through the same type, then the ordering among these re-orderable providers will be in their original order with respect to each other.

When reordering, only exact type matches are considered. Reorder does not play well with Loose().

Functions marked reorder are currently inelligible for the STATIC set.

Note: reordering will happen too late for UpFlows(), DownFlows(), and GenerateFromInjectionChain() to correctly capture the final shape.

Reorder should be considered experimental in the sense that the rules for placement of such providers are likely to be adjusted as feedback arrives.

package main

import (
	"fmt"

	"github.com/muir/nject"
)

func main() {
	type string2 string
	seq1 := nject.Sequence("example",
		nject.Shun(func() string {
			fmt.Println("fallback default included")
			return "fallback default"
		}),
		func(s string) string2 {
			return "<" + string2(s) + ">"
		},
	)
	seq2 := nject.Sequence("later inputs",
		// for this to work, it must be reordered to be in front
		// of the string->string2 provider
		nject.Reorder(func() string {
			return "override value"
		}),
	)
	fmt.Println(nject.Run("combination",
		seq1,
		seq2,
		func(s string2) {
			fmt.Println(s)
		},
	))
}

Output:

<override value>
<nil>

func ReplaceNamed ¶ added in v1.6.0

func ReplaceNamed(target string, fn interface{}) Provider

ReplaceNamed will edit the set of injectors, replacing target injector, identified by the name it was given with Provide(), with the injector provided here. This replacement happens very early in the injection chain processing, before Reorder or injector selection. If target does not exist, the injection chain is deemed invalid.

package main

import (
	"fmt"

	"github.com/muir/nject"
)

func main() {
	type string2 string
	seq1 := nject.Sequence("example",
		nject.Provide("default-string", func() string {
			fmt.Println("fallback default included")
			return "fallback default"
		}),
		func(s string) string2 {
			return "<" + string2(s) + ">"
		},
	)
	seq2 := nject.Sequence("later inputs",
		nject.ReplaceNamed("default-string", func() string {
			return "override value"
		}),
	)
	fmt.Println(nject.Run("combination",
		seq1,
		seq2,
		func(s string2) {
			fmt.Println(s)
		},
	))
}

Output:

<override value>
<nil>

func Required ¶

func Required(fn interface{}) Provider

Required creates a new provider and annotates it as required: it will be included in the provider chain even if its outputs are not used.

When used on an existing Provider, it creates an annotated copy of that provider.

func SaveTo ¶ added in v1.1.0

func SaveTo(varPointers ...interface{}) (Provider, error)

SaveTo generates a required provider. The input parameters to FillVars must be pointers. The generated provider takes as inputs the types needed to assign through the pointers.

If you want to fill a struct, use MakeStructBuilder() instead.

The first argument to FillVars may not be a pointer to a function.

package main

import (
	"fmt"

	"github.com/muir/nject"
)

func main() {
	var s string
	var i int
	fmt.Println(nject.Run("example",
		func() string { return "one" },
		func() int { return 3 },
		nject.MustSaveTo(&s, &i)), s, i)
}

Output:

<nil> one 3

func Shun ¶

func Shun(fn interface{}) Provider

Shun creates a new provider and annotates it as not desired: even if it appears to be needed because another provider uses its output, the chain will be built without it if possible.

func Singleton ¶

func Singleton(fn interface{}) Provider

Singleton marks a provider as a forced singleton. The provider will be invoked only once even if it is included in multiple different Sequences. It will be in the the STATIC chain. There is no check that the input arguments available at the time the provider would be called are consistent from one invocation to the next. The provider will be called exactly once with whatever inputs are provided the in the first chain that invokes the provider.

An alternative way to get singleton behavior is with Memoize() combined with MustCache().

package main

import (
	"fmt"

	"github.com/muir/nject"
)

func main() {
	type aStruct struct {
		ValueInStruct int
	}
	structProvider := nject.Singleton(func(s string, i int) *aStruct {
		return &aStruct{
			ValueInStruct: len(s) * i,
		}
	})
	_ = nject.Run("chain1",
		"four",
		4,
		structProvider,
		func(a *aStruct, s string, i int) {
			fmt.Printf("inputs are %s and %d, value is %d\n", s, i, a.ValueInStruct)
		},
	)
	_ = nject.Run("chain2",
		"seven",
		5,
		structProvider,
		func(a *aStruct, s string, i int) {
			fmt.Printf("inputs are %s and %d, value is %d\n", s, i, a.ValueInStruct)
		},
	)

}

Output:

inputs are four and 4, value is 16
inputs are seven and 5, value is 16

func MakeReflective ¶

func MakeReflective(
	inputs []reflect.Type,
	outputs []reflect.Type,
	function func([]reflect.Value) []reflect.Value,
) Reflective

MakeReflective is a simple utility to create a Reflective

func MakeReflectiveWrapper ¶ added in v1.1.0

func MakeReflectiveWrapper(
	downIn []reflect.Type,
	upOut []reflect.Type,
	downOut []reflect.Type,
	upIn []reflect.Type,
	function func([]reflect.Value) []reflect.Value,
) ReflectiveWrapper

MakeReflectiveWrapper is a utility to create a ReflectiveWrapper

The first argument, downIn, is the types that must be received in the down chain and provided to function. This does not include the func([]reflec.Value) []reflect.Value that is actually used for the first argument.

The second argument, upOut, is the types that are returned on the up chain.

The third argument, downOut, is the types provided in the call to the inner function and thus are passed down the down chain.

The forth argument, upIn, is the types returned by the call to the inner function and thus are received from the up chain.

When function is called, the first argument will be a reflect.Value, of course, that is the value of a function that takes []reflect.Value and returns []reflect.Value.

EXPERIMENTAL: this is currently considered experimental and could be removed in a future release. If you're using this, please open a pull request to remove this comment.