Feature Request: Advanced DI Documentation / Cookbook

[rayalan]

So having spent time figuring out how to convert various oddities of my app into Aurelia's dependency injection system, I would like to see an "advanced" document (since the current one is called "basics"), or perhaps a cookbook that shows some advanced patterns with light commentary. I eventually came across #57 and #38, which pointed me in the right direction.

As far as I can tell, the DI system exports a number of interesting functions that aren't mentioned, or are mentioned in passing in the basic documentation (e.g. Factory, FactoryInvoker).

My ideal cookbook would include:

• @inject will silently succeed and pass undefined if called before there's an initialized container. (Oops...)

• If one wants to pass both injected arguments and constructor arguments, one needs a factory class / function (e.g. like the subsequent one).

• Discussion of using the injection system from an arbitrary point (e.g. testing or writing a factory point), such as:

  import {Container} from 'aurelia-framework'
  function myWidgetFactory(...args) {
      let container = Container.instance;
      let resource = container.get(ResourceType);
      return new Widget(resource, ...args);
  }
  

  The key aspect here, I think, are the ability to access the root container.

• Examples of the Factory() usage outside the context of @inject. I realized while learning the above code that I can do something like:

  function interestingIfNotUsefulPattern(...someArgs) {
      let factoryBase = Factory.of(GenericClass);
      let factory = factoryBase.get(currentContainer);
      return factory(...someArgs);
  }
  

  Seeing the ability to do the above, completely independent of injection, helped orient me to how Factory was working, and how it might be interesting to leverage in other circumstances than injecting with a decorator.

• Consider whether any of the undocumented methods (e.g. FactoryInvoker, invoker, invokeAsFactory) make any sense to document.

I'm not entirely sure that's the right way to format the documentation, but having gotten to the point where I now have working code, it's my best suggestion for helping others learn better.

[Alexander-Taran]

@rayalan would you like to help out with this one and provide a PR?