chore(core): address review comments - 04/08/2019

docs/site/Creating-components.md

@@ -15,15 +15,20 @@ import {MyValueProvider} from './providers/my-value.provider';
 import {Component} from '@loopback/core';
 
 export class MyComponent implements Component {
-  constructor() {
-    this.controllers = [MyController];
-    this.providers = {
-      'my-value': MyValueProvider,
-    };
-    this.classes = {
-      'my-validator': MyValidator,
-    };
+  servers = {
+    'my-server': MyServer,
+  };
+  lifeCycleObservers = [MyObserver];
+  controllers = [MyController];
+  providers = {
+    'my-value': MyValueProvider,
+  };
+  classes = {
+    'my-validator': MyValidator,
+  };
 
+  constructor() {
+    // Set up `bindings`
     const bindingX = Binding.bind('x').to('Value X');
     const bindingY = Binding.bind('y').toClass(ClassY);
     this.bindings = [bindingX, bindingY];
@@ -57,6 +62,8 @@ class is created and then:
 - Each Class is bound to its key in `classes` object via
   `app.bind(key).toClass(cls)`
 - Each Binding is added via `app.add(binding)`
+- Each Server class is registered via `app.server()`
+- Each LifeCycleObserver class is registered via `app.lifeCycleObserver()`
 
 Please note that `providers` and `classes` are shortcuts for provider and class
 `bindings`.
@@ -68,6 +75,8 @@ create the following bindings in the application context:
 - `my-validator` -> `MyValidator` (class)
 - `x` -> `'Value X'` (value)
 - `y` -> `ClassY` (class)
+- `my-server` -> `MyServer` (server)
+- `lifeCycleObservers.MyObserver` -> `MyObserver` (life cycle observer)
 
 ## Providers
 

docs/site/Extension-life-cycle.md

@@ -10,7 +10,9 @@ permalink: /doc/en/lb4/Extension-life-cycle.html
 
 As described in [Life cycle](Life-cycle.md), a LoopBack
 [Application](Application.md) has its own life cycles at runtime. Corresponding
-events such as `start` and `stop` are emitted upon the state change.
+events such as `start` and `stop` are emitted upon the state change. Please note
+that LoopBack only support `start` and `stop` events for an application's life
+cycles at this moment.
 
 Extension modules for LoopBack often contribute artifacts such as servers,
 datasources, and connectors to the application. They typically provide a
@@ -24,7 +26,8 @@ register life cycle observers.
 ### Implement a life cycle observer
 
 A life cycle observer class optionally implements `start` and `stop` methods to
-be invoked upon `start` and `stop` events.
+be invoked upon `start` and `stop` events emitted by an application's life cycle
+respectively.
 
 ```ts
 import {LifeCycleObserver} from '@loopback/core';
@@ -62,10 +65,16 @@ tag - `CoreTags.LIFE_CYCLE_OBSERVER`.
 app.lifeCycleObserver(MyObserver);
 ```
 
-Life cycle observers can be registered via a component too:
+Life cycle observers can be declared via a component class too. when the
+component is mounted to an application, the observers are automatically
+registered.
 
 ```ts
-export class MyComponentWithObservers {
+export class MyComponentWithObservers implements Component {
   lifeCycleObservers = [XObserver, YObserver];
 }
+
+// Mount the component
+app.mount(MyComponentWithObservers);
+// Now `XObserver` and `YObserver` are registered in the application.
 ```

packages/boot/src/__tests__/fixtures/lifecycle-observer.artifact.ts

@@ -5,13 +5,25 @@
 
 import {LifeCycleObserver} from '@loopback/core';
 
+/**
+ * An mock-up `LifeCycleObserver`. Please note that `start` and `stop` methods
+ * can be async or sync.
+ */
 export class MyLifeCycleObserver implements LifeCycleObserver {
   status = '';
 
+  /**
+   * Handling `start` event asynchronously
+   */
   async start() {
+    // Perform some work asynchronously
+    // await startSomeAsyncWork(...)
     this.status = 'started';
   }
 
+  /**
+   * Handling `stop` event synchronously.
+   */
   stop() {
     this.status = 'stopped';
   }

packages/cli/generators/observer/index.js

@@ -20,7 +20,6 @@ module.exports = class ObserverGenerator extends ArtifactGenerator {
   }
 
   _setupGenerator() {
-
     this.option('group', {
       description: 'Name of the observer group for ordering',
       required: false,

packages/core/src/application.ts

@@ -238,7 +238,7 @@ export class Application extends Context implements LifeCycleObserver {
       namespace: CoreBindings.LIFE_CYCLE_OBSERVERS,
       type: CoreTags.LIFE_CYCLE_OBSERVER,
       defaultScope: BindingScope.SINGLETON,
-    }).tag(CoreTags.LIFE_CYCLE_OBSERVER);
+    }).apply(asLifeCycleObserver);
     this.add(binding);
     return binding;
   }

packages/core/src/lifecycle.ts

@@ -10,7 +10,7 @@ import {
   Constructor,
   ValueOrPromise,
 } from '@loopback/context';
-import {CoreBindings, CoreTags} from './keys';
+import {CoreTags} from './keys';
 
 /**
  * Observers to handle life cycle start/stop events
@@ -49,13 +49,13 @@ export function isLifeCycleObserverClass(
 }
 
 /**
- * Configure the binding as life cycle observer
- * @param binding Binding
+ * A `BindingTemplate` function to configure the binding as life cycle observer
+ * by tagging it with `CoreTags.LIFE_CYCLE_OBSERVER`.
+ *
+ * @param binding Binding object
  */
 export function asLifeCycleObserver<T = unknown>(binding: Binding<T>) {
-  return binding
-    .tag(CoreTags.LIFE_CYCLE_OBSERVER)
-    .tag({namespace: CoreBindings.LIFE_CYCLE_OBSERVERS});
+  return binding.tag(CoreTags.LIFE_CYCLE_OBSERVER);
 }
 
 /**