feat(context): use invocation context for method dependency injection

Use case: interceptors may add or change bindings to influence how the
method parameter injection is resolved.

Author: raymondfeng

packages/context/src/__tests__/acceptance/interceptor.acceptance.ts

@@ -367,6 +367,94 @@ describe('Interceptor', () => {
     });
   });
 
+  context('invocation options for invokeMethodWithInterceptors', () => {
+    it('can skip parameter injection', async () => {
+      const controller = givenController();
+
+      ctx.bind('name').to('Jane');
+      const msg = await invokeMethodWithInterceptors(
+        ctx,
+        controller,
+        'greetWithDI',
+        // 'John' is passed in as an arg
+        ['John'],
+        {
+          skipParameterInjection: true,
+        },
+      );
+      expect(msg).to.equal('Hello, John');
+      expect(events).to.eql([
+        'log: before-greetWithDI',
+        'log: after-greetWithDI',
+      ]);
+    });
+
+    it('can support parameter injection', async () => {
+      const controller = givenController();
+      ctx.bind('name').to('Jane');
+      const msg = await invokeMethodWithInterceptors(
+        ctx,
+        controller,
+        'greetWithDI',
+        // No name is passed in here as it will be provided by the injection
+        [],
+        {
+          skipParameterInjection: false,
+        },
+      );
+      // `Jane` is bound to `name` in the current context
+      expect(msg).to.equal('Hello, Jane');
+      expect(events).to.eql([
+        'log: before-greetWithDI',
+        'log: after-greetWithDI',
+      ]);
+    });
+
+    it('does not allow skipInterceptors', async () => {
+      const controller = givenController();
+      expect(() => {
+        invokeMethodWithInterceptors(ctx, controller, 'greetWithDI', ['John'], {
+          skipInterceptors: true,
+        });
+      }).to.throw(/skipInterceptors is not allowed/);
+    });
+
+    function givenController() {
+      class MyController {
+        // Apply `log` to an async instance method with parameter injection
+        @intercept(log)
+        async greetWithDI(@inject('name') name: string) {
+          return `Hello, ${name}`;
+        }
+      }
+      return new MyController();
+    }
+  });
+
+  context('controller method with both interception and injection', () => {
+    it('allows interceptor to influence parameter injection', async () => {
+      const result = await invokeMethodWithInterceptors(
+        ctx,
+        new MyController(),
+        'interceptedHello',
+        [],
+        {skipParameterInjection: false},
+      );
+      // `Mary` is bound to `name` by the interceptor
+      expect(result).to.eql('Hello, Mary');
+    });
+
+    class MyController {
+      @intercept(async (invocationCtx, next) => {
+        invocationCtx.bind('name').to('Mary');
+        return await next();
+      })
+      async interceptedHello(@inject('name') name: string) {
+        return `Hello, ${name}`;
+      }
+    }
+  });
+
   context('class level interceptors', () => {
     it('invokes sync and async interceptors', async () => {
       // Apply `log` to all methods on the class

packages/context/src/__tests__/unit/invocation-context.unit.ts

@@ -4,11 +4,12 @@
 // License text available at https://opensource.org/licenses/MIT
 
 import {expect} from '@loopback/testlab';
-import {Context, InvocationContext} from '../..';
+import {Context, inject, InvocationContext} from '../..';
 
 describe('InvocationContext', () => {
   let ctx: Context;
   let invocationCtxForGreet: InvocationContext;
+  let invocationCtxForHello: InvocationContext;
   let invocationCtxForCheckName: InvocationContext;
   let invalidInvocationCtx: InvocationContext;
   let invalidInvocationCtxForStaticMethod: InvocationContext;
@@ -60,6 +61,14 @@ describe('InvocationContext', () => {
     expect(invocationCtxForCheckName.invokeTargetMethod()).to.eql(true);
   });
 
+  it('invokes target method with injection', async () => {
+    expect(
+      await invocationCtxForHello.invokeTargetMethod({
+        skipParameterInjection: false,
+      }),
+    ).to.eql('Hello, Jane');
+  });
+
   it('does not close when an interceptor is in processing', () => {
     const result = invocationCtxForGreet.invokeTargetMethod();
     expect(invocationCtxForGreet.isBound('abc'));
@@ -75,6 +84,10 @@ describe('InvocationContext', () => {
     async greet(name: string) {
       return `Hello, ${name}`;
     }
+
+    async hello(@inject('name') name: string) {
+      return `Hello, ${name}`;
+    }
   }
 
   function givenContext() {
@@ -90,6 +103,14 @@ describe('InvocationContext', () => {
       ['John'],
     );
 
+    invocationCtxForHello = new InvocationContext(
+      ctx,
+      new MyController(),
+      'hello',
+      [],
+    );
+    invocationCtxForHello.bind('name').to('Jane');
+
     invocationCtxForCheckName = new InvocationContext(
       ctx,
       MyController,

packages/context/src/interceptor.ts

@@ -11,6 +11,7 @@ import {
   MetadataMap,
   MethodDecoratorFactory,
 } from '@loopback/metadata';
+import * as assert from 'assert';
 import * as debugFactory from 'debug';
 import {Binding, BindingTemplate} from './binding';
 import {bind} from './binding-decorator';
@@ -26,6 +27,7 @@ import {
 import {
   InvocationArgs,
   InvocationContext,
+  InvocationOptions,
   InvocationResult,
 } from './invocation';
 import {
@@ -284,13 +286,18 @@ export function intercept(...interceptorOrKeys: InterceptorOrKey[]) {
  * @param target - Target class (for static methods) or object (for instance methods)
  * @param methodName - Method name
  * @param args - An array of argument values
+ * @param options - Options for the invocation
  */
 export function invokeMethodWithInterceptors(
   context: Context,
   target: object,
   methodName: string,
   args: InvocationArgs,
+  options: InvocationOptions = {},
 ): ValueOrPromise<InvocationResult> {
+  // Do not allow `skipInterceptors` as it's against the function name
+  // `invokeMethodWithInterceptors`
+  assert(!options.skipInterceptors, 'skipInterceptors is not allowed');
   const invocationCtx = new InterceptedInvocationContext(
     context,
     target,
@@ -302,7 +309,8 @@ export function invokeMethodWithInterceptors(
   return tryWithFinally(
     () => {
       const interceptors = invocationCtx.loadInterceptors();
-      const targetMethodInvoker = () => invocationCtx.invokeTargetMethod();
+      const targetMethodInvoker = () =>
+        invocationCtx.invokeTargetMethod(options);
       interceptors.push(targetMethodInvoker);
       return invokeInterceptors(invocationCtx, interceptors);
     },

packages/context/src/invocation.ts

@@ -94,9 +94,20 @@ export class InvocationContext extends Context {
   /**
    * Invoke the target method with the given context
    * @param context - Invocation context
+   * @param options - Options for the invocation
    */
-  invokeTargetMethod() {
+  invokeTargetMethod(
+    options: InvocationOptions = {skipParameterInjection: true},
+  ) {
     const targetWithMethods = this.assertMethodExists();
+    if (!options.skipParameterInjection) {
+      return invokeTargetMethodWithInjection(
+        this,
+        targetWithMethods,
+        this.methodName,
+        this.args,
+      );
+    }
     return invokeTargetMethod(
       this,
       targetWithMethods,
@@ -137,44 +148,38 @@ export function invokeMethod(
   nonInjectedArgs: InvocationArgs = [],
   options: InvocationOptions = {},
 ): ValueOrPromise<InvocationResult> {
-  if (options.skipParameterInjection) {
-    if (options.skipInterceptors) {
+  if (options.skipInterceptors) {
+    if (options.skipParameterInjection) {
       // Invoke the target method directly without injection or interception
       return invokeTargetMethod(ctx, target, method, nonInjectedArgs);
     } else {
-      // Invoke the target method with interception but no injection
-      return invokeMethodWithInterceptors(ctx, target, method, nonInjectedArgs);
+      return invokeTargetMethodWithInjection(
+        ctx,
+        target,
+        method,
+        nonInjectedArgs,
+      );
     }
   }
-  // Parameter injection is required
-  const invoker = options.skipInterceptors
-    ? invokeTargetMethod
-    : invokeMethodWithInterceptors;
-  return invokeMethodWithInvoker(invoker, ctx, target, method, nonInjectedArgs);
+  // Invoke the target method with interception but no injection
+  return invokeMethodWithInterceptors(
+    ctx,
+    target,
+    method,
+    nonInjectedArgs,
+    options,
+  );
 }
 
 /**
- * An invoker for a method within the given context and arguments
- */
-type MethodInvoker = (
-  ctx: Context,
-  target: Record<string, Function>,
-  methodName: string,
-  args: InvocationArgs,
-) => ValueOrPromise<InvocationResult>;
-
-/**
- * Invoke a method with the given invoker. Method parameter dependency injection
- * is honored.
- * @param invoker - Method invoker
+ * Invoke a method. Method parameter dependency injection is honored.
  * @param target - Target of the method, it will be the class for a static
  * method, and instance or class prototype for a prototype method
  * @param method - Name of the method
  * @param ctx - Context
  * @param nonInjectedArgs - Optional array of args for non-injected parameters
  */
-function invokeMethodWithInvoker(
-  invoker: MethodInvoker,
+function invokeTargetMethodWithInjection(
   ctx: Context,
   target: object,
   method: string,
@@ -205,7 +210,7 @@ function invokeMethodWithInvoker(
     if (debug.enabled) {
       debug('Injected arguments for %s:', methodName, args);
     }
-    return invoker(ctx, targetWithMethods, method, args);
+    return invokeTargetMethod(ctx, targetWithMethods, method, args);
   });
 }