Awilix

Extremely powerful Inversion of Control (IoC) container for Node.JS

Dependency Injection
jeffijoe/awilixawilix

README

Awilix


Extremely powerful, performant, & battle-tested Dependency Injection (DI) container for JavaScript/Node,
written in TypeScript.

Awilix enables you to write composable, testable software using dependency injection without special annotations, which in turn decouples your core application code from the intricacies of the DI mechanism.

💡 Check out this

intro to Dependency Injection with Awilix


Installation


Install with npm

  1. ```
  2. npm install awilix
  3. ```

Or yarn

  1. ```
  2. yarn add awilix
  3. ```

You can also use the UMD build fromunpkg

  1. ```html
  2. <script src="https://unpkg.com/awilix/lib/awilix.umd.js"/>
  3. <script>
  4. const container = Awilix.createContainer()
  5. </script>
  6. ```

Usage


Awilix has a pretty simple API (but with many possible ways to invoke it). At
minimum, you need to do 3 things:

- Create a container
- Register some modules in it
- Resolve and use!

index.js

  1. ```javascript
  2. const awilix = require('awilix')

  4. // Create the container and set the injectionMode to PROXY (which is also the default).
  5. const container = awilix.createContainer({
  6.   injectionMode: awilix.InjectionMode.PROXY
  7. })

  9. // This is our app code... We can use
  10. // factory functions, constructor functions
  11. // and classes freely.
  12. class UserController {
  13.   // We are using constructor injection.
  14.   constructor(opts) {
  15.     // Save a reference to our dependency.
  16.     this.userService = opts.userService
  17.   }

  19.   // imagine ctx is our HTTP request context...
  20.   getUser(ctx) {
  21.     return this.userService.getUser(ctx.params.id)
  22.   }
  23. }

  25. container.register({
  26.   // Here we are telling Awilix how to resolve a
  27.   // userController: by instantiating a class.
  28.   userController: awilix.asClass(UserController)
  29. })

  31. // Let's try with a factory function.
  32. const makeUserService = ({ db }) => {
  33.   // Notice how we can use destructuring
  34.   // to access dependencies
  35.   return {
  36.     getUser: id => {
  37.       return db.query(`select * from users where id=${id}`)
  38.     }
  39.   }
  40. }

  42. container.register({
  43.   // the `userService` is resolved by
  44.   // invoking the function.
  45.   userService: awilix.asFunction(makeUserService)
  46. })

  48. // Alright, now we need a database.
  49. // Let's make that a constructor function.
  50. // Notice how the dependency is referenced by name
  51. // directly instead of destructuring an object.
  52. // This is because we register it in "CLASSIC"
  53. // injection mode below.
  54. function Database(connectionString, timeout) {
  55.   // We can inject plain values as well!
  56.   this.conn = connectToYourDatabaseSomehow(connectionString, timeout)
  57. }

  59. Database.prototype.query = function(sql) {
  60.   // blah....
  61.   return this.conn.rawSql(sql)
  62. }

  64. // We use register coupled with asClass to tell Awilix to
  65. // use `new Database(...)` instead of just `Database(...)`.
  66. // We also want to use `CLASSIC` injection mode for this
  67. // registration. Read more about injection modes below.
  68. container.register({
  69.   db: awilix.asClass(Database).classic()
  70. })

  72. // Lastly we register the connection string and timeout values
  73. // as we need them in the Database constructor.
  74. container.register({
  75.   // We can register things as-is - this is not just
  76.   // limited to strings and numbers, it can be anything,
  77.   // really - they will be passed through directly.
  78.   connectionString: awilix.asValue(process.env.CONN_STR),
  79.   timeout: awilix.asValue(1000)
  80. })

  82. // We have now wired everything up!
  83. // Let's use it! (use your imagination with the router thing..)
  84. router.get('/api/users/:id', container.resolve('userController').getUser)

  86. // Alternatively, using the `cradle` proxy..
  87. router.get('/api/users/:id', container.cradle.userController.getUser)

  89. // Using  `container.cradle.userController` is actually the same as calling
  90. // `container.resolve('userController')` - the cradle is our proxy!
  91. ```

That example is rather lengthy, but if you extract things to their proper files
it becomes more manageable.

Check out a working Koa example!

Lifetime management


Awilix supports managing the lifetime of instances. This means that you can
control whether objects are resolved and used once, cached within a certain
scope, or cached for the lifetime of the process.

There are 3 lifetime types available.

- Lifetime.TRANSIENT: This is the default. The registration is resolved every
  time it is needed. This means if you resolve a class more than once, you will
  get back a new instance every time.
- Lifetime.SCOPED: The registration is scoped to the container - that means
  that the resolved value will be reused when resolved from the same scope (or a
  child scope).
- Lifetime.SINGLETON: The registration is always reused no matter what - that
  means that the resolved value is cached in the root container.

They are exposed on the awilix.Lifetime object.

  1. ```js
  2. const Lifetime = awilix.Lifetime
  3. ```

To register a module with a specific lifetime:

  1. ```js
  2. const { asClass, asFunction, asValue } = awilix

  4. class MailService {}

  6. container.register({
  7.   mailService: asClass(MailService, { lifetime: Lifetime.SINGLETON })
  8. })

  10. // or using the chaining configuration API..
  11. container.register({
  12.   mailService: asClass(MailService).setLifetime(Lifetime.SINGLETON)
  13. })

  15. // or..
  16. container.register({
  17.   mailService: asClass(MailService).singleton()
  18. })

  20. // or.......
  21. container.register('mailService', asClass(MailService, { lifetime: SINGLETON }))
  22. ```

Scoped lifetime


In web applications, managing state without depending too much on the web
framework can get difficult. Having to pass tons of information into every
function just to make the right choices based on the authenticated user.

Scoped lifetime in Awilix makes this simple - and fun!

  1. ```js
  2. const { createContainer, asClass, asValue } = awilix
  3. const container = createContainer()

  5. class MessageService {
  6.   constructor({ currentUser }) {
  7.     this.user = currentUser
  8.   }

  10.   getMessages() {
  11.     const id = this.user.id
  12.     // wee!
  13.   }
  14. }

  16. container.register({
  17.   messageService: asClass(MessageService).scoped()
  18. })

  20. // imagine middleware in some web framework..
  21. app.use((req, res, next) => {
  22.   // create a scoped container
  23.   req.scope = container.createScope()

  25.   // register some request-specific data..
  26.   req.scope.register({
  27.     currentUser: asValue(req.user)
  28.   })

  30.   next()
  31. })

  33. app.get('/messages', (req, res) => {
  34.   // for each request we get a new message service!
  35.   const messageService = req.scope.resolve('messageService')
  36.   messageService.getMessages().then(messages => {
  37.     res.send(200, messages)
  38.   })
  39. })

  41. // The message service can now be tested
  42. // without depending on any request data!
  43. ```

IMPORTANT! If a singleton is resolved, and it depends on a scoped or
transient registration, those will remain in the singleton for it's lifetime!

  1. ```js
  2. const makePrintTime = ({ time }) => () => {
  3.   console.log('Time:', time)
  4. }

  6. const getTime = () => new Date().toString()

  8. container.register({
  9.   printTime: asFunction(makePrintTime).singleton(),
  10.   time: asFunction(getTime).transient()
  11. })

  13. // Resolving `time` 2 times will
  14. // invoke `getTime` 2 times.
  15. container.resolve('time')
  16. container.resolve('time')

  18. // These will print the same timestamp at all times,
  19. // because `printTime` is singleton and
  20. // `getTime` was invoked when making the singleton.
  21. container.resolve('printTime')()
  22. container.resolve('printTime')()
  23. ```

Read the documentation for [container.createScope()](#containercreatescope)
for more examples.

Injection modes


The injection mode determines how a function/constructor receives its
dependencies. Pre-2.3.0, only one mode was supported - PROXY - which remains
the default mode.

Awilix v2.3.0 introduced an alternative injection mode: CLASSIC. The injection
modes are available on awilix.InjectionMode

- InjectionMode.PROXY (default): Injects a proxy to functions/constructors
  which looks like a regular object.

  js
  class UserService {
    constructor(opts) {
      this.emailService = opts.emailService
      this.logger = opts.logger
    }
  }
  

  or with destructuring:

  js
  class UserService {
    constructor({ emailService, logger }) {
      this.emailService = emailService
      this.logger = logger
    }
  }
  

- InjectionMode.CLASSIC: Parses the function/constructor parameters, and
  matches them with registrations in the container. CLASSIC mode has a
  slightly higher initialization cost as it has to parse the function/class
  to figure out the dependencies at the time of registration, however resolving
  them will be much faster than when using PROXY. _Don't use CLASSIC if
  you minify your code!_ We recommend using CLASSIC in Node and PROXY in
  environments where minification is needed.

  js
  class UserService {
    constructor(emailService, logger) {
      this.emailService = emailService
      this.logger = logger
    }
  }
  

  Additionally, if the class has a base class but does not declare a constructor of its own, Awilix
  simply invokes the base constructor with whatever dependencies it requires.

  js
  class Car {
    constructor(engine) {
      this.engine = engine
    }
  }

  class Porsche extends Car {
    vroom() {
      console.log(this.engine) // whatever "engine" is
    }
  }