docs: add doc.go and expand README for V1

Document lifecycle concepts, companion packages, and API reference. Add gitignore for coverage artifacts. Co-authored-by: Cursor <cursoragent@cursor.com>
refactor: consolidate Require API and split lifecycle files
2026-06-29 17:58:06 -07:00 · 2026-06-29 17:58:05 -07:00 · 2026-06-29 17:58:00 -07:00
11 changed files with 452 additions and 284 deletions
@@ -0,0 +1,6 @@
+# Test coverage
+coverage.out
+coverage.html
+
+# Go build artifacts
+*.test
@@ -1,12 +1,14 @@
 # app

-app is a simple and lightweight app lifecycle management library.
+app orchestrates modular application setup and teardown for Go services.

-## Example
+## Install

-Keep your `main.go` as simple as possible, all it's responsible for is creating the lifecycle, defining a default logger, and orchestrating setup and teardown.
+```bash
+go get gitea.auvem.com/go-toolkit/app
+```

-**main.go**
+## Quick start

 ```go
 package main
@@ -16,75 +18,74 @@ import (
 	"fmt"
 	"log/slog"

+	"gitea.auvem.com/go-toolkit/applog"
 	"gitea.auvem.com/go-toolkit/app"
 )

 func main() {
-	// Create a new lifecycle, defaulting to no printed logs
-	lifecycle := app.NewLifecycle().WithLogger(slog.New(slog.DiscardHandler))
+	lifecycle := app.NewLifecycle(
+		applog.AppLogOpts{ConsoleOutput: os.Stderr}.Module(),
+	)
 	defer func() {
 		if err := lifecycle.Teardown(); err != nil {
-			fmt.Println("Error during shutdown", err)
+			fmt.Println("shutdown error:", err)
 		}
 	}()

-	// Encodes the lifecycle into a context to be used downstream
+	if err := lifecycle.Setup(); err != nil {
+		panic(err)
+	}
+
 	ctx := lifecycle.Context(context.Background())
-
-	// Off to you, call your entrypoint here.
-	Hello(ctx)
+	_ = ctx
+	lifecycle.Logger().Info("ready")
 }
 ```

-Now, let's define a basic logging module and handle loading that module.
+## Concepts

-**logger.go**
+- **Module** — a named subsystem with optional `Setup`, `Teardown`, and `Depends`
+- **Lifecycle** — holds modules and runs setup/teardown in dependency order
+- **Setup** — initializes all modules registered via `NewLifecycle`
+- **Require** — adds and initializes modules on demand (typical for CLI subcommands via [appcli](https://gitea.auvem.com/go-toolkit/appcli))
+- **Autoload** — when enabled (default), `Depends` names are set up automatically before the dependent module

-```go
-package main
+## Dependencies

-import (
-	"log/slog"
+List dependency module **names** in `ModuleOpts.Depends`. Dependent modules must be registered in the same lifecycle (via `NewLifecycle` or an earlier `Require`). Circular dependencies return an error.

-	"gitea.auvem.com/go-toolkit/app"
-)
+## Teardown

-func ModuleLog(setDefault bool) *app.Module {
-	return app.NewModule("logger", app.ModuleOpts{
-		Setup: func(m *app.Module) error {
-			handler := slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{})
-			if setDefault {
-				slog.SetDefault(handler)
-			}
+Always defer `lifecycle.Teardown()`. Teardown runs in **reverse setup order** so dependents shut down before their dependencies.

-			m.Lifecycle().WithLogger(handler)
-		}
-	})
-}
-```
+## Context

-Logging can, however, be somewhat of a complex operation in itself, so I'd highly recommend checking out my [applog](https://gitea.auvem.com/go-toolkit/applog) project, which features tight integration with this app.
+Use `lifecycle.Context(ctx)` so downstream code and `appcli` commands can call `app.LifecycleFromContext(ctx)`.

-Finally, lets put our new lifecycle (and logger) to work!
+## Companion packages

-**hello.go**
+| Package | Role |
+|---------|------|
+| [applog](https://gitea.auvem.com/go-toolkit/applog) | slog + tint logging module |
+| [appcli](https://gitea.auvem.com/go-toolkit/appcli) | urfave/cli v3 integration |
+| [dbx](https://gitea.auvem.com/go-toolkit/dbx) | database module |
+| [migrate](https://gitea.auvem.com/go-toolkit/migrate) | goose migrations module |

-```go
-package main
+## API reference

-import (
-	"context"
+| Symbol | Description |
+|--------|-------------|
+| `NewLifecycle(modules...)` | Create lifecycle with optional initial modules |
+| `Lifecycle.Setup()` | Set up all registered modules |
+| `Lifecycle.Teardown()` | Tear down in reverse setup order |
+| `Lifecycle.Require(modules...)` | Set up modules on demand |
+| `Lifecycle.RequireWithOpts(opts, modules...)` | Require with custom logger or unique-name enforcement |
+| `Lifecycle.GetModule(name)` | Look up a registered module |
+| `NewModule(name, opts)` | Define a module |
+| `LifecycleFromContext(ctx)` | Retrieve lifecycle from context |

-	"gitea.auvem.com/go-toolkit/app"
-)
+## Error handling

-func Hello(ctx context.Context) {
-	app := app.LifecycleFromContext(ctx)
-	if app == nil {
-		panic("hello must run within an app lifecycle")
-	}
-	lifecycle.Require(ModuleLog(true))
-
-	app.Logger().Info("Hello world!", "foo", "bar")
-}
-```
+- Partial setup failure rolls back already-initialized modules
+- `Teardown` joins errors from all modules but attempts every teardown
+- A second `Setup` or `Teardown` on the same lifecycle returns an error
@@ -1,5 +0,0 @@
-// Package app provides the core setup and teardown functions for the
-// backend application. It handles the initialization of all sub-systems
-// and the logger. app should never be imported except by a main package.
-// Examples of suitable main packages are cmd and test.
-package app
@@ -0,0 +1,26 @@
+// Package app orchestrates modular application setup and teardown.
+//
+// Register subsystems as [Module] values, attach them to a [Lifecycle], and call
+// [Lifecycle.Setup] or [Lifecycle.Require] to initialize resources in dependency
+// order. Always call [Lifecycle.Teardown] (typically via defer) to release
+// resources in reverse setup order.
+//
+// Module authors (dbx, applog, migrate, etc.) and main/cmd packages both import
+// app. Use [Lifecycle.Context] to propagate the lifecycle through context.Context
+// for CLI commands via [gitea.auvem.com/go-toolkit/appcli].
+//
+// # Concepts
+//
+//   - [Module] — named unit with optional Setup, Teardown, and Depends
+//   - [Lifecycle] — registry and orchestrator for modules
+//   - Setup order — dependencies first; autoload resolves Depends when enabled
+//   - Require — lazy/conditional setup (common in CLI subcommands)
+//
+// # API overview
+//
+// Lifecycle — [NewLifecycle], [Lifecycle.Setup], [Lifecycle.Teardown],
+// [Lifecycle.Require], [Lifecycle.RequireWithOpts], [Lifecycle.GetModule],
+// [Lifecycle.Context], [LifecycleFromContext]
+//
+// Module — [NewModule], [Module.Lifecycle], [Module.Logger], [Module.Loaded]
+package app
@@ -0,0 +1,6 @@
+package app
+
+import "errors"
+
+// ErrModuleNotFound is returned when a module is not found in the lifecycle.
+var ErrModuleNotFound = errors.New("module not found")
@@ -5,8 +5,6 @@ import (
 	"errors"
 	"fmt"
 	"log/slog"
-	"sort"
-	"strings"
 )

 type contextKey string
@@ -29,6 +27,7 @@ type Lifecycle struct {
 	modules []*Module
 	opts    LifecycleOpts

+	setupOrder      []*Module
 	setupCount      int
 	setupTracker    map[string]int
 	teardownCount   int
@@ -38,7 +37,6 @@ type Lifecycle struct {
 // NewLifecycle creates a new Lifecycle instance with a default logger and the
 // given modules. It panics if any module has a duplicate name.
 func NewLifecycle(modules ...*Module) *Lifecycle {
-	// Ensure modules are unique
 	unique := make(map[string]bool)
 	for _, mod := range modules {
 		if _, exists := unique[mod.name]; exists {
@@ -96,17 +94,18 @@ func (app *Lifecycle) Logger() *slog.Logger {
 	return app.opts.Logger
 }

-// Setup initializes all modules in the order they were defined and checks
-// for dependencies. It returns an error if any module fails to initialize or
-// if dependencies are not satisfied. Lifecycle.Teardown should always be run at the end
-// of the application lifecycle to ensure all resources are cleaned up properly.
+// Setup initializes all registered modules, resolving dependencies via autoload
+// when enabled. Modules run setup in dependency order; among independent modules,
+// registration order is preserved. Teardown runs in reverse setup order.
 func (app *Lifecycle) Setup() error {
 	if app.setupCount > 0 {
 		return fmt.Errorf("lifecycle already set up, cannot set up again")
 	}

+	setupBefore := len(app.setupOrder)
 	for _, mod := range app.modules {
-		if err := app.setupSingle(nil, mod); err != nil {
+		if err := app.setupSingle(nil, mod, nil); err != nil {
+			app.rollbackFrom(setupBefore)
 			return err
 		}
 	}
@@ -117,24 +116,24 @@ func (app *Lifecycle) Setup() error {
 	return nil
 }

-// Teardown runs all module teardown functions in reverse order of setup.
-// Teardown should always be run at the end of the application lifecycle
-// to ensure all resources are cleaned up properly. All module tear down
-// errors are returned as a single error (non-blocking).
+// Teardown runs teardown for all set-up modules in reverse setup order.
+// All module teardown errors are joined and returned (non-blocking).
 func (app *Lifecycle) Teardown() error {
 	if app.teardownCount > 0 {
 		return fmt.Errorf("lifecycle already torn down, cannot tear down again")
 	}

 	var err error
-	for i := len(app.modules) - 1; i >= 0; i-- {
-		if singleErr := app.teardownSingle(app.modules[i]); singleErr != nil {
+	var failureCount int
+	for i := len(app.setupOrder) - 1; i >= 0; i-- {
+		if singleErr := app.teardownSingle(app.setupOrder[i]); singleErr != nil {
 			err = errors.Join(err, singleErr)
+			failureCount++
 		}
 	}

 	if err != nil {
-		app.Logger().Error("Error tearing down modules", "failures", app.setupCount-app.teardownCount, "error", err)
+		app.Logger().Error("Error tearing down modules", "failures", failureCount, "error", err)
 		return err
 	}

@@ -143,183 +142,3 @@ func (app *Lifecycle) Teardown() error {

 	return nil
 }
-
-// Require adds module(s) to the lifecycle and immediately runs any setup
-// functions. Relevant when a module is not part of the main application
-// but may still be conditionally necessary. Any modules that are already
-// set up are ignored.
-func (app *Lifecycle) Require(modules ...*Module) error {
-	return app.require(nil, false, modules...)
-}
-
-// RequireUnique is the same as Require, but it returns an error if any requested
-// module is already set up--rather than ignoring it.
-func (app *Lifecycle) RequireUnique(modules ...*Module) error {
-	return app.require(nil, true, modules...)
-}
-
-// RequireL adds module(s) to the lifecycle with a specific logger and
-// immediately runs any setup functions. See Require for more details.
-// This variation is useful when you need to set up modules with a non-
-// default logger.
-func (app *Lifecycle) RequireL(logger *slog.Logger, modules ...*Module) error {
-	if logger == nil {
-		return fmt.Errorf("logger cannot be nil")
-	}
-	return app.require(logger, false, modules...)
-}
-
-// RequireUniqueL is the same as RequireL, but it returns an error if any requested
-// module is already set up--rather than ignoring it.
-func (app *Lifecycle) RequireUniqueL(logger *slog.Logger, modules ...*Module) error {
-	if logger == nil {
-		return fmt.Errorf("logger cannot be nil")
-	}
-	return app.require(logger, true, modules...)
-}
-
-// require is a helper function that attempts to add module(s) to the lifecycle
-// and immediately run any setup functions.
-func (app *Lifecycle) require(logger *slog.Logger, unique bool, modules ...*Module) error {
-	if len(modules) == 0 {
-		return fmt.Errorf("no modules to require")
-	}
-
-	for i, mod := range modules {
-		if mod == nil {
-			return fmt.Errorf("module %d is nil", i)
-		}
-
-		// Check if the module has already been set up
-		if _, ok := app.setupTracker[mod.name]; ok {
-			if unique {
-				return fmt.Errorf("module %s is already set up, cannot require again", mod)
-			}
-
-			app.Logger().Warn("module already set up, ignoring", "module", mod)
-
-			// Mark duplicate module as loaded
-			mod.loaded = true
-			mod.lifecycle = app
-			mod.logger = logger
-
-			continue
-		}
-
-		// Add the module to the lifecycle
-		app.modules = append(app.modules, mod)
-
-		// Run the setup function for the module
-		if err := app.setupSingle(logger, mod); err != nil {
-			return fmt.Errorf("error setting up required module %s: %w", mod, err)
-		}
-	}
-
-	app.Logger().Info("New modules initialized", "all", mapToString(app.setupTracker))
-	return nil
-}
-
-// setupSingle is a helper function to set up a single module. Returns an error
-// if the module cannot be set up or if dependencies are not satisfied.
-func (app *Lifecycle) setupSingle(logger *slog.Logger, mod *Module) error {
-	if mod == nil {
-		return fmt.Errorf("module is nil")
-	}
-
-	// Set the parent lifecycle and logger override
-	mod.lifecycle = app
-	mod.logger = logger
-
-	// Check if all dependencies are satisfied
-	for _, dep := range mod.depends {
-		if _, ok := app.setupTracker[dep]; !ok {
-			if app.opts.DisableAutoload {
-				return fmt.Errorf("dependency %s not satisfied for '%s'", dep, mod)
-			} else {
-				// Attempt to set up the dependency
-				depmod, err := app.getModuleByName(dep)
-				if err != nil {
-					return fmt.Errorf("error getting dependency '%s' for %s: %w", dep, mod, err)
-				}
-
-				if err := app.setupSingle(logger, depmod); err != nil {
-					return fmt.Errorf("error setting up dependency %s for %s: %w", depmod, mod, err)
-				}
-			}
-		}
-	}
-
-	if mod.setup != nil {
-		// Run the setup function for the module
-		if err := mod.setup(mod); err != nil {
-			return fmt.Errorf("error initializing %s: %w", mod, err)
-		}
-	}
-
-	// Mark this module as setup
-	app.setupTracker[mod.name] = app.setupCount
-	app.setupCount++
-	mod.loaded = true
-	return nil
-}
-
-// teardownSingle is a helper function to tear down a single module. Returns
-// an error if anything goes wrong.
-func (app *Lifecycle) teardownSingle(mod *Module) error {
-	if mod == nil {
-		return fmt.Errorf("module is nil")
-	}
-
-	// Check if the module was set up
-	if _, ok := app.setupTracker[mod.name]; !ok {
-		return fmt.Errorf("module %s is not set up, cannot tear down", mod)
-	}
-
-	// Run the teardown function for the module
-	if mod.teardown != nil {
-		if err := mod.teardown(mod); err != nil {
-			return fmt.Errorf("error tearing down %s: %w", mod, err)
-		}
-	}
-
-	// Mark this module as torn down
-	app.teardownTracker[mod.name] = app.teardownCount
-	app.teardownCount++
-	mod.loaded = false
-	return nil
-}
-
-// getModuleByName retrieves a module by its name from the lifecycle.
-func (app *Lifecycle) getModuleByName(name string) (*Module, error) {
-	for _, mod := range app.modules {
-		if mod.name == name {
-			return mod, nil
-		}
-	}
-	return nil, ErrModuleNotFound
-}
-
-// mapToString converts a map to an ordered, opinionated string representation.
-func mapToString(m map[string]int) string {
-	if len(m) == 0 {
-		return "[]"
-	}
-
-	// Sort the map by value
-	values := make([]int, 0, len(m))
-	reverseMap := make(map[int]string, len(m))
-	for k, v := range m {
-		values = append(values, v)
-		reverseMap[v] = k
-	}
-	sort.Ints(values)
-
-	result := make([]string, 0, len(m))
-	for _, v := range values {
-		if name, ok := reverseMap[v]; ok {
-			result = append(result, fmt.Sprintf("'%s'", name))
-		}
-	}
-
-	return "[" + strings.Join(result, " ") + "]"
-}
@@ -0,0 +1,81 @@
+package app_test
+
+import (
+	"fmt"
+	"testing"
+
+	"gitea.auvem.com/go-toolkit/app"
+	"github.com/stretchr/testify/assert"
+)
+
+func TestSetupTeardownIntegration(t *testing.T) {
+	var order []string
+	modA := app.NewModule("a", app.ModuleOpts{
+		Setup:    func(m *app.Module) error { order = append(order, "setup:a"); return nil },
+		Teardown: func(m *app.Module) error { order = append(order, "teardown:a"); return nil },
+	})
+	modB := app.NewModule("b", app.ModuleOpts{
+		Setup:    func(m *app.Module) error { order = append(order, "setup:b"); return nil },
+		Teardown: func(m *app.Module) error { order = append(order, "teardown:b"); return nil },
+		Depends:  []string{"a"},
+	})
+
+	lc := app.NewLifecycle(modB, modA)
+	assert.NoError(t, lc.Setup())
+	assert.Equal(t, []string{"setup:a", "setup:b"}, order)
+
+	order = nil
+	assert.NoError(t, lc.Teardown())
+	assert.Equal(t, []string{"teardown:b", "teardown:a"}, order)
+}
+
+func TestSetupNoDoubleSetupWithAutoload(t *testing.T) {
+	var count int
+	modA := app.NewModule("a", app.ModuleOpts{
+		Setup: func(m *app.Module) error { count++; return nil },
+	})
+	modB := app.NewModule("b", app.ModuleOpts{
+		Setup:   func(m *app.Module) error { count++; return nil },
+		Depends: []string{"a"},
+	})
+
+	lc := app.NewLifecycle(modB, modA)
+	assert.NoError(t, lc.Setup())
+	assert.Equal(t, 2, count)
+}
+
+func TestSetupPartialFailureRollback(t *testing.T) {
+	var tornDown bool
+	modA := app.NewModule("a", app.ModuleOpts{
+		Setup:    func(m *app.Module) error { return nil },
+		Teardown: func(m *app.Module) error { tornDown = true; return nil },
+	})
+	modB := app.NewModule("b", app.ModuleOpts{
+		Setup: func(m *app.Module) error { return fmt.Errorf("fail b") },
+	})
+
+	lc := app.NewLifecycle(modA, modB)
+	err := lc.Setup()
+	assert.Error(t, err)
+	assert.True(t, tornDown)
+	assert.False(t, modA.Loaded())
+}
+
+func TestSetupCircularDependency(t *testing.T) {
+	modA := app.NewModule("a", app.ModuleOpts{Depends: []string{"b"}})
+	modB := app.NewModule("b", app.ModuleOpts{Depends: []string{"a"}})
+	lc := app.NewLifecycle(modA, modB)
+	err := lc.Setup()
+	assert.Error(t, err)
+	assert.Contains(t, err.Error(), "circular dependency")
+}
+
+func TestGetModule(t *testing.T) {
+	mod := app.NewModule("db", app.ModuleOpts{})
+	lc := app.NewLifecycle(mod)
+	got, err := lc.GetModule("db")
+	assert.NoError(t, err)
+	assert.Equal(t, mod, got)
+	_, err = lc.GetModule("missing")
+	assert.Error(t, err)
+}
@@ -0,0 +1,170 @@
+package app
+
+import (
+	"fmt"
+	"log/slog"
+	"sort"
+	"strings"
+)
+
+func (app *Lifecycle) require(opts RequireOpts, modules ...*Module) error {
+	if len(modules) == 0 {
+		return fmt.Errorf("no modules to require")
+	}
+
+	if opts.Logger != nil && opts.Unique {
+		// unique with custom logger is valid
+	}
+	if opts.Logger == nil && opts.Unique {
+		// valid
+	}
+
+	setupBefore := len(app.setupOrder)
+
+	for i, mod := range modules {
+		if mod == nil {
+			app.rollbackFrom(setupBefore)
+			return fmt.Errorf("module %d is nil", i)
+		}
+
+		if _, ok := app.setupTracker[mod.name]; ok {
+			if opts.Unique {
+				app.rollbackFrom(setupBefore)
+				return fmt.Errorf("module %s is already set up, cannot require again", mod)
+			}
+
+			app.Logger().Warn("module already set up, ignoring", "module", mod)
+			mod.loaded = true
+			mod.lifecycle = app
+			mod.logger = opts.Logger
+			continue
+		}
+
+		app.modules = append(app.modules, mod)
+
+		if err := app.setupSingle(opts.Logger, mod, nil); err != nil {
+			app.rollbackFrom(setupBefore)
+			return fmt.Errorf("error setting up required module %s: %w", mod, err)
+		}
+	}
+
+	app.Logger().Info("New modules initialized", "all", mapToString(app.setupTracker))
+	return nil
+}
+
+func (app *Lifecycle) setupSingle(logger *slog.Logger, mod *Module, visiting map[string]bool) error {
+	if mod == nil {
+		return fmt.Errorf("module is nil")
+	}
+
+	if _, ok := app.setupTracker[mod.name]; ok {
+		return nil
+	}
+
+	if visiting == nil {
+		visiting = make(map[string]bool)
+	}
+	if visiting[mod.name] {
+		return fmt.Errorf("circular dependency detected involving %s", mod)
+	}
+	visiting[mod.name] = true
+	defer delete(visiting, mod.name)
+
+	mod.lifecycle = app
+	mod.logger = logger
+
+	for _, dep := range mod.depends {
+		if _, ok := app.setupTracker[dep]; !ok {
+			if app.opts.DisableAutoload {
+				return fmt.Errorf("dependency %s not satisfied for '%s'", dep, mod)
+			}
+
+			depmod, err := app.getModuleByName(dep)
+			if err != nil {
+				return fmt.Errorf("error getting dependency '%s' for %s: %w", dep, mod, err)
+			}
+
+			if err := app.setupSingle(logger, depmod, visiting); err != nil {
+				return fmt.Errorf("error setting up dependency %s for %s: %w", depmod, mod, err)
+			}
+		}
+	}
+
+	if mod.setup != nil {
+		if err := mod.setup(mod); err != nil {
+			return fmt.Errorf("error initializing %s: %w", mod, err)
+		}
+	}
+
+	app.setupTracker[mod.name] = app.setupCount
+	app.setupOrder = append(app.setupOrder, mod)
+	app.setupCount++
+	mod.loaded = true
+	return nil
+}
+
+func (app *Lifecycle) teardownSingle(mod *Module) error {
+	if mod == nil {
+		return fmt.Errorf("module is nil")
+	}
+
+	if _, ok := app.setupTracker[mod.name]; !ok {
+		return fmt.Errorf("module %s is not set up, cannot tear down", mod)
+	}
+
+	if mod.teardown != nil {
+		if err := mod.teardown(mod); err != nil {
+			return fmt.Errorf("error tearing down %s: %w", mod, err)
+		}
+	}
+
+	app.teardownTracker[mod.name] = app.teardownCount
+	app.teardownCount++
+	mod.loaded = false
+	return nil
+}
+
+func (app *Lifecycle) rollbackFrom(startIndex int) {
+	for i := len(app.setupOrder) - 1; i >= startIndex; i-- {
+		mod := app.setupOrder[i]
+		if mod.teardown != nil {
+			_ = mod.teardown(mod)
+		}
+		delete(app.setupTracker, mod.name)
+		mod.loaded = false
+	}
+	app.setupOrder = app.setupOrder[:startIndex]
+	app.setupCount = startIndex
+}
+
+func (app *Lifecycle) getModuleByName(name string) (*Module, error) {
+	for _, mod := range app.modules {
+		if mod.name == name {
+			return mod, nil
+		}
+	}
+	return nil, ErrModuleNotFound
+}
+
+func mapToString(m map[string]int) string {
+	if len(m) == 0 {
+		return "[]"
+	}
+
+	values := make([]int, 0, len(m))
+	reverseMap := make(map[int]string, len(m))
+	for k, v := range m {
+		values = append(values, v)
+		reverseMap[v] = k
+	}
+	sort.Ints(values)
+
+	result := make([]string, 0, len(m))
+	for _, v := range values {
+		if name, ok := reverseMap[v]; ok {
+			result = append(result, fmt.Sprintf("'%s'", name))
+		}
+	}
+
+	return "[" + strings.Join(result, " ") + "]"
+}
@@ -246,10 +246,16 @@ func TestLifecycle_Teardown(t *testing.T) {

 			lc := NewLifecycle(tc.modules...)

-			// Fake setup for all modules
-			for _, mod := range tc.modules {
-				mod.loaded = true             // Mark as loaded
-				lc.setupTracker[mod.name] = 0 // Mark as set up
+			if len(tc.modules) > 0 {
+				setupBefore := len(lc.setupOrder)
+				for i, mod := range tc.modules {
+					lc.setupOrder = append(lc.setupOrder, mod)
+					lc.setupTracker[mod.name] = i
+					mod.loaded = true
+					mod.lifecycle = lc
+				}
+				lc.setupCount = len(lc.setupOrder)
+				_ = setupBefore
 			}

 			err := lc.Teardown()
@@ -283,6 +289,8 @@ func TestLifecycle_Teardown(t *testing.T) {
 		// Fake setup for the module
 		lc.modules[0].loaded = true
 		lc.setupTracker[lc.modules[0].name] = 0
+		lc.setupOrder = []*Module{lc.modules[0]}
+		lc.setupCount = 1

 		err := lc.Teardown()
 		assert.NoError(err, "expected first Teardown to succeed")
@@ -418,7 +426,7 @@ func TestLifecycle_require(t *testing.T) {
 			assert := assert.New(t)

 			lc := NewLifecycle()
-			err := lc.require(tc.logger, tc.unique, tc.modules...)
+			err := lc.require(RequireOpts{Logger: tc.logger, Unique: tc.unique}, tc.modules...)

 			if tc.expectedErr == "" {
 				assert.NoError(err, "expected require to succeed")
@@ -550,7 +558,7 @@ func TestLifecycle_setupSingle(t *testing.T) {
 				lc = NewLifecycle(tc.modules...)
 			}

-			err := lc.setupSingle(l, tc.targetModule)
+			err := lc.setupSingle(l, tc.targetModule, nil)

 			if tc.expectedErr == "" {
 				assert.NoError(err, "expected no error from setupSingle")
@@ -616,12 +624,17 @@ func TestLifecycle_teardownSingle(t *testing.T) {

 			lc := NewLifecycle()

-			// Fake setup for all modules
 			var setupCount int
-			for _, mod := range tc.modules {
-				lc.setupTracker[mod] = setupCount
+			for _, modName := range tc.modules {
+				lc.setupTracker[modName] = setupCount
+				for _, m := range lc.modules {
+					if m.name == modName {
+						lc.setupOrder = append(lc.setupOrder, m)
+					}
+				}
 				setupCount++
 			}
+			lc.setupCount = setupCount

 			err := lc.teardownSingle(tc.targetModule)

@@ -1,25 +1,14 @@
 package app

 import (
-	"errors"
 	"fmt"
 	"log/slog"
 	"strings"
 )

-// ErrModuleNotFound is returned when a module is not found in the lifecycle.
-var ErrModuleNotFound = errors.New("module not found")
-
 // ModuleFn is a function type for module setup and teardown functions.
 type ModuleFn func(*Module) error

-// GenericModule is an interface that allows modules to be extended with custom
-// functionality, as the module can return a pointer to the underlying Module.
-type GenericModule interface {
-	// Module returns the underlying Module instance.
-	Module() *Module
-}
-
 // Module represents a sub-system of the application, with its setup and
 // teardown functions and dependencies.
 type Module struct {
@@ -60,7 +49,8 @@ func (s *Module) Lifecycle() *Lifecycle {
 }

 // Logger returns the logger for the module. Uses the lifecycle's logger unless
-// a specific logger has been set during module load.
+// a specific logger has been set during module load. Panics if the module is
+// not associated with a lifecycle and no override logger was set.
 func (s *Module) Logger() *slog.Logger {
 	if s.logger != nil {
 		return s.logger
@@ -0,0 +1,61 @@
+package app
+
+import (
+	"fmt"
+	"log/slog"
+)
+
+// RequireOpts configures [Lifecycle.RequireWithOpts] behavior.
+type RequireOpts struct {
+	// Logger overrides the lifecycle logger for the required modules. If nil,
+	// the lifecycle logger is used.
+	Logger *slog.Logger
+
+	// Unique, when true, returns an error if any requested module name is
+	// already set up instead of ignoring duplicate instances.
+	Unique bool
+}
+
+// Require adds module(s) to the lifecycle and immediately runs setup.
+// Modules that are already set up (by name) are ignored.
+func (app *Lifecycle) Require(modules ...*Module) error {
+	return app.require(RequireOpts{}, modules...)
+}
+
+// RequireWithOpts is like [Lifecycle.Require] with additional options.
+func (app *Lifecycle) RequireWithOpts(opts RequireOpts, modules ...*Module) error {
+	return app.require(opts, modules...)
+}
+
+// GetModule returns a registered module by name.
+func (app *Lifecycle) GetModule(name string) (*Module, error) {
+	mod, err := app.getModuleByName(name)
+	if err != nil {
+		return nil, fmt.Errorf("get module %q: %w", name, err)
+	}
+	return mod, nil
+}
+
+// RequireL loads modules using a specific logger. Deprecated: use
+// RequireWithOpts(RequireOpts{Logger: logger}, modules...).
+func (app *Lifecycle) RequireL(logger *slog.Logger, modules ...*Module) error {
+	if logger == nil {
+		return fmt.Errorf("logger cannot be nil")
+	}
+	return app.require(RequireOpts{Logger: logger}, modules...)
+}
+
+// RequireUnique loads modules and errors if any name is already set up.
+// Deprecated: use RequireWithOpts(RequireOpts{Unique: true}, modules...).
+func (app *Lifecycle) RequireUnique(modules ...*Module) error {
+	return app.require(RequireOpts{Unique: true}, modules...)
+}
+
+// RequireUniqueL combines RequireL and RequireUnique.
+// Deprecated: use RequireWithOpts(RequireOpts{Logger: logger, Unique: true}, modules...).
+func (app *Lifecycle) RequireUniqueL(logger *slog.Logger, modules ...*Module) error {
+	if logger == nil {
+		return fmt.Errorf("logger cannot be nil")
+	}
+	return app.require(RequireOpts{Logger: logger, Unique: true}, modules...)
+}