docs: rework documentation

Author: NoNameProvided

README.md

@@ -19,7 +19,7 @@ Main features includes:
 > Note: This installation guide is for usage with TypeScript, if you wish to use
 > TypeDI without Typescript please read the documentation about how get started.
 
-First install the required packages via:
+To start using TypeDI install the required packages via NPM:
 
 ```bash
 npm install typedi reflect-metadata

docs/README.md

@@ -3,218 +3,7 @@
 TypeDI is a [dependency injection](https://en.wikipedia.org/wiki/Dependency_injection) tool for JavaScript and TypeScript.
 Using TypeDI you can build well-structured and easily tested applications.
 
-- [Usage with JavaScript](#usage-with-javascript)
-- [Usage with TypeScript](#usage-with-typescript)
-
-## Usage with JavaScript
-
-Install the module:
-
-`npm install typedi --save`
-
-Now you can use TypeDI.
-The most simple usage example is:
-
-```javascript
-class SomeClass {
-  someMethod() {}
-}
-
-var Container = require('typedi').Container;
-var someClass = Container.get(SomeClass);
-someClass.someMethod();
-```
-
-Then you can call `Container.get(SomeClass)` from anywhere in your application
-and you'll always have the same instance of `SomeClass`.
-
-In your class's constructor you always receive as a last argument a container which you can use to get other dependencies.
-
-```javascript
-class BeanFactory {
-  create() {}
-}
-
-class SugarFactory {
-  create() {}
-}
-
-class WaterFactory {
-  create() {}
-}
-
-class CoffeeMaker {
-  constructor(container) {
-    this.beanFactory = container.get(BeanFactory);
-    this.sugarFactory = container.get(SugarFactory);
-    this.waterFactory = container.get(WaterFactory);
-  }
-
-  make() {
-    this.beanFactory.create();
-    this.sugarFactory.create();
-    this.waterFactory.create();
-  }
-}
-
-var Container = require('typedi').Container;
-var coffeeMaker = Container.get(CoffeeMaker);
-coffeeMaker.make();
-```
-
-With TypeDI you can use a named services. Example:
-
-```javascript
-var Container = require('typedi').Container;
-
-class BeanFactory implements Factory {
-  create() {}
-}
-
-class SugarFactory implements Factory {
-  create() {}
-}
-
-class WaterFactory implements Factory {
-  create() {}
-}
-
-class CoffeeMaker {
-  beanFactory: Factory;
-  sugarFactory: Factory;
-  waterFactory: Factory;
-
-  constructor(container) {
-    this.beanFactory = container.get('bean.factory');
-    this.sugarFactory = container.get('sugar.factory');
-    this.waterFactory = container.get('water.factory');
-  }
-
-  make() {
-    this.beanFactory.create();
-    this.sugarFactory.create();
-    this.waterFactory.create();
-  }
-}
-
-Container.set('bean.factory', new BeanFactory(Container));
-Container.set('sugar.factory', new SugarFactory(Container));
-Container.set('water.factory', new WaterFactory(Container));
-Container.set('coffee.maker', new CoffeeMaker(Container));
-
-var coffeeMaker = Container.get('coffee.maker');
-coffeeMaker.make();
-```
-
-This feature especially useful if you want to store (and inject later on) some settings or configuration options.
-For example:
-
-```javascript
-var Container = require('typedi').Container;
-
-// somewhere in your global app parameters
-Container.set('authorization-token', 'RVT9rVjSVN');
-
-class UserRepository {
-  constructor(container) {
-    this.authorizationToken = container.get('authorization-token');
-  }
-}
-```
-
-When you write tests you can easily provide your own "fake" dependencies to classes you are testing using `set` method:
-
-```javascript
-Container.set(CoffeeMaker, new FakeCoffeeMaker());
-
-// or for named services
-
-Container.set([
-  { id: 'bean.factory', value: new FakeBeanFactory() },
-  { id: 'sugar.factory', value: new FakeSugarFactory() },
-  { id: 'water.factory', value: new FakeWaterFactory() },
-]);
-```
-
-TypeDI also supports a function dependency injection. Here is how it looks like:
-
-```javascript
-var Service = require('typedi').Service;
-var Container = require('typedi').Container;
-
-var PostRepository = Service(() => ({
-  getName() {
-    return 'hello from post repository';
-  },
-}));
-
-var PostManager = Service(() => ({
-  getId() {
-    return 'some post id';
-  },
-}));
-
-class PostQueryBuilder {
-  build() {
-    return 'SUPER * QUERY';
-  }
-}
-
-var PostController = Service([PostManager, PostRepository, PostQueryBuilder], (manager, repository, queryBuilder) => {
-  return {
-    id: manager.getId(),
-    name: repository.getName(),
-    query: queryBuilder.build(),
-  };
-});
-
-var postController = Container.get(PostController);
-console.log(postController);
-```
-
-## Usage with TypeScript
-
-1. Install module:
-
-   `npm install typedi --save`
-
-2. Install [reflect-metadata](https://www.npmjs.com/package/reflect-metadata) package:
-
-   `npm install reflect-metadata --save`
-
-   and import it somewhere in the global place of your app before any service declaration or import (for example in `app.ts`):
-
-   `import "reflect-metadata";`
-
-3. You may need to install node typings:
-
-   `npm install @types/node --save-dev`
-
-4) Enabled following settings in `tsconfig.json`:
-
-```json
-"emitDecoratorMetadata": true,
-"experimentalDecorators": true,
-```
-
-Now you can use TypeDI.
-The most simple usage example is:
-
-```typescript
-import 'reflect-metadata';
-import { Service, Container } from 'typedi';
-
-@Service()
-class SomeClass {
-  someMethod() {}
-}
-
-let someClass = Container.get(SomeClass);
-someClass.someMethod();
-```
-
-Then you can call `Container.get(SomeClass)` from anywhere in your application
-and you'll always have the same instance of `SomeClass`.
+## Typescript Usage
 
 You can use **property injection** and inject services into your class using `@Inject` decorator:
 
@@ -717,23 +506,3 @@ console.log(postController);
 If you need to remove registered service from container simply use `Container.remove(...)` method.
 Also you can completely reset the container by calling `Container.reset()` method.
 This will effectively remove all registered services from the container.
-
-## Troubleshooting
-
-### Use TypeDI with routing-controllers and/or TypeORM
-
-In order to use typedi with routing-controllers and/or typeorm, it's **necessary** to tell these libs to use the typedi container.
-Otherwise you may face [this kind of issue](https://github.com/pleerock/typedi/issues/4).
-
-```Typescript
-import {useContainer as routingUseContainer} from "routing-controllers";
-import {useContainer as ormUseContainer} from "typeorm";
-import {Container} from "typedi";
-
-routingUseContainer(Container);
-ormUseContainer(Container);
-```
-
-## Samples
-
-Take a look on samples in [./sample](https://github.com/pleerock/typedi/tree/master/sample) for examples of usage.

docs/SUMMARY.md

@@ -1,4 +1,21 @@
 # Table of contents
 
-- [TypeDI](README.md)
-- [Changelog](changelog.md)
+- [Old documentation](README.md)
+
+- [Getting Started](typescript/01-getting-started.md)
+- [Usage Guide](typescript/02-basic-usage-guide.md)
+  - [Container API](typescript/03-container-api.md)
+  - [@Service decorator](typescript/04-service-decorator.md)
+  - [@Inject decorator](typescript/05-inject-decorator.md)
+  - [Service Tokens](typescript/06-service-tokens.md)
+  - [Usage with TypeORM](typescript/07-usage-with-typeorm.md)
+- Advanced Usage
+  - [Creating custom decorators](typescript/08-custom-decorators.md)
+  - [Using scoped container](typescript/09-using-scoped-containers.md)
+  - [Transient services](typescript/10-using-transient-services.md)
+
+## Usage without TypeScript
+
+- [Getting Started](javascript/01-getting-started.md)
+- Usage
+  - [Old documentation](javascript/02-basic-usage.md)

docs/javascript/01-getting-started.md

@@ -0,0 +1,42 @@
+# Getting started without TypeScript
+
+It's possible to use TypeDI without TypesScript, however some of the functionality is limited or not available.
+These differences are listed below in the [Limitations][limitations-sections] section.
+
+## Installation
+
+To start using TypeDI with JavaScript install it via NPM:
+
+```bash
+npm install typedi
+```
+
+## Basic usage
+
+The most basic usage is to request an instance of a class definition. TypeDI will check if an instance of the class has
+been created before and return the cached version or it will create a new instance, cache and return it.
+
+```js
+import { Container } from 'typedi';
+
+class ExampleClass {
+  print() {
+    console.log('I am alive!');
+  }
+}
+
+/** Request an instance of ExampleClass from TypeDI. */
+const classInstance = Container.get(ExampleClass);
+
+/** We received an instance of ExampleClass and ready to work with it. */
+classInstance.print();
+```
+
+For more advanced usage examples and patterns please read the [next page][basic-usage-page].
+
+## Limitations
+
+_To be written..._
+
+[limitations-sections]: #limitations
+[basic-usage-page]: ./02-basic-usage.md