{"id":34907661,"url":"https://github.com/smarty/injector","last_synced_at":"2026-05-23T06:03:21.366Z","repository":{"id":328021166,"uuid":"1113963734","full_name":"smarty/injector","owner":"smarty","description":"Richly featured dependency injector for Golang. Use with caution: any dependency injector comes with the cost of higher abstraction and separates setup from usage on interface boundaries.","archived":false,"fork":false,"pushed_at":"2025-12-15T20:56:27.000Z","size":18,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-12-27T20:37:13.007Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/smarty.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-10T17:53:58.000Z","updated_at":"2025-12-15T20:56:04.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/smarty/injector","commit_stats":null,"previous_names":["smarty/injector"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/smarty/injector","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smarty%2Finjector","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smarty%2Finjector/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smarty%2Finjector/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smarty%2Finjector/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/smarty","download_url":"https://codeload.github.com/smarty/injector/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smarty%2Finjector/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33384606,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-23T04:15:53.637Z","status":"ssl_error","status_checked_at":"2026-05-23T04:15:53.242Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-12-26T10:31:28.876Z","updated_at":"2026-05-23T06:03:21.360Z","avatar_url":"https://github.com/smarty.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Injector\n\nA lightweight, high-performance dependency injection library for Go.\n\n## Overview\n\n`injector` is a compile-time-safe dependency injection container designed for Go applications that need reliable, fast dependency resolution at startup. It provides multiple caching strategies to optimize for different access patterns and supports flexible lifecycle management for registered types.\n\n## Features\n\n- **Type-Safe API**: Generic functions for compile-time type safety\n- **Multiple Lifecycle Options**: Singleton, Scope, and Transient lifecycles\n- **Error Handling**: Constructors can optionally return an error value\n- **Flexible Registration**: Register by type with custom constructors\n- **Named Lookups**: Retrieve dependencies by type name\n- **Caching Strategies**: Choose between Map, BubbleList, and PriorityList caches\n- **Dependency Verification**: Validate your dependency graph before runtime\n- **Scoped Instances**: Create isolated scopes for request-specific dependencies\n- **Function Injection**: Automatically inject dependencies into functions\n\n## Installation\n\n```bash\ngo get github.com/smarty/injector\n```\n\n## Quick Start\n\n### Basic Usage\n\n```go\npackage main\n\nimport (\n\t\"github.com/smarty/injector\"\n)\n\ntype Database interface {\n\tQuery(sql string) ([]string, error)\n}\n\ntype MySQLDB struct{}\n\nfunc (d *MySQLDB) Query(sql string) ([]string, error) {\n\t// Implementation\n\treturn []string{}, nil\n}\n\nfunc main() {\n\tdi := injector.New()\n\n\t// Register a singleton instance\n\tinjector.RegisterSingleton[Database](di, func() Database {\n\t\treturn \u0026MySQLDB{}\n\t})\n\n\t// Verify the dependency graph\n\tif err := injector.Verify(di); err != nil {\n\t\tpanic(err)\n\t}\n\n\t// Retrieve the database\n\tdb, err := injector.Get[Database](di)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\n\t// Use the database\n\t_ = db\n}\n```\n\n### Lifecycle Options\n\n#### Singleton\nInstantiated once and reused across the entire application lifetime.\n\n```go\ninjector.RegisterSingleton[MyType](di, constructor)\n```\n\n#### Scope\nInstantiated once per `Get()` call, allowing for request-scoped or operation-scoped instances.\n\n```go\ninjector.RegisterScope[MyType](di, constructor)\n```\n\n#### Transient\nInstantiated every time it's requested as a dependency.\n\n```go\ninjector.RegisterTransient[MyType](di, constructor)\n```\n\n### Error Handling in Constructors\n\nConstructors can return an error in addition to the instance:\n\n```go\ninjector.RegisterSingletonError[MyType](di, func() (MyType, error) {\n\t// Return instance and error\n\treturn MyType{}, nil\n})\n```\n\n### Function Injection\n\nAutomatically inject dependencies into functions:\n\n```go\nfunc setupDatabase(db Database) error {\n\t// Setup logic\n\treturn nil\n}\n\n// Call the function with injected dependencies\nerr := injector.Call(di, setupDatabase)\n```\n\n### Named Lookups\n\nRegister types that can be retrieved by name:\n\n```go\ndb, err := injector.GetByName(di, \"Database\")\n```\n\n### Caching Strategies\n\nChoose the caching strategy that best fits your access patterns:\n\n```go\n// Map: Good for random access patterns (default)\ndi := injector.New(injector.Map)\n\n// BubbleList: Good for stable access patterns\ndi := injector.New(injector.BubbleList)\n\n// PriorityList: Good for stable but changing access patterns\ndi := injector.New(injector.PriorityList)\n```\n\n## API Reference\n\n### Core Methods\n\n- **`New(cacheStrategy ...CacheStrategy) *Injector`**: Create a new injector instance\n- **`Get[T](di *Injector) (T, error)`**: Retrieve a dependency by type\n- **`GetByName(di *Injector, name string) (any, error)`**: Retrieve a dependency by name\n- **`Call(di *Injector, function any) error`**: Call a function with injected dependencies\n- **`Call1` through `Call4`**: Call functions with specific return value counts\n- **`CallN(di *Injector, function any) ([]any, error)`**: Call a function with any number of returns\n- **`Verify(di *Injector) error`**: Validate the dependency graph\n\n### Registration Methods\n\n- **`RegisterSingleton[T](di *Injector, constructor any) error`**: Register a singleton\n- **`RegisterSingletonError[T](di *Injector, constructor any) error`**: Register a singleton with error handling\n- **`RegisterScope[T](di *Injector, constructor any) error`**: Register a scoped instance\n- **`RegisterScopeError[T](di *Injector, constructor any) error`**: Register a scoped instance with error handling\n- **`RegisterTransient[T](di *Injector, constructor any) error`**: Register a transient instance\n- **`RegisterTransientError[T](di *Injector, constructor any) error`**: Register a transient with error handling\n\n## Error Handling\n\nThe injector provides specific error types for different failure scenarios:\n\n- `ErrorAlreadyRegistered`: A type has already been registered\n- `ErrorBadState`: Injector is in an invalid state for the requested operation\n- `ErrorDependencyLoop`: A circular dependency has been detected\n- `ErrorNotRegistered`: A required dependency has not been registered\n- `ErrorNotStructOrInterface`: A type is not suitable for registration\n- `ErrorVariadicArguments`: A function has a variadic signature\n\n## Performance Considerations\n\n- The injector is optimized for **startup-time usage**. Generating dependencies takes a few microseconds per call.\n- Choose a caching strategy based on your access patterns:\n  - **Map**: Random access, no reordering overhead\n  - **BubbleList**: Stable patterns, benefits from reordering on stable workloads\n  - **PriorityList**: Changing patterns that settle over time\n\n## Testing\n\nThe library includes comprehensive tests covering:\n- Type registration and validation\n- Dependency resolution\n- Circular dependency detection\n- Error handling\n- Performance benchmarks\n\nRun tests with:\n```bash\ngo test ./...\n```\n\nRun benchmarks with:\n```bash\ngo test -bench=. ./...\n```\n\n## Roadmap\n\n### Planned Features\n\n- **Struct Tag Support for Automatic Field Injection** - Allow dependency injection directly into struct fields via tags (e.g., `di:\"inject\"`).\n\n- **Factory Pattern Support** - Register factory functions that can take parameters to create multiple instances with different configurations. Useful for creating variants of the same type based on input parameters.\n\n## License\n\nMIT License - See [LICENSE](LICENSE) for details\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmarty%2Finjector","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsmarty%2Finjector","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmarty%2Finjector/lists"}