@loopback/context 1.11.0 → 1.12.0

package/src/inject.ts

@@ -12,7 +12,7 @@ import {
   ParameterDecoratorFactory,
   PropertyDecoratorFactory,
 } from '@loopback/metadata';
-import {BindingTag} from './binding';
+import {Binding, BindingTag} from './binding';
 import {
   BindingFilter,
   BindingSelector,
@@ -20,7 +20,7 @@ import {
   isBindingAddress,
 } from './binding-filter';
 import {BindingAddress} from './binding-key';
-import {Context} from './context';
+import {BindingCreationPolicy, Context} from './context';
 import {ContextView, createViewGetter} from './context-view';
 import {ResolutionSession} from './resolution-session';
 import {BoundValue, ValueOrPromise} from './value-promise';
@@ -186,7 +186,9 @@ export function inject(
 }
 
 /**
- * The function injected by `@inject.getter(bindingSelector)`.
+ * The function injected by `@inject.getter(bindingSelector)`. It can be used
+ * to fetch bound value(s) from the underlying binding(s). The return value will
+ * be an array if the `bindingSelector` is a `BindingFilter` function.
  */
 export type Getter<T> = () => Promise<T>;
 
@@ -201,10 +203,28 @@ export namespace Getter {
 }
 
 /**
- * The function injected by `@inject.setter(key)`.
+ * The function injected by `@inject.setter(bindingKey)`. It sets the underlying
+ * binding to a constant value using `binding.to(value)`.
+ *
+ * For example:
+ *
+ * ```ts
+ * setterFn('my-value');
+ * ```
+ * @param value The value for the underlying binding
  */
 export type Setter<T> = (value: T) => void;
 
+/**
+ * Metadata for `@inject.binding`
+ */
+export interface InjectBindingMetadata extends InjectionMetadata {
+  /**
+   * Controls how the underlying binding is resolved/created
+   */
+  bindingCreation?: BindingCreationPolicy;
+}
+
 export namespace inject {
   /**
    * Inject a function for getting the actual bound value.
@@ -249,16 +269,49 @@ export namespace inject {
    */
   export const setter = function injectSetter(
     bindingKey: BindingAddress,
-    metadata?: InjectionMetadata,
+    metadata?: InjectBindingMetadata,
   ) {
     metadata = Object.assign({decorator: '@inject.setter'}, metadata);
     return inject(bindingKey, metadata, resolveAsSetter);
   };
 
+  /**
+   * Inject the binding object for the given key. This is useful if a binding
+   * needs to be set up beyond just a constant value allowed by
+   * `@inject.setter`. The injected binding is found or created based on the
+   * `metadata.bindingCreation` option. See `BindingCreationPolicy` for more
+   * details.
+   *
+   * For example:
+   *
+   * ```ts
+   * class MyAuthAction {
+   *   @inject.binding('current-user', {
+   *     bindingCreation: BindingCreationPolicy.ALWAYS_CREATE,
+   *   })
+   *   private userBinding: Binding<UserProfile>;
+   *
+   *   async authenticate() {
+   *     this.userBinding.toDynamicValue(() => {...});
+   *   }
+   * }
+   * ```
+   *
+   * @param bindingKey Binding key
+   * @param metadata Metadata for the injection
+   */
+  export const binding = function injectBinding(
+    bindingKey: BindingAddress,
+    metadata?: InjectBindingMetadata,
+  ) {
+    metadata = Object.assign({decorator: '@inject.binding'}, metadata);
+    return inject(bindingKey, metadata, resolveAsBinding);
+  };
+
   /**
    * Inject an array of values by a tag pattern string or regexp
    *
-   * @example
+   * For example,
    * ```ts
    * class AuthenticationManager {
    *   constructor(
@@ -315,52 +368,98 @@ export namespace inject {
   };
 }
 
+/**
+ * Assert the target type inspected from TypeScript for injection to be the
+ * expected type. If the types don't match, an error is thrown.
+ * @param injection Injection information
+ * @param expectedType Expected type
+ * @param expectedTypeName Name of the expected type to be used in the error
+ * @returns The name of the target
+ */
+export function assertTargetType(
+  injection: Readonly<Injection>,
+  expectedType: Function,
+  expectedTypeName?: string,
+) {
+  const targetName = ResolutionSession.describeInjection(injection).targetName;
+  const targetType = inspectTargetType(injection);
+  if (targetType && targetType !== expectedType) {
+    expectedTypeName = expectedTypeName || expectedType.name;
+    throw new Error(
+      `The type of ${targetName} (${
+        targetType.name
+      }) is not ${expectedTypeName}`,
+    );
+  }
+  return targetName;
+}
+
+/**
+ * Resolver for `@inject.getter`
+ * @param ctx
+ * @param injection
+ * @param session
+ */
 function resolveAsGetter(
   ctx: Context,
   injection: Readonly<Injection>,
-  session?: ResolutionSession,
+  session: ResolutionSession,
 ) {
-  assertTargetIsGetter(injection);
+  assertTargetType(injection, Function, 'Getter function');
   const bindingSelector = injection.bindingSelector as BindingAddress;
   // We need to clone the session for the getter as it will be resolved later
-  session = ResolutionSession.fork(session);
+  const forkedSession = ResolutionSession.fork(session);
   return function getter() {
     return ctx.get(bindingSelector, {
-      session,
+      session: forkedSession,
       optional: injection.metadata.optional,
     });
   };
 }
 
-function assertTargetIsGetter(injection: Readonly<Injection>) {
-  const targetType = inspectTargetType(injection);
-  if (targetType && targetType !== Function) {
-    const targetName = ResolutionSession.describeInjection(injection)!
-      .targetName;
+/**
+ * Resolver for `@inject.setter`
+ * @param ctx
+ * @param injection
+ */
+function resolveAsSetter(ctx: Context, injection: Injection) {
+  const targetName = assertTargetType(injection, Function, 'Setter function');
+  const bindingSelector = injection.bindingSelector;
+  if (!isBindingAddress(bindingSelector)) {
     throw new Error(
-      `The type of ${targetName} (${targetType.name}) is not a Getter function`,
+      `@inject.setter (${targetName}) does not allow BindingFilter.`,
     );
   }
+  // No resolution session should be propagated into the setter
+  return function setter(value: unknown) {
+    const binding = findOrCreateBindingForInjection(ctx, injection);
+    binding.to(value);
+  };
 }
 
-function resolveAsSetter(ctx: Context, injection: Injection) {
-  const targetType = inspectTargetType(injection);
-  const targetName = ResolutionSession.describeInjection(injection)!.targetName;
-  if (targetType && targetType !== Function) {
-    throw new Error(
-      `The type of ${targetName} (${targetType.name}) is not a Setter function`,
-    );
-  }
+function resolveAsBinding(ctx: Context, injection: Injection) {
+  const targetName = assertTargetType(injection, Binding);
   const bindingSelector = injection.bindingSelector;
   if (!isBindingAddress(bindingSelector)) {
     throw new Error(
-      `@inject.setter for (${targetType.name}) does not allow BindingFilter`,
+      `@inject.binding (${targetName}) does not allow BindingFilter.`,
     );
   }
-  // No resolution session should be propagated into the setter
-  return function setter(value: unknown) {
-    ctx.bind(bindingSelector).to(value);
-  };
+  return findOrCreateBindingForInjection(ctx, injection);
+}
+
+function findOrCreateBindingForInjection(
+  ctx: Context,
+  injection: Injection<unknown>,
+) {
+  const bindingCreation =
+    injection.metadata &&
+    (injection.metadata as InjectBindingMetadata).bindingCreation;
+  const binding: Binding<unknown> = ctx.findOrCreateBinding(
+    injection.bindingSelector as BindingAddress,
+    bindingCreation,
+  );
+  return binding;
 }
 
 /**
@@ -396,8 +495,9 @@ export function describeInjectedArguments(
 }
 
 /**
- * Inspect the target type
- * @param injection
+ * Inspect the target type for the injection to find out the corresponding
+ * JavaScript type
+ * @param injection Injection information
  */
 function inspectTargetType(injection: Readonly<Injection>) {
   let type = MetadataInspector.getDesignTypeForProperty(
@@ -427,25 +527,14 @@ function inspectTargetType(injection: Readonly<Injection>) {
 function resolveValuesByFilter(
   ctx: Context,
   injection: Readonly<Injection>,
-  session?: ResolutionSession,
+  session: ResolutionSession,
 ) {
-  assertTargetIsArray(injection);
+  assertTargetType(injection, Array);
   const bindingFilter = injection.bindingSelector as BindingFilter;
   const view = new ContextView(ctx, bindingFilter);
   return view.resolve(session);
 }
 
-function assertTargetIsArray(injection: Readonly<Injection>) {
-  const targetType = inspectTargetType(injection);
-  if (targetType !== Array) {
-    const targetName = ResolutionSession.describeInjection(injection)!
-      .targetName;
-    throw new Error(
-      `The type of ${targetName} (${targetType.name}) is not Array`,
-    );
-  }
-}
-
 /**
  * Resolve to a getter function that returns an array of bound values matching
  * the filter function for `@inject.getter`.
@@ -457,9 +546,9 @@ function assertTargetIsArray(injection: Readonly<Injection>) {
 function resolveAsGetterByFilter(
   ctx: Context,
   injection: Readonly<Injection>,
-  session?: ResolutionSession,
+  session: ResolutionSession,
 ) {
-  assertTargetIsGetter(injection);
+  assertTargetType(injection, Function, 'Getter function');
   const bindingFilter = injection.bindingSelector as BindingFilter;
   return createViewGetter(ctx, bindingFilter, session);
 }
@@ -469,21 +558,9 @@ function resolveAsGetterByFilter(
  * for `@inject.view`
  * @param ctx Context object
  * @param injection Injection information
- * @param session Resolution session
  */
-function resolveAsContextView(
-  ctx: Context,
-  injection: Readonly<Injection>,
-  session?: ResolutionSession,
-) {
-  const targetType = inspectTargetType(injection);
-  if (targetType && targetType !== ContextView) {
-    const targetName = ResolutionSession.describeInjection(injection)!
-      .targetName;
-    throw new Error(
-      `The type of ${targetName} (${targetType.name}) is not ContextView`,
-    );
-  }
+function resolveAsContextView(ctx: Context, injection: Readonly<Injection>) {
+  assertTargetType(injection, ContextView);
 
   const bindingFilter = injection.bindingSelector as BindingFilter;
   const view = new ContextView(ctx, bindingFilter);

package/src/resolution-session.ts

@@ -157,7 +157,7 @@ export class ResolutionSession {
    */
   static describeInjection(injection?: Readonly<Injection>) {
     /* istanbul ignore if */
-    if (injection == null) return undefined;
+    if (injection == null) return {};
     const name = getTargetName(
       injection.target,
       injection.member,