Awilix v3 Release Candidate 🚀

[jeffijoe]

I've pushed awilix@3.0.0-rc.6 to npm which has a few breaking changes for JS users and a few more for TS users (new, better typings as v3 is now written in TypeScript).

Please try it out so I can ship it as stable ASAP!

✨ New Features

With v3 comes a few new cool features.

Disposer support (#48)

This has been a very requested feature. The idea is you can tell Awilix how to dispose
of a dependency—for example, to close a database connection—when calling container.dispose().

const pg = require('pg')
const { createContainer, asFunction } = require('awilix')
const container = createContainer()
  .register({
    pool: (
      asFunction(() => new pg.Pool({ ... }))
        .singleton()
        .disposer((pool) => pool.end())
    )
  })

// .. later, but only if a `pool` was ever created
container.dispose().then(() => {
  console.log('One disposable connection.. disposed! Huehehehe')
})

alias resolver (#55)

This new resolver lets you alias a registration. This is best illustrated with an example:

const { alias, asValue, createContainer } = require('awilix')

const container = createContainer()

container.register({
  laughingOutLoud: asValue('hahahahaha'),
  lol: alias('laughingOutLoud')
})

container.resolve('lol') // 'hahahahaha'

It's essentially the exact same as calling container.resolve('laughingOutLoad'), but lol might be easier to type out in your constructors. 😎

Default values in constructors/functions (#46)

This is a pretty small feature but was the most difficult to land, mainly because I had to write a smarter parser and tokenizer, not to mention they are now way better at skipping over code. Check out the tests, it's pretty wild.

class MyClass {
  constructor(db, timeout = 1000) { /*...*/ }
}

container.register({
  db: asFunction(..)
})

// Look! No errors!! :D
container.build(MyClass) instanceof MyClass // true

Official support for running in the browser (#69)

Awilix now ships with 4 module flavors: CommonJS (same old), ES Modules for Node, ES Modules for the Browser and UMD.

Please see the Universal Module section in the readme for details.

🚨 Known breaking changes

The following is a list of known breaking changes. If there's any I've missed feel free to let me know.

The entire library is now written in TypeScript! (#49)

This means a bunch of interfaces have been renamed and made more correct.
If you're a TypeScript user, this is great news for you. 😄

ResolutionMode is now InjectionMode (#57)

• ResolutionMode.js renamed to injection-mode.ts
• ResolutionMode renamed to InjectionMode

"Registrations" are now "Resolvers" (#51)

The terminology is now "you register a resolver to a name".

• TypeScript interfaces renamed
• REGISTRATION symbol renamed to RESOLVER
• registrations.js renamed to resolvers.ts
• registrationOptions in loadModules renamed to resolverOptions

registerClass, registerFunction and registerValue removed (#60)

This was done to simplify the API surface, and also simplifies the implementation greatly (less overloads). You should be using container.register with asClass, asFunction and asValue instead.

Resolver configuration chaining API is now immutable (#62)

This simplifies the TypeScript types and is also considered a good practice. All configuration functions rely on this, meaning you should not do:

// I don't know why you would, but DONT DO THIS!
const singleton = asClass(MyClass).singleton
singleton()

However, this also means you can now "split" a resolver to configure it differently. For example:

class GenericSender {
  constructor(transport) {
    this.transport = transport
  }

  send() {
    if (this.transport === 'email') {
      // ... etc
    }
  }

  dispose() { /*...*/ }
}

const base = asClass(GenericSender).scoped().disposer((g) => g.dispose())
const emailSender = base.inject(() => ({ transport: 'email' })
const pushSender = base.inject(() => ({ transport: 'push' })

container.register({
  emailSender,
  pushSender
})

Removed AwilixNotAFunctionError in favor of a generic AwilixTypeError (#52)

This should not have an impact on userland code but I thought I'd mention it.

There are a bunch of internal uses of this error, so I thought it made sense to consolidate them into one error type.

👀 Other cool changes

• Code is now formatted with Prettier
• Awilix is now using husky + lint-staged to lint, format and test every commit to ensure top code quality.
• Switched to Jest from Mocha
• Switched from eslint to tslint
• Rewrote the function parameter parser, it is now much better at correctly skipping over default value expressions to reach the next parameter.
• Most (if not all) of the code is now documented and should be readable.

---

Please give it whirl and let me know how it goes! I'll update the changelog once stable ships.

/cc @ddproxy @cjhoward92 @blove @cikasfm @Seldszar

[Seldszar]

Will do ASAP! 😃

[Seldszar]

I think I have an issue, it seems some files are not included.
The only files in the tarball are package.json, CHANGELOG.md, LICENSE.md and README.md.

[jeffijoe]

@Seldszar oh damn, forgot to update the publish script to include a build step haha, gimme a sec!

[jeffijoe]

@Seldszar awilix@3.0.0-rc.2 pushed, good catch!

[Seldszar]

Perfect!
Let's tame this beast!

[jeffijoe]

@Seldszar I just thought of a potential issue with the disposer feature, please see #65

EDIT: fixed and pushed as 3.0.0-rc.3

[ith]

@jeffijoe I found some typings issue for typescript and awilix-koa -> #67

[jeffijoe]

#67 has been moved to jeffijoe/awilix-koa#3 — thanks @ith!

[jeffijoe]

Awilix v3 is now on npm - thank you all for your input! 🚀