# evyweb/ioctopus architecture

> Architecture diagram of the GitHub repository evyweb/ioctopus, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/evyweb/ioctopus
- Repository: https://github.com/evyweb/ioctopus

## Overview

##### Project Type and Purpose
- This is an open-source TypeScript library (an IoC container) that provides dependency registration and resolution without external metadata.
- It exposes a public API (`createContainer`, `createModule`, `bind`, `get`, `load`, `unload`, `runInScope`) to let consumers wire up primitives, functions, classes, factories, modules, and manage scopes.

##### File Structure Analysis
- **src/**: core implementation
- container.ts – Container class (holds bindings, modules, resolution logic)
- module.ts – Module class (isolated binding sets)
- types.ts – Type definitions and tokens
- index.ts – Public entry point that re-exports APIs
- **specs/**: automated tests illustrating use-cases (registry, modules, currying, circular detection)
- **assets/**: logo for README
- **.github/** + **vitest.config.mts**: CI and test configuration
- **.changeset/** and **CHANGELOG.md**: versioning

##### Key Insights from README
- Supports six binding strategies: `toValue`, `toFunction`, `toCurry`, `toHigherOrderFunction`, `toFactory`, `toClass`
- Modules can be created and loaded in any order; the last loaded wins (override)
- Scopes: singleton (default), transient, scoped (per execution context)
- Circular dependency detection built into resolution phase

##### Main Components
a. **Public API Layer**
- Input from consumer code: calls to `createContainer`, `createModule` and subsequent `bind`, `load`, `get`, `runInScope`.
b. **Container Manager** (container.ts)
- Maintains:
- Binding Registry (map of token → binding descriptor)
- Module Registry (map of moduleKey → Module instance)
- Instance Cache (per‐scope or singleton)
- Orchestrates resolution, scoping, and module overrides.
c. **Module Manager** (module.ts)
- Isolated binding registry per module
- Exposes same `bind` API but scoped to that module
d. **Resolution Engine**
- Reads binding descriptors, fetches required tokens from Binding Registry
- Delegates to specific **Binding Strategy Handlers**:
- Value Handler
- Function Handler
- Currying Handler
- Higher-order Function Handler
- Factory Handler
- Class Handler
e. **Scope Manager**
- Determines instance lifetime based on binding’s scope parameter (singleton, transient, scoped)
- Manages scoped contexts via `runInScope`
f. **Circular Dependency Detector**
- During resolution, tracks the current resolution path stack
- Throws an error on cycles

##### Relationships and Data Flow
- **Consumer** → (calls) **ContainerManager.createContainer** → returns **Container instance**
- **Consumer** → (calls) **ModuleManager.createModule** → returns **Module instance**
- **Consumer** → (calls) **Container.bind / Module.bind** → populates Binding Registry
- **Consumer** → (calls) **Container.load** → merges Module’s bindings into Container’s registry (overrides existing)
- **Consumer** → (calls) **Container.get(token)** →
- ContainerManager consults ScopeManager →
- ResolutionEngine resolves token →
- CircularDetector tracks path →
- StrategyHandler instantiates/resolves →
- ScopeManager caches or re-creates instance → returns to consumer

##### Architectural Patterns and Principles
- Inversion of Control / Dependency Injection
- Plugin-style modules for extensibility and override
- Strategy pattern for different binding types
- Scoped execution contexts (akin to request scope in web frameworks)
- Fail-fast circular dependency detection

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Top-level consumer
    Consumer["Consumer Code"]:::external

    %% Public API Layer
    PublicAPI["Public API Layer<br/>(createContainer, createModule, bind, get, load, unload, runInScope)"]:::api
    Consumer -->|"calls"| PublicAPI

    %% Core Components
    subgraph "Core Engine"
        direction TB
        ContainerManager["ContainerManager"]:::core
        ModuleManager["ModuleManager"]:::core
        ContainerManager --> BindingRegistry
        ContainerManager --> ModuleRegistryCore
        ContainerManager --> InstanceCache
        ContainerManager --> ResolutionEngine
        ModuleManager --> ModuleRegistry
        ResolutionEngine -->|"uses"| StrategyHandlers
        ResolutionEngine --> CircularDetector
        ResolutionEngine --> ScopeManager
        ScopeManager -.->|"caches instances in"| InstanceCache
    end

    %% Registries and Cache
    BindingRegistry["BindingRegistry"]:::registry
    ModuleRegistryCore["ModuleRegistry (Global)"]:::registry
    ModuleRegistry["ModuleRegistry (Module)"]:::registry
    InstanceCache["InstanceCache"]:::registry

    %% Resolution Engine & Handlers
    ResolutionEngine["Resolution Engine"]:::core

    subgraph "Binding Strategy Handlers" 
        direction TB
        ValueHandler["Value Handler"]:::strategy
        FunctionHandler["Function Handler"]:::strategy
        CurryHandler["Curry Handler"]:::strategy
        HOFHandler["Higher-order Function Handler"]:::strategy
        FactoryHandler["Factory Handler"]:::strategy
        ClassHandler["Class Handler"]:::strategy
    end
    StrategyHandlers --> ValueHandler
    StrategyHandlers --> FunctionHandler
    StrategyHandlers --> CurryHandler
    StrategyHandlers --> HOFHandler
    StrategyHandlers --> FactoryHandler
    StrategyHandlers --> ClassHandler

    %% Scope Manager
    ScopeManager["Scope Manager<br/>(singleton, transient, scoped)"]:::core

    %% Circular Dependency Detector
    CircularDetector["Circular Dependency Detector"]:::error

    %% Module loading flow
    PublicAPI -->|"createContainer"| ContainerManager
    PublicAPI -->|"createModule"| ModuleManager
    PublicAPI -->|"bind / load / get"| ContainerManager

    %% Artifacts and Configurations
    subgraph "Project Artifacts"
        direction TB
        AutomatedTests["Automated Test Suite"]:::docs
        CIWorkflow["CI Workflow Config"]:::docs
        Versioning["Versioning & Changelog"]:::docs
        LogoAsset["Logo Asset"]:::docs
    end

    %% Styles and click events
    classDef external fill:#E0E0E0,stroke:#999,stroke-width:1px
    classDef api fill:#D0E8FF,stroke:#039,stroke-width:1px
    classDef core fill:#DFFFD0,stroke:#383,stroke-width:1px
    classDef registry fill:#FFF4CF,stroke:#A66,stroke-width:1px,stroke-dasharray: 5 5
    classDef strategy fill:#FFE8A8,stroke:#E57A00,stroke-width:1px
    classDef error fill:#FFD0D0,stroke:#D00,stroke-width:1px
    classDef docs fill:#F0F0F0,stroke:#666,stroke-width:1px,stroke-dasharray: 2 2

    %% Click events
    click PublicAPI "https://github.com/evyweb/ioctopus/blob/master/src/index.ts"
    click ContainerManager "https://github.com/evyweb/ioctopus/blob/master/src/container.ts"
    click ModuleManager "https://github.com/evyweb/ioctopus/blob/master/src/module.ts"
    click BindingRegistry "https://github.com/evyweb/ioctopus/blob/master/src/container.ts"
    click ModuleRegistryCore "https://github.com/evyweb/ioctopus/blob/master/src/container.ts"
    click ModuleRegistry "https://github.com/evyweb/ioctopus/blob/master/src/module.ts"
    click InstanceCache "https://github.com/evyweb/ioctopus/blob/master/src/container.ts"
    click ResolutionEngine "https://github.com/evyweb/ioctopus/blob/master/src/container.ts"
    click ValueHandler "https://github.com/evyweb/ioctopus/blob/master/src/container.ts"
    click FunctionHandler "https://github.com/evyweb/ioctopus/blob/master/src/container.ts"
    click CurryHandler "https://github.com/evyweb/ioctopus/blob/master/src/container.ts"
    click HOFHandler "https://github.com/evyweb/ioctopus/blob/master/src/container.ts"
    click FactoryHandler "https://github.com/evyweb/ioctopus/blob/master/src/container.ts"
    click ClassHandler "https://github.com/evyweb/ioctopus/blob/master/src/container.ts"
    click ScopeManager "https://github.com/evyweb/ioctopus/blob/master/src/container.ts"
    click CircularDetector "https://github.com/evyweb/ioctopus/blob/master/src/container.ts"
    click AutomatedTests "https://github.com/evyweb/ioctopus/tree/master/specs/"
    click CIWorkflow "https://github.com/evyweb/ioctopus/blob/master/.github/workflows/main.yml"
    click Versioning "https://github.com/evyweb/ioctopus/tree/master/.changeset/"
    click Versioning "https://github.com/evyweb/ioctopus/blob/master/CHANGELOG.md"
    click LogoAsset "https://github.com/evyweb/ioctopus/tree/master/assets/"
```
