Skip to content

Add cookbook with real-world usage patterns #3

@danielstarman

Description

@danielstarman

Summary

Add a cookbook section (either in the README or a separate docs/cookbook.md) showing concrete, copy-pasteable patterns for real-world usage.

Motivation

The current README demonstrates the API with a toy Database -> Repo -> Service example. This is fine for understanding the API, but doesn't show why you'd reach for a DI container instead of just passing arguments manually. A cookbook with realistic examples would lower adoption friction and answer the "why miniject?" question.

Suggested patterns to cover

  • CLI app startup - composition root that wires up config + services, passes to CLI handler
  • Test fixtures - using scope() to override specific dependencies without rebuilding the graph
  • Diamond dependencies - 15+ services where manual wiring gets painful, showing the real value proposition
  • Optional dependencies - Database | None = None pattern for services with optional features
  • Per-context scopes - different configurations for different execution contexts (e.g., batch vs interactive)
  • Factory functions - when to use factories vs auto-wiring vs instances

Also consider

A short "Gotchas" section covering:

  • from __future__ import annotations behavior with get_type_hints
  • Forward reference timing
  • Override scope (keyword overrides apply to the immediate constructor only, not the full graph)
  • Why Annotated[...] is rejected and what to do instead

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions