gioc

   █████████  █████    ███████      █████████    
  ███░░░░░███░░███   ███░░░░░███   ███░░░░░███   
 ███     ░░░  ░███  ███     ░░███ ███     ░░░    
░███          ░███ ░███      ░███░███            
░███    █████ ░███ ░███      ░███░███            
░░███  ░░███  ░███ ░░███     ███ ░░███     ███   
 ░░█████████  █████ ░░░███████░   ░░█████████    
  ░░░░░░░░░  ░░░░░    ░░░░░░░      ░░░░░░░░░     
    

gioc organises dependencies into modules, resolves the full dependency graph at startup, and wires every provider in topological order — catching circular dependencies before your application runs.

go get github.com/0x626f/gioc

Releases are tagged with semantic versioning. Pin a release with:

go get github.com/0x626f/gioc@v0.1.0

Concepts

Quick start

package main

import (
    "fmt"
    "github.com/0x626f/gioc"
)

type Config struct{ DSN string }
type DB     struct{ DSN string }
type App    struct{ DB *DB }

func main() {
    configToken := "Config"
    dbToken     := "DB"

    mod := gioc.NewModule("app")
    mod.Provide(
        gioc.ValueProvider[*Config](configToken, &Config{DSN: "postgres://localhost/mydb"}, false),

        gioc.FactoryProvider[*DB](dbToken, gioc.Factory[*DB]{
            Injects:    gioc.Inject(configToken),
            ValueScope: gioc.Singleton,
            Constructor: func(deps gioc.Injections) (*DB, error) {
                cfg, err := gioc.Resolve[*Config](configToken, deps)
                if err != nil {
                    return nil, err
                }
                return &DB{DSN: cfg.DSN}, nil
            },
        }, false),

        gioc.FactoryProvider[*App]("", gioc.Factory[*App]{
            Injects:    gioc.Inject(dbToken),
            ValueScope: gioc.Singleton,
            Constructor: func(deps gioc.Injections) (*App, error) {
                db, err := gioc.Resolve[*DB](dbToken, deps)
                if err != nil {
                    return nil, err
                }
                return &App{DB: db}, nil
            },
        }, false),
    )

    c := gioc.NewContainer()
    c.AddModules(mod)
    if err := c.Run(); err != nil {
        panic(err)
    }

    app, err := gioc.Get[*App](c, "App", mod)
    if err != nil {
        panic(err)
    }

    fmt.Println("container wired successfully", app.DB.DSN)
}

Providers

ValueProvider

Wraps an already-constructed value. Always Singleton — every consumer receives the same pointer.

gioc.ValueProvider[*Config]("", &Config{DSN: "..."}, true)
//                           ^     ^                  ^
//                           |     value              exportable
//                           token (empty = derived from type)

FactoryProvider

Constructs the instance via a function. Supports both Singleton and Prototype scopes.

gioc.FactoryProvider[*Service]("", gioc.Factory[*Service]{
    Injects:     gioc.Inject("Logger", "Database"),
    ValueScope:  gioc.Singleton,
    Constructor: func(deps gioc.Injections) (*Service, error) {
        log, _ := gioc.Resolve[*Logger]("Logger", deps)
        db,  _ := gioc.Resolve[*Database]("Database", deps)
        return &Service{Log: log, DB: db}, nil
    },
}, false)

The same factory can be built with NewFactory:

factory := gioc.NewFactory[*Service](
    gioc.Inject("Logger", "Database"),
    gioc.Singleton,
    func(deps gioc.Injections) (*Service, error) {
        log, _ := gioc.Resolve[*Logger]("Logger", deps)
        db,  _ := gioc.Resolve[*Database]("Database", deps)
        return &Service{Log: log, DB: db}, nil
    },
)

Token auto-derivation

When the token argument is an empty string, it is derived from the type name:

gioc.CreateToken[*MyService]() // → "MyService"
gioc.CreateToken[MyService]()  // → "MyService"

Modules

infraMod := gioc.NewModule("infra")
infraMod.Provide(
    gioc.ValueProvider[*Logger]("", &Logger{}, true), // exported
)

appMod := gioc.NewModule("app")
appMod.Import(infraMod)   // providers of infraMod are visible here
appMod.Provide(
    gioc.FactoryProvider[*Service]("", gioc.Factory[*Service]{
        Injects: gioc.Inject(gioc.CreateToken[Logger]()),
        Constructor: func(deps gioc.Injections) (*Service, error) {
            log, _ := gioc.Resolve[*Logger](gioc.CreateToken[Logger](), deps)
            return &Service{Log: log}, nil
        },
    }, false),
)

Global modules

Mark a module as global to make its providers available to every other module in the container — no explicit Import call needed.

sharedMod := gioc.NewModule("shared").Global()
sharedMod.Provide(gioc.ValueProvider[*Logger]("", &Logger{}, false))

appMod := gioc.NewModule("app") // no Import(sharedMod) required
appMod.Provide(gioc.FactoryProvider[*Service]("", gioc.Factory[*Service]{
    Injects: gioc.Inject(gioc.CreateToken[Logger]()),
    Constructor: func(deps gioc.Injections) (*Service, error) {
        log, _ := gioc.Resolve[*Logger](gioc.CreateToken[Logger](), deps)
        return &Service{Log: log}, nil
    },
}, false))

c := gioc.NewContainer()
c.AddModules(sharedMod, appMod) // sharedMod's Logger is injected into appMod automatically
c.Run()

Global modules are initialised before regular modules, so their singletons are ready when the rest of the container starts up. If the same token is registered both locally and in a global module, the local provider takes priority.

Chaining

NewModule, Global, Import, and Provide all return *Module, so they can be chained:

gioc.NewModule("app").
    Import(infraMod).
    Provide(providerA, providerB)

Resolving dependencies in constructors

Resolve — find by token in Injections

Constructor: func(deps gioc.Injections) (*Service, error) {
    db, err := gioc.Resolve[*Database]("Database", deps)
    if err != nil {
        return nil, err
    }
    return &Service{DB: db}, nil
},

Use MustResolve when a missing or incorrectly typed dependency should panic:

Constructor: func(deps gioc.Injections) (*Service, error) {
    db := gioc.MustResolve[*Database]("Database", deps)
    return &Service{DB: db}, nil
},

Container.Resolve — fetch a raw provider after Run

Singleton providers return the instance created during Run; prototype providers create a fresh instance for each call.

inj, err := c.Resolve("Database", appMod)
if err != nil {
    return err
}
_ = inj

Get — fetch and unwrap after Run

Get combines Container.Resolve with type assertion when callers want a typed value directly. If no module context is provided, it searches the container's root modules in registration order.

db, err := gioc.Get[*Database](c, "Database", appMod)
if err != nil {
    return err
}

Require — panic-guard at the top of a constructor

Constructor: func(deps gioc.Injections) (*Service, error) {
    gioc.Require(deps, "Logger", "Database") // panics if either is missing
    ...
},

Injections also exposes methods for non-generic lookup and validation:

instance, err := deps.Resolve("Logger")
required := deps.MustResolve("Database")
deps.Require("Logger", "Database")

Scopes

// Singleton — one instance shared across all consumers
gioc.Factory[*Pool]{ValueScope: gioc.Singleton, Constructor: ...}

// Prototype — new instance created for every consumer
gioc.Factory[*Request]{ValueScope: gioc.Prototype, Constructor: ...}

Error handling

Run returns typed errors that can be inspected:

if err := c.Run(); err != nil {
    var cycleErr *gioc.CircularInjectionError
    var depErr   *gioc.DependencyError
    switch {
    case errors.As(err, &cycleErr):
        log.Fatalf("cycle detected: %v", cycleErr)
    case errors.As(err, &depErr):
        log.Fatalf("missing dependency: %v", depErr)
    }
}

Full wiring example

type AppConfig struct{ DSN string }
type DBPool   struct{ DSN string }
type UserRepo struct{ Pool *DBPool }
type UserSvc  struct{ Repo *UserRepo }

const (
    tokenConfig  = "AppConfig"
    tokenPool    = "DBPool"
    tokenRepo    = "UserRepo"
    tokenSvc     = "UserSvc"
)

// infrastructure module — global, AppConfig is visible to all modules automatically
infraMod := gioc.NewModule("infra").Global()
infraMod.Provide(
    gioc.ValueProvider[*AppConfig](tokenConfig, &AppConfig{DSN: "postgres://prod"}, false),
)

// services module — no Import needed; AppConfig comes from the global infra module
svcMod := gioc.NewModule("services")
svcMod.Provide(
    gioc.FactoryProvider[*DBPool](tokenPool, gioc.Factory[*DBPool]{
        Injects:    gioc.Inject(tokenConfig),
        ValueScope: gioc.Singleton,
        Constructor: func(deps gioc.Injections) (*DBPool, error) {
            cfg, _ := gioc.Resolve[*AppConfig](tokenConfig, deps)
            return &DBPool{DSN: cfg.DSN}, nil
        },
    }, true),
    gioc.FactoryProvider[*UserRepo](tokenRepo, gioc.Factory[*UserRepo]{
        Injects:    gioc.Inject(tokenPool),
        ValueScope: gioc.Singleton,
        Constructor: func(deps gioc.Injections) (*UserRepo, error) {
            pool, _ := gioc.Resolve[*DBPool](tokenPool, deps)
            return &UserRepo{Pool: pool}, nil
        },
    }, true),
    gioc.FactoryProvider[*UserSvc](tokenSvc, gioc.Factory[*UserSvc]{
        Injects:    gioc.Inject(tokenRepo),
        ValueScope: gioc.Singleton,
        Constructor: func(deps gioc.Injections) (*UserSvc, error) {
            repo, _ := gioc.Resolve[*UserRepo](tokenRepo, deps)
            return &UserSvc{Repo: repo}, nil
        },
    }, true),
)

c := gioc.NewContainer()
c.AddModules(infraMod, svcMod)
if err := c.Run(); err != nil {
    log.Fatal(err)
}