dscope

dscope - A Dependency Injection Library for Go

dscope is a powerful and flexible dependency injection library for Go, designed to promote clean architecture, enhance testability, and manage dependencies with ease. It emphasizes immutability, lazy initialization, and type safety.

Why use dscope?

Managing dependencies in larger Go applications can become complex. dscope offers several advantages:

• Type-Safe Dependencies: Leverages Go's type system to ensure that dependencies are resolved correctly at compile time or with clear runtime panics if a type is missing. Generic functions like Get[T](scope) provide compile-time type checking for retrievals.
• Define and Depend on Interfaces (or Concrete Types): While you can register and request concrete types directly, dscope fully supports defining providers that return interfaces and requesting dependencies via those interfaces, promoting loose coupling.
• Cleaner Function Signatures: The scope.Call(yourFunction) feature automatically resolves the arguments for yourFunction from the scope. This means yourFunction only needs to declare its essential operational arguments, not a long list of dependencies it needs to acquire manually.
• Enhanced Testability:
  • Immutability: Scopes are immutable. Operations like Fork create new scopes, leaving the original untouched. This predictability is great for testing.
  • Easy Overriding: You can easily Fork a scope and provide alternative (mock or stub) implementations for specific types, making unit and integration testing more straightforward.
• Immutable and Predictable Scopes: Each scope is an immutable container. Modifying a scope (e.g., adding new definitions or overriding existing ones) results in a new scope instance. This makes the state of dependencies predictable and easier to reason about.
• Lazy Initialization: Values within a scope are initialized lazily. A provider function is only called when the value it provides (or a dependant value) is actually requested for the first time. This can improve application startup time and resource usage.
• Fine-Grained Recomputation: Fork recomputes only the overridden type and its transitive dependents. Prefer single-value types over composites with multiple mutable fields: overriding one value then recomputes only the providers that depend on it, not every consumer of the composite.

Core Concepts

Scope

A Scope is an immutable container holding definitions for various types. It's the central piece from which you resolve dependencies. The Universe is the initial empty scope.

Definitions

Definitions are functions or pointers that tell a scope how to create or provide an instance of a type.

• Provider Functions: Functions that return one or more values. Their arguments are themselves resolved as dependencies from the scope.

  func NewMyService(db Database) MyService { /* ... */ }
  func NewConfigAndLogger() (Config, Logger) { /* ... */ }
  

• Pointer Values: Pointers to existing instances can also be used as definitions. The pointed-at value will be provided.

  cfg := &MyConfig{Value: "example"}
  scope := dscope.New(cfg) // MyConfig is now available
  

Fork

Fork is the primary mechanism for creating new scopes. When you Fork an existing scope, you create a new scope that contains every definition of the original, with the new definitions layered on top. The two scopes are independent branches: you can add new definitions or override existing ones in the new scope without affecting the original.

baseScope := dscope.New(func() int { return 42 })
branch1 := baseScope.Fork(func() string { return "hello" }) // same int as base, adds string
branch2 := baseScope.Fork(func() int { return 100 })   // overrides int

Reset

Reset creates a new scope in which every provider result is recomputed lazily on the next access. The original scope is unaffected.

calls := 0
scope := dscope.New(func() int {
	calls++
	return calls
})
fmt.Println(dscope.Get[int](scope))      // Output: 1
fmt.Println(dscope.Get[int](scope))      // Output: 1 (result is cached)

resetScope := scope.Reset()
fmt.Println(dscope.Get[int](resetScope)) // Output: 2 (recomputed)

dscope.Reset (type Reset func() Scope) is also provided as a built-in dependency bound to the current scope's Reset method, so it can be injected into providers, similar to dscope.Fork:

scope.Call(func(reset dscope.Reset) {
	// reset() returns a reset scope of the current scope
})
```## Basic Usage Examples

### 1. Creating a New Scope

You can create a new scope from scratch using `dscope.New()` (which is equivalent to `dscope.Universe.Fork()`).

```go
package main

import (
	"fmt"
	"github.com/reusee/dscope"
)

// Define some types
type Greeter string
type Message string

// Define provider functions
func provideGreeter() Greeter {
	return "Hello"
}

func provideMessage(g Greeter) Message {
	return Message(fmt.Sprintf("%s, dscope!", g))
}

func main() {
	scope := dscope.New(
		provideGreeter,
		provideMessage,
	)
	// Scope is now configured
}

2. Getting Values by Type

You can retrieve values from the scope using scope.GetType(reflect.Type), the generic dscope.Get[T](scope), or scope.Assign(pointers...).

• dscope.Get[T](scope) (Recommended for type safety):

  msg := dscope.Get[Message](scope)
  fmt.Println(msg) // Output: Hello, dscope!
  

• scope.TryGet[T]() (Non-panicking lookup): returns the value and whether the type is defined in the scope, instead of panicking on a missing type.

  if msg, ok := scope.TryGet[Message](); ok {
      fmt.Println(msg) // Output: Hello, dscope!
  }
  

• scope.Assign(pointers...):

  var m Message
  var g Greeter
  scope.Assign(&m, &g)
  fmt.Println(g, m) // Output: Hello Hello, dscope!
  

• scope.GetType(reflect.Type) / scope.TryGetType(reflect.Type) (reflection-based lookup; GetType panics on a missing type):

  import "reflect"
  // ...
  msgVal, ok := scope.TryGetType(reflect.TypeOf(Message("")))
  if ok {
      fmt.Println(msgVal.Interface().(Message))
  }
  

3. Calling Functions in a Scope

scope.Call(fn) executes fn, automatically resolving its arguments from the scope. Return values are wrapped in a CallResult.

type Salutation string

func provideSalutation() Salutation {
	return "Greetings"
}

scope = scope.Fork(provideSalutation) // Add Salutation to the scope

result := scope.Call(func(s Salutation, m Message) string {
	return fmt.Sprintf("%s! %s", s, m)
})

var finalMsg string
result.Assign(&finalMsg) // Assigns the string return value
// or result.Extract(&finalMsg) if order matters and you know the return position

fmt.Println(finalMsg) // Output: Greetings! Hello, dscope!```

### 4. Forking a Scope

Forking creates a new scope that contains the original's definitions, allowing you to add or override definitions.

```go
baseScope := dscope.New(func() int { return 10 })

// Fork 1: Add a new type
branch1 := baseScope.Fork(func(i int) string {
	return fmt.Sprintf("Number: %d", i)
})
fmt.Println(dscope.Get[string](branch1)) // Output: Number: 10

// Fork 2: Override an existing type
branch2 := baseScope.Fork(func() int { return 20 })
fmt.Println(dscope.Get[int](branch2)) // Output: 20

// Original scope is unaffected
fmt.Println(dscope.Get[int](baseScope)) // Output: 10

5. Modules

Modules help organize definitions. You can embed dscope.Module in your structs and then use dscope.Methods(moduleInstances...) to add all exported methods of those instances (and their embedded modules) as providers to the scope.

type DatabaseModule struct {
	dscope.Module
}

func (dbm *DatabaseModule) ProvideDBConnection() string { // Becomes a provider
	return "db_connection_string"
}

type ServiceModule struct {
	dscope.Module
	DBDep DatabaseModule // Embedded module's methods will also be added
}

func (sm *ServiceModule) ProvideMyService(dbConn string) string { // Becomes a provider
	return "service_using_" + dbConn
}

func main() {
	// Using concrete instance
	scope := dscope.New(
		dscope.Methods(new(ServiceModule))...,
	)
	service := dscope.Get[string](scope) // Will try to get "service_using_db_connection_string"
	fmt.Println(service)
}

Output:

service_using_db_connection_string

You can also pass instances of structs that embed dscope.Module directly to New or Fork:

type ModA struct {
    dscope.Module
}
func (m ModA) GetA() string { return "A from ModA" }

type ModB struct {
    dscope.Module
    MyModA ModA // ModA's methods will be included
}
func (m ModB) GetB() string { return "B from ModB" }


func main() {
    scope := dscope.New(
        new(ModB), // Automatically uses Methods() for types embedding dscope.Module
    )
    fmt.Println(dscope.Get[string](scope, dscope.WithTypeQualifier("GetA"))) // Assuming a way to qualify if GetA and GetB return string
    // For distinct return types, direct Get[T] works:
    // e.g. if GetA returns type AVal and GetB returns type BVal
    // aVal := dscope.Get[AVal](scope)
    // bVal := dscope.Get[BVal](scope)
}

Note: The example with dscope.WithTypeQualifier is illustrative if multiple providers return the same type. If return types are unique, dscope.Get[ReturnType] is sufficient. dscope primarily resolves by type.

6. Struct Field Injection

dscope can inject dependencies into the fields of a struct.

• Using dscope:"." or dscope:"inject" tag:

  type MyStruct struct {
      Dep1 Greeter `dscope:"."` // or dscope:"inject"
      Dep2 Message `dscope:"."`
  }
  
  scope := dscope.New(provideGreeter, provideMessage)
  var myInstance MyStruct
  // scope.Call(func(inject dscope.InjectStruct) { inject(&myInstance) })
  // OR directly:
  scope.InjectStruct(&myInstance)
  
  
  fmt.Printf("Injected: Greeter='%s', Message='%s'\n", myInstance.Dep1, myInstance.Dep2)
  // Output: Injected: Greeter='Hello', Message='Hello, dscope!'
  

• Using dscope.Inject[T] for lazy field injection: Fields of type dscope.Inject[T] are populated with a function that, when called, resolves T from the scope. This is useful for optional dependencies or dependencies needed much later.

  type AnotherStruct struct {
      LazyGreeter dscope.Inject[Greeter]
      RegularMsg  Message `dscope:"."`
  }
  
  scope := dscope.New(provideGreeter, provideMessage)
  var anotherInstance AnotherStruct
  scope.InjectStruct(&anotherInstance)
  
  fmt.Printf("Regular Message: %s\n", anotherInstance.RegularMsg)
  // LazyGreeter is not resolved yet.
  // To get the greeter:
  actualGreeter := anotherInstance.LazyGreeter()
  fmt.Printf("Lazy Greeter: %s\n", actualGreeter)
  // Output:
  // Regular Message: Hello, dscope!
  // Lazy Greeter: Hello
  

This covers the core features and usage patterns of dscope. Its design promotes modularity and testability in Go applications.