add place holder feature

- fix validate lifetime bug which cause flaky tests
- fix "simple" examples

Author: duongphuhiep

README.md

@@ -450,6 +450,8 @@ The `ore.GetResolvedScopedInstances[TInterface](context)` function returns a lis
 | RegisterEagerSingleton | RegisterEagerSingletonToContainer |
 | RegisterLazyCreator | RegisterLazyCreatorToContainer |
 | RegisterLazyFunc | RegisterLazyFuncToContainer |
+| RegisterPlaceHolder | RegisterPlaceHolderToContainer |
+| ProvideScopedValue | ProvideScopedValueToContainer |
 
 Most of time you only need the Default Container. In rare use case such as the Modular Monolith Architecture, you might want to use multiple containers, one per module. Ore provides minimum support for "module" in this case:
 
@@ -475,10 +477,62 @@ trader, _ := ore.GetFromContainer[*Trader](traderContainer, context.Background()
 ```
 
 Important: You will have to prevent cross modules access to the containers by yourself. For eg, don't let your "Broker
-module" to have access to the `tranderContainer` of the "Trader module".
+module" to have access to the `traderContainer` of the "Trader module".
 
 <br />
 
+### Injecting value at Runtime
+
+A common scenario is that your "Service" depends on something which you couldn't provide on registration time. You can provide this dependency only when certain requests or events arrive later. Ore allows you to build an "incomplete" dependency graph using the "place holder".
+
+```go
+//register SomeService which depends on "someConfig"
+ore.RegisterLazyFunc[*SomeService](ore.Scoped, func(ctx context.Context) (*SomeService, context.Context) {
+  someConfig, ctx := ore.Get[string](ctx, "someConfig")
+  return &SomeService{someConfig}, ctx
+})
+
+//someConfig is unknow at registration time because 
+//this value depends on the future user's request
+ore.RegisterPlaceHolder[string]("someConfig")
+
+//a new request arrive
+ctx := context.Background()
+//suppose that the request is sent by "admin"
+ctx = context.WithValue(ctx, "role", "admin")
+
+//inject a different somConfig value depending on the request's content
+userRole := ctx.Value("role").(string)
+if userRole == "admin" {
+  ctx = ore.ProvideScopedValue(ctx, "Admin config", "someConfig")
+} else if userRole == "supervisor" {
+  ctx = ore.ProvideScopedValue(ctx, "Supervisor config", "someConfig")
+} else if userRole == "user" {
+  if (isAuthenticatedUser) {
+    ctx = ore.ProvideScopedValue(ctx, "Public user config", "someConfig")
+  } else {
+    ctx = ore.ProvideScopedValue(ctx, "Private user config", "someConfig")
+  }
+}
+
+//Get the service to handle this request
+service, ctx := ore.Get[*SomeService](ctx)
+fmt.Println(service.someConfig) //"Admin config"
+```
+
+([See full codes here](./examples/placeholderdemo/main.go))
+
+- `ore.RegisterPlaceHolder[T](key...)` registers a future value with Scoped lifetime.
+  - This value will be injected in runtime using the `ProvideScopedValue` function.
+  - Resolving objects which depend on this value will panic if the value has not been provided.
+
+- `ore.ProvideScopedValue[T](context, value T, key...)` injects a concrete value into the given context
+  - `ore` can access (`Get()` or `GetList()`) to this value only if the corresponding place holder (which matches the type and keys) is registered.
+
+- A value provided to a place holder would never replace value returned by other resolvers. It's the opposite, if a type (and key) could be resolved by a real resolver (such as `RegisterLazyFunc`, `RegisterLazyCreator`...), then the later would take precedent.
+
+<br/>
+
 ## More Complex Example
 
 ```go

container.go

@@ -61,6 +61,17 @@ func (this *Container) Validate() {
 		panic("Validation is disabled")
 	}
 	ctx := context.Background()
+
+	//provide default value for all placeHolders
+	for _, resolvers := range this.resolvers {
+		for _, resolver := range resolvers {
+			if resolver.isPlaceHolder() {
+				ctx = resolver.providePlaceHolderDefaultValue(this, ctx)
+			}
+		}
+	}
+
+	//invoke all resolver to detect potential registration problem
 	for _, resolvers := range this.resolvers {
 		for _, resolver := range resolvers {
 			_, ctx = resolver.resolveService(this, ctx)

errors.go

@@ -22,6 +22,14 @@ func cyclicDependency(resolver resolverMetadata) error {
 	return fmt.Errorf("detect cyclic dependency where: %s depends on itself", resolver)
 }
 
+func placeHolderValueNotProvided(resolver resolverMetadata) error {
+	return fmt.Errorf("No value has been provided for this place holder: %s", resolver)
+}
+
+func typeAlreadyRegistered(typeID typeID) error {
+	return fmt.Errorf("The type '%s' has already been registered (as a Resolver or as a Place Holder). Cannot override it with other Place Holder", typeID)
+}
+
 var alreadyBuilt = errors.New("services container is already built")
 var alreadyBuiltCannotAdd = errors.New("cannot appendToContainer, services container is already built")
 var nilKey = errors.New("cannot have nil keys")

examples/placeholderdemo/main.go

@@ -0,0 +1,48 @@
+package main
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/firasdarwish/ore"
+)
+
+type UserRole struct {
+}
+type SomeService struct {
+	someConfig string
+}
+
+func main() {
+	//register SomeService which depends on "someConfig"
+	ore.RegisterLazyFunc[*SomeService](ore.Scoped, func(ctx context.Context) (*SomeService, context.Context) {
+		someConfig, ctx := ore.Get[string](ctx, "someConfig")
+		return &SomeService{someConfig}, ctx
+	})
+
+	//someConfig is unknow at registration time
+	//the value of "someConfig" depends on the future user's request
+	ore.RegisterPlaceHolder[string]("someConfig")
+
+	//Seal registration, no further registration is allowed
+	ore.Build()
+	ore.Validate()
+
+	//a request arrive
+	ctx := context.Background()
+	//suppose that the request is sent by "admin"
+	ctx = context.WithValue(ctx, "role", "admin")
+
+	//inject a different config depends on the request,
+	userRole := ctx.Value("role").(string)
+	if userRole == "admin" {
+		ctx = ore.ProvideScopedValue(ctx, "Admin config", "someConfig")
+	} else if userRole == "supervisor" {
+		ctx = ore.ProvideScopedValue(ctx, "Supervisor config", "someConfig")
+	} else if userRole == "user" {
+		ctx = ore.ProvideScopedValue(ctx, "Public user config", "someConfig")
+	}
+
+	service, _ := ore.Get[*SomeService](ctx)
+	fmt.Println(service.someConfig) //"Admin config"
+}

examples/simple/main.go

@@ -8,21 +8,19 @@ import (
 )
 
 func main() {
-
 	ore.RegisterLazyFunc[Counter](ore.Singleton, func(ctx context.Context) (Counter, context.Context) {
 		fmt.Println("NEWLY INITIALIZED FROM FUNC")
-		return &counter{}, ctx
+		return &mycounter{}, ctx
 	}, "firas")
 
 	ore.RegisterLazyFunc[Counter](ore.Singleton, func(ctx context.Context) (Counter, context.Context) {
 		fmt.Println("NEWLY INITIALIZED FROM FUNC")
-		return &counter{}, ctx
+		return &mycounter{}, ctx
 	}, "darwish")
 
-	ore.RegisterLazyCreator[Counter](ore.Singleton, &counter{})
+	ore.RegisterLazyCreator[Counter](ore.Singleton, &mycounter{})
 
-	var cc Counter
-	cc = &counter{}
+	cc := &mycounter{}
 	ore.RegisterEagerSingleton[Counter](cc)
 
 	ctx := context.Background()
@@ -47,7 +45,7 @@ func main() {
 	gc.Add(1)
 	gc.Add(1)
 
-	gc, ctx = ore.Get[GenericCounter[uint]](ctx)
+	gc, _ = ore.Get[GenericCounter[uint]](ctx)
 	gc.Add(1)
 
 	fmt.Println(gc.Total())
@@ -62,3 +60,42 @@ type GenericCounter[T numeric] interface {
 	Add(num T)
 	Total() T
 }
+
+type mycounter struct {
+	count int
+}
+
+var _ Counter = (*mycounter)(nil)
+
+func (c *mycounter) AddOne() {
+	c.count++
+}
+
+func (c *mycounter) Total() int {
+	return c.count
+}
+
+func (*mycounter) New(ctx context.Context) (Counter, context.Context) {
+	fmt.Println("NEWLY INITIALIZED")
+	return &mycounter{}, ctx
+}
+
+type numeric interface {
+	uint
+}
+
+type genCounter[T numeric] struct {
+	count T
+}
+
+func (t *genCounter[T]) Add(num T) {
+	t.count += num
+}
+
+func (t *genCounter[T]) Total() T {
+	return t.count
+}
+
+func (*genCounter[T]) New(ctx context.Context) (GenericCounter[T], context.Context) {
+	return &genCounter[T]{}, ctx
+}

examples/simple/service.go

@@ -97,6 +97,11 @@ func GetListFromContainer[T any](con *Container, ctx context.Context, key ...Key
 
 		for index := 0; index < len(resolvers); index++ {
 			resolver := resolvers[index]
+			if resolver.isPlaceHolder() && !resolver.isScopedValueResolved(ctx) {
+				//the resolver is a placeHolder and the placeHolder's value has not been provided
+				//don't panic, just skip (don't add anything to the list)
+				continue
+			}
 			con, newCtx := resolver.resolveService(con, ctx)
 			servicesArray = append(servicesArray, con.value.(T))
 			ctx = newCtx

getters.go

@@ -4,6 +4,7 @@ package assert2
 import (
 	"fmt"
 	"runtime/debug"
+	"strings"
 
 	"github.com/stretchr/testify/assert"
 )
@@ -37,19 +38,19 @@ func PanicsWithError(t assert.TestingT, errStringMatcher StringMatcher, f assert
 
 func ErrorStartsWith(prefix string) StringMatcher {
 	return func(s string) bool {
-		return s != "" && s[:len(prefix)] == prefix
+		return strings.HasPrefix(s, prefix)
 	}
 }
 
 func ErrorEndsWith(suffix string) StringMatcher {
 	return func(s string) bool {
-		return s != "" && s[len(s)-len(suffix):] == suffix
+		return strings.HasSuffix(s, suffix)
 	}
 }
 
 func ErrorContains(substr string) StringMatcher {
 	return func(s string) bool {
-		return s != "" && s[:len(substr)] == substr
+		return strings.Contains(s, substr)
 	}
 }
 

internal/testtools/assert2/assertions.go

@@ -11,6 +11,10 @@ var (
 	contextKeysRepositoryID specialContextKey = "The context keys repository"
 	//contextKeyResolversStack is a special context key. The value of this key is the [ResolversStack].
 	contextKeyResolversStack specialContextKey = "Dependencies stack"
+
+	//placeHolderResolverID is a special resolverID of every "placeHolder". "placeHolder" is a special resolver
+	//describing a "promise" for a concrete value, which will be provided in runtime.
+	placeHolderResolverID = -1
 )
 
 type contextKeysRepository = []contextKey
@@ -43,19 +47,28 @@ func addResolver[T any](this *Container, resolver serviceResolverImpl[T], key ..
 	typeID := typeIdentifier[T](key...)
 
 	this.lock.Lock()
+	defer this.lock.Unlock()
+
+	resolverID := len(this.resolvers[typeID])
+	if resolver.isPlaceHolder() {
+		if resolverID > 0 {
+			panic(typeAlreadyRegistered(typeID))
+		}
+		resolverID = placeHolderResolverID
+	}
+
 	resolver.id = contextKey{
 		typeID:      typeID,
 		containerID: this.containerID,
-		index:       len(this.resolvers[typeID]),
+		resolverID:  resolverID,
 	}
 	this.resolvers[typeID] = append(this.resolvers[typeID], resolver)
-	this.lock.Unlock()
 }
 
 func replaceResolver[T any](this *Container, resolver serviceResolverImpl[T]) {
 	this.lock.Lock()
-	this.resolvers[resolver.id.typeID][resolver.id.index] = resolver
-	this.lock.Unlock()
+	defer this.lock.Unlock()
+	this.resolvers[resolver.id.typeID][resolver.id.resolverID] = resolver
 }
 
 func addAliases[TInterface, TImpl any](this *Container) {
@@ -65,13 +78,13 @@ func addAliases[TInterface, TImpl any](this *Container) {
 		return
 	}
 	this.lock.Lock()
+	defer this.lock.Unlock()
 	for _, ot := range this.aliases[aliasType] {
 		if ot == originalType {
 			return //already registered
 		}
 	}
 	this.aliases[aliasType] = append(this.aliases[aliasType], originalType)
-	this.lock.Unlock()
 }
 
 func Build() {