feat(core): improve component bindings

docs/site/Creating-components.md

@@ -20,6 +20,13 @@ export class MyComponent implements Component {
     this.providers = {
       'my-value': MyValueProvider,
     };
+    this.classes = {
+      'my-validator': MyValidator,
+    };
+
+    const bindingX = Binding.bind('x').to('Value X');
+    const bindingY = Binding.bind('y').toClass(ClassY);
+    this.bindings = [bindingX, bindingY];
   }
 }
 ```
@@ -28,10 +35,22 @@ When a component is mounted to an application, a new instance of the component
 class is created and then:
 
 - Each Controller class is registered via `app.controller()`,
-- Each Provider is bound to its key in `providers` object.
+- Each Provider is bound to its key in `providers` object via
+  `app.bind(key).toProvider(providerClass)`
+- Each Class is bound to its key in `classes` object via
+  `app.bind(key).toClass(cls)`
+- Each Binding is added via `app.add(binding)`
+
+Please note that `providers` and `classes` are shortcuts for provider and class
+`bindings`.
 
 The example `MyComponent` above will add `MyController` to application's API and
-create a new binding `my-value` that will be resolved using `MyValueProvider`.
+create the following bindings in the application context:
+
+- `my-value` -> `MyValueProvider` (provider)
+- `my-validator` -> `MyValidator` (class)
+- `x` -> `'Value X'` (value)
+- `y` -> `ClassY` (class)
 
 ## Providers
 

packages/context/src/binding.ts

@@ -383,7 +383,7 @@ export class Binding<T = BoundValue> {
    *
    * @param provider The value provider to use.
    */
-  public toProvider(providerClass: Constructor<Provider<T>>): this {
+  toProvider(providerClass: Constructor<Provider<T>>): this {
     /* istanbul ignore if */
     if (debug.enabled) {
       debug('Bind %s to provider %s', this.key, providerClass.name);
@@ -436,4 +436,14 @@ export class Binding<T = BoundValue> {
     }
     return json;
   }
+
+  /**
+   * A static method to create a binding so that we can do
+   * `Binding.bind('foo').to('bar');` as `new Binding('foo').to('bar')` is not
+   * easy to read.
+   * @param key Binding key
+   */
+  static bind(key: string): Binding {
+    return new Binding(key);
+  }
 }

packages/context/src/context.ts

@@ -47,22 +47,32 @@ export class Context {
   bind<ValueType = BoundValue>(
     key: BindingAddress<ValueType>,
   ): Binding<ValueType> {
+    const binding = new Binding<ValueType>(key.toString());
+    this.add(binding);
+    return binding;
+  }
+
+  /**
+   * Add a binding to the context. If a locked binding already exists with the
+   * same key, an error will be thrown.
+   * @param binding The configured binding to be added
+   */
+  add(binding: Binding<unknown>): this {
+    const key = binding.key;
     /* istanbul ignore if */
     if (debug.enabled) {
       debug('Adding binding: %s', key);
     }
-    key = BindingKey.validate(key);
+
     const keyExists = this.registry.has(key);
     if (keyExists) {
       const existingBinding = this.registry.get(key);
       const bindingIsLocked = existingBinding && existingBinding.isLocked;
       if (bindingIsLocked)
         throw new Error(`Cannot rebind key "${key}" to a locked binding`);
     }
-
-    const binding = new Binding<ValueType>(key);
     this.registry.set(key, binding);
-    return binding;
+    return this;
   }
 
   /**
@@ -75,7 +85,7 @@ export class Context {
    * @param key Binding key
    * @returns true if the binding key is found and removed from this context
    */
-  unbind<ValueType = BoundValue>(key: BindingAddress<ValueType>): boolean {
+  unbind(key: BindingAddress<unknown>): boolean {
     key = BindingKey.validate(key);
     const binding = this.registry.get(key);
     if (binding == null) return false;
@@ -89,7 +99,7 @@ export class Context {
    * delegating to the parent context
    * @param key Binding key
    */
-  contains<ValueType = BoundValue>(key: BindingAddress<ValueType>): boolean {
+  contains(key: BindingAddress<unknown>): boolean {
     key = BindingKey.validate(key);
     return this.registry.has(key);
   }
@@ -98,7 +108,7 @@ export class Context {
    * Check if a key is bound in the context or its ancestors
    * @param key Binding key
    */
-  isBound<ValueType = BoundValue>(key: BindingAddress<ValueType>): boolean {
+  isBound(key: BindingAddress<unknown>): boolean {
     if (this.contains(key)) return true;
     if (this._parent) {
       return this._parent.isBound(key);
@@ -110,9 +120,7 @@ export class Context {
    * Get the owning context for a binding key
    * @param key Binding key
    */
-  getOwnerContext<ValueType = BoundValue>(
-    key: BindingAddress<ValueType>,
-  ): Context | undefined {
+  getOwnerContext(key: BindingAddress<unknown>): Context | undefined {
     if (this.contains(key)) return this;
     if (this._parent) {
       return this._parent.getOwnerContext(key);

packages/context/test/unit/context.unit.ts

@@ -80,6 +80,30 @@ describe('Context', () => {
       const key = 'a' + BindingKey.PROPERTY_SEPARATOR + 'b';
       expect(() => ctx.bind(key)).to.throw(/Binding key .* cannot contain/);
     });
+
+    it('rejects rebinding of a locked key', () => {
+      ctx.bind('foo').lock();
+      expect(() => ctx.bind('foo')).to.throw(
+        'Cannot rebind key "foo" to a locked binding',
+      );
+    });
+  });
+
+  describe('add', () => {
+    it('accepts a binding', () => {
+      const binding = new Binding('foo').to('bar');
+      ctx.add(binding);
+      expect(ctx.getBinding(binding.key)).to.be.exactly(binding);
+      const result = ctx.contains('foo');
+      expect(result).to.be.true();
+    });
+
+    it('rejects rebinding of a locked key', () => {
+      ctx.bind('foo').lock();
+      expect(() => ctx.add(new Binding('foo'))).to.throw(
+        'Cannot rebind key "foo" to a locked binding',
+      );
+    });
   });
 
   describe('contains', () => {

packages/core/src/component.ts

@@ -3,17 +3,24 @@
 // This file is licensed under the MIT License.
 // License text available at https://opensource.org/licenses/MIT
 
-import {Constructor, Provider, BoundValue} from '@loopback/context';
+import {Constructor, Provider, BoundValue, Binding} from '@loopback/context';
 import {Server} from './server';
 import {Application, ControllerClass} from './application';
 
 /**
- * A map of name/class pairs for binding providers
+ * A map of provider classes to be bound to a context
  */
 export interface ProviderMap {
   [key: string]: Constructor<Provider<BoundValue>>;
 }
 
+/**
+ * A map of classes to be bound to a context
+ */
+export interface ClassMap {
+  [key: string]: Constructor<BoundValue>;
+}
+
 /**
  * A component declares a set of artifacts so that they cane be contributed to
  * an application as a group
@@ -23,17 +30,46 @@ export interface Component {
    * An array of controller classes
    */
   controllers?: ControllerClass[];
+
   /**
-   * A map of name/class pairs for binding providers
+   * A map of providers to be bound to the application context
+   * * For example:
+   * ```ts
+   * {
+   *   'authentication.strategies.ldap': LdapStrategyProvider
+   * }
+   * ```
    */
   providers?: ProviderMap;
+
+  /**
+   * A map of classes to be bound to the application context.
+   *
+   * For example:
+   * ```ts
+   * {
+   *   'rest.body-parsers.xml': XmlBodyParser
+   * }
+   * ```
+   */
+  classes?: ClassMap;
+
   /**
    * A map of name/class pairs for servers
    */
   servers?: {
     [name: string]: Constructor<Server>;
   };
 
+  /**
+   * An array of bindings to be aded to the application context. For example,
+   * ```ts
+   * const bindingX = Binding.bind('x').to('Value X');
+   * this.bindings = [bindingX]
+   * ```
+   */
+  bindings?: Binding[];
+
   /**
    * Other properties
    */
@@ -49,9 +85,9 @@ export interface Component {
  * @param {Component} component
  */
 export function mountComponent(app: Application, component: Component) {
-  if (component.controllers) {
-    for (const controllerCtor of component.controllers) {
-      app.controller(controllerCtor);
+  if (component.classes) {
+    for (const classKey in component.classes) {
+      app.bind(classKey).toClass(component.classes[classKey]);
     }
   }
 
@@ -61,6 +97,18 @@ export function mountComponent(app: Application, component: Component) {
     }
   }
 
+  if (component.bindings) {
+    for (const binding of component.bindings) {
+      app.add(binding);
+    }
+  }
+
+  if (component.controllers) {
+    for (const controllerCtor of component.controllers) {
+      app.controller(controllerCtor);
+    }
+  }
+
   if (component.servers) {
     for (const serverKey in component.servers) {
       app.server(component.servers[serverKey], serverKey);

packages/core/test/unit/application.unit.ts

@@ -3,9 +3,15 @@
 // This file is licensed under the MIT License.
 // License text available at https://opensource.org/licenses/MIT
 
-import {Constructor, Context} from '@loopback/context';
 import {expect} from '@loopback/testlab';
-import {Application, Component, Server} from '../..';
+import {Application, Server, Component, CoreBindings} from '../..';
+import {
+  Context,
+  Constructor,
+  Binding,
+  Provider,
+  inject,
+} from '@loopback/context';
 
 describe('Application', () => {
   describe('controller binding', () => {
@@ -35,10 +41,8 @@ describe('Application', () => {
 
   describe('component binding', () => {
     let app: Application;
-    class MyController {}
-    class MyComponent implements Component {
-      controllers = [MyController];
-    }
+
+    class MyComponent implements Component {}
 
     beforeEach(givenApp);
 
@@ -56,6 +60,73 @@ describe('Application', () => {
       );
     });
 
+    it('binds controllers from a component', () => {
+      class MyController {}
+
+      class MyComponentWithControllers implements Component {
+        controllers = [MyController];
+      }
+
+      app.component(MyComponentWithControllers);
+      expect(
+        app.getBinding('controllers.MyController').valueConstructor,
+      ).to.be.exactly(MyController);
+    });
+
+    it('binds bindings from a component', () => {
+      const binding = Binding.bind('foo');
+      class MyComponentWithBindings implements Component {
+        bindings = [binding];
+      }
+
+      app.component(MyComponentWithBindings);
+      expect(app.getBinding('foo')).to.be.exactly(binding);
+    });
+
+    it('binds classes from a component', () => {
+      class MyClass {}
+
+      class MyComponentWithClasses implements Component {
+        classes = {'my-class': MyClass};
+      }
+
+      app.component(MyComponentWithClasses);
+      expect(app.contains('my-class')).to.be.true();
+      expect(app.getBinding('my-class').valueConstructor).to.be.exactly(
+        MyClass,
+      );
+      expect(app.getSync('my-class')).to.be.instanceof(MyClass);
+    });
+
+    it('binds providers from a component', () => {
+      class MyProvider implements Provider<string> {
+        value() {
+          return 'my-str';
+        }
+      }
+
+      class MyComponentWithProviders implements Component {
+        providers = {'my-provider': MyProvider};
+      }
+
+      app.component(MyComponentWithProviders);
+      expect(app.contains('my-provider')).to.be.true();
+      expect(app.getSync('my-provider')).to.be.eql('my-str');
+    });
+
+    it('binds from a component constructor', () => {
+      class MyComponentWithDI implements Component {
+        constructor(@inject(CoreBindings.APPLICATION_INSTANCE) ctx: Context) {
+          // Programmatically bind to the context
+          ctx.bind('foo').to('bar');
+        }
+      }
+
+      app.component(MyComponentWithDI);
+      expect(app.contains('foo')).to.be.true();
+      expect(app.getSync('foo')).to.be.eql('bar');
+    });
+
     function givenApp() {
       app = new Application();
     }