@loopback/context 1.8.1 → 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,8 +20,8 @@ import {
   isBindingAddress,
 } from './binding-filter';
 import {BindingAddress} from './binding-key';
-import {Context} from './context';
-import {ContextView} from './context-view';
+import {BindingCreationPolicy, Context} from './context';
+import {ContextView, createViewGetter} from './context-view';
 import {ResolutionSession} from './resolution-session';
 import {BoundValue, ValueOrPromise} from './value-promise';
 
@@ -39,7 +39,7 @@ export interface ResolverFunction {
   (
     ctx: Context,
     injection: Readonly<Injection>,
-    session?: ResolutionSession,
+    session: ResolutionSession,
   ): ValueOrPromise<BoundValue>;
 }
 
@@ -73,7 +73,7 @@ export interface Injection<ValueType = BoundValue> {
     | number;
 
   bindingSelector: BindingSelector<ValueType>; // Binding selector
-  metadata?: InjectionMetadata; // Related metadata
+  metadata: InjectionMetadata; // Related metadata
   resolve?: ResolverFunction; // A custom resolve function
 }
 
@@ -111,7 +111,7 @@ export function inject(
   if (typeof bindingSelector === 'function' && !resolve) {
     resolve = resolveValuesByFilter;
   }
-  metadata = Object.assign({decorator: '@inject'}, metadata);
+  const injectionMetadata = Object.assign({decorator: '@inject'}, metadata);
   return function markParameterOrPropertyAsInjected(
     target: Object,
     member: string,
@@ -131,7 +131,7 @@ export function inject(
           member,
           methodDescriptorOrParameterIndex,
           bindingSelector,
-          metadata,
+          metadata: injectionMetadata,
           resolve,
         },
         // Do not deep clone the spec as only metadata is mutable and it's
@@ -167,7 +167,7 @@ export function inject(
           member,
           methodDescriptorOrParameterIndex,
           bindingSelector,
-          metadata,
+          metadata: injectionMetadata,
           resolve,
         },
         // Do not deep clone the spec as only metadata is mutable and it's
@@ -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,
-      optional: injection.metadata && injection.metadata.optional,
+      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,13 +546,11 @@ 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;
-  const view = new ContextView(ctx, bindingFilter);
-  view.open();
-  return view.asGetter(session);
+  return createViewGetter(ctx, bindingFilter, session);
 }
 
 /**
@@ -471,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

@@ -3,24 +3,20 @@
 // This file is licensed under the MIT License.
 // License text available at https://opensource.org/licenses/MIT
 
+import {DecoratorFactory} from '@loopback/metadata';
+import * as debugModule from 'debug';
 import {Binding} from './binding';
 import {Injection} from './inject';
-import {ValueOrPromise, BoundValue, tryWithFinally} from './value-promise';
-import * as debugModule from 'debug';
-import {DecoratorFactory} from '@loopback/metadata';
+import {BoundValue, tryWithFinally, ValueOrPromise} from './value-promise';
 
 const debugSession = debugModule('loopback:context:resolver:session');
 const getTargetName = DecoratorFactory.getTargetName;
 
-// NOTE(bajtos) The following import is required to satisfy TypeScript compiler
-// tslint:disable-next-line:no-unused
-import {BindingKey} from './binding-key';
-
 /**
  * A function to be executed with the resolution session
  */
 export type ResolutionAction = (
-  session?: ResolutionSession,
+  session: ResolutionSession,
 ) => ValueOrPromise<BoundValue>;
 
 /**
@@ -161,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,
@@ -169,7 +165,7 @@ export class ResolutionSession {
     );
     return {
       targetName: name,
-      bindingKey: injection.bindingSelector,
+      bindingSelector: injection.bindingSelector,
       // Cast to Object so that we don't have to expose InjectionMetadata
       metadata: injection.metadata as Object,
     };
@@ -343,3 +339,22 @@ export interface ResolutionOptions {
    */
   optional?: boolean;
 }
+
+/**
+ * Resolution options or session
+ */
+export type ResolutionOptionsOrSession = ResolutionOptions | ResolutionSession;
+
+/**
+ * Normalize ResolutionOptionsOrSession to ResolutionOptions
+ * @param optionsOrSession resolution options or session
+ */
+export function asResolutionOptions(
+  optionsOrSession?: ResolutionOptionsOrSession,
+): ResolutionOptions {
+  // backwards compatibility
+  if (optionsOrSession instanceof ResolutionSession) {
+    return {session: optionsOrSession};
+  }
+  return optionsOrSession || {};
+}

package/src/resolver.ts

@@ -55,7 +55,13 @@ export function instantiateClass<T>(
       debug('Non-injected arguments:', nonInjectedArgs);
     }
   }
-  const argsOrPromise = resolveInjectedArguments(ctor, '', ctx, session);
+  const argsOrPromise = resolveInjectedArguments(
+    ctor,
+    '',
+    ctx,
+    session,
+    nonInjectedArgs,
+  );
   const propertiesOrPromise = resolveInjectedProperties(ctor, ctx, session);
   const inst: ValueOrPromise<T> = transformValueOrPromise(
     argsOrPromise,
@@ -146,7 +152,7 @@ function resolve<T>(
           session: s,
           // If the `optional` flag is set for the injection, the resolution
           // will return `undefined` instead of throwing an error
-          optional: injection.metadata && injection.metadata.optional,
+          optional: injection.metadata.optional,
         });
       }
     },