How evyweb/ioctopus works
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