Feedback Applied.

Author: virkt25

src/index.ts

@@ -4,3 +4,4 @@
 // License text available at https://opensource.org/licenses/MIT
 
 export * from './mixins/logger.mixin';
+export * from './types';

src/mixins/README.md

@@ -1,76 +1,122 @@
 # Mixins
 
-This directory contains mixins for `Application`.
+This directory contains source files for the mixins exported by this extension.
 
 ## Overview
 
-A mixin is a class which take the input of a base class and adds / modifies existing functions / status values and returns a new class which can be instantiated. The type of the returned class will still be the base class. Mixins let you extend the BaseClass by adding more functions to it, overriding existing ones or modifiying their behavior.
+Sometimes it's helpful to write partial classes and then combining them together to build more powerful classes. This pattern is called Mixins (mixing in partial classes) and is supported by LoopBack 4. 
 
-## Basic Usage
+LoopBack 4 supports mixins at an `Application` level. Your partial class can then be mixed into the `Application` class. A mixin class can modify or override existing methods of the class or add new ones! It is also possible to mixin multiple classes together as needed.
 
-The general idea behind using a mixin is to pass in the BaseClass to the Mixin and create a new class. 
-
-**Example**
-```
-cosnt newClass = MixinClass(BaseClass);
+### High level example
+```ts
+const MixedClass = MyMixinClass(Application);
+const MultipleMixedClassesClass = MyMixinClass(MyMixinClass2(Application));
 ```
 
-Mixins can be nested, as such you can do the following:
-```
-cosnt newClass = MixinClass1(MixinClass2(BaseClass))
-```
 
-### LoggerMixin
+## Getting Started
 
-LoggerMixin adds capabilities to a LoopBack Next Application by adding a `.logger()` function that is used to bind a Logger class to `Context` automatically. The binding key will be `loggers.${Class.name}` where `Class.name` is the name of the Logger class being bound. Components are also able to provide their own Logger implementation which will be bound via `.component()` automatically when using this Mixin.
+For hello-extensions we write a simple Mixin that allows the `Application` class to bind a `Logger` class from ApplicationOptions, Components, or `.logger()` method that is mixed in. `Logger` instances are bound to the key `loggers.${Logger.name}`. Once a Logger has been bound, the user can retrieve it by using [Dependency Injection](http://loopback.io/doc/en/lb4/Dependency-injection.html) and the key for the `Logger`.
 
-**Example**
-```
-const LoggingApplication = LoggerMixin(Application); // we mixin the Application class from @loopback/core
+### What is a Logger?
+> A Logger class is provides a mechanism for logging messages of varying priority by providing an implementation for `Logger.info()` & `Logger.error()`. An example of a Logger is `console` which has `console.log()` and `console.error()`. 
 
-const app = new LoggingApplication({
-  loggers: [ColorLogger] // we can provide an array of loggers to bind automatically at startup
-});
-
-// Example Logger
-class ColorLogger {
+#### An example Logger
+```ts
+class ColorLogger implements Logger {
   log(...args: any[]) {
     console.log('log  :', ...args);
   }
 
-  info(...args: any[]) {
+  error(...args: any[]) {
     const data = args.join(' ');
-    console.log('\x1b[32m info : ' + data + '\x1b[0m');
+    // log in red color
+    console.log('\x1b[31m error: ' + data + '\x1b[0m');
   }
+}
+```
 
-  warn(...args: any[]) {
-    const data = args.join(' ');
-    console.log('\x1b[33m warn : ' + data + '\x1b[0m');
+## LoggerMixin
+A complete & functional implementation can be found in `logger.mixin.ts`. *Here are some key things to keep in mind when writing your own Mixin*.
+
+### constructor()
+A Mixin constructor must take an array of any type as it's argument. This would represent `ApplicationOptions` for our base class `Application` as well as any properties we would like for our Mixin. 
+
+It is also important for the constructor to call `super(args)` so `Application` continues to work as expected.
+```ts
+constructor(...args: any[]) {
+  super(args);
+}```
+
+### Binding via `ApplicationOptions`
+As mentioned earlier, since our `args` represents `ApplicationOptions`, we can make it possible for users to pass in their `Logger` implementations in a `loggers` array on `ApplicationOptions`. We can then read the array and automatically bind these for the user. 
+
+#### Example user experience
+```ts
+new LoggerMixin(Application)({
+  loggers: [ColorLogger],
+});
+```
+
+#### Example Implementation
+To implement this, we would check `this.options` to see if it has a `loggers` array and if so, bind it by calling the `.logger()` method. (More on that below).
+```ts
+if (this.options.loggers) {
+  for (const logger of this.options.loggers) {
+    this.logger(logger);
   }
+}
+```
 
-  error(...args: any[]) {
-    const data = args.join(' ');
-    console.log('\x1b[31m error: ' + data + '\x1b[0m');
+### Binding via `.logger()`
+As mentioned earlier, we can add a new function to our `Application` class called `.logger()` into which a user would pass in their `Logger` implementation so we can bind it to the `loggers.*` key for them. We just add this new method on our partial Mixin class.
+```ts
+logger(logClass: Logger) {
+  const loggerKey = `loggers.${logClass.name}`;
+  this.bind(loggerKey).toClass(logClass);
+}
+```
+
+### Binding a `Logger` from a `Component`
+Our base class of `Application` already has a method that binds components. We can modify this method to continue binding a `Component` as usual but also binding any `Logger` instances provided by that `Component`. When modifying behavior of an existing method, we can ensure existing behavior by calling the `super.method()`. In our case the method is `.component()`.
+```ts
+component(component: Constructor<any>) {
+  super.component(component); // ensures existing behavior from Application
+  this.mountComponentLoggers(component);
+}
+```
+
+We have now modified `.component()` to do it's thing and then call our method `mountComponentLoggers()`. In this method is where we check for `Logger` implementations declared by the component in a `loggers` array by retrieving the instance of the `Component`. Then if `loggers` array exists, we bind the `Logger` instances as normal (by leveraging our `.logger()` method). 
+
+```ts
+mountComponentLoggers(component: Constructor<any>) {
+  const componentKey = `components.${component.name}`;
+  const compInstance = this.getSync(componentKey);
+
+  if (compInstance.loggers) {
+    for (const logger of compInstance.loggers) {
+      this.logger(logger);
+    }
   }
-};
+}
 ```
 
-Once a Logger has been bound, you can retrieve it by using [Dependency Inject](http://loopback.io/doc/en/lb4/Dependency-injection.html)
 
-#### More Examples for binding a Logger**
+## Examples for using LoggerMixin
 ```
 // Using the app's .logger() function. 
 class LoggingApplication extends LoggerMixin(Application) {
-  constructor() {
-    super();
+  constructor(...args: any[]) {
+    super(...args);
       const app = this;
   }
 
   app.logger(ColorLogger);
 }
 
-// Binding a Logger provided by a components
-class MyComponent {
+// Binding a Logger provided by a component
+class MyComponent implements Component{
   loggers: [ColorLogger];
 }
 

src/mixins/logger.mixin.ts

@@ -6,6 +6,7 @@
 // tslint:disable:no-any
 
 import {Constructor} from '@loopback/context';
+import {Logger} from '../types';
 
 /**
 * A mixin class for Application that creates a .logger()
@@ -47,7 +48,7 @@ export function LoggerMixin<T extends Constructor<any>>(superClass: T) {
     * app.logger(Logger);
     * ```
     */
-    logger(logClass: Constructor<any>) {
+    logger(logClass: Constructor<Logger>) {
       const loggerKey = `loggers.${logClass.name}`;
       this.bind(loggerKey).toClass(logClass);
     }
@@ -73,7 +74,7 @@ export function LoggerMixin<T extends Constructor<any>>(superClass: T) {
     */
     component(component: Constructor<any>) {
       super.component(component);
-      this.mountComponentLogger(component);
+      this.mountComponentLoggers(component);
     }
 
     /**
@@ -83,7 +84,7 @@ export function LoggerMixin<T extends Constructor<any>>(superClass: T) {
     *
     * @param component The component to mount Logger's of
     */
-    mountComponentLogger(component: Constructor<any>) {
+    mountComponentLoggers(component: Constructor<any>) {
       const componentKey = `components.${component.name}`;
       const compInstance = this.getSync(componentKey);
 

src/types.ts

@@ -0,0 +1,17 @@
+// Copyright IBM Corp. 2013,2017. All Rights Reserved.
+// Node module: loopback-next-extension-starter
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/licenses/MIT
+
+// Types and interfaces exposed by the extension go here
+
+// tslint:disable-next-line:no-any
+export type LogArgs = any[];
+
+export interface Logger {
+  log(...args: LogArgs): void;
+  error(...args: LogArgs): void;
+
+  info?(...args: LogArgs): void;
+  warn?(...args: LogArgs): void;
+}

test/unit/logger-mixin.test.ts renamed to test/unit/mixins/logger.mixin.test.ts

@@ -4,7 +4,7 @@
 // License text available at https://opensource.org/licenses/MIT
 
 import {expect} from '@loopback/testlab';
-import {LoggerMixin} from '../..';
+import {LoggerMixin, LogArgs, Logger} from '../../..';
 import {Application, Component} from '@loopback/core';
 import {Constructor} from '@loopback/context';
 
@@ -61,26 +61,12 @@ describe('LoggerMixin', () => {
 
   class AppWithLogger extends LoggerMixin(Application) {}
 
-  class MyLogger {
-    // tslint:disable-next-line:no-any
-    log(...args: any[]) {
+  class MyLogger implements Logger {
+    log(...args: LogArgs) {
       console.log('log  :', ...args);
     }
 
-    // tslint:disable-next-line:no-any
-    info(...args: any[]) {
-      const data = args.join(' ');
-      console.log('\x1b[32m info : ' + data + '\x1b[0m');
-    }
-
-    // tslint:disable-next-line:no-any
-    warn(...args: any[]) {
-      const data = args.join(' ');
-      console.log('\x1b[33m warn : ' + data + '\x1b[0m');
-    }
-
-    // tslint:disable-next-line:no-any
-    error(...args: any[]) {
+    error(...args: LogArgs) {
       const data = args.join(' ');
       console.log('\x1b[31m error: ' + data + '\x1b[0m');
     }