# jeffijoe/awilix architecture

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

- Interactive diagram: https://gitdiagram.com/jeffijoe/awilix
- Repository: https://github.com/jeffijoe/awilix

## Overview

##### Main Components
- The Dependency Injection Container (the core “container” in src/container.ts and the exported API in src/awilix.ts).
- Resolver Modules: These are the interfaces that handle how a module is registered (asClass, asFunction, asValue, and aliasTo) and include the fluent API (methods such as .singleton(), .scoped(), .transient(), and .inject()).
- Lifecycle Manager: This part manages different lifetime strategies (transient, scoped, singleton) as detailed in the README and implemented in files like src/lifetime.ts.
- Injection Mode Manager: Represents the two modes (PROXY and CLASSIC) that govern how dependencies are provided to constructors or functions. This is highlighted in src/injection-mode.ts.
- Auto-Loader Module: The functionality provided by container.loadModules (with its resolver options and naming conventions) that is documented extensively in the README.
- Supporting Utilities: These include files for parsing parameters (src/param-parser.ts), tokenizing functions (src/function-tokenizer.ts), and resolving dependencies (src/resolvers.ts, src/list-modules.ts, src/load-modules.ts).
- Error Handling Components: Such as AwilixResolutionError and AwilixRegistrationError that capture and report configuration or resolution issues.

##### Relationships and Interactions
- The central container is responsible for holding registrations in its “cache” (as seen in src/container.ts) and serves as the hub.
- Modules (classes, functions, or values) are registered via resolver functions (asClass, asFunction, asValue) into the container.
- Upon resolution, the container consults its cache and, based on the lifetime settings, determines if a new instance should be created or an existing one reused.
- Injection modes dictate how the container assembles dependencies, with the PROXY mode using a dynamic proxy to inject resolutions at call time, and CLASSIC reading function signatures (as handled by the relevant utility modules).
- A module loader automatically scans file patterns and applies consistent naming and registration conventions (a key example is found in the auto-loading examples described in the README).
- Local injections or per-module configuration (using the injector function) provide additional control over dependency values for specific modules.
- The disposal mechanism (container.dispose()) uses cached registrations that have disposer functions attached to safely tear down resources.

##### Architectural Patterns and Design Principles
- Separation of concerns is achieved by splitting the container’s tasks into resolution, registration, lifetime management, and error handling.
- Extensibility is built into the auto-loading and local-injection mechanisms, all of which promote a composable design.
- The use of fluent APIs (the chainable functions like .singleton(), .scoped(), etc.) indicates an orientation toward readability and ease of configuration.
- Emphasis on testability is evident from the extensive test folders and examples, ensuring that all resolutions and dependencies can be unit and integration tested.

##### Relevant Technologies and Frameworks
- The project is based on Node.js with strong TypeScript support.
- It leverages modern JavaScript ES features (e.g., Proxy) and testing frameworks (as demonstrated by the “src/__tests__” folder).
- Integration examples use frameworks like Koa (in the examples/koa directory) and demonstrate usage through Babel and TypeScript variants.

## Diagram (Mermaid)

```mermaid
graph TB
  subgraph "Core Library"
    DI["DI Container"]:::core
    API["Awilix API"]:::core
    RES["Resolver Modules"]:::config
    LIFE["Lifecycle Manager"]:::config
    INJ["Injection Mode Manager"]:::config
    LOAD["Module Loader"]:::config
    LIST["Module Lister"]:::config
    subgraph "Supporting Utilities"
      PP["Parameter Parser"]:::utility
      FT["Function Tokenizer"]:::utility
      UT["Utils"]:::utility
    end
    ERR["Error Handling"]:::error
  end
  
  subgraph "Usage Examples"
    KOA["Koa Example"]:::example
    BABEL["Babel Example"]:::example
    TS["TypeScript Example"]:::example
    NODE["Simple Node App"]:::example
  end

  DI -->|"exports"| API
  DI -->|"registers"| RES
  DI -->|"manages"| LIFE
  DI -->|"applies"| INJ
  DI -->|"loads"| LOAD
  DI -->|"lists"| LIST
  DI -->|"uses"| PP
  DI -->|"uses"| FT
  DI -->|"uses"| UT
  DI -->|"handles"| ERR

  KOA -->|"createsScoped"| DI
  BABEL -->|"registers"| DI
  TS -->|"registers"| DI
  NODE -->|"resolves"| DI

  click DI "https://github.com/jeffijoe/awilix/blob/master/src/container.ts"
  click API "https://github.com/jeffijoe/awilix/blob/master/src/awilix.ts"
  click RES "https://github.com/jeffijoe/awilix/blob/master/src/resolvers.ts"
  click LIFE "https://github.com/jeffijoe/awilix/blob/master/src/lifetime.ts"
  click INJ "https://github.com/jeffijoe/awilix/blob/master/src/injection-mode.ts"
  click LOAD "https://github.com/jeffijoe/awilix/blob/master/src/load-modules.ts"
  click LIST "https://github.com/jeffijoe/awilix/blob/master/src/list-modules.ts"
  click PP "https://github.com/jeffijoe/awilix/blob/master/src/param-parser.ts"
  click FT "https://github.com/jeffijoe/awilix/blob/master/src/function-tokenizer.ts"
  click UT "https://github.com/jeffijoe/awilix/blob/master/src/utils.ts"
  click ERR "https://github.com/jeffijoe/awilix/blob/master/src/errors.ts"

  classDef core fill:#ADD8E6,stroke:#000,stroke-width:2px;
  classDef config fill:#FFD700,stroke:#000,stroke-width:2px;
  classDef utility fill:#90EE90,stroke:#000,stroke-width:2px;
  classDef error fill:#FF6347,stroke:#000,stroke-width:2px;
  classDef example fill:#FFA07A,stroke:#000,stroke-width:2px;
```
