How jeffijoe/awilix works
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.