docs: add documentation for Tokens

Author: NoNameProvided

docs/README.md

@@ -83,7 +83,6 @@ Container.set([
 
 ## TypeScript Advanced Usage Examples
 
-- [Services with token name](#services-with-token-name)
 - [Using factory function to create service](#using-factory-function-to-create-service)
 - [Using factory class to create service](#using-factory-class-to-create-service)
 - [Problem with circular references](#problem-with-circular-references)
@@ -93,45 +92,6 @@ Container.set([
 - [Using multiple containers and scoped containers](#using-multiple-containers-and-scoped-containers)
 - [Remove registered services or reset container state](#remove-registered-services-or-reset-container-state)
 
-### Services with token name
-
-You can use a services with a `Token` instead of name or target class.
-In this case you can use type safe interface-based services.
-
-```typescript
-import { Container, Service, Inject, Token } from 'typedi';
-
-export interface Factory {
-  create(): void;
-}
-
-export const FactoryService = new Token<Factory>();
-
-@Service(FactoryService)
-export class BeanFactory implements Factory {
-  create() {}
-}
-
-@Service()
-export class CoffeeMaker {
-  private factory: Factory;
-
-  constructor(@Inject(type => FactoryService) factory: Factory) {
-    this.factory = factory;
-  }
-
-  make() {
-    this.factory.create();
-  }
-}
-
-let coffeeMaker = Container.get(CoffeeMaker);
-coffeeMaker.make();
-
-let factory = Container.get(FactoryService); // factory is instance of Factory
-factory.create();
-```
-
 ### Using factory function to create service
 
 You can create your services with the container using factory functions.

docs/typescript/06-service-tokens.md

@@ -1 +1,71 @@
 # Service Tokens
+
+Service tokens are unique identifiers what provides a type-safe access to a value stored in a `Conatiner`.
+
+```ts
+import 'reflect-metadata';
+import { Container, Token } from 'typedi';
+
+export const JWT_SECRET_TOKEN = new Token<string>('MY_SECRET');
+
+Container.set(JWT_SECRET_TOKEN, 'wow-such-secure-much-encryption');
+
+/**
+ * Somewhere else in the application after the JWT_SECRET_TOKEN is
+ * imported in can be used to request the secret from the Container.
+ *
+ * This value is type-safe also because the Token is typed.
+ */
+const JWT_SECRET = Container.get(JWT_SECRET_TOKEN);
+```
+
+## Injecting service tokens
+
+They can be used with the `@Inject()` decorator to overwrite the inferred type of the property of argument.
+
+```ts
+import 'reflect-metadata';
+import { Container, Token, Inject, Service } from 'typedi';
+
+export const JWT_SECRET_TOKEN = new Token<string>('MY_SECRET');
+
+Container.set(JWT_SECRET_TOKEN, 'wow-such-secure-much-encryption');
+
+@Service()
+class Example {
+  @Inject(JWT_SECRET_TOKEN)
+  myProp: string;
+}
+
+const instance = Container.get(Example);
+// The instance.myProp property has the value assigned for the Token
+```
+
+## Tokens with same name
+
+Two token **with the same name are different tokens**. The name is only used to help the developer identify the tokens
+during debugging and development. (It's included in error the messages.)
+
+```ts
+import 'reflect-metadata';
+import { Container, Token } from 'typedi';
+
+const tokenA = new Token('TOKEN');
+const tokenB = new Token('TOKEN');
+
+Container.set(tokenA, 'value-A');
+Container.set(tokenB, 'value-B');
+
+const tokenValueA = Container.get(tokenA);
+// tokenValueA is "value-A"
+const tokenValueB = Container.get(tokenB);
+// tokenValueB is "value-B"
+
+console.log(tokenValueA === tokenValueB);
+// returns false, as Tokens are always unique
+```
+
+### Difference between Token and string identifier
+
+They both achieve the same goal, however it's recommended to use `Tokens` as they are type-safe and cannot be mistyped,
+while a mistyped string identifier will silently return `undefined` as value by default.