@loopback/context 1.23.4 → 1.25.1

package/src/context.ts

@@ -3,7 +3,7 @@
 // This file is licensed under the MIT License.
 // License text available at https://opensource.org/licenses/MIT
 
-import * as debugFactory from 'debug';
+import debugFactory from 'debug';
 import {EventEmitter} from 'events';
 import {v1 as uuidv1} from 'uuid';
 import {Binding, BindingTag} from './binding';
@@ -133,7 +133,7 @@ export class Context extends EventEmitter {
       _parent = undefined;
     }
     this._parent = _parent;
-    this.name = name || uuidv1();
+    this.name = name ?? uuidv1();
   }
 
   /**
@@ -186,7 +186,7 @@ export class Context extends EventEmitter {
     if (this._parent == null) return;
 
     // Keep track of parent event listeners so that we can remove them
-    this._parentEventListeners = this._parentEventListeners || new Map();
+    this._parentEventListeners = this._parentEventListeners ?? new Map();
     if (this._parentEventListeners.has(event)) return;
 
     const parentEventListener = (
@@ -350,7 +350,7 @@ export class Context extends EventEmitter {
     const keyExists = this.registry.has(key);
     if (keyExists) {
       existingBinding = this.registry.get(key);
-      const bindingIsLocked = existingBinding && existingBinding.isLocked;
+      const bindingIsLocked = existingBinding?.isLocked;
       if (bindingIsLocked)
         throw new Error(`Cannot rebind key "${key}" to a locked binding`);
     }
@@ -502,7 +502,7 @@ export class Context extends EventEmitter {
     const binding = this.registry.get(key);
     // If not found, return `false`
     if (binding == null) return false;
-    if (binding && binding.isLocked)
+    if (binding?.isLocked)
       throw new Error(`Cannot unbind key "${key}" of a locked binding`);
     this.registry.delete(key);
     this.emit('unbind', binding, this);
@@ -514,7 +514,7 @@ export class Context extends EventEmitter {
    * @param observer - Context observer instance or function
    */
   subscribe(observer: ContextEventObserver): Subscription {
-    this.observers = this.observers || new Set();
+    this.observers = this.observers ?? new Set();
     this.setupEventHandlersIfNeeded();
     this.observers.add(observer);
     return new ContextSubscription(this, observer);
@@ -885,7 +885,7 @@ export class Context extends EventEmitter {
       return this._parent.getBinding<ValueType>(key, options);
     }
 
-    if (options && options.optional) return undefined;
+    if (options?.optional) return undefined;
     throw new Error(
       `The key '${key}' is not bound to any value in context ${this.name}`,
     );
@@ -968,10 +968,26 @@ export class Context extends EventEmitter {
   /**
    * Create a plain JSON object for the context
    */
-  toJSON(): Object {
-    const json: {[key: string]: Object} = {};
+  toJSON(): object {
+    const bindings: Record<string, object> = {};
     for (const [k, v] of this.registry) {
-      json[k] = v.toJSON();
+      bindings[k] = v.toJSON();
+    }
+    return bindings;
+  }
+
+  /**
+   * Inspect the context and dump out a JSON object representing the context
+   * hierarchy
+   */
+  // TODO(rfeng): Evaluate https://nodejs.org/api/util.html#util_custom_inspection_functions_on_objects
+  inspect(): object {
+    const json: Record<string, unknown> = {
+      name: this.name,
+      bindings: this.toJSON(),
+    };
+    if (this._parent) {
+      json.parent = this._parent.inspect();
     }
     return json;
   }

package/src/index.ts

@@ -14,14 +14,14 @@ export * from './binding-sorter';
 export * from './context';
 export * from './context-observer';
 export * from './context-view';
-export * from './interceptor-chain';
 export * from './inject';
+export * from './inject-config';
 export * from './interception-proxy';
 export * from './interceptor';
-export * from './inject-config';
+export * from './interceptor-chain';
+export * from './invocation';
 export * from './keys';
 export * from './provider';
 export * from './resolution-session';
 export * from './resolver';
 export * from './value-promise';
-export * from './invocation';

package/src/inject-config.ts

@@ -65,7 +65,7 @@ export function config(
   propertyPath?: string | ConfigInjectionMetadata,
   metadata?: ConfigInjectionMetadata,
 ) {
-  propertyPath = propertyPath || '';
+  propertyPath = propertyPath ?? '';
   if (typeof propertyPath === 'object') {
     metadata = propertyPath;
     propertyPath = '';
@@ -87,7 +87,7 @@ export namespace config {
     propertyPath?: string | ConfigInjectionMetadata,
     metadata?: ConfigInjectionMetadata,
   ) {
-    propertyPath = propertyPath || '';
+    propertyPath = propertyPath ?? '';
     if (typeof propertyPath === 'object') {
       metadata = propertyPath;
       propertyPath = '';
@@ -109,7 +109,7 @@ export namespace config {
     propertyPath?: string | ConfigInjectionMetadata,
     metadata?: ConfigInjectionMetadata,
   ) {
-    propertyPath = propertyPath || '';
+    propertyPath = propertyPath ?? '';
     if (typeof propertyPath === 'object') {
       metadata = propertyPath;
       propertyPath = '';

package/src/inject.ts

@@ -311,11 +311,11 @@ export namespace inject {
    * @param metadata - Metadata for the injection
    */
   export const binding = function injectBinding(
-    bindingKey: BindingAddress,
+    bindingKey?: BindingAddress,
     metadata?: InjectBindingMetadata,
   ) {
     metadata = Object.assign({decorator: '@inject.binding'}, metadata);
-    return inject(bindingKey, metadata, resolveAsBinding);
+    return inject(bindingKey ?? '', metadata, resolveAsBinding);
   };
 
   /**
@@ -395,7 +395,7 @@ export function assertTargetType(
   const targetName = ResolutionSession.describeInjection(injection).targetName;
   const targetType = inspectTargetType(injection);
   if (targetType && targetType !== expectedType) {
-    expectedTypeName = expectedTypeName || expectedType.name;
+    expectedTypeName = expectedTypeName ?? expectedType.name;
     throw new Error(
       `The type of ${targetName} (${targetType.name}) is not ${expectedTypeName}`,
     );
@@ -440,14 +440,21 @@ function resolveAsSetter(ctx: Context, injection: Injection) {
       `@inject.setter (${targetName}) does not allow BindingFilter.`,
     );
   }
+  if (bindingSelector === '') {
+    throw new Error('Binding key is not set for @inject.setter');
+  }
   // No resolution session should be propagated into the setter
   return function setter(value: unknown) {
     const binding = findOrCreateBindingForInjection(ctx, injection);
-    binding.to(value);
+    binding!.to(value);
   };
 }
 
-function resolveAsBinding(ctx: Context, injection: Injection) {
+function resolveAsBinding(
+  ctx: Context,
+  injection: Injection,
+  session: ResolutionSession,
+) {
   const targetName = assertTargetType(injection, Binding);
   const bindingSelector = injection.bindingSelector;
   if (!isBindingAddress(bindingSelector)) {
@@ -455,13 +462,15 @@ function resolveAsBinding(ctx: Context, injection: Injection) {
       `@inject.binding (${targetName}) does not allow BindingFilter.`,
     );
   }
-  return findOrCreateBindingForInjection(ctx, injection);
+  return findOrCreateBindingForInjection(ctx, injection, session);
 }
 
 function findOrCreateBindingForInjection(
   ctx: Context,
   injection: Injection<unknown>,
+  session?: ResolutionSession,
 ) {
+  if (injection.bindingSelector === '') return session?.currentBinding;
   const bindingCreation =
     injection.metadata &&
     (injection.metadata as InjectBindingMetadata).bindingCreation;
@@ -544,7 +553,7 @@ export function describeInjectedArguments(
   target: Object,
   method?: string,
 ): Readonly<Injection>[] {
-  method = method || '';
+  method = method ?? '';
 
   // Try to read from cache
   const cache =
@@ -554,7 +563,7 @@ export function describeInjectedArguments(
       {
         ownMetadataOnly: true,
       },
-    ) || {};
+    ) ?? {};
   let meta: Readonly<Injection>[] = cache[method];
   if (meta) return meta;
 
@@ -575,7 +584,7 @@ export function describeInjectedArguments(
       target,
       method,
       options,
-    ) || [];
+    ) ?? [];
 
   // Cache the result
   cache[method] = meta;
@@ -686,6 +695,6 @@ export function describeInjectedProperties(
     MetadataInspector.getAllPropertyMetadata<Readonly<Injection>>(
       PROPERTIES_KEY,
       target,
-    ) || {};
+    ) ?? {};
   return metadata;
 }

package/src/interception-proxy.ts

@@ -5,7 +5,8 @@
 
 import {Context} from './context';
 import {invokeMethodWithInterceptors} from './interceptor';
-import {InvocationArgs} from './invocation';
+import {InvocationArgs, InvocationSource} from './invocation';
+import {ResolutionSession} from './resolution-session';
 import {ValueOrPromise} from './value-promise';
 
 /**
@@ -57,13 +58,29 @@ export type AsInterceptedFunction<T> = T extends (
  */
 export type AsyncProxy<T> = {[P in keyof T]: AsInterceptedFunction<T[P]>};
 
+/**
+ * Invocation source for injected proxies. It wraps a snapshot of the
+ * `ResolutionSession` that tracks the binding/injection stack.
+ */
+export class ProxySource implements InvocationSource<ResolutionSession> {
+  type = 'proxy';
+  constructor(readonly value: ResolutionSession) {}
+
+  toString() {
+    return this.value.getBindingPath();
+  }
+}
+
 /**
  * A proxy handler that applies interceptors
  *
  * See https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Proxy
  */
 export class InterceptionHandler<T extends object> implements ProxyHandler<T> {
-  constructor(private context = new Context()) {}
+  constructor(
+    private context = new Context(),
+    private session?: ResolutionSession,
+  ) {}
 
   get(target: T, propertyName: PropertyKey, receiver: unknown) {
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -77,6 +94,7 @@ export class InterceptionHandler<T extends object> implements ProxyHandler<T> {
           target,
           propertyName,
           args,
+          {source: this.session && new ProxySource(this.session)},
         );
       };
     } else {
@@ -93,6 +111,10 @@ export class InterceptionHandler<T extends object> implements ProxyHandler<T> {
 export function createProxyWithInterceptors<T extends object>(
   target: T,
   context?: Context,
+  session?: ResolutionSession,
 ): AsyncProxy<T> {
-  return new Proxy(target, new InterceptionHandler(context)) as AsyncProxy<T>;
+  return new Proxy(
+    target,
+    new InterceptionHandler(context, ResolutionSession.fork(session)),
+  ) as AsyncProxy<T>;
 }

package/src/interceptor-chain.ts

@@ -3,7 +3,7 @@
 // This file is licensed under the MIT License.
 // License text available at https://opensource.org/licenses/MIT
 
-import * as debugFactory from 'debug';
+import debugFactory from 'debug';
 import {BindingFilter} from './binding-filter';
 import {BindingAddress} from './binding-key';
 import {BindingComparator} from './binding-sorter';

package/src/interceptor.ts

@@ -11,8 +11,8 @@ import {
   MetadataMap,
   MethodDecoratorFactory,
 } from '@loopback/metadata';
-import * as assert from 'assert';
-import * as debugFactory from 'debug';
+import assert from 'assert';
+import debugFactory from 'debug';
 import {Binding, BindingTemplate} from './binding';
 import {bind} from './binding-decorator';
 import {filterByTag} from './binding-filter';
@@ -48,7 +48,10 @@ export class InterceptedInvocationContext extends InvocationContext {
    */
   getGlobalInterceptorBindingKeys(): string[] {
     const bindings: Readonly<Binding<Interceptor>>[] = this.find(
-      filterByTag(ContextTags.GLOBAL_INTERCEPTOR),
+      binding =>
+        filterByTag(ContextTags.GLOBAL_INTERCEPTOR)(binding) &&
+        // Only include interceptors that match the source type of the invocation
+        this.applicableTo(binding),
     );
     this.sortGlobalInterceptorBindings(bindings);
     const keys = bindings.map(b => b.key);
@@ -56,6 +59,27 @@ export class InterceptedInvocationContext extends InvocationContext {
     return keys;
   }
 
+  /**
+   * Check if the binding for a global interceptor matches the source type
+   * of the invocation
+   * @param binding - Binding
+   */
+  private applicableTo(binding: Readonly<Binding<unknown>>) {
+    const sourceType = this.source?.type;
+    // Unknown source type, always apply
+    if (sourceType == null) return true;
+    const allowedSource: string | string[] =
+      binding.tagMap[ContextTags.GLOBAL_INTERCEPTOR_SOURCE];
+    return (
+      // No tag, always apply
+      allowedSource == null ||
+      // source matched
+      allowedSource === sourceType ||
+      // source included in the string[]
+      (Array.isArray(allowedSource) && allowedSource.includes(sourceType))
+    );
+  }
+
   /**
    * Sort global interceptor bindings by `globalInterceptorGroup` tags
    * @param bindings - An array of global interceptor bindings
@@ -67,7 +91,7 @@ export class InterceptedInvocationContext extends InvocationContext {
     const orderedGroups =
       this.getSync(ContextBindings.GLOBAL_INTERCEPTOR_ORDERED_GROUPS, {
         optional: true,
-      }) || [];
+      }) ?? [];
     return sortBindingsByPhase(
       bindings,
       ContextTags.GLOBAL_INTERCEPTOR_GROUP,
@@ -88,11 +112,11 @@ export class InterceptedInvocationContext extends InvocationContext {
         INTERCEPT_METHOD_KEY,
         this.target,
         this.methodName,
-      ) || [];
+      ) ?? [];
     const targetClass =
       typeof this.target === 'function' ? this.target : this.target.constructor;
     const classInterceptors =
-      MetadataInspector.getClassMetadata(INTERCEPT_CLASS_KEY, targetClass) ||
+      MetadataInspector.getClassMetadata(INTERCEPT_CLASS_KEY, targetClass) ??
       [];
     // Inserting class level interceptors before method level ones
     interceptors = mergeInterceptors(classInterceptors, interceptors);
@@ -305,6 +329,7 @@ export function invokeMethodWithInterceptors(
     target,
     methodName,
     args,
+    options.source,
   );
 
   invocationCtx.assertMethodExists();

package/src/invocation.ts

@@ -4,8 +4,8 @@
 // License text available at https://opensource.org/licenses/MIT
 
 import {DecoratorFactory} from '@loopback/metadata';
-import * as assert from 'assert';
-import * as debugFactory from 'debug';
+import assert from 'assert';
+import debugFactory from 'debug';
 import {Context} from './context';
 import {invokeMethodWithInterceptors} from './interceptor';
 import {resolveInjectedArguments} from './resolver';
@@ -26,6 +26,20 @@ export type InvocationResult = any;
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export type InvocationArgs = any[];
 
+/**
+ * An interface to represent the caller of the invocation
+ */
+export interface InvocationSource<T = unknown> {
+  /**
+   * Type of the invoker, such as `proxy` and `route`
+   */
+  readonly type: string;
+  /**
+   * Metadata for the source, such as `ResolutionSession`
+   */
+  readonly value: T;
+}
+
 /**
  * InvocationContext represents the context to invoke interceptors for a method.
  * The context can be used to access metadata about the invocation as well as
@@ -47,6 +61,7 @@ export class InvocationContext extends Context {
     public readonly target: object,
     public readonly methodName: string,
     public readonly args: InvocationArgs,
+    public readonly source?: InvocationSource,
   ) {
     super(parent);
   }
@@ -71,7 +86,8 @@ export class InvocationContext extends Context {
    * Description of the invocation
    */
   get description() {
-    return `InvocationContext(${this.name}): ${this.targetName}`;
+    const source = this.source == null ? '' : `${this.source} => `;
+    return `InvocationContext(${this.name}): ${source}${this.targetName}`;
   }
 
   toString() {
@@ -129,6 +145,11 @@ export type InvocationOptions = {
    * Skip invocation of interceptors
    */
   skipInterceptors?: boolean;
+  /**
+   * Information about the source object that makes the invocation. For REST,
+   * it's a `Route`. For injected proxies, it's a `Binding`.
+   */
+  source?: InvocationSource;
 };
 
 /**
@@ -189,7 +210,7 @@ function invokeTargetMethodWithInjection(
   /* istanbul ignore if */
   if (debug.enabled) {
     debug('Invoking method %s', methodName);
-    if (nonInjectedArgs && nonInjectedArgs.length) {
+    if (nonInjectedArgs?.length) {
       debug('Non-injected arguments:', nonInjectedArgs);
     }
   }

package/src/keys.ts

@@ -40,6 +40,13 @@ export namespace ContextTags {
    */
   export const GLOBAL_INTERCEPTOR = 'globalInterceptor';
 
+  /**
+   * Binding tag for global interceptors to specify sources of invocations that
+   * the interceptor should apply. The tag value can be a string or string[], such
+   * as `'route'` or `['route', 'proxy']`.
+   */
+  export const GLOBAL_INTERCEPTOR_SOURCE = 'globalInterceptorSource';
+
   /**
    * Binding tag for group name of global interceptors
    */

package/src/resolution-session.ts

@@ -4,7 +4,7 @@
 // License text available at https://opensource.org/licenses/MIT
 
 import {DecoratorFactory} from '@loopback/metadata';
-import * as debugModule from 'debug';
+import debugModule from 'debug';
 import {Binding} from './binding';
 import {Injection} from './inject';
 import {BoundValue, tryWithFinally, ValueOrPromise} from './value-promise';
@@ -93,7 +93,7 @@ export class ResolutionSession {
     binding: Readonly<Binding>,
     session?: ResolutionSession,
   ): ResolutionSession {
-    session = session || new ResolutionSession();
+    session = session ?? new ResolutionSession();
     session.pushBinding(binding);
     return session;
   }
@@ -125,7 +125,7 @@ export class ResolutionSession {
     injection: Readonly<Injection>,
     session?: ResolutionSession,
   ): ResolutionSession {
-    session = session || new ResolutionSession();
+    session = session ?? new ResolutionSession();
     session.pushInjection(injection);
     return session;
   }
@@ -268,7 +268,7 @@ export class ResolutionSession {
     const binding = top.value;
     /* istanbul ignore if */
     if (debugSession.enabled) {
-      debugSession('Exit binding:', binding && binding.toJSON());
+      debugSession('Exit binding:', binding?.toJSON());
       debugSession('Resolution path:', this.getResolutionPath() || '<empty>');
     }
     return binding;
@@ -321,6 +321,10 @@ export class ResolutionSession {
   getResolutionPath() {
     return this.stack.map(i => ResolutionSession.describe(i)).join(' --> ');
   }
+
+  toString() {
+    return this.getResolutionPath();
+  }
 }
 
 /**
@@ -363,5 +367,5 @@ export function asResolutionOptions(
   if (optionsOrSession instanceof ResolutionSession) {
     return {session: optionsOrSession};
   }
-  return optionsOrSession || {};
+  return optionsOrSession ?? {};
 }

package/src/resolver.ts

@@ -4,8 +4,8 @@
 // License text available at https://opensource.org/licenses/MIT
 
 import {DecoratorFactory} from '@loopback/metadata';
-import * as assert from 'assert';
-import * as debugModule from 'debug';
+import assert from 'assert';
+import debugModule from 'debug';
 import {BindingScope} from './binding';
 import {isBindingAddress} from './binding-filter';
 import {BindingAddress} from './binding-key';
@@ -51,7 +51,7 @@ export function instantiateClass<T>(
   /* istanbul ignore if */
   if (debug.enabled) {
     debug('Instantiating %s', getTargetName(ctor));
-    if (nonInjectedArgs && nonInjectedArgs.length) {
+    if (nonInjectedArgs?.length) {
       debug('Non-injected arguments:', nonInjectedArgs);
     }
   }
@@ -93,7 +93,7 @@ function resolveContext(
   injection: Readonly<Injection>,
   session?: ResolutionSession,
 ) {
-  const currentBinding = session && session.currentBinding;
+  const currentBinding = session?.currentBinding;
   if (
     currentBinding == null ||
     currentBinding.scope !== BindingScope.SINGLETON
@@ -201,7 +201,7 @@ export function resolveInjectedArguments(
   // Example value:
   //   [ , 'key1', , 'key2']
   const injectedArgs = describeInjectedArguments(target, method);
-  const extraArgs = nonInjectedArgs || [];
+  const extraArgs = nonInjectedArgs ?? [];
 
   let argLength = DecoratorFactory.getNumberOfParameters(target, method);