@loopback/cli 4.0.0-alpha.9 → 4.1.1

package/generators/extension/index.js

@@ -1,15 +1,15 @@
-// Copyright IBM Corp. 2017. All Rights Reserved.
+// Copyright IBM Corp. and LoopBack contributors 2017,2020. All Rights Reserved.
 // Node module: @loopback/cli
 // This file is licensed under the MIT License.
 // License text available at https://opensource.org/licenses/MIT
 
 'use strict';
-const Generator = require('yeoman-generator');
 const utils = require('../../lib/utils');
 
 const ProjectGenerator = require('../../lib/project-generator');
+const g = require('../../lib/globalize');
 
-module.exports = class extends ProjectGenerator {
+module.exports = class ExtensionGenerator extends ProjectGenerator {
   // Note: arguments and options should be defined in the constructor.
   constructor(args, opts) {
     super(args, opts);
@@ -20,30 +20,41 @@ module.exports = class extends ProjectGenerator {
 
     this.option('componentName', {
       type: String,
-      description: 'Component name',
+      description: g.f('Component name'),
     });
 
     return super._setupGenerator();
   }
 
   setOptions() {
+    if (this.shouldExit()) return;
     return super.setOptions();
   }
 
   promptProjectName() {
+    if (this.shouldExit()) return;
     return super.promptProjectName();
   }
 
   promptProjectDir() {
+    if (this.shouldExit()) return;
     return super.promptProjectDir();
   }
 
   promptComponent() {
+    if (this.shouldExit()) return;
+
+    if (this.options.componentName) {
+      Object.assign(this.projectInfo, {
+        componentName: this.options.componentName,
+      });
+    }
+
     const prompts = [
       {
         type: 'input',
         name: 'componentName',
-        message: 'Component class name:',
+        message: g.f('Component class name:'),
         when: this.projectInfo.componentName == null,
         default: utils.toClassName(this.projectInfo.name) + 'Component',
       },
@@ -55,14 +66,32 @@ module.exports = class extends ProjectGenerator {
   }
 
   promptOptions() {
+    if (this.shouldExit()) return;
     return super.promptOptions();
   }
 
+  promptYarnInstall() {
+    if (this.shouldExit()) return;
+    return super.promptYarnInstall();
+  }
+
   scaffold() {
+    if (this.projectInfo) {
+      this.projectInfo.optionsInterface = `${this.projectInfo.componentName}Options`;
+      this.projectInfo.bindingsNamespace = `${this.projectInfo.componentName}Bindings`;
+      const uppercaseUnderscore = this.projectInfo.name
+        .toUpperCase()
+        .replace(/\W/g, '_');
+      this.projectInfo.defaultOptions = `DEFAULT_${uppercaseUnderscore}_OPTIONS`;
+    }
     return super.scaffold();
   }
 
   install() {
     return super.install();
   }
+
+  end() {
+    return super.end();
+  }
 };

package/generators/extension/templates/README.md.ejs

@@ -0,0 +1,32 @@
+# <%= project.name %>
+
+[![LoopBack](https://github.com/loopbackio/loopback-next/raw/master/docs/site/imgs/branding/Powered-by-LoopBack-Badge-(blue)-@2x.png)](http://loopback.io/)
+
+## Installation
+
+Install <%= project.componentName %> using `npm`;
+
+```sh
+$ [npm install | yarn add] <%= project.name %>
+```
+
+## Basic Use
+
+Configure and load <%= project.componentName %> in the application constructor
+as shown below.
+
+```ts
+import {<%= project.componentName %>, <%= project.optionsInterface %>, <%= project.defaultOptions %>} from '<%= project.name %>';
+// ...
+export class MyApplication extends BootMixin(ServiceMixin(RepositoryMixin(RestApplication))) {
+  constructor(options: ApplicationConfig = {}) {
+    const opts: <%= project.optionsInterface %> = <%= project.defaultOptions %>;
+    this.configure(<%= project.bindingsNamespace %>.COMPONENT).to(opts);
+      // Put the configuration options here
+    });
+    this.component(<%= project.componentName %>);
+    // ...
+  }
+  // ...
+}
+```

package/generators/extension/templates/src/component.ts.ejs

@@ -0,0 +1,22 @@
+import {
+  Application,
+  injectable,
+  Component,
+  config,
+  ContextTags,
+  CoreBindings,
+  inject,
+} from '@loopback/core';
+import {<%= project.bindingsNamespace %>} from './keys'
+import {<%= project.defaultOptions %>, <%= project.optionsInterface %>} from './types';
+
+// Configure the binding for <%= project.componentName %>
+@injectable({tags: {[ContextTags.KEY]: <%= project.bindingsNamespace %>.COMPONENT}})
+export class <%= project.componentName %> implements Component {
+  constructor(
+    @inject(CoreBindings.APPLICATION_INSTANCE)
+    private application: Application,
+    @config()
+    private options: <%= project.optionsInterface %> = <%= project.defaultOptions %>,
+  ) {}
+}

package/generators/extension/templates/src/controllers/README.md

@@ -1,5 +1,6 @@
 # Controllers
 
-This directory contains source files for the controllers exported by this extension.
+This directory contains source files for the controllers exported by this
+extension.
 
-For more information, see http://loopback.io/doc/en/lb4/Controllers.html.
+For more information, see <http://loopback.io/doc/en/lb4/Controllers.html>.

package/generators/extension/templates/src/decorators/README.md

@@ -2,16 +2,21 @@
 
 ## Overview
 
-Decorators provide annotations for class methods and arguments. Decorators use the form `@decorator` where `decorator` is the name of the function that will be called at runtime.
+Decorators provide annotations for class methods and arguments. Decorators use
+the form `@decorator` where `decorator` is the name of the function that will be
+called at runtime.
 
 ## Basic Usage
 
 ### txIdFromHeader
 
-This simple decorator allows you to annotate a `Controller` method argument. The decorator will annotate the method argument with the value of the header `X-Transaction-Id` from the request.
+This simple decorator allows you to annotate a `Controller` method argument. The
+decorator will annotate the method argument with the value of the header
+`X-Transaction-Id` from the request.
 
 **Example**
-```
+
+```ts
 class MyController {
   @get('/')
   getHandler(@txIdFromHeader() txId: string) {
@@ -22,7 +27,8 @@ class MyController {
 
 ## Related Resources
 
-You can check out the following resource to learn more about decorators and how they are used in LoopBack Next.
+You can check out the following resource to learn more about decorators and how
+they are used in LoopBack Next.
 
 - [TypeScript Handbook: Decorators](https://www.typescriptlang.org/docs/handbook/decorators.html)
 - [Decorators in LoopBack](http://loopback.io/doc/en/lb4/Decorators.html)

package/generators/extension/templates/src/index.ts.ejs

@@ -0,0 +1,3 @@
+export * from './component';
+export * from './keys';
+export * from './types';

package/generators/extension/templates/src/keys.ts.ejs

@@ -0,0 +1,11 @@
+import {BindingKey, CoreBindings} from '@loopback/core';
+import {<%= project.componentName %>} from './component';
+
+/**
+ * Binding keys used by this component.
+ */
+export namespace <%= project.bindingsNamespace %> {
+  export const COMPONENT = BindingKey.create<<%= project.componentName %>>(
+    `${CoreBindings.COMPONENTS}.<%= project.componentName %>`,
+  );
+}

package/generators/extension/templates/src/mixins/README.md

@@ -4,15 +4,21 @@ This directory contains source files for the mixins exported by this extension.
 
 ## Overview
 
-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.
+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.
 
-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.
+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.
 
 ### High level example
+
 ```ts
 class MyApplication extends MyMixinClass(Application) {
   // Your code
-};
+}
 
 // Multiple Classes mixed together
 class MyApp extends MyMixinClass(MyMixinClass2(Application)) {
@@ -22,12 +28,23 @@ class MyApp extends MyMixinClass(MyMixinClass2(Application)) {
 
 ## Getting Started
 
-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`.
+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`.
 
 ### 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()`.
+
+> 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()`.
 
 #### An example Logger
+
 ```ts
 class ColorLogger implements Logger {
   log(...args: LogArgs) {
@@ -42,12 +59,19 @@ class ColorLogger implements Logger {
 ```
 
 ## 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*.
+
+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.
+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);
@@ -55,23 +79,32 @@ constructor(...args: any[]) {
 ```
 
 ### 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.
+
+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
-class MyApp extends LoggerMixin(Application){
+class MyApp extends LoggerMixin(Application) {
   constructor(...args: any[]) {
     super(...args);
   }
-};
+}
 
 const app = new MyApp({
-  loggers: [ColorLogger]
+  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).
+
+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) {
@@ -81,7 +114,12 @@ if (this.options.loggers) {
 ```
 
 ### 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.
+
+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}`;
@@ -90,7 +128,13 @@ logger(logClass: Logger) {
 ```
 
 ### 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()`.
+
+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
@@ -98,7 +142,11 @@ component(component: Constructor<any>) {
 }
 ```
 
-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).
+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>) {
@@ -114,7 +162,12 @@ mountComponentLoggers(component: Constructor<any>) {
 ```
 
 ## Retrieving the Logger instance
-Now that we have bound a Logger to our Application via one of the many ways made possible by `LoggerMixin`, we need to be able to retrieve it so we can use it. Let's say we want to use it in a controller. Here's an example to retrieving it so we can use it.
+
+Now that we have bound a Logger to our Application via one of the many ways made
+possible by `LoggerMixin`, we need to be able to retrieve it so we can use it.
+Let's say we want to use it in a controller. Here's an example to retrieving it
+so we can use it.
+
 ```ts
 class MyController {
   constructor(@inject('loggers.ColorLogger') protected log: Logger) {}
@@ -127,7 +180,9 @@ class MyController {
 ```
 
 ## Examples for using LoggerMixin
+
 ### Using the app's `.logger()` method
+
 ```ts
 class LoggingApplication extends LoggerMixin(Application) {
   constructor(...args: any[]) {
@@ -138,6 +193,7 @@ class LoggingApplication extends LoggerMixin(Application) {
 ```
 
 ### Using the app's constructor
+
 ```ts
 class LoggerApplication extends LoggerMixin(Application) {
   constructor() {
@@ -149,12 +205,12 @@ class LoggerApplication extends LoggerMixin(Application) {
 ```
 
 ### Binding a Logger provided by a component
+
 ```ts
-class LoggingComponent implements Component{
+class LoggingComponent implements Component {
   loggers: [ColorLogger];
 }
 
-const app = new LoggingApplication({
-  components: [LoggingComponent] // Logger from MyComponent will be bound to loggers.ColorLogger
-});
+const app = new LoggingApplication();
+app.component(LoggingComponent); // Logger from MyComponent will be bound to loggers.ColorLogger
 ```

package/generators/extension/templates/src/providers/README.md

@@ -1,61 +1,84 @@
 # Providers
 
-This directory contains providers contributing additional bindings, for example custom sequence actions.
+This directory contains providers contributing additional bindings, for example
+custom sequence actions.
 
 ## Overview
 
-A [provider](http://loopback.io/doc/en/lb4/Creating-components.html#providers) is a class that provides a `value()` function. This function is called `Context` when another entity requests a value to be injected.
+A [provider](http://loopback.io/doc/en/lb4/Creating-components.html#providers)
+is a class that provides a `value()` function. This function is called `Context`
+when another entity requests a value to be injected.
 
-Here we create a provider for a logging function that can be used as a new action in a custom [sequence](http://loopback.io/doc/en/lb4/Sequence.html).
+Here we create a provider for a logging function that can be used as a new
+action in a custom [sequence](http://loopback.io/doc/en/lb4/Sequence.html).
 
-The logger will log the URL, the parsed request parameters, and the result. The logger is also capable of timing the sequence if you start a timer at the start of the sequence using `this.logger.startTimer()`.
+The logger will log the URL, the parsed request parameters, and the result. The
+logger is also capable of timing the sequence if you start a timer at the start
+of the sequence using `this.logger.startTimer()`.
 
 ## Basic Usage
 
 ### TimerProvider
 
-TimerProvider is automatically bound to your Application's [Context](http://loopback.io/doc/en/lb4/Context.html) using the LogComponent which exports this provider with a binding key of `extension-starter.timer`. You can learn more about components in the [related resources section](#related-resources).
+TimerProvider is automatically bound to your Application's
+[Context](http://loopback.io/doc/en/lb4/Context.html) using the LogComponent
+which exports this provider with a binding key of `extension-starter.timer`. You
+can learn more about components in the
+[related resources section](#related-resources).
 
-This provider makes availble to your application a timer function which given a start time _(given as an array [seconds, nanoseconds])_ can give you a total time elapsed since the start in milliseconds. The timer can also start timing if no start time is given. This is used by LogComponent to allow a user to time a Sequence. 
+This provider makes available to your application a timer function which given a
+start time _(given as an array [seconds, nanoseconds])_ can give you a total
+time elapsed since the start in milliseconds. The timer can also start timing if
+no start time is given. This is used by LogComponent to allow a user to time a
+Sequence.
 
-*NOTE:* _You can get the start time in the required format by using `this.logger.startTimer()`._
+_NOTE:_ _You can get the start time in the required format by using
+`this.logger.startTimer()`._
+
+You can provide your own implementation of the elapsed time function by binding
+it to the binding key (accessible via `ExtensionStarterBindings`) as follows:
 
-You can provide your own implementation of the elapsed time function by binding it to the binding key (accessible via `ExtensionStarterBindings`) as follows:
 ```ts
 app.bind(ExtensionStarterBindings.TIMER).to(timerFn);
-``` 
+```
 
 ### LogProvider
 
-LogProvider can automatically be bound to your Application's Context using the LogComponent which exports the provider with a binding key of `extension-starter.actions.log`. 
+LogProvider can automatically be bound to your Application's Context using the
+LogComponent which exports the provider with a binding key of
+`extension-starter.actions.log`.
 
 The key can be accessed by importing `ExtensionStarterBindings` as follows:
 
 **Example: Binding Keys**
+
 ```ts
 import {ExtensionStarterBindings} from 'HelloExtensions';
 // Key can be accessed as follows now
 const key = ExtensionStarterBindings.LOG_ACTION;
 ```
 
-LogProvider gives us a seuqence action and a `startTimer` function. In order to use the sequence action, you must define your own sequence as shown below. 
+LogProvider gives us a sequence action and a `startTimer` function. In order to
+use the sequence action, you must define your own sequence as shown below.
 
 **Example: Sequence**
+
 ```ts
 class LogSequence implements SequenceHandler {
   constructor(
     @inject(coreSequenceActions.FIND_ROUTE) protected findRoute: FindRoute,
     @inject(coreSequenceActions.PARSE_PARAMS)
     protected parseParams: ParseParams,
-    @inject(coreSequenceActions.INVOKE_METHOD)
-    protected invoke: InvokeMethod,
+    @inject(coreSequenceActions.INVOKE_METHOD) protected invoke: InvokeMethod,
     @inject(coreSequenceActions.SEND) protected send: Send,
     @inject(coreSequenceActions.REJECT) protected reject: Reject,
     // We get the logger injected by the LogProvider here
     @inject(ExtensionStarterBindings.LOG_ACTION) protected logger: LogFn,
   ) {}
 
-  async handle(req: ParsedRequest, res: ServerResponse) {
+  async handle(context: RequestContext) {
+    const {request, response} = context;
+
     // We define these variable outside so they can be accessed by logger.
     let args: any = [];
     let result: any;
@@ -65,39 +88,42 @@ class LogSequence implements SequenceHandler {
     const start = this.logger.startTimer();
 
     try {
-      const route = this.findRoute(req);
-      args = await this.parseParams(req, route);
+      const route = this.findRoute(request);
+      args = await this.parseParams(request, route);
       result = await this.invoke(route, args);
-      this.send(res, result);
-    } catch (err) {
-      result = err; // so we can log the error message in the logger
-      this.reject(res, req, err);
+      this.send(response, result);
+    } catch (error) {
+      result = error; // so we can log the error message in the logger
+      this.reject(context, error);
     }
 
     // We call the logger function given to us by LogProvider
-    this.logger(req, args, result, start);
+    this.logger(request, args, result, start);
   }
 }
 ```
 
-Once a sequence has been written, we can just use that in our Application as follows:
+Once a sequence has been written, we can just use that in our Application as
+follows:
 
 **Example: Application**
+
 ```ts
 const app = new Application({
   sequence: LogSequence,
-  components: [LogComponent]
 });
+app.component(LogComponent);
 
 // Now all requests handled by our sequence will be logged.
 ```
 
 ## Related Resources
 
-You can check out the following resource to learn more about providers, components, sequences, and binding keys.
+You can check out the following resource to learn more about providers,
+components, sequences, and binding keys.
 
 - [Providers](http://loopback.io/doc/en/lb4/Creating-components.html#providers)
 - [Creating Components](http://loopback.io/doc/en/lb4/Creating-components.html)
-- [Using Components](http://loopback.io/doc/en/lb4/Using-components.html)
+- [Using Components](http://loopback.io/doc/en/lb4/Components.html)
 - [Sequence](http://loopback.io/doc/en/lb4/Sequence.html)
 - [Binding Keys](http://loopback.io/doc/en/lb4/Decorators.html)

package/generators/extension/templates/src/repositories/README.md

@@ -2,4 +2,4 @@
 
 This directory contains code for repositories provided by this extension.
 
-For more information, see http://loopback.io/doc/en/lb4/Repositories.html.
+For more information, see <http://loopback.io/doc/en/lb4/Repositories.html>.

package/generators/extension/templates/src/types.ts.ejs

@@ -0,0 +1,15 @@
+/**
+* Interface defining the component's options object
+*/
+export interface <%= project.optionsInterface %> {
+  // Add the definitions here
+
+}
+
+/**
+* Default options for the component
+*/
+export const <%= project.defaultOptions %>: <%= project.optionsInterface %> = {
+  // Specify the values here
+
+};