Update LoopBack 4 docs with rest refactor changes (#475)

* docs(context): Update to reference rest module
* docs(di): Update examples with rest usage
* docs(getting-started): reference rest package
* docs(reserved-keys): Reorg keys to match refactor
* docs(routes): Update to match rest refactor
* docs(sequence): Update to match rest refactor
* docs(test-adv): Update to match rest refactor
* docs(testing): Rework examples for rest

pages/en/lb4/Context.md

@@ -12,57 +12,73 @@ summary:
 
 - An abstraction of all state and dependencies in your application.
 - Context is what LB uses to "manage" everything.
-- A global registry for anything/everything in your app (all configs, state, dependencies, classes, etc).
+- A global registry for anything/everything in your app (all configs, state,
+dependencies, classes, etc).
 - An IoC container used to inject dependencies into your code.
 
 Why is it important to you?
 
-- You can use the context as a way to give loopback more "info" so that other dependencies in your app may retrieve it (ie. a centralized place/global builtin/in-memory storage mechanism).
-- LoopBack can help "manage" your resources automatically (through [Dependency Injection](Dependency-injection.html) and decorators).
-- You have full access to updated/real-time application+request state at all times.
+- You can use the context as a way to give loopback more "info" so that other
+dependencies in your app may retrieve it (ie. a centralized place/global
+builtin/in-memory storage mechanism).
+- LoopBack can help "manage" your resources automatically (through
+[Dependency Injection](Dependency-injection.html) and decorators).
+- You have full access to updated/real-time application+request state at all
+times.
 
 LoopBack supports two types of context: Application-level and Request-level
 
 ## Application-level context (global)
 
-- stores all the initial and modified app state throughout the entire life of the app (while the process is alive)
-- Generally configured when the application is created (though other things may modify things in the context while alive/running)
+- stores all the initial and modified app state throughout the entire life of
+the app (while the process is alive)
+- Generally configured when the application is created (though other things may
+modify things in the context while alive/running)
 
 Here is a simple example:
 
 ```js
 const Application = require('@loopback/core').Application;
 const app = new Application(); // `app` is a "Context"
-class MySequence { ... }
-app.sequence(MySequence);
+class MyController { ... }
+app.controller(MyController);
 ```
 
-In this case, you are using our sequence sugar/helper to register a new default sequence. The important point to note is `MySequence` is actually registered into the Application Context (`app` is a Context).
+In this case, you are using the `.controller` helper method to register a new
+controller. The important point to note is `MyController` is actually registered
+into the Application Context (`app` is a Context).
 
 ## Request-level context (request)
 
-- dynamically created for each incoming server request
-- extends the application level context (to give you access to application level dependencies during the request/response lifecycle)
-- is garbage collected once the response is sent (memory management)
+Using [`@loopback/rest`](https://github.com/strongloop/loopback-next/blob/master/packages/rest) as an
+example, we can create custom sequences that:
+- are dynamically created for each incoming server request
+- extend the application level context (to give you access to application level dependencies during the request/response lifecycle)
+- are garbage collected once the response is sent (memory management)
 
 Let's see this in action:
 
 ```js
 class MySequence extends DefaultSequence {
   handle(request, response) { // we provide these value for convenience (taken from the Context)
-    const req = this.ctx.getSync('http.request'); // but it is still available in the sequence/request context
+    // but they are still available in the sequence/request context
+    const req = await this.ctx.get('rest.http.request');
     this.send(`hello ${req.params.name}`);
   }
 }
 ```
 
 - `this.ctx` is available to your sequence
-- allows you to craft your response using resources from the app in addition to the resources available to the request in real-time (right when you need it)
-- `getSync` is one way to get stuff out of the context, there are many others, see below
+- allows you to craft your response using resources from the app in addition to
+the resources available to the request in real-time (right when you need it)
+- `getSync` is one way to get stuff out of the context, there are many others,
+see below
 
 ## Storing and retrieving items from a Context
 
-Items in the Context are indexed via a key and bound to a `ContextValue`. A `ContextKey` is simply a string value and is used to look up whatever you store along with the key. For example:
+Items in the Context are indexed via a key and bound to a `ContextValue`.
+A `ContextKey` is simply a string value and is used to look up whatever you
+store along with the key. For example:
 
 ```js
 // app level
@@ -71,18 +87,26 @@ app.bind('hello').to('world'); // ContextKey='hello', ContextValue='world'
 console.log(app.getSync('hello')); // => 'world'
 ```
 
-In this case, we bind the 'world' string ContextValue to the 'hello' ContextKey. When we fetch the ContextValue via `getSync`, we give it the ContextKey and it returns the ContextValue that was initially bound (we can do other fancy things too -- ie. instantiate your classes, etc)
+In this case, we bind the 'world' string ContextValue to the 'hello' ContextKey.
+When we fetch the ContextValue via `getSync`, we give it the ContextKey and it
+returns the ContextValue that was initially bound (we can do other fancy things
+too -- ie. instantiate your classes, etc)
 
-The process of registering a ContextValue into the Context is known as _binding_. Sequence-level bindings work the same way (shown 2 examples before).
+The process of registering a ContextValue into the Context is known as
+_binding_. Sequence-level bindings work the same way (shown 2 examples before).
 
 ## Dependency injection
 
 - Many configs are adding to the Context during app instantiation/boot time by you/developer.
-- When things are registered, the Context provides a way to use your dependencies during runtime.
+- When things are registered, the Context provides a way to use your
+dependencies during runtime.
 
-How you access these things is via low level helpers like `app.getSync` or the `sequence` class that is provided to you as shown in the example in the previous section.
+How you access these things is via low level helpers like `app.getSync` or the
+`sequence` class that is provided to you as shown in the example in the previous
+section.
 
-However, when using classes, LoopBack provides a better way to get at stuff in the contxet via the `@inject` decorator:
+However, when using classes, LoopBack provides a better way to get at stuff in
+the context via the `@inject` decorator:
 
 ```js
 const Application = require('@loopback/core');
@@ -100,13 +124,21 @@ class HelloController {
 }
 ```
 
-Notice we just use the default name as though it were available to the constructor. Context allows LoopBack to give you the necessary information at runtime even if you do not know the value when writing up the Controller. The above will print `Hello John` at run time.
+Notice we just use the default name as though it were available to the
+constructor. Context allows LoopBack to give you the necessary information at
+runtime even if you do not know the value when writing up the Controller.
+The above will print `Hello John` at run time.
 
-Please refer to [Dependency injection](Dependency-injection.html) for further details.
+Please refer to [Dependency injection](Dependency-injection.html) for further
+details.
 
 ## Context metadata and sugar decorators
 
-Other interesting decorators can be used to help give LoopBack hints to additional metadata you may want to provide in order to automatically set things up. For example, let's take the previous example and make it available on the `GET /greet` route.
+Other interesting decorators can be used to help give LoopBack hints to
+additional metadata you may want to provide in order to automatically set things
+up. For example, let's take the previous example and make it available on the
+`GET /greet` route using decorators provided by
+[`@loopback/rest`](https://github.com/strongloop/loopback-next/blob/master/packages/rest):
 
 ```js
 class HelloController {
@@ -121,4 +153,6 @@ class HelloController {
 }
 ```
 
-These "sugar" decorators allow you to quickly build up your application without having to code up all the additional logic by simply giving LoopBack hints (in the form of metadata) to your intent.
+These "sugar" decorators allow you to quickly build up your application without
+having to code up all the additional logic by simply giving LoopBack hints
+(in the form of metadata) to your intent.

pages/en/lb4/Dependency-Injection.md

@@ -43,10 +43,16 @@ In LoopBack, we use [Context](Context.html) to keep track of all injectable depe
 
 There are several different ways for configuring the values to inject, the simplest options is to call `app.bind(key).to(value)`. Building on top of the example above, one can configure the app to use a Basic HTTP authentication strategy as follows:
 
-```js
+```ts
+// TypeScript example
+
 import {BasicStrategy} from 'passport-http';
+import {Application} from '@loopback/core';
+import {RestServer} from '@loopback/rest';
+// basic scaffolding stuff happens in between...
 
-app.bind('authentication.strategy').to(new BasicStrategy(loginUser));
+const server = await app.getServer(RestServer); // The REST server has its own context!
+server.bind('authentication.strategy').to(new BasicStrategy(loginUser));
 
 function loginUser(username, password, cb) {
   // check that username + password are valid
@@ -55,12 +61,12 @@ function loginUser(username, password, cb) {
 
 However, when you want to create a binding that will instantiate a class and automatically inject required dependencies, then you need to use `.toClass()` method:
 
-```js
-app.bind('authentication.provider').toClass(AuthenticationProvider);
+```ts
+server.bind('authentication.provider').toClass(AuthenticationProvider);
 
-const provider = await app.get('authentication.provider');
+const provider = await server.get('authentication.provider');
 // provider is an AuthenticationProvider instance
-// provider.strategy was set to the value returned by app.get('authentication.strategy')
+// provider.strategy was set to the value returned by server.get('authentication.strategy')
 ```
 
 When a binding is created via `.toClass()`, [Context](Context.html) will create a new instance of the class when resolving the value of this binding, injecting constructor arguments and property values as configured via `@inject` decorator.

pages/en/lb4/Getting-started.md

@@ -28,21 +28,27 @@ The starting point is [ECMAScript 6](http://www.ecma-international.org/ecma-262/
 
 Here is the most basic LoopBack 4 application:
 
-```js
+```ts
 import {Application} from '@loopback/core';
+import {RestComponent, RestServer} from '@loopback/rest';
 
-const app = new Application();
-app.handler((sequence, request, response) => {
-  sequence.send(response, 'hello world');
+const app = new Application({
+  components: [RestComponent],
 });
 
 (async function start() {
+  // Grab the REST server instance
+  const server = await app.getServer(RestServer);
+  // Setup our handler!
+  server.handler((sequence, request, response) => {
+    sequence.send(response, 'hello world');
+  });
   await app.start();
-  console.log(`The app is running on port ${app.getSync('http.port')}`);
+  console.log(`REST server listening on port ${server.getSync('rest.port')}`);
 })();
 ```
 
-The example above creates an `Application` that responds to all HTTP requests with the text "Hello World".
+The example above creates an `Application` and a `RestServer` that responds to all HTTP requests with the text "Hello World".
 
 To see what the complete application looks like, see [loopback-next-hello-world](https://github.com/strongloop/loopback-next-hello-world/).
 

pages/en/lb4/Reserved-binding-keys.md

@@ -88,12 +88,33 @@ import { CoreBindings } from '@loopback/authentication'
 
 ### Binding keys
 
-**Sequence Actions binding keys**
+|Name|CONSTANT|Type|Description|
+|---|---|---|---|
+|`application.apiSpec`|`API_SPEC`|`OpenApiSpec`|OpenAPI Specification describing your application's routes|
+|`bindElement`|`BIND_ELEMENT`|`BindElement`|Convenience provider function to bind value to `Context`|
+|`components.${component.name}`||`Component`|Components used by your application|
+|`controllers.${controller.name}`||`ControllerClass`|The controller's bound to the application|
+|`controller.current.ctor`|`CONTROLLER_CLASS`|`ControllerClass`|The controller for the current request|
+|`controller.current.operation`|`CONTROLLER_METHOD_NAME`|`string`|Name of the operation for the current request|
+|`controller.method.meta`|`CONTROLLER_METHOD_META`|`ControllerMetaData`|Metadata for a given controller|
+|`getFromContext`|`GET_FROM_CONTEXT`|`GetFromContext`|Convenience provider function to return the `BoundValue` from the `Context`|
+
+## Package: rest
+
+|`rest.handler`|`HANDLER`|`HttpHandler`|The HTTP Request Handler|
+|`rest.port`|`PORT`|`number`|HTTP Port the application will run on|
+|`rest.http.request`|`Http.REQUEST`|`ServerRequest`|The raw `http` request object|
+|`rest.http.request.context`|`Http.CONTEXT`|`Context`|Request level context|
+|`rest.http.response`|`Http.RESPONSE`|`ServerResponse`|The raw `http` response object|
+|`routes.${route.verb}.${route.path}`||`RouteEntry`|Route entry specified in api-spec|
+|`rest.sequence`|`SEQUENCE`|`SequenceHandler`|Class that implements the sequence for your application|
+
+**Rest Sequence Action Binding Keys**
 
-To use the Sequence Actions CONSTANT's, bind/inject to `CoreBindings.SequenceActions.CONSTANT` *OR*
+To use the Rest Sequence Actions CONSTANTs, bind/inject to `RestBindings.SequenceActions.CONSTANT` *OR*
 
 ```js
-const SequenceActions = CoreBindings.SequenceActions;
+const SequenceActions = RestBindings.SequenceActions;
 SequenceActions.CONSTANT // CONSTANT to bind/inject
 ```
 
@@ -106,26 +127,6 @@ SequenceActions.CONSTANT // CONSTANT to bind/inject
 |`sequence.actions.reject`|`REJECT`|`Reject`|Sequence action to reject the request with an error|
 |`sequence.actions.send`|`SEND`|`Send`|Sequence action to send the response back to client|
 
-**Other binding keys**
-
-|Name|CONSTANT|Type|Description|
-|---|---|---|---|
-|`application.apiSpec`|`API_SPEC`|`OpenApiSpec`|OpenAPI Specification describing your application's routes|
-|`bindElement`|`BIND_ELEMENT`|`BindElement`|Convenience provider function to bind value to `Context`|
-|`components.${component.name}`||`Component`|Components used by your application|
-|`controllers.${controller.name}`||`ControllerClass`|The controller's bound to the application|
-|`controller.current.ctor`|`CONTROLLER_CLASS`|`ControllerClass`|The controller for the current request|
-|`controller.current.operation`|`CONTROLLER_METHOD_NAME`|`string`|Name of the operation for the current request|
-|`controller.method.meta`|`CONTROLLER_METHOD_META`|`ControllerMetaData`|Metadata for a given controller|
-|`getFromContext`|`GET_FROM_CONTEXT`|`GetFromContext`|Convenience provider function to return the `BoundValue` from the `Context`|
-|`http.handler`|`HTTP_HANDLER`|`HttpHandler`|The HTTP Request Handler|
-|`http.port`|`HTTP_PORT`|`number`|HTTP Port the application will run on|
-|`http.request`|`Http.REQUEST`|`ServerRequest`|The raw `http` request object|
-|`http.request.context`|`Http.CONTEXT`|`Context`|Request level context|
-|`http.response`|`Http.RESPONSE`|`ServerResponse`|The raw `http` response object|
-|`routes.${route.verb}.${route.path}`||`RouteEntry`|Route entry specified in api-spec|
-|`sequence`|`SEQUENCE`|`SequenceHandler`|Class that implements the sequence for your application|
-
 ## Package: openapi-spec
 
 **Reserved prefixes:**

pages/en/lb4/Routes.md

@@ -12,6 +12,9 @@ summary:
 
 A `Route` is the mapping between your API specification and an Operation (JavaScript implementation). It tells LoopBack which function to `invoke()` given an HTTP request.
 
+The `Route` object and its associated types are provided as a part of the
+[(`@loopback/rest`)](https://github.com/strongloop/loopback-next/blob/master/packages/rest) package.
+
 ## Operations
 
 Operations are JavaScript functions that accept Parameters. They can be implemented as plain JavaScript functions or as methods in [Controllers](Controllers.html).
@@ -32,10 +35,11 @@ In the example above, `name` is a Parameter. Parameters are values, usually pars
  - `header`
  - `path` (url)
 
-## Creating Routes
+## Creating REST Routes
 
 The example below defines a `Route` that will be matched for `GET /`. When the `Route` is matched, the `greet` Operation (above) will be called. It accepts an OpenAPI [OperationObject](https://github.com/OAI/OpenAPI-Specification/blob/0e51e2a1b2d668f434e44e5818a0cdad1be090b4/versions/2.0.md#operationObject) which is defined using `spec`.
-
+The route is then attached to a valid server context running underneath the
+application.
 ```js
 const app = new Application();
 
@@ -48,17 +52,23 @@ const spec = {
     }
   }
 };
-const route = new Route('get', '/', spec, greet);
-app.route(route);
 
-app.start();
+(async function start() {
+  const server = await app.getServer(RestServer);
+  const route = new Route('get', '/', spec, greet);
+  server.route(route);
+  await app.start();
+})();
+
 ```
 
-## Declaring Routes with API specifications
+## Declaring REST Routes with API specifications
 
 Below is an example [Open API Specification](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#swagger-object) that defines the same operation as the example above. This a declarative approach to defining operations. The `x-operation` field in the example below references the handler JavaScript function for the API operation, and should not be confused with `x-operation-name`, which is a string for the Controller method name.
 
 ```js
+
+const server = await app.getServer(RestServer);
 const spec = {
   basePath: '/',
   paths: {
@@ -77,7 +87,7 @@ const spec = {
   }
 };
 
-app.api(spec);
+server.api(spec);
 ```
 
 ## Invoking operations using Routes