aurelia / aurelia/dependency-injection

Feature Request: Advanced DI Documentation / Cookbook

Open
#142 1 comment 7 reactions 0 assignees View on GitHub
documentation
Dominant language
TypeScript
Stars
159
Forks
64
PR merge metrics
No merged PRs in 30d

Description

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 https://github.com/aurelia/dependency-injection/issues/57 and https://github.com/aurelia/dependency-injection/issues/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.

Contributor guide

Open the contributing guide

Research direction

Read the existing “basics” documentation and the linked dependency-injection issues 57 and 38 first. Review the mentioned @inject, Container.instance, Factory, FactoryInvoker, invoker, and invokeAsFactory behavior, then define an advanced guide or cookbook covering the requested patterns and clearly identify which undocumented methods merit inclusion.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.