DataSource Declarative CLI + Boot

.gitignore

@@ -10,3 +10,4 @@ packages/*/dist*
 examples/*/dist*
 **/package
 .sandbox
+packages/cli/generators/datasource/connectors.json

docs/site/Booting-an-Application.md

@@ -226,6 +226,24 @@ The `repositories` object supports the following options:
 | `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). |
 
+### DataSource Booter
+
+This Booter's purpose is to discover [DataSource](DataSource.md) type Artifacts
+and to bind them to the Application's Context. The use of this Booter requires
+`RepositoryMixin` from `@loopback/repository` to be mixed into your Application
+class.
+
+You can configure the conventions used in your project for a DataSource by
+passing a `datasources` object on `BootOptions` property of your Application.
+The `datasources` object support the following options:
+
+| Options      | Type                 | Default              | Description                                                                                                   |
+| ------------ | -------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------- |
+| `dirs`       | `string \| string[]` | `['datasources']`    | Paths relative to projectRoot to look in for DataSource artifacts                                             |
+| `extensions` | `string \| string[]` | `['.datasource.js']` | File extensions to match for DataSource artifacts                                                             |
+| `nested`     | `boolean`            | `true`               | Look in nested directories in `dirs` for DataSource artifacts                                                 |
+| `glob`       | `string`             |                      | A `glob` pattern string. This takes precendence over above 3 options (which are used to make a glob pattern). |
+
 ### Custom Booters
 
 A custom Booter can be written as a Class that implements the `Booter`

docs/site/Concepts.md

@@ -49,6 +49,9 @@ LoopBack 4 introduces some new concepts that are important to understand:
   `@loopback/repository-json-schema` module uses the decorators' metadata to
   build a matching JSON Schema.
 
+- [**DataSources**](DataSources.md): A named configuration for a Connector
+  instance that represents data in an external system.
+
 - [**Repository**](Repositories.md): A type of service that represents a
   collection of data within a DataSource.
 

docs/site/Controller-generator.md

@@ -37,10 +37,10 @@ the name.
 
 The tool will prompt you for:
 
-- Name of the controller. If the name had been supplied from the command line,
-  the prompt is skipped and the controller is built with the name from the
+- **Name of the controller.** If the name had been supplied from the command
+  line, the prompt is skipped and the controller is built with the name from the
   command-line argument.
-- Type of the controller. You can select from the following types:
+- **Type of the controller.** You can select from the following types:
   - **Empty Controller** - An empty controller definition
   - **REST Controller with CRUD Methods** - A controller wired up to a model and
     repository definition, with pre-defined CRUD methods.

docs/site/DataSource-generator.md

@@ -0,0 +1,60 @@
+---
+lang: en
+title: 'DataSource generator'
+keywords: LoopBack 4.0, LoopBack 4
+tags:
+sidebar: lb4_sidebar
+permalink: /doc/en/lb4/DataSource-generator.html
+summary:
+---
+
+{% include content/generator-create-app.html lang=page.lang %}
+
+### Synopsis
+
+Adds new [DataSource](Datasources.md) class and config files to a LoopBack
+application.
+
+```sh
+lb4 datasource [options] [<name>]
+```
+
+### Options
+
+`--connector` : Name of datasource connector
+
+This can be a connector supported by LoopBack / Community / Custom.
+
+{% include_relative includes/CLI-std-options.md %}
+
+### Arguments
+
+`<name>` - Required name of the datasource to create as an argiment to the
+command. If provided, the tool will use that as the default when it prompts for
+the name.
+
+### Interactive Prompts
+
+The tool will prompt you for:
+
+- **Name of the datasource.** _(dataSourceName)_ If the name had been supplied
+  from the command line, the prompt is skipped and the datasource is built with
+  the name from the command-line argument.
+- **Name of connector.** If not supplied via command line, you will be presented
+  with a list of connector to select from (including an `other` option for
+  custom connector).
+- **Connector configuration.** If the connector is not a custom connector, the
+  CLI will prompt for the connector configuration information.
+
+### Output
+
+Once all the prompts have been answered, the CLI will do the following:
+
+- Install `@loopback/repository` and the connector package (if it's not a custom
+  connector).
+- Create a file with the connector configuration as follows:
+  `/datasources/${dataSource.dataSourceName}.datasource.json`
+- Create a DataSource class which recieves the connector config using
+  [Dependency Injection](Dependency-injection.md) as follows:
+  `/datasources/${dataSource.dataSourceName}.datasource.ts`
+- Update `index.ts` to export the newly created DataSource class.

docs/site/DataSources.md

@@ -0,0 +1,46 @@
+---
+lang: en
+title: 'DataSources'
+keywords: LoopBack 4.0, LoopBack 4
+tags:
+sidebar: lb4_sidebar
+permalink: /doc/en/lb4/DataSources.html
+summary:
+---
+
+## Overview
+
+A `DataSource` in LoopBack 4 is a named configuration for a Connector instance
+that represents data in an external system. The Connector is used by
+`legacy-juggler-bridge` to power LoopBack 4 Repositories for Data operations.
+
+### Creating a DataSource
+
+It is recommended to use the [`lb4 datasource` command](DataSource-generator.md)
+provided by the CLI to generate a DataSource. The CLI will prompt for all
+necessary connector information and create the following files:
+
+- `${dataSource.dataSourceName}.datasource.json` containing the connector
+  configuration
+- `${dataSource.dataSourceName}.datasource.ts` containing a class extending
+  `juggler.DataSource`. This class can be used to override the default
+  DataSource behaviour programaticaly. Note: The connector configuration stored
+  in the `.json` file is injected into this class using
+  [Dependency Injection](Dependency-injection.md).
+
+Both the above files are generated in `src/datasources/` directory by the CLI.
+It will also update `src/datasources/index.ts` to export the new DataSource
+class.
+
+Example DataSource Class:
+
+```ts
+import {inject} from '@loopback/core';
+import {juggler, DataSource} from '@loopback/repository';
+
+export class DbDataSource extends juggler.DataSource {
+  constructor(@inject('datasources.config.db') dsConfig: DataSource) {
+    super(dsConfig);
+  }
+}
+```

docs/site/Glossary.md

@@ -23,7 +23,8 @@ values for writing web applications and APIs. For more information, see
 **Controller**: The implementation of API endpoints.
 
 **DataSource**: A named configuration for a Connector instance that represents
-data in an external system.
+data in an external system. For more information, see
+[DataSource](DataSource.md).
 
 **Element:** The building blocks of a Sequence, such as route, params, and
 result. For more information, see [Sequence](Sequence.md#elements).

docs/site/sidebars/lb4_sidebar.yml

@@ -78,6 +78,10 @@ children:
     url: Controllers.html
     output: 'web, pdf'
 
+  - title: 'DataSources'
+    url: DataSources.html
+    output: 'web, pdf'
+
   - title: 'Routes'
     url: Routes.html
     output: 'web, pdf'
@@ -127,6 +131,10 @@ children:
     url: Controller-generator.html
     output: 'web, pdf'
 
+  - title: 'DataSource generator'
+    url: DataSource-generator.html
+    output: 'web, pdf'
+
   - title: 'Extension generator'
     url: Extension-generator.html
     output: 'web, pdf'

docs/site/tables/lb4-artifact-commands.html

@@ -12,15 +12,16 @@
   </thead>
   <tbody>
     <tr>
-      <td>
-        <code>lb4 controller</code>
-      </td>
-      <td> Add a new controller to a LoopBack 4 application
-      </td>
-      <td>
-        <a href="Controller-generator.html">Controller generator</a>
-      </td>
+      <td><code>lb4 controller</code></td>
+      <td>Add a new controller to a LoopBack 4 application</td>
+      <td><a href="Controller-generator.html">Controller generator</a></td>
     </tr>
 
+    <tr>
+        <td><code>lb4 datasource</code></td>
+        <td>Add a new datasource to a LoopBack 4 application</td>
+        <td><a href="DataSource-generator.html">DataSource generator</a></td>
+      </tr>
+
   </tbody>
 </table>

docs/site/todo-tutorial-datasource.md

@@ -22,38 +22,22 @@ create a datasource definition to make this possible.
 
 ### Building a Datasource
 
-Create a new folder in the root directory of the project called `config`, and
-then inside that folder, create a `datasources.json` file. For the purposes of
-this tutorial, we'll be using the memory connector provided with the Juggler.
-
-#### config/datasources.json
-
-```json
-{
-  "name": "db",
-  "connector": "memory",
-  "file": "./data/db.json"
-}
-```
-
-Inside the `src/datasources` directory create a new file called
-`db.datasource.ts`. This file will create a strongly-typed export of our
-datasource using the `juggler.DataSource`, which we can consume in our
-application via injection.
-
-#### src/datasources/db.datasource.ts
-
-```ts
-import * as path from 'path';
-import {juggler} from '@loopback/repository';
-
-const dsConfigPath = path.resolve(
-  __dirname,
-  '../../../config/datasources.json',
-);
-const config = require(dsConfigPath);
-
-export const db = new juggler.DataSource(config);
+From inside the project folder, we'll run the `lb4 datasource` command to create
+a DataSource. For the purposes of this tutorial, we'll be using the memory
+connector provided with the Juggler.
+
+```sh
+lb4 datasource
+? Datasource name: db
+? Select the connector for db: In-memory db (supported by StrongLoop)
+? window.localStorage key to use for persistence (browser only):
+? Full path to file for persistence (server only): ./data/db.json
+
+  create src/datasources/db.datasource.json
+  create src/datasources/db.datasource.ts
+  update src/datasources/index.ts
+
+Datasource db is now created in src/datasources/
 ```
 
 Create a `data` folder in the applications root and add a new file called

examples/todo/src/application.ts

@@ -6,7 +6,6 @@
 import {ApplicationConfig} from '@loopback/core';
 import {RestApplication} from '@loopback/rest';
 import {MySequence} from './sequence';
-import {db} from './datasources/db.datasource';
 
 /* tslint:disable:no-unused-variable */
 // Binding and Booter imports are required to infer types for BootMixin!
@@ -40,17 +39,5 @@ export class TodoListApplication extends BootMixin(
         nested: true,
       },
     };
-
-    this.setupDatasources();
-  }
-
-  setupDatasources() {
-    // This will allow you to test your application without needing to
-    // use a "real" datasource!
-    const datasource =
-      this.options && this.options.datasource
-        ? new juggler.DataSource(this.options.datasource)
-        : db;
-    this.dataSource(datasource);
   }
 }

examples/todo/config/datasources.json → examples/todo/src/datasources/db.datasource.json

@@ -1,5 +1,6 @@
 {
   "name": "db",
   "connector": "memory",
+  "localStorage": "",
   "file": "./data/db.json"
 }

examples/todo/src/datasources/db.datasource.ts

@@ -3,22 +3,17 @@
 // This file is licensed under the MIT License.
 // License text available at https://opensource.org/licenses/MIT
 
-import * as path from 'path';
-// The juggler reference must exist for consuming code to correctly infer
-// type info used in the "db" export (contained in juggler.DataSource).
-// tslint:disable-next-line:no-unused-variable
-import {juggler} from '@loopback/repository';
+import {inject} from '@loopback/core';
+import {juggler, DataSource} from '@loopback/repository';
+const config = require('./db.datasource.json');
 
-const dsConfigPath = path.resolve(
-  __dirname,
-  '../../../config/datasources.json',
-);
-const config = require(dsConfigPath);
+export class DbDataSource extends juggler.DataSource {
+  static dataSourceName = 'db';
 
-// TODO(bajtos) Ideally, datasources should be created by @loopback/boot
-// and registered with the app for dependency injection.
-// However, we need to investigate how to access these datasources from
-// integration tests where we don't have access to the full app object.
-// For example, @loopback/boot can provide a helper function for
-// performing a partial boot that creates datasources only.
-export const db = new juggler.DataSource(config);
+  constructor(
+    @inject('datasources.config.db', {optional: true})
+    dsConfig: DataSource = config,
+  ) {
+    super(dsConfig);
+  }
+}

examples/todo/src/datasources/index.ts

@@ -0,0 +1,6 @@
+// Copyright IBM Corp. 2017,2018. All Rights Reserved.
+// Node module: @loopback/example-todo
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/licenses/MIT
+
+export * from './db.datasource';

examples/todo/test/acceptance/application.acceptance.ts

@@ -19,6 +19,20 @@ describe('Application', () => {
   before(givenAnApplication);
   before(async () => {
     await app.boot();
+
+    /**
+     * Override DataSource to not write to file for testing. Since we aren't
+     * persisting data to file and each injection normally instatiates a new
+     * instance, we must change the BindingScope to a singleton so only one
+     * instance is created and used for all injections (preserving access to
+     * the same memory space).
+     */
+    app.bind('datasources.config.db').to({
+      name: 'db',
+      connector: 'memory',
+    });
+
+    // Start Application
     await app.start();
   });
   before(givenARestServer);
@@ -109,10 +123,6 @@ describe('Application', () => {
       rest: {
         port: 0,
       },
-      datasource: {
-        name: 'db',
-        connector: 'memory',
-      },
     });
   }