Add support for mixed sync/async bindings (#193)

* Add support for mixed sync/async bindings

Allow dynamic bindings to be created using an async function returning
a promise.

Modify `ctx.get` to always return a promise, regardless of whether
the binding is sync or async.

Modify dependency injection code to detect sync vs. async dependencies
and optimise the code building the dependencies to prefer sync flow
if allowed by dependencies.

packages/authentication/test/acceptance/authentication/feature.md

@@ -58,10 +58,10 @@ const USERS = {
 };
 
 // my get user function
-app.bind('authentication.user').to(() => {
+app.bind('authentication.user').to(async () => {
   const ctx = this;
-  const username = ctx.get('authentication.credentials.username');
-  const password = ctx.get('authentication.credentials.password');
+  const username = await ctx.get('authentication.credentials.username');
+  const password = await ctx.get('authentication.credentials.password');
   const user = USERS[username];
   if (!user) return null;
   if (!verifyPassword(user.password, password)) return null;

packages/context/index.ts

@@ -4,5 +4,7 @@
 // License text available at https://opensource.org/licenses/MIT
 
 export {Binding, BoundValue} from './src/binding';
-export {Context, Constructor} from './src/context';
+export {Context} from './src/context';
+export {Constructor} from './src/resolver';
 export {inject} from './src/inject';
+export const isPromise = require('is-promise');

packages/context/package.json

@@ -16,6 +16,8 @@
   },
   "devDependencies": {
     "@loopback/testlab": "^4.0.0-alpha.1",
+    "@types/bluebird": "^3.5.2",
+    "bluebird": "^3.5.0",
     "mocha": "^3.2.0"
   },
   "keywords": [

packages/context/src/binding.ts

@@ -3,15 +3,14 @@
 // This file is licensed under the MIT License.
 // License text available at https://opensource.org/licenses/MIT
 
-import {Context, Constructor} from './context';
+import {Context} from './context';
+import {Constructor, instantiateClass} from './resolver';
 
 // tslint:disable-next-line:no-any
 export type BoundValue = any;
 
+// FIXME(bajtos) The binding class should be parameterized by the value type stored
 export class Binding {
-  // FIXME(bajtos) The binding class should be parameterized by the value type stored
-  public value: BoundValue;
-  public getValue: () => BoundValue = () => { throw new Error(`No value was configured for binding ${this._key}.`); };
   private _tagName: string;
 
   // For bindings bound via toClass, this property contains the constructor function
@@ -21,6 +20,30 @@ export class Binding {
   get key() { return this._key; }
   get tagName() { return this._tagName; }
 
+  /**
+   * This is an internal function optimized for performance.
+   * Users should use `@inject(key)` or `ctx.get(key)` instead.
+   *
+   * Get the value bound to this key. Depending on `isSync`, this function returns either:
+   *  - the bound value
+   *  - a promise of the bound value
+   *
+   * Consumers wishing to consume sync values directly should use `isPromise`
+   * to check the type of the returned value to decide how to handle it.
+   *
+   * ```
+   * const result = binding.getValue();
+   * if (isPromise(result)) {
+   *   result.then(doSomething)
+   * } else {
+   *   doSomething(result);
+   * }
+   * ```
+   */
+  getValue(): BoundValue | Promise<BoundValue> {
+    return Promise.reject(new Error(`No value was configured for binding ${this._key}.`));
+  }
+
   lock() {
     this.isLocked = true;
   }
@@ -30,18 +53,54 @@ export class Binding {
     return this;
   }
 
+  /**
+   * Bind the key to a constant value.
+   *
+   * @param value The bound value.
+   *
+   * @example
+   *
+   * ```ts
+   * ctx.bind('appName').to('CodeHub');
+   * ```
+   */
   to(value: BoundValue): this {
     this.getValue = () => value;
     return this;
   }
 
-  toDynamicValue(factoryFn: () => BoundValue): this {
+  /**
+   * Bind the key to a computed (dynamic) value.
+   *
+   * @param factoryFn The factory function creating the value.
+   *   Both sync and async functions are supported.
+   *
+   * @example
+   *
+   * ```ts
+   * // synchronous
+   * ctx.bind('now').toDynamicValue(() => Date.now());
+   *
+   * // asynchronous
+   * ctx.bind('something').toDynamicValue(
+   *  async () => Promise.delay(10).then(doSomething)
+   * );
+   * ```
+   */
+  toDynamicValue(factoryFn: () => BoundValue | Promise<BoundValue>): this {
     this.getValue = factoryFn;
     return this;
   }
 
+  /**
+   * Bind the key to an instance of the given class.
+   *
+   * @param ctor The class constructor to call. Any constructor
+   *   arguments must be annotated with `@inject` so that
+   *   we can resolve them from the context.
+   */
   toClass<T>(ctor: Constructor<T>): this {
-    this.getValue = () => this._context.createClassInstance(ctor);
+    this.getValue = () => instantiateClass(ctor, this._context);
     this.valueConstructor = ctor;
     return this;
   }

packages/context/src/context.ts

@@ -4,10 +4,8 @@
 // License text available at https://opensource.org/licenses/MIT
 
 import {Binding, BoundValue} from './binding';
-import {inject, describeInjectedArguments} from './inject';
-
-// tslint:disable-next-line:no-any
-export type Constructor<T> = new(...args: any[]) => T;
+import {inject} from './inject';
+import {isPromise} from './isPromise';
 
 export class Context {
   private registry: Map<string, Binding>;
@@ -30,32 +28,6 @@ export class Context {
     return binding;
   }
 
-  createClassInstance<T>(ctor: Constructor<T>) : T {
-    const args = this._resolveInjectedArguments(ctor);
-    return new ctor(...args);
-  }
-
-  private _resolveInjectedArguments(fn: Function): BoundValue[] {
-    const args: BoundValue[] = [];
-    // NOTE: the array may be sparse, i.e.
-    //   Object.keys(injectedArgs).length !== injectedArgs.length
-    // Example value:
-    //   [ , 'key1', , 'key2']
-    const injectedArgs = describeInjectedArguments(fn);
-
-    for (let ix = 0; ix < fn.length; ix++) {
-      const bindingKey = injectedArgs[ix];
-      if (!bindingKey) {
-        throw new Error(
-          `Cannot resolve injected arguments for function ${fn.name}: ` +
-          `The argument ${ix+1} was not decorated for dependency injection.`);
-      }
-
-      args.push(this.get(bindingKey));
-    }
-    return args;
-  }
-
   contains(key: string): boolean {
     return this.registry.has(key);
   }
@@ -89,10 +61,32 @@ export class Context {
     return bindings;
   }
 
-  get(key: string) {
+  get(key: string): Promise<BoundValue> {
+    try {
+      const binding = this.getBinding(key);
+      return Promise.resolve(binding.getValue());
+    } catch (err) {
+      return Promise.reject(err);
+    }
+  }
+
+  getSync(key: string): BoundValue {
+    const binding = this.getBinding(key);
+    const valueOrPromise = binding.getValue();
+
+    if (isPromise(valueOrPromise)) {
+      throw new Error(
+        `Cannot get ${key} synchronously: ` +
+        `the value requires async computation`);
+    }
+
+    return valueOrPromise;
+  }
+
+  getBinding(key: string): Binding {
     const binding = this.registry.get(key);
     if (!binding)
       throw new Error(`The key ${key} was not bound to any value.`);
-    return binding.getValue();
+    return binding;
   }
 }

packages/context/src/isPromise.ts

@@ -0,0 +1,12 @@
+// Copyright IBM Corp. 2013,2017. All Rights Reserved.
+// Node module: loopback
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/licenses/MIT
+
+export function isPromise<T>(value: T | Promise<T>): value is Promise<T> {
+  if (!value)
+    return false;
+  if (typeof value !== 'object' && typeof value !== 'function')
+    return false;
+  return typeof (value as Promise<T>).then === 'function';
+}

packages/context/src/resolver.ts

@@ -0,0 +1,77 @@
+// Copyright IBM Corp. 2013,2017. All Rights Reserved.
+// Node module: loopback
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/licenses/MIT
+
+import { Context } from './context';
+import { Binding, BoundValue } from './binding';
+import { isPromise } from './isPromise';
+import { describeInjectedArguments } from './inject';
+
+// tslint:disable-next-line:no-any
+export type Constructor<T> = new(...args: any[]) => T;
+
+/**
+ * Create an instance of a class which constructor has arguments
+ * decorated with `@inject`.
+ *
+ * The function returns a class when all dependencies were
+ * resolved synchronously, or a Promise otherwise.
+ *
+ * @param ctor The class constructor to call.
+ * @param ctx The context containing values for `@inject` resolution
+ */
+export function instantiateClass<T>(ctor: Constructor<T>, ctx: Context): T | Promise<T> {
+  const argsOrPromise = resolveInjectedArguments(ctor, ctx);
+  if (isPromise(argsOrPromise)) {
+    return argsOrPromise.then(args => new ctor(...args));
+  } else {
+    return new ctor(...argsOrPromise);
+  }
+}
+
+/**
+ * Given a function with arguments decorated with `@inject`,
+ * return the list of arguments resolved using the values
+ * bound in `ctx`.
+
+ * The function returns an argument array when all dependencies were
+ * resolved synchronously, or a Promise otherwise.
+ *
+ * @param fn The function for which the arguments should be resolved.
+ * @param ctx The context containing values for `@inject` resolution
+ */
+export function resolveInjectedArguments(fn: Function, ctx: Context): BoundValue[] | Promise<BoundValue[]> {
+  // NOTE: the array may be sparse, i.e.
+  //   Object.keys(injectedArgs).length !== injectedArgs.length
+  // Example value:
+  //   [ , 'key1', , 'key2']
+  const injectedArgs = describeInjectedArguments(fn);
+
+  const args: BoundValue[] = new Array(fn.length);
+  let asyncResolvers: Promise<void>[] | undefined = undefined;
+
+  for (let ix = 0; ix < fn.length; ix++) {
+    const bindingKey = injectedArgs[ix];
+    if (!bindingKey) {
+      throw new Error(
+        `Cannot resolve injected arguments for function ${fn.name}: ` +
+        `The argument ${ix + 1} was not decorated for dependency injection.`);
+    }
+
+    const binding = ctx.getBinding(bindingKey);
+    const valueOrPromise = binding.getValue();
+    if (isPromise(valueOrPromise)) {
+      if (!asyncResolvers) asyncResolvers = [];
+      asyncResolvers.push(valueOrPromise.then((v: BoundValue) => args[ix] = v));
+    } else {
+      args[ix] = valueOrPromise as BoundValue;
+    }
+  }
+
+  if (asyncResolvers) {
+    return Promise.all(asyncResolvers).then(() => args);
+  } else {
+    return args;
+  }
+}

packages/context/test/acceptance/_feature.md

@@ -26,8 +26,8 @@ child.get('foo'); // => 'bar'
 let ctx = new Context();
 ctx.bind(':name').to('hello world')
 
-ctx.get('foo'); // => hello world
-ctx.get('bat'); // => hello world
+await ctx.get('foo'); // => hello world
+await ctx.get('bat'); // => hello world
 ```
 
 ## Scenario: Simple Dynamic Paramaterized Binding
@@ -47,8 +47,8 @@ ctx.bind(':name').to((name) => {
   return data[name];
 });
 
-ctx.get('foo'); // => bar
-ctx.get('bat'); // => baz
+await ctx.get('foo'); // => bar
+await ctx.get('bat'); // => baz
 ```
 
 ## Scenario: Namespaced Paramaterized Binding
@@ -61,6 +61,6 @@ ctx.get('bat'); // => baz
 let ctx = new Context();
 ctx.bind('foo.:name').to('hello world');
 
-ctx.get('foo.bar'); // => hello world
-ctx.get('foo.bat'); // => hello world
+await ctx.get('foo.bar'); // => hello world
+await ctx.get('foo.bat'); // => hello world
 ```

packages/context/test/acceptance/class-level-bindings.feature.md

@@ -28,6 +28,6 @@
  }
  ctx.bind('controllers.info').toClass(InfoController);
 
- const instance = ctx.get('controllers.info');
+ const instance = await ctx.get('controllers.info');
  instance.appName; // => CodeHub
  ```