feat: add repository booter (#1030)

* feat(repository): add AppWithRepository interface

* feat(boot): add repository booter

* feat(example-getting-started): use repository booter

packages/boot/README.md

@@ -6,7 +6,8 @@ A convention based project Bootstrapper and Booters for LoopBack Applications
 
 A Booter is a Class that can be bound to an Application and is called
 to perform a task before the Application is started. A Booter may have multiple
-phases to complete its task.
+phases to complete its task. The task for a convention based Booter is to discover
+and bind Artifacts (Controllers, Repositories, Models, etc.).
 
 An example task of a Booter may be to discover and bind all artifacts of a
 given type.
@@ -28,16 +29,11 @@ $ npm i @loopback/boot
 
 ```ts
 import {Application} from '@loopback/core';
-import {BootMixin} from '@loopback/boot';
+import {BootMixin, Booter, Binding} from '@loopback/boot';
 class BootApp extends BootMixin(Application) {}
 
 const app = new BootApp();
 app.projectRoot = __dirname;
-app.bootOptions = {
-  controlles: {
-    // Configure ControllerBooter Conventiones here.
-  }
-}
 
 await app.boot();
 await app.start();
@@ -49,14 +45,43 @@ List of Options available on BootOptions Object.
 |Option|Type|Description|
 |-|-|-|
 |`controllers`|`ArtifactOptions`|ControllerBooter convention options|
+|`repositories`|`ArtifactOptions`|RepositoryBooter convention options|
 
 ### ArtifactOptions
 
-**Add Table for ArtifactOptions**
+|Options|Type|Description|
+|-|-|-|
+|`dirs`|`string \| string[]`|Paths relative to projectRoot to look in for Artifact|
+|`extensions`|`string \| string[]`|File extensions to match for Artifact|
+|`nested`|`boolean`|Look in nested directories in `dirs` for Artifact|
+|`glob`|`string`|A `glob` pattern string. This takes precendence over above 3 options (which are used to make a glob pattern).|
 
 ### BootExecOptions
 
-**Add Table for BootExecOptions**
+**Experimental support. May be removed or changed in a non-compatible way in future without warning**
+
+To use `BootExecOptions` you must directly call `bootstrapper.boot()` and pass in `BootExecOptions`.
+`app.boot()` provided by `BootMixin` does not take any paramters.
+
+```ts
+const bootstrapper: Bootstrapper = await this.get(BootBindings.BOOTSTRAPPER_KEY);
+const execOptions: BootExecOptions = {
+  booters: [MyBooter1, MyBooter2],
+  filter: {
+    phases: ['configure', 'discover']
+  }
+};
+
+const ctx = bootstrapper.boot(execOptions);
+```
+
+You can pass in the `BootExecOptions` object with the following properties:
+
+| Property         | Type                    | Description                                      |
+| ---------------- | ----------------------- | ------------------------------------------------ |
+| `booters`        | `Constructor<Booter>[]` | Array of Booters to bind before running `boot()` |
+| `filter.booters` | `string[]`              | Names of Booter classes that should be run       |
+| `filter.phases`  | `string[]`              | Names of Booter phases to run                    |
 
 ## Available Booters
 
@@ -74,11 +99,31 @@ Available Options on the `controllers` object on `BootOptions` are as follows:
 
 |Options|Type|Default|Description|
 |-|-|-|-|
-|`dirs`|`string | string[]`|`['controllers']`|Paths relative to projectRoot to look in for Controller artifacts|
-|`extensions`|`string | string[]`|`['.controller.js']`|File extensions to match for Controller artifacts|
+|`dirs`|`string \| string[]`|`['controllers']`|Paths relative to projectRoot to look in for Controller artifacts|
+|`extensions`|`string \| string[]`|`['.controller.js']`|File extensions to match for Controller artifacts|
 |`nested`|`boolean`|`true`|Look in nested directories in `dirs` for Controller artifacts|
 |`glob`|`string`||A `glob` pattern string. This takes precendence over above 3 options (which are used to make a glob pattern).|
 
+### RepositoryBooter
+
+#### Description
+Discovers and binds Repository Classes using `app.repository()` (Application must use
+`RepositoryMixin` from `@loopback/repository`).
+
+#### Options
+The Options for this can be passed via `BootOptions` when calling `app.boot(options:BootOptions)`.
+
+The options for this are passed in a `repositories` object on `BootOptions`.
+
+Available Options on the `repositories` object on `BootOptions` are as follows:
+
+|Options|Type|Default|Description|
+|-|-|-|-|
+|`dirs`|`string \| string[]`|`['repositories']`|Paths relative to projectRoot to look in for Repository artifacts|
+|`extensions`|`string \| string[]`|`['.repository.js']`|File extensions to match for Repository artifacts|
+|`nested`|`boolean`|`true`|Look in nested directories in `dirs` for Repository artifacts|
+|`glob`|`string`||A `glob` pattern string. This takes precendence over above 3 options (which are used to make a glob pattern).|
+
 ## Contributions
 
 - [Guidelines](https://github.com/strongloop/loopback-next/wiki/Contributing#guidelines)

packages/boot/docs.json

@@ -4,6 +4,7 @@
     "src/booters/base-artifact.booter.ts",
     "src/booters/booter-utils.ts",
     "src/booters/controller.booter.ts",
+    "src/booters/repository.booter.ts",
     "src/booters/index.ts",
     "src/boot.component.ts",
     "src/boot.mixin.ts",

packages/boot/package.json

@@ -28,6 +28,7 @@
   "dependencies": {
     "@loopback/context": "^0.1.1",
     "@loopback/core": "^0.1.1",
+    "@loopback/repository": "^0.1.1",
     "@types/debug": "0.0.30",
     "@types/glob": "^5.0.34",
     "debug": "^3.1.0",

packages/boot/src/boot.component.ts

@@ -6,7 +6,7 @@
 import {Bootstrapper} from './bootstrapper';
 import {Component, Application, CoreBindings} from '@loopback/core';
 import {inject, BindingScope} from '@loopback/context';
-import {ControllerBooter} from './booters';
+import {ControllerBooter, RepositoryBooter} from './booters';
 import {BootBindings} from './keys';
 
 /**
@@ -17,7 +17,7 @@ import {BootBindings} from './keys';
 export class BootComponent implements Component {
   // Export a list of default booters in the component so they get bound
   // automatically when this component is mounted.
-  booters = [ControllerBooter];
+  booters = [ControllerBooter, RepositoryBooter];
 
   /**
    *

packages/boot/src/booters/controller.booter.ts

@@ -44,7 +44,7 @@ export class ControllerBooter extends BaseArtifactBooter {
 }
 
 /**
- * Default ArtifactOptions for a ControllerBooter.
+ * Default ArtifactOptions for ControllerBooter.
  */
 export const ControllerDefaults: ArtifactOptions = {
   dirs: ['controllers'],

packages/boot/src/booters/index.ts

@@ -6,3 +6,4 @@
 export * from './base-artifact.booter';
 export * from './booter-utils';
 export * from './controller.booter';
+export * from './repository.booter';

packages/boot/src/booters/repository.booter.ts

@@ -0,0 +1,79 @@
+// Copyright IBM Corp. 2018. All Rights Reserved.
+// Node module: @loopback/boot
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/licenses/MIT
+
+import {CoreBindings} from '@loopback/core';
+import {inject} from '@loopback/context';
+import {AppWithRepository} from '@loopback/repository';
+import {BaseArtifactBooter} from './base-artifact.booter';
+import {BootBindings} from '../keys';
+import {ArtifactOptions} from '../interfaces';
+
+/**
+ * A class that extends BaseArtifactBooter to boot the 'Repository' artifact type.
+ * Discovered repositories are bound using `app.repository()` which must be added
+ * to an Application using the `RepositoryMixin` from `@loopback/repository`.
+ *
+ * Supported phases: configure, discover, load
+ *
+ * @param app Application instance
+ * @param projectRoot Root of User Project relative to which all paths are resolved
+ * @param [bootConfig] Repository Artifact Options Object
+ */
+export class RepositoryBooter extends BaseArtifactBooter {
+  constructor(
+    @inject(CoreBindings.APPLICATION_INSTANCE) public app: AppWithRepository,
+    @inject(BootBindings.PROJECT_ROOT) public projectRoot: string,
+    @inject(`${BootBindings.BOOT_OPTIONS}#repositories`)
+    public repositoryOptions: ArtifactOptions = {},
+  ) {
+    super();
+
+    /**
+     * Repository Booter requires the use of RepositoryMixin (so we have `app.repository`)
+     * for binding a Repository Class. We check for it's presence and run
+     * accordingly.
+     */
+    // tslint:disable-next-line:no-any
+    if (!this.app.repository) {
+      console.warn(
+        'app.repository() function is needed for RepositoryBooter. You can add ' +
+          'it to your Application using RepositoryMixin from @loopback/repository.',
+      );
+
+      /**
+       * If RepositoryMixin is not used and a `.repository()` function is not
+       * available, we change the methods to be empty so bootstrapper can
+       * still run without any side-effects of loading this Booter.
+       */
+      this.configure = async () => {};
+      this.discover = async () => {};
+      this.load = async () => {};
+    } else {
+      // Set Repository Booter Options if passed in via bootConfig
+      this.options = Object.assign({}, RepositoryDefaults, repositoryOptions);
+    }
+  }
+
+  /**
+   * Uses super method to get a list of Artifact classes. Boot each class by
+   * binding it to the application using `app.repository(repository);` if present.
+   */
+  async load() {
+    await super.load();
+    this.classes.forEach(cls => {
+      // tslint:disable-next-line:no-any
+      this.app.repository(cls);
+    });
+  }
+}
+
+/**
+ * Default ArtifactOptions for RepositoryBooter.
+ */
+export const RepositoryDefaults: ArtifactOptions = {
+  dirs: ['repositories'],
+  extensions: ['.repository.js'],
+  nested: true,
+};

packages/boot/src/interfaces.ts

@@ -67,6 +67,7 @@ export const BOOTER_PHASES = ['configure', 'discover', 'load'];
  */
 export type BootOptions = {
   controllers?: ArtifactOptions;
+  repositories?: ArtifactOptions;
   /**
    * Additional Properties
    */

packages/boot/test/acceptance/controller.booter.acceptance.ts

@@ -6,10 +6,10 @@
 import {Client, createClientForHandler, TestSandbox} from '@loopback/testlab';
 import {RestServer} from '@loopback/rest';
 import {resolve} from 'path';
-import {ControllerBooterApp} from '../fixtures/application';
+import {BooterApp} from '../fixtures/application';
 
 describe('controller booter acceptance tests', () => {
-  let app: ControllerBooterApp;
+  let app: BooterApp;
   const SANDBOX_PATH = resolve(__dirname, '../../.sandbox');
   const sandbox = new TestSandbox(SANDBOX_PATH);
 
@@ -44,10 +44,8 @@ describe('controller booter acceptance tests', () => {
       'controllers/multiple.artifact.js.map',
     );
 
-    const BooterApp = require(resolve(SANDBOX_PATH, 'application.js'))
-      .ControllerBooterApp;
-
-    app = new BooterApp();
+    const MyApp = require(resolve(SANDBOX_PATH, 'application.js')).BooterApp;
+    app = new MyApp();
   }
 
   async function stopApp() {

packages/boot/test/fixtures/application.ts

@@ -5,13 +5,20 @@
 
 import {RestApplication} from '@loopback/rest';
 import {ApplicationConfig} from '@loopback/core';
+// tslint:disable:no-unused-variable
+import {
+  RepositoryMixin,
+  Class,
+  Repository,
+  juggler,
+} from '@loopback/repository';
+// tslint:enable:no-unused-variable
 
-/* tslint:disable:no-unused-variable */
 // Binding and Booter imports are required to infer types for BootMixin!
+// tslint:disable-next-line:no-unused-variable
 import {BootMixin, Booter, Binding} from '../../index';
-/* tslint:enable:no-unused-variable */
 
-export class ControllerBooterApp extends BootMixin(RestApplication) {
+export class BooterApp extends RepositoryMixin(BootMixin(RestApplication)) {
   constructor(options?: ApplicationConfig) {
     super(options);
     this.projectRoot = __dirname;

packages/boot/test/fixtures/multiple.artifact.ts

@@ -5,14 +5,14 @@
 
 import {get} from '@loopback/openapi-v2';
 
-export class ControllerOne {
+export class ArtifactOne {
   @get('/one')
   one() {
     return 'ControllerOne.one()';
   }
 }
 
-export class ControllerTwo {
+export class ArtifactTwo {
   @get('/two')
   two() {
     return 'ControllerTwo.two()';

packages/boot/test/integration/controller.booter.integration.ts

@@ -5,7 +5,7 @@
 
 import {expect, TestSandbox} from '@loopback/testlab';
 import {resolve} from 'path';
-import {ControllerBooterApp} from '../fixtures/application';
+import {BooterApp} from '../fixtures/application';
 
 describe('controller booter integration tests', () => {
   const SANDBOX_PATH = resolve(__dirname, '../../.sandbox');
@@ -15,15 +15,15 @@ describe('controller booter integration tests', () => {
   const CONTROLLERS_PREFIX = 'controllers';
   const CONTROLLERS_TAG = 'controller';
 
-  let app: ControllerBooterApp;
+  let app: BooterApp;
 
-  beforeEach(resetSandbox);
+  beforeEach(async () => await sandbox.reset());
   beforeEach(getApp);
 
   it('boots controllers when app.boot() is called', async () => {
     const expectedBindings = [
-      `${CONTROLLERS_PREFIX}.ControllerOne`,
-      `${CONTROLLERS_PREFIX}.ControllerTwo`,
+      `${CONTROLLERS_PREFIX}.ArtifactOne`,
+      `${CONTROLLERS_PREFIX}.ArtifactTwo`,
     ];
 
     await app.boot();
@@ -46,13 +46,7 @@ describe('controller booter integration tests', () => {
       'controllers/multiple.artifact.js.map',
     );
 
-    const BooterApp = require(resolve(SANDBOX_PATH, 'application.js'))
-      .ControllerBooterApp;
-
-    app = new BooterApp();
-  }
-
-  async function resetSandbox() {
-    await sandbox.reset();
+    const MyApp = require(resolve(SANDBOX_PATH, 'application.js')).BooterApp;
+    app = new MyApp();
   }
 });