loom

Loom

English | 简体中文

Loom is a compile-time dependency injection tool for Go.

You declare a dependency graph with loom.Graph, ordinary constructor functions, and a small marker API. loom generate reads that declaration and writes plain Go that calls your constructors in the right order. The generated code contains no reflection, no service locator, and no runtime container — just a function.

var AppGraph = loom.Graph[*Application](
    loom.WithContext(),
    loom.Provide(NewConfig),
    loom.Provide(NewLogger),
    loom.Provide(NewDatabase),
    loom.Provide(NewRepository[User]),
    loom.Provide(NewRepository[Article]),
    loom.As[UserStore](NewUserStore),
    loom.Provide(NewUserService),
    loom.Provide(NewHTTPServer),
    loom.Provide(NewApplication),
)

loom generate ./...

// Code generated by loom. DO NOT EDIT.

func InitApp(ctx context.Context) (*Application, *loom.Lifecycle, error) {
    lifecycle := loom.NewLifecycle()

    config := NewConfig()

    logger := NewLogger(config)

    database, databaseCleanup, err := NewDatabase(config)
    if err != nil {
        return nil, nil, errors.Join(err, lifecycle.Rollback(ctx))
    }
    lifecycle.AddCleanup(databaseCleanup)

    userRepository := NewRepository[User](database)
    articleRepository := NewRepository[Article](database)
    userStore := NewUserStore(userRepository, logger)
    userService := NewUserService(userStore, logger)
    httpServer := NewHTTPServer(lifecycle, config, logger, userService)
    application := NewApplication(config, logger, database, httpServer, userService)

    return application, lifecycle, nil
}

Two Repository[...] instances are built from one *Database, interfaces are bound explicitly, and resources are released in reverse order.

Why Loom

Install

Pin the generator to your module, so everyone and CI run the same version:

go get -tool github.com/Xwudao/loom/cmd/loom@latest
go tool loom generate ./...

Or install the binary once:

go install github.com/Xwudao/loom/cmd/loom@latest

loom is designed for Go 1.25 and newer (it is built and tested on Go 1.27).

Coming from Wire

Two differences are worth calling out.

As replaces Provide, it does not accompany it. loom.As[I](NewC) registers NewC and exposes the same instance as I, so listing both is a duplicate provider. Loom says so directly:

loom: multiple providers found for *store
providers:
    internal/app/providers.go:33:15  NewStore()
    internal/app/providers.go:34:17  NewStore()

hint:
    loom.As[Store](NewStore) already provides both *store and Store; remove the separate loom.Provide(NewStore)

There is no stub file. Wire kept its injectors behind a wireinject build tag, so the call site only type-checked after generation. A Loom graph is an ordinary package-level variable: gopls, go vet and go test all see it. The trade-off is that on the very first run the initializer a call site refers to does not exist yet; loom generate recognises exactly the undefined: InitApp errors it is about to fix and still reports every other type error.

Quick start

package app

import "github.com/Xwudao/loom"

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

func NewConfig() *Config       { return &Config{DSN: "memory://"} }
func NewDB(cfg *Config) *DB    { return &DB{DSN: cfg.DSN} }
func NewApp(db *DB) *App       { return &App{DB: db} }

// AppGraph is the graph declaration. The generated function is InitApp.
var AppGraph = loom.Graph[*App](
    loom.Provide(NewConfig),
    loom.Provide(NewDB),
    loom.Provide(NewApp),
)

$ loom generate ./...
loom: wrote app/loom_gen.go ([InitApp])

app, lifecycle, err := InitApp()
if err != nil {
    return err
}
if err := lifecycle.Start(ctx); err != nil {
    return err
}
defer lifecycle.Stop(shutdownCtx)
return app.Run(ctx)

Add //go:generate go run github.com/Xwudao/loom/cmd/loom generate to a file to wire generation into go generate ./....

Providers

A provider is a package-level function (or a package-level variable of function type) with one of these shapes:

func NewThing(...) T
func NewThing(...) (T, error)
func NewThing(...) (T, Cleanup)          // Cleanup = func(context.Context) error
func NewThing(...) (T, Cleanup, error)

Cleanup may also be func(), func() error, or func(context.Context); Loom adapts it. Variadic constructors are supported: func NewThing(opts ...string) is resolved from a []string provider and called as NewThing(opts...). Multi-value providers (func() (A, B)) are intentionally not supported — split them into two providers.

Register a provider with:

loom.Provide(NewDB)

Generics

Generic constructors must be instantiated, which makes the type argument part of the dependency key:

func NewRepository[T any](db *DB) *Repository[T]

loom.Provide(NewRepository[User])     // provides *Repository[User]
loom.Provide(NewRepository[Article])  // provides *Repository[Article]

A constructor that takes *Repository[User] will never receive the Article one. Loom compares types with go/types, not with strings, so aliases, pointer generics, and nested generics behave exactly as the compiler sees them.

Interface binding

Bind a constructor's result to an interface explicitly:

loom.As[UserStore](NewUserStore)

The generator verifies that NewUserStore's result implements UserStore, and reports a diagnostic at the call site when it does not:

loom: provider NewUserStore returns *httpserver.Store, which does not implement UserStore
at:
    internal/user/providers.go:22:2

The concrete type remains available too, so As never creates a second instance.

A graph may also expose a constructor that a module already provides. The binding stays in the graph, which matters when the interface lives in a package that imports the module — putting As in the module would close an import cycle:

var StoreModule = loom.Module(
    loom.Provide(NewStore),
)

// iface imports store, so the binding cannot live in StoreModule.
var AppGraph = loom.Graph[*App](
    StoreModule,
    loom.As[iface.Finisher](store.NewStore),
    loom.Provide(NewApp),
)

Listing one constructor twice in the same declaration is still reported, since that is a redundant line rather than a statement about what the graph exposes.

Modules

Group providers into reusable sets. Modules nest, and including the same module twice is a no-op.

var DatabaseModule = loom.Module(
    loom.Provide(NewDatabase),
    loom.Provide(NewRepository[User]),
    loom.Provide(NewRepository[Article]),
)

var ServiceModule = loom.Module(
    DatabaseModule,
    loom.As[UserStore](NewUserStore),
    loom.Provide(NewUserService),
)

Supply

Inject an existing value with loom.Supply. The expression is reproduced in the generated code, so it must be relocatable (identifiers, qualified names, literals, calls):

loom.Supply(config)
loom.Supply(Version{Major: 1, Minor: 2})

Note that Go evaluates the argument once during package initialization and again inside the generated initializer. Assign side-effecting expressions to a package-level variable first.

Lifecycle

*loom.Lifecycle is injectable. Register start/stop callbacks for long-lived services:

func NewHTTPServer(lc *loom.Lifecycle, cfg *Config) *HTTPServer {
    server := &HTTPServer{Addr: cfg.Addr}
    lc.Append(loom.Hook{
        OnStart: func(ctx context.Context) error { return server.Listen(ctx) },
        OnStop:  func(ctx context.Context) error { return server.Close() },
    })
    return server
}

Hooks run in registration order on Start and in reverse on Stop. If a hook fails to start, already-started hooks and cleanups are rolled back.

context.Context is injectable in two ways. loom.WithContext() threads the caller's context through, adding a leading ctx parameter to the generated function:

var AppGraph = loom.Graph[*App](
    loom.WithContext(),
    ...
)

Or a graph supplies it like any other dependency, which is what a Wire injector with a ProvideContext function does. An explicit provider wins over WithContext, so loom.Provide(ProvideContext) keeps the generated signature unchanged.

Cleanup and rollback

A constructor may return a cleanup alongside its value. Loom registers it with the lifecycle, so:

• on a construction failure, everything built so far is released in reverse order (Lifecycle.Rollback);
• on Lifecycle.Stop, started hooks stop first, then cleanups run, all in reverse registration order.

Do not return a cleanup and register an OnStop hook for the same resource.

The generated function

Every graph produces one function, named after the graph variable:

The signature is stable:

func InitApp() (*App, *loom.Lifecycle, error)
// with loom.WithContext():
func InitApp(ctx context.Context) (*App, *loom.Lifecycle, error)

Generated code is written to loom_gen.go, gofmt-formatted, and only rewritten when its content actually changes.

Bootstrapping and regeneration

Loom has no stub file, so on a first run the initializer does not exist yet and every call site of it is reported by the type checker as undefined. That is expected, not an error: loom generate tolerates undefined: InitApp for the exact function names it is about to create, so you can write the graph and its call site in the same commit. Any other error is still reported.

Generation is all-or-nothing: every package is resolved and rendered before anything is written, so a diagnostic in one package cannot leave others half-generated. If the graph is valid but a symbol is out of date in a way the type checker cannot see, the generated call site fails to compile, which is the backstop.

Variables are named after the type they hold (Repository[User] becomes userRepository). When that name is already spoken for, Loom prefers an explicit package-qualified name over a numeric suffix, in these cases:

CLI

loom generate ./...        generate initializers (default ./...)
loom graph ./cmd/server    print the dependency graph
loom graph -format=dot ./cmd/server | dot -Tsvg > graph.svg
loom graph -format=json ./cmd/server
loom skills                  # install the agent skill into .agents/skills/loom
loom version
loom help

loom skills finds the nearest project .agents/skills directory (so it also works from a subdirectory) and installs the Loom usage skill at .agents/skills/loom. The skill includes a separate Wire migration reference.

loom generate -dry-run reports what would change without writing, and exits non-zero when a committed generated file is out of date, so it can gate CI:

$ loom generate -dry-run ./...
loom: internal/app/loom_gen.go out of date
loom: 1 generated file(s) out of date; run 'loom generate'

$ loom graph ./examples/full
InitApp  (examples/full/graph.go:22)
*Application
├── AppName
├── *Config
├── *Logger
│   └── *Config  (shared)
├── *Database
│   └── *Config  (shared)
├── *HTTPServer
│   ├── *loom.Lifecycle
│   ├── *Config  (shared)
│   └── *UserService
│       └── UserStore
│           └── *Repository[User]
└── *ArticleService
    └── *Repository[Article]

Diagnostics

Missing providers, cycles, and duplicates report the whole path:

loom: cannot build *App

dependency path:
    *App
      -> *UserService
      -> UserStore  (missing)

providers:
    internal/app/app.go:14:6       NewApp(*UserService)
    internal/user/service.go:13:6  NewUserService(UserStore)

hint:
    provider NewUserStore returns *userStore, which implements UserStore;
    bind it with loom.As[UserStore](NewUserStore)

What Loom is not

Loom never resolves dependencies at runtime. There is no container, no Resolve, no Get, and no reflection. The only runtime primitive is loom.Lifecycle, an ordered list of hooks and cleanups.

Version 0.1 deliberately omits named/keyed dependencies, optional dependencies, value groups, decorators, scopes (transient/request), and runtime replacement.

Repository layout

loom/
├── cmd/loom/            CLI
├── internal/
│   ├── load/            go/packages loading (one types universe)
│   ├── parse/           graph discovery and IR construction
│   ├── model/           providers, graphs, type index
│   ├── resolve/         topological resolution and cycle detection
│   ├── codegen/         deterministic Go emission
│   ├── diag/            diagnostics
│   └── gen/             orchestration + golden/benchmark tests
├── examples/            basic, generic, interface, lifecycle, rollback, full
├── lifecycle.go         Hook, Cleanup, Lifecycle
└── marker.go            Provide, As, Supply, Module, Graph, Name, WithContext

See docs/design.md for the design decisions behind the marker API, the type model, and the lifecycle semantics. See docs/compatibility.md for the API and generated-code compatibility policy.

Development

go test ./...
go vet ./...
go generate ./...   # regenerate examples and commit the result