{"id":48470167,"url":"https://github.com/origadmin/kore","last_synced_at":"2026-04-07T06:03:01.298Z","repository":{"id":343187981,"uuid":"1176633534","full_name":"origadmin/kore","owner":"origadmin","description":null,"archived":false,"fork":false,"pushed_at":"2026-03-09T08:44:33.000Z","size":42,"stargazers_count":0,"open_issues_count":5,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-09T12:47:20.107Z","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/origadmin.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":".github/SECURITY.md","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},"funding":{"github":["origadmin"],"open_collective":"origadmin","ko_fi":"origadmin","patreon":"origadmin","custom":["https://origadmin.org/donate"],"github_followers":true}},"created_at":"2026-03-09T08:08:37.000Z","updated_at":"2026-03-09T08:44:36.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/origadmin/kore","commit_stats":null,"previous_names":["origadmin/kore"],"tags_count":null,"template":false,"template_full_name":"origadmin/go-project-template","purl":"pkg:github/origadmin/kore","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/origadmin%2Fkore","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/origadmin%2Fkore/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/origadmin%2Fkore/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/origadmin%2Fkore/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/origadmin","download_url":"https://codeload.github.com/origadmin/kore/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/origadmin%2Fkore/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31501903,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-07T03:10:19.677Z","status":"ssl_error","status_checked_at":"2026-04-07T03:10:13.982Z","response_time":105,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: 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":"2026-04-07T06:03:01.015Z","updated_at":"2026-04-07T06:03:01.272Z","avatar_url":"https://github.com/origadmin.png","language":"Go","funding_links":["https://github.com/sponsors/origadmin","https://opencollective.com/origadmin","https://ko-fi.com/origadmin","https://patreon.com/origadmin","https://origadmin.org/donate",true],"categories":[],"sub_categories":[],"readme":"# Kore\n\nKore is a lightweight, clean, and highly extensible Dependency Injection (DI) framework for Go. It focuses on the clean separation of **Discovery** (locating dependencies) and **Identity** (component metadata), providing a predictable and type-safe way to manage complex component graphs.\n\n## Key Features\n\n- **Clean Architecture**: Separates navigation (`Locator`) from instantiation context (`Handle`).\n- **Discovery vs Identity**: Components can find others via locators without leaking their own internal state.\n- **Multidimensional Isolation**: Support for Categories, Scopes, and Capability Tags.\n- **Lazy Initialization**: Components are instantiated only when first requested.\n- **Circular Dependency Detection**: Built-in safety against recursive dependency chains.\n- **Zero External Dependencies**: Pure Go implementation.\n\n## Installation\n\n```bash\ngo get github.com/origadmin/kore\n```\n\n## Quick Start\n\n### 1. Define Your Components\n\n```go\ntype Database struct {\n    DSN string\n}\n\ntype Logger struct {\n    Prefix string\n}\n\ntype Service struct {\n    db     *Database\n    logger *Logger\n}\n```\n\n### 2. Register Providers\n\n```go\nimport \"github.com/origadmin/kore\"\n\nreg := kore.New()\n\n// Register a Logger\nreg.Register(\"logger\", func(ctx context.Context, h kore.Handle) (any, error) {\n    return \u0026Logger{Prefix: \"[APP]\"}, nil\n})\n\n// Register a Database with dependency on Logger\nreg.Register(\"database\", func(ctx context.Context, h kore.Handle) (any, error) {\n    // Find Logger using Locator\n    logger, _ := kore.GetDefault[*Logger](ctx, h.Locator().In(\"logger\"))\n    return \u0026Database{DSN: \"localhost:5432\"}, nil\n})\n```\n\n### 3. Load and Use\n\n```go\nctx := context.Background()\nreg.Load(ctx, nil) // Load configurations\n\n// Retrieve the database\ndb, err := kore.GetDefault[*Database](ctx, reg.In(\"database\"))\n```\n\n## Core Concepts: The Multi-dimensional DI\n\nKore organizes components into a three-dimensional coordinate system, allowing for precise control over component visibility and lifecycle.\n\n### 1. Horizontal Dimension: Categories\nCategories define **what** a component is (e.g., `database`, `cache`, `logger`). \n- **Purpose**: Grouping identical types of infrastructure.\n- **Usage**: You can iterate over all components within a category or retrieve a specific one by name.\n\n### 2. Vertical Dimension: Scopes\nScopes define **where** a component exists (e.g., `_global`, `server`, `client`).\n- **Hierarchy**: Components in a specific scope are isolated from others.\n- **Fallback**: Kore supports intelligent fallback mechanisms, allowing local scopes to inherit or override global defaults.\n\n### 3. Specialization: Capability Tags\nTags define **which variant** or **what capability** a provider offers (e.g., `gateway`, `mock`, `production`).\n- **Isolation**: A `Locator` created with the `gateway` tag can only \"see\" providers registered with that same tag (or common providers).\n- **Perspective**: This allows you to create different \"perspectives\" of the same dependency graph for different parts of your application.\n\n## Dual-Axis Isolation Model\n\nKore provides a robust isolation model that separates components along two orthogonal axes: **Vertical (Contextual)** and **Horizontal (Functional)**.\n\n### Vertical Isolation: S-Single (Scope-based)\nVertical isolation is achieved through **Scopes**, partitioning components based on their **Runtime Environment**.\n- **Mechanism**: Each Scope (e.g., `_global`, `server`, `client`) is a physically distinct instance container.\n- **S-Single**: For a given `(Category, Scope, Name)`, there is exactly one instance. This ensures that a component in the `server` scope cannot accidentally reference or interfere with a component in the `client` scope, even if they share the same name.\n- **Use Case**: Environment-specific overrides and lifecycle management.\n\n### Horizontal Isolation: T-Multi (Tag-based)\nHorizontal isolation is achieved through **Tags**, partitioning components based on their **Responsibility and Capability**.\n- **Mechanism**: Providers register themselves with specific Capability Tags. When you enter a category via `reg.In(cat, WithInTags(\"gateway\"))`, you create a **Perspective**.\n- **T-Multi**: A single Category can house multiple providers for the same name, but only those matching the requested \"Perspective Tags\" (the Capability Set) are visible.\n- **Responsibility Filtering**: This allows you to hide internal-only components from public-facing locators or switch between different implementation variants (e.g., `production` vs `mock`) without changing the component's name or code.\n- **Inheritance**: \"Common\" providers (those with no tags) are visible across all horizontal perspectives, acting as a shared foundation.\n\n## Native Configuration Binding\n\nUnlike other DI frameworks that treat configuration as an afterthought, Kore is a **Config-First** engine.\n- **The Resolver**: Every category can have a `Resolver` that maps raw input (YAML, JSON, or Map) to structured `ModuleConfig`.\n- **Automatic Instantiation**: Once a config entry is mapped (e.g., a database config named `mysql`), Kore automatically knows how to use the registered `Provider` to turn that config into a live object.\n- **Active Instance**: Supports an `Active` flag in configuration to designate which named instance should be the `_default` for that category.\n\n## Comparison with Mainstream Frameworks\n\n| Feature | Kore | Google Wire | Uber Fx / Dig |\n| :--- | :--- | :--- | :--- |\n| **Mechanism** | Run-time (Provider-based) | Compile-time (Code Gen) | Run-time (Reflection) |\n| **Dependency Resolution** | Explicit via `Locator` | Implicit via Type Matching | Implicit via Type Matching |\n| **Identity vs Search** | **Absolute Separation** | None (Single Graph) | None (Single Graph) |\n| **Multi-instance Support** | Native (Category/Name/Tag) | Complex (using tags/alias) | Complex (using groups/names) |\n| **Configuration Binding** | Built-in `Resolver` | Manual | Manual / External |\n| **Error Detection** | First-use / Initialization | Compile-time | App Start-up |\n\n## Why Kore? The Competitive Edge\n\nKore is not just another object wirer; it is a **Structured Discovery Engine**. Compared to mainstream frameworks like Google Wire or Uber Fx, Kore provides a multi-dimensional approach to dependency management.\n\n### Feature Comparison\n\n| Feature | Kore | Google Wire | Uber Fx / Dig |\n| :--- | :--- | :--- | :--- |\n| **Vertical Isolation (S-Single)** | **Native (Scopes)**: Physical isolation of instances by environment. | **None**: Single global graph; naming conflicts are manual. | **Weak**: Limited lifecycle scoping; lacks multi-layer isolation. |\n| **Horizontal Filtering (T-Multi)** | **Native (Tags)**: Logical filtering of responsibilities via Perspectives. | **None**: Relies on static types or manual struct naming. | **Complex**: Requires annotations or groups; hard to maintain. |\n| **Config Binding (Config-First)** | **Deeply Integrated**: Automatic mapping from raw config to instances. | **None**: Pure wiring; config handling is entirely external. | **None**: Requires external libraries; mapping is scattered. |\n| **Separation (Identity/Locator)** | **Absolute (Plan A)**: Identity (Handle) is isolated from Discovery. | **Mixed**: Components have excessive visibility into the graph. | **Obscure**: Reflection leads to implicit container coupling. |\n| **Multi-instance Management** | **Seamless**: Native support for N-instances via Category/Name/Tag. | **Verbose**: Requires unique types/providers for each instance. | **Heavy**: Complexity grows exponentially with instance counts. |\n\n### The Kore Advantage\n\n#### 1. Precision via S-Single \u0026 T-Multi\n- **Vertical (S-Single)**: Ensures that your `server` database and `monitoring` database never touch, even if they share the same provider. \n- **Horizontal (T-Multi)**: Allows you to define implementation variants (e.g., `public-api` vs `internal-tool`) in the same category and switch between them simply by changing the locator's perspective.\n\n#### 2. Native Configuration-to-Instance Pipeline\nKore bridges the gap between static code and dynamic configuration. By defining a `Resolver`, you transform your DI from a static object graph into a dynamic engine that responds to your environment settings.\n\n#### 3. Predictability over Magic\nBy enforcing an explicit `h.Locator().Get()` pattern, Kore removes the \"magic\" of reflection and the \"clutter\" of code generation. You gain absolute traceability of every dependency in your system.\n\n## Architecture: Plan A (Composition)\n\nKore implements the **Plan A** composition pattern, where the `Handle` (Identity) provided during instantiation does not inherit from the `Locator` (Navigation). Instead, it provides a `Locator()` method. This ensures that:\n\n1.  **Identity is Local**: A component's name and config are only accessible via its own `Handle`.\n2.  **Navigation is Explicit**: To find another component, you must explicitly use a `Locator`.\n3.  **Automatic State Stripping**: Calling `In()` on a locator returns a fresh locator without any residual identity from the caller, preventing accidental state leakage.\n\n## License\n\nKore is released under the MIT License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Forigadmin%2Fkore","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Forigadmin%2Fkore","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Forigadmin%2Fkore/lists"}