@loopback/context 3.5.1 → 3.8.1

package/src/binding.ts

@@ -9,11 +9,13 @@ import {BindingAddress, BindingKey} from './binding-key';
 import {Context} from './context';
 import {inspectInjections} from './inject';
 import {createProxyWithInterceptors} from './interception-proxy';
+import {invokeMethod} from './invocation';
 import {JSONObject} from './json-types';
 import {ContextTags} from './keys';
 import {Provider} from './provider';
 import {
   asResolutionOptions,
+  ResolutionContext,
   ResolutionOptions,
   ResolutionOptionsOrSession,
   ResolutionSession,
@@ -129,6 +131,56 @@ export enum BindingType {
   ALIAS = 'Alias',
 }
 
+/**
+ * Binding source for `to`
+ */
+export type ConstantBindingSource<T> = {
+  type: BindingType.CONSTANT;
+  value: T;
+};
+
+/**
+ * Binding source for `toDynamicValue`
+ */
+export type DynamicValueBindingSource<T> = {
+  type: BindingType.DYNAMIC_VALUE;
+  value: ValueFactory<T> | DynamicValueProviderClass<T>;
+};
+
+/**
+ * Binding source for `toClass`
+ */
+export type ClassBindingSource<T> = {
+  type: BindingType.CLASS;
+  value: Constructor<T>;
+};
+
+/**
+ * Binding source for `toProvider`
+ */
+export type ProviderBindingSource<T> = {
+  type: BindingType.PROVIDER;
+  value: Constructor<Provider<T>>;
+};
+
+/**
+ * Binding source for `toAlias`
+ */
+export type AliasBindingSource<T> = {
+  type: BindingType.ALIAS;
+  value: BindingAddress<T>;
+};
+
+/**
+ * Source for the binding, including the type and value
+ */
+export type BindingSource<T> =
+  | ConstantBindingSource<T>
+  | DynamicValueBindingSource<T>
+  | ClassBindingSource<T>
+  | ProviderBindingSource<T>
+  | AliasBindingSource<T>;
+
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export type TagMap = MapObject<any>;
 
@@ -170,11 +222,62 @@ export type BindingEventListener = (
   event: BindingEvent,
 ) => void;
 
-type ValueGetter<T> = (
-  ctx: Context,
-  options: ResolutionOptions,
+/**
+ * A factory function for `toDynamicValue`
+ */
+export type ValueFactory<T = unknown> = (
+  resolutionCtx: ResolutionContext,
 ) => ValueOrPromise<T | undefined>;
 
+/**
+ * A class with a static `value` method as the factory function for
+ * `toDynamicValue`.
+ *
+ * @example
+ * ```ts
+ * import {inject} from '@loopback/context';
+ *
+ * export class DynamicGreetingProvider {
+ *   static value(@inject('currentUser') user: string) {
+ *     return `Hello, ${user}`;
+ *   }
+ * }
+ * ```
+ */
+export interface DynamicValueProviderClass<T = unknown>
+  extends Constructor<unknown>,
+    Function {
+  value: (...args: BoundValue[]) => ValueOrPromise<T>;
+}
+
+/**
+ * Adapt the ValueFactoryProvider class to be a value factory
+ * @param provider - ValueFactoryProvider class
+ */
+function toValueFactory<T = unknown>(
+  provider: DynamicValueProviderClass<T>,
+): ValueFactory<T> {
+  return resolutionCtx =>
+    invokeMethod(provider, 'value', resolutionCtx.context, [], {
+      skipInterceptors: true,
+    });
+}
+
+/**
+ * Check if the factory is a value factory provider class
+ * @param factory - A factory function or a dynamic value provider class
+ */
+export function isDynamicValueProviderClass<T = unknown>(
+  factory: unknown,
+): factory is DynamicValueProviderClass<T> {
+  // Not a class
+  if (typeof factory !== 'function' || !String(factory).startsWith('class ')) {
+    return false;
+  }
+  const valueMethod = (factory as DynamicValueProviderClass).value;
+  return typeof valueMethod === 'function';
+}
+
 /**
  * Binding represents an entry in the `Context`. Each binding has a key and a
  * corresponding value getter.
@@ -199,27 +302,34 @@ export class Binding<T = BoundValue> extends EventEmitter {
     return this._scope ?? BindingScope.TRANSIENT;
   }
 
-  private _type?: BindingType;
   /**
    * Type of the binding value getter
    */
   public get type(): BindingType | undefined {
-    return this._type;
+    return this._source?.type;
   }
 
   private _cache: WeakMap<Context, T>;
-  private _getValue: ValueGetter<T>;
+  private _getValue?: ValueFactory<T>;
 
-  private _valueConstructor?: Constructor<T>;
-  private _providerConstructor?: Constructor<Provider<T>>;
-  private _alias?: BindingAddress<T>;
+  /**
+   * The original source value received from `to`, `toClass`, `toDynamicValue`,
+   * `toProvider`, or `toAlias`.
+   */
+  private _source?: BindingSource<T>;
+
+  public get source() {
+    return this._source;
+  }
 
   /**
    * For bindings bound via `toClass()`, this property contains the constructor
    * function of the class
    */
   public get valueConstructor(): Constructor<T> | undefined {
-    return this._valueConstructor;
+    return this._source?.type === BindingType.CLASS
+      ? this._source?.value
+      : undefined;
   }
 
   /**
@@ -227,7 +337,9 @@ export class Binding<T = BoundValue> extends EventEmitter {
    * constructor function of the provider class
    */
   public get providerConstructor(): Constructor<Provider<T>> | undefined {
-    return this._providerConstructor;
+    return this._source?.type === BindingType.PROVIDER
+      ? this._source?.value
+      : undefined;
   }
 
   constructor(key: BindingAddress<T>, public isLocked: boolean = false) {
@@ -269,6 +381,28 @@ export class Binding<T = BoundValue> extends EventEmitter {
     this._cache = new WeakMap();
   }
 
+  /**
+   * Invalidate the binding cache so that its value will be reloaded next time.
+   * This is useful to force reloading a singleton when its configuration or
+   * dependencies are changed.
+   * **WARNING**: The state held in the cached value will be gone.
+   *
+   * @param ctx - Context object
+   */
+  refresh(ctx: Context) {
+    if (!this._cache) return;
+    if (this.scope === BindingScope.SINGLETON) {
+      // Cache the value
+      const ownerCtx = ctx.getOwnerContext(this.key);
+      if (ownerCtx != null) {
+        this._cache.delete(ownerCtx);
+      }
+    } else if (this.scope === BindingScope.CONTEXT) {
+      // Cache the value at the current context
+      this._cache.delete(ctx);
+    }
+  }
+
   /**
    * This is an internal function optimized for performance.
    * Users should use `@inject(key)` or `ctx.get(key)` instead.
@@ -331,11 +465,17 @@ export class Binding<T = BoundValue> extends EventEmitter {
       }
     }
     const options = asResolutionOptions(optionsOrSession);
-    if (this._getValue) {
+    if (typeof this._getValue === 'function') {
       const result = ResolutionSession.runWithBinding(
         s => {
           const optionsWithSession = Object.assign({}, options, {session: s});
-          return this._getValue(ctx, optionsWithSession);
+          // We already test `this._getValue` is a function. It's safe to assert
+          // that `this._getValue` is not undefined.
+          return this._getValue!({
+            context: ctx,
+            binding: this,
+            options: optionsWithSession,
+          });
         },
         this,
         options.session,
@@ -442,16 +582,19 @@ export class Binding<T = BoundValue> extends EventEmitter {
    * Set the `_getValue` function
    * @param getValue - getValue function
    */
-  private _setValueGetter(getValue: ValueGetter<T>) {
+  private _setValueGetter(getValue: ValueFactory<T>) {
     // Clear the cache
     this._clearCache();
-    this._getValue = (ctx: Context, options: ResolutionOptions) => {
-      if (options.asProxyWithInterceptors && this._type !== BindingType.CLASS) {
+    this._getValue = resolutionCtx => {
+      if (
+        resolutionCtx.options.asProxyWithInterceptors &&
+        this._source?.type !== BindingType.CLASS
+      ) {
         throw new Error(
-          `Binding '${this.key}' (${this._type}) does not support 'asProxyWithInterceptors'`,
+          `Binding '${this.key}' (${this._source?.type}) does not support 'asProxyWithInterceptors'`,
         );
       }
-      return getValue(ctx, options);
+      return getValue(resolutionCtx);
     };
     this.emitChangedEvent('value');
   }
@@ -494,7 +637,10 @@ export class Binding<T = BoundValue> extends EventEmitter {
     if (debug.enabled) {
       debug('Bind %s to constant:', this.key, value);
     }
-    this._type = BindingType.CONSTANT;
+    this._source = {
+      type: BindingType.CONSTANT,
+      value,
+    };
     this._setValueGetter(() => value);
     return this;
   }
@@ -517,13 +663,25 @@ export class Binding<T = BoundValue> extends EventEmitter {
    * );
    * ```
    */
-  toDynamicValue(factoryFn: () => ValueOrPromise<T>): this {
+  toDynamicValue(
+    factory: ValueFactory<T> | DynamicValueProviderClass<T>,
+  ): this {
     /* istanbul ignore if */
     if (debug.enabled) {
-      debug('Bind %s to dynamic value:', this.key, factoryFn);
+      debug('Bind %s to dynamic value:', this.key, factory);
     }
-    this._type = BindingType.DYNAMIC_VALUE;
-    this._setValueGetter(ctx => factoryFn());
+    this._source = {
+      type: BindingType.DYNAMIC_VALUE,
+      value: factory,
+    };
+
+    let factoryFn: ValueFactory<T>;
+    if (isDynamicValueProviderClass(factory)) {
+      factoryFn = toValueFactory(factory);
+    } else {
+      factoryFn = factory;
+    }
+    this._setValueGetter(resolutionCtx => factoryFn(resolutionCtx));
     return this;
   }
 
@@ -548,12 +706,14 @@ export class Binding<T = BoundValue> extends EventEmitter {
     if (debug.enabled) {
       debug('Bind %s to provider %s', this.key, providerClass.name);
     }
-    this._type = BindingType.PROVIDER;
-    this._providerConstructor = providerClass;
-    this._setValueGetter((ctx, options) => {
+    this._source = {
+      type: BindingType.PROVIDER,
+      value: providerClass,
+    };
+    this._setValueGetter(({context, options}) => {
       const providerOrPromise = instantiateClass<Provider<T>>(
         providerClass,
-        ctx,
+        context,
         options.session,
       );
       return transformValueOrPromise(providerOrPromise, p => p.value());
@@ -573,17 +733,19 @@ export class Binding<T = BoundValue> extends EventEmitter {
     if (debug.enabled) {
       debug('Bind %s to class %s', this.key, ctor.name);
     }
-    this._type = BindingType.CLASS;
-    this._setValueGetter((ctx, options) => {
-      const instOrPromise = instantiateClass(ctor, ctx, options.session);
+    this._source = {
+      type: BindingType.CLASS,
+      value: ctor,
+    };
+    this._setValueGetter(({context, options}) => {
+      const instOrPromise = instantiateClass(ctor, context, options.session);
       if (!options.asProxyWithInterceptors) return instOrPromise;
       return createInterceptionProxyFromInstance(
         instOrPromise,
-        ctx,
+        context,
         options.session,
       );
     });
-    this._valueConstructor = ctor;
     return this;
   }
 
@@ -597,10 +759,12 @@ export class Binding<T = BoundValue> extends EventEmitter {
     if (debug.enabled) {
       debug('Bind %s to alias %s', this.key, keyWithPath);
     }
-    this._type = BindingType.ALIAS;
-    this._alias = keyWithPath;
-    this._setValueGetter((ctx, options) => {
-      return ctx.getValueOrPromise(keyWithPath, options);
+    this._source = {
+      type: BindingType.ALIAS,
+      value: keyWithPath,
+    };
+    this._setValueGetter(({context, options}) => {
+      return context.getValueOrPromise(keyWithPath, options);
     });
     return this;
   }
@@ -647,14 +811,16 @@ export class Binding<T = BoundValue> extends EventEmitter {
     if (this.type != null) {
       json.type = this.type;
     }
-    if (this._valueConstructor != null) {
-      json.valueConstructor = this._valueConstructor.name;
-    }
-    if (this._providerConstructor != null) {
-      json.providerConstructor = this._providerConstructor.name;
-    }
-    if (this._alias != null) {
-      json.alias = this._alias.toString();
+    switch (this._source?.type) {
+      case BindingType.CLASS:
+        json.valueConstructor = this._source?.value.name;
+        break;
+      case BindingType.PROVIDER:
+        json.providerConstructor = this._source?.value.name;
+        break;
+      case BindingType.ALIAS:
+        json.alias = this._source?.value.toString();
+        break;
     }
     return json;
   }

package/src/context.ts

@@ -5,7 +5,6 @@
 
 import debugFactory, {Debugger} from 'debug';
 import {EventEmitter} from 'events';
-import {v4 as uuidv4} from 'uuid';
 import {Binding, BindingInspectOptions, BindingTag} from './binding';
 import {
   ConfigurationResolver,
@@ -37,6 +36,7 @@ import {
   Constructor,
   getDeepProperty,
   isPromiseLike,
+  uuid,
   ValueOrPromise,
 } from './value-promise';
 
@@ -151,7 +151,7 @@ export class Context extends EventEmitter {
   }
 
   private generateName() {
-    const id = uuidv4();
+    const id = uuid();
     if (this.constructor === Context) return id;
     return `${this.constructor.name}-${id}`;
   }

package/src/inject.ts

@@ -20,7 +20,7 @@ import {
   isBindingAddress,
   isBindingTagFilter,
 } from './binding-filter';
-import {BindingAddress} from './binding-key';
+import {BindingAddress, BindingKey} from './binding-key';
 import {BindingComparator} from './binding-sorter';
 import {BindingCreationPolicy, Context} from './context';
 import {ContextView, createViewGetter} from './context-view';
@@ -40,8 +40,17 @@ const METHODS_KEY = MetadataAccessor.create<Injection, MethodDecorator>(
   'inject:methods',
 );
 
+// TODO(rfeng): We may want to align it with `ValueFactory` interface that takes
+// an argument of `ResolutionContext`.
 /**
- * A function to provide resolution of injected values
+ * A function to provide resolution of injected values.
+ *
+ * @example
+ * ```ts
+ * const resolver: ResolverFunction = (ctx, injection, session) {
+ *   return session.currentBinding?.key;
+ * }
+ * ```
  */
 export interface ResolverFunction {
   (
@@ -313,7 +322,7 @@ export namespace inject {
    * @param metadata - Metadata for the injection
    */
   export const binding = function injectBinding(
-    bindingKey?: BindingAddress,
+    bindingKey?: string | BindingKey<unknown>,
     metadata?: InjectBindingMetadata,
   ) {
     metadata = Object.assign({decorator: '@inject.binding'}, metadata);
@@ -377,7 +386,7 @@ export namespace inject {
    * ```
    */
   export const context = function injectContext() {
-    return inject('', {decorator: '@inject.context'}, ctx => ctx);
+    return inject('', {decorator: '@inject.context'}, (ctx: Context) => ctx);
   };
 }
 
@@ -604,22 +613,19 @@ export function describeInjectedArguments(
  * @param injection - Injection information
  */
 export function inspectTargetType(injection: Readonly<Injection>) {
-  let type = MetadataInspector.getDesignTypeForProperty(
-    injection.target,
-    injection.member!,
-  );
-  if (type) {
-    return type;
+  if (typeof injection.methodDescriptorOrParameterIndex === 'number') {
+    const designType = MetadataInspector.getDesignTypeForMethod(
+      injection.target,
+      injection.member!,
+    );
+    return designType.parameterTypes[
+      injection.methodDescriptorOrParameterIndex as number
+    ];
   }
-  const designType = MetadataInspector.getDesignTypeForMethod(
+  return MetadataInspector.getDesignTypeForProperty(
     injection.target,
     injection.member!,
   );
-  type =
-    designType.parameterTypes[
-      injection.methodDescriptorOrParameterIndex as number
-    ];
-  return type;
 }
 
 /**

package/src/interceptor-chain.ts

@@ -12,28 +12,55 @@ import {InvocationResult} from './invocation';
 import {transformValueOrPromise, ValueOrPromise} from './value-promise';
 const debug = debugFactory('loopback:context:interceptor-chain');
 
+/**
+ * Any type except `void`. We use this type to enforce that interceptor functions
+ * always return a value (including undefined or null).
+ */
+export type NonVoid = string | number | boolean | null | undefined | object;
+
 /**
  * The `next` function that can be used to invoke next generic interceptor in
  * the chain
  */
-export type Next = () => ValueOrPromise<InvocationResult>;
+export type Next = () => ValueOrPromise<NonVoid>;
 
 /**
  * An interceptor function to be invoked in a chain for the given context.
  * It serves as the base interface for various types of interceptors, such
  * as method invocation interceptor or request/response processing interceptor.
  *
+ * We choose `NonVoid` as the return type to avoid possible bugs that an
+ * interceptor forgets to return the value from `next()`. For example, the code
+ * below will fail to compile.
+ *
+ * ```ts
+ * const myInterceptor: Interceptor = async (ctx, next) {
+ *   // preprocessing
+ *   // ...
+ *
+ *   // There is a subtle bug that the result from `next()` is not further
+ *   // returned back to the upstream interceptors
+ *   const result = await next();
+ *
+ *   // postprocessing
+ *   // ...
+ *   // We must have `return ...` here
+ *   // either return `result` or another value if the interceptor decides to
+ *   // have its own response
+ * }
+ * ```
+ *
  * @typeParam C - `Context` class or a subclass of `Context`
  * @param context - Context object
  * @param next - A function to proceed with downstream interceptors or the
  * target operation
  *
- * @returns The invocation result as a value (sync) or promise (async)
+ * @returns The invocation result as a value (sync) or promise (async).
  */
 export type GenericInterceptor<C extends Context = Context> = (
   context: C,
   next: Next,
-) => ValueOrPromise<InvocationResult>;
+) => ValueOrPromise<NonVoid>;
 
 /**
  * Interceptor function or a binding key that resolves a generic interceptor
@@ -53,8 +80,12 @@ class InterceptorChainState<C extends Context = Context> {
   /**
    * Create a state for the interceptor chain
    * @param interceptors - Interceptor functions or binding keys
+   * @param finalHandler - An optional final handler
    */
-  constructor(private interceptors: GenericInterceptorOrKey<C>[]) {}
+  constructor(
+    public readonly interceptors: GenericInterceptorOrKey<C>[],
+    public readonly finalHandler: Next = () => undefined,
+  ) {}
 
   /**
    * Get the index for the current interceptor
@@ -138,12 +169,24 @@ export class GenericInterceptorChain<C extends Context = Context> {
   /**
    * Invoke the interceptor chain
    */
-  invokeInterceptors(): ValueOrPromise<InvocationResult> {
+  invokeInterceptors(finalHandler?: Next): ValueOrPromise<InvocationResult> {
     // Create a state for each invocation to provide isolation
-    const state = new InterceptorChainState<C>(this.getInterceptors());
+    const state = new InterceptorChainState<C>(
+      this.getInterceptors(),
+      finalHandler,
+    );
     return this.next(state);
   }
 
+  /**
+   * Use the interceptor chain as an interceptor
+   */
+  asInterceptor(): GenericInterceptor<C> {
+    return (ctx, next) => {
+      return this.invokeInterceptors(next);
+    };
+  }
+
   /**
    * Invoke downstream interceptors or the target method
    */
@@ -152,7 +195,7 @@ export class GenericInterceptorChain<C extends Context = Context> {
   ): ValueOrPromise<InvocationResult> {
     if (state.done()) {
       // No more interceptors
-      return undefined;
+      return state.finalHandler();
     }
     // Invoke the next interceptor in the chain
     return this.invokeNextInterceptor(state);
@@ -206,3 +249,19 @@ export function invokeInterceptors<
   const chain = new GenericInterceptorChain(context, interceptors);
   return chain.invokeInterceptors();
 }
+
+/**
+ * Compose a list of interceptors as a single interceptor
+ * @param interceptors - A list of interceptor functions or binding keys
+ */
+export function composeInterceptors<C extends Context = Context>(
+  ...interceptors: GenericInterceptorOrKey<C>[]
+): GenericInterceptor<C> {
+  return (ctx, next) => {
+    const interceptor = new GenericInterceptorChain(
+      ctx,
+      interceptors,
+    ).asInterceptor();
+    return interceptor(ctx, next);
+  };
+}