@loopback/context 3.10.0 → 3.12.0

package/src/binding.ts

@@ -58,6 +58,10 @@ export enum BindingScope {
   TRANSIENT = 'Transient',
 
   /**
+   * @deprecated Finer-grained scopes such as `APPLICATION`, `SERVER`, or
+   * `REQUEST` should be used instead to ensure the scope of sharing of resolved
+   * binding values.
+   *
    * The binding provides a value as a singleton within each local context. The
    * value is calculated only once per context and cached for subsequential
    * uses. Child contexts have their own value and do not share with their
@@ -79,6 +83,7 @@ export enum BindingScope {
    * 3. `'b1'` is resolved in `app` but not in `req2`, a new value `2` is
    * calculated and used for `req2` afterward
    * - req2.get('b1') ==> 2 (always)
+   *
    */
   CONTEXT = 'Context',
 
@@ -104,6 +109,62 @@ export enum BindingScope {
    * - req2.get('b1') ==> 0 (always)
    */
   SINGLETON = 'Singleton',
+
+  /*
+   * The following scopes are checked against the context hierarchy to find
+   * the first matching context for a given scope in the chain. Resolved binding
+   * values will be cached and shared on the scoped context. This ensures a
+   * binding to have the same value for the scoped context.
+   */
+
+  /**
+   * Application scope
+   *
+   * @remarks
+   * The binding provides an application-scoped value within the context
+   * hierarchy. Resolved value for this binding will be cached and shared for
+   * the same application context (denoted by its scope property set to
+   * `BindingScope.APPLICATION`).
+   *
+   */
+  APPLICATION = 'Application',
+
+  /**
+   * Server scope
+   *
+   * @remarks
+   * The binding provides an server-scoped value within the context hierarchy.
+   * Resolved value for this binding will be cached and shared for the same
+   * server context (denoted by its scope property set to
+   * `BindingScope.SERVER`).
+   *
+   * It's possible that an application has more than one servers configured,
+   * such as a `RestServer` and a `GrpcServer`. Both server contexts are created
+   * with `scope` set to `BindingScope.SERVER`. Depending on where a binding
+   * is resolved:
+   * - If the binding is resolved from the RestServer or below, it will be
+   * cached using the RestServer context as the key.
+   * - If the binding is resolved from the GrpcServer or below, it will be
+   * cached using the GrpcServer context as the key.
+   *
+   * The same binding can resolved/shared/cached for all servers, each of which
+   * has its own value for the binding.
+   */
+  SERVER = 'Server',
+
+  /**
+   * Request scope
+   *
+   * @remarks
+   * The binding provides an request-scoped value within the context hierarchy.
+   * Resolved value for this binding will be cached and shared for the same
+   * request context (denoted by its scope property set to
+   * `BindingScope.REQUEST`).
+   *
+   * The `REQUEST` scope is very useful for controllers, services and artifacts
+   * that want to have a single instance/value for a given request.
+   */
+  REQUEST = 'Request',
 }
 
 /**
@@ -352,23 +413,18 @@ export class Binding<T = BoundValue> extends EventEmitter {
 
   /**
    * Cache the resolved value by the binding scope
-   * @param ctx - The current context
+   * @param resolutionCtx - The resolution context
    * @param result - The calculated value for the binding
    */
   private _cacheValue(
-    ctx: Context,
+    resolutionCtx: Context,
     result: ValueOrPromise<T>,
   ): ValueOrPromise<T> {
     // Initialize the cache as a weakmap keyed by context
     if (!this._cache) this._cache = new WeakMap<Context, ValueOrPromise<T>>();
-    if (this.scope === BindingScope.SINGLETON) {
-      // Cache the value
-      this._cache.set(ctx.getOwnerContext(this.key)!, result);
-    } else if (this.scope === BindingScope.CONTEXT) {
-      // Cache the value at the current context
-      this._cache.set(ctx, result);
+    if (this.scope !== BindingScope.TRANSIENT) {
+      this._cache.set(resolutionCtx!, result);
     }
-    // Do not cache for `TRANSIENT`
     return result;
   }
 
@@ -383,7 +439,7 @@ export class Binding<T = BoundValue> extends EventEmitter {
 
   /**
    * 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
+   * This is useful to force reloading a cached value when its configuration or
    * dependencies are changed.
    * **WARNING**: The state held in the cached value will be gone.
    *
@@ -391,15 +447,11 @@ export class Binding<T = BoundValue> extends EventEmitter {
    */
   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);
+    if (this.scope !== BindingScope.TRANSIENT) {
+      const resolutionCtx = ctx.getResolutionContext(this);
+      if (resolutionCtx != null) {
+        this._cache.delete(resolutionCtx);
       }
-    } else if (this.scope === BindingScope.CONTEXT) {
-      // Cache the value at the current context
-      this._cache.delete(ctx);
     }
   }
 
@@ -451,22 +503,20 @@ export class Binding<T = BoundValue> extends EventEmitter {
     if (debug.enabled) {
       debug('Get value for binding %s', this.key);
     }
+
+    const options = asResolutionOptions(optionsOrSession);
+    const resolutionCtx = this.getResolutionContext(ctx, options);
+    if (resolutionCtx == null) return undefined;
     // First check cached value for non-transient
     if (this._cache) {
-      if (this.scope === BindingScope.SINGLETON) {
-        const ownerCtx = ctx.getOwnerContext(this.key);
-        if (ownerCtx && this._cache.has(ownerCtx)) {
-          return this._cache.get(ownerCtx)!;
-        }
-      } else if (this.scope === BindingScope.CONTEXT) {
-        if (this._cache.has(ctx)) {
-          return this._cache.get(ctx)!;
+      if (this.scope !== BindingScope.TRANSIENT) {
+        if (resolutionCtx && this._cache.has(resolutionCtx)) {
+          return this._cache.get(resolutionCtx)!;
         }
       }
     }
-    const options = asResolutionOptions(optionsOrSession);
-    const resolutionCtx = {
-      context: ctx,
+    const resolutionMetadata = {
+      context: resolutionCtx!,
       binding: this,
       options,
     };
@@ -477,25 +527,62 @@ export class Binding<T = BoundValue> extends EventEmitter {
           // We already test `this._getValue` is a function. It's safe to assert
           // that `this._getValue` is not undefined.
           return this._getValue!({
-            ...resolutionCtx,
+            ...resolutionMetadata,
             options: optionsWithSession,
           });
         },
         this,
         options.session,
       );
-      return this._cacheValue(ctx, result);
+      return this._cacheValue(resolutionCtx!, result);
     }
     // `@inject.binding` adds a binding without _getValue
     if (options.optional) return undefined;
     return Promise.reject(
       new ResolutionError(
         `No value was configured for binding ${this.key}.`,
-        resolutionCtx,
+        resolutionMetadata,
       ),
     );
   }
 
+  /**
+   * Locate and validate the resolution context
+   * @param ctx - Current context
+   * @param options - Resolution options
+   */
+  private getResolutionContext(ctx: Context, options: ResolutionOptions) {
+    const resolutionCtx = ctx.getResolutionContext(this);
+    switch (this.scope) {
+      case BindingScope.APPLICATION:
+      case BindingScope.SERVER:
+      case BindingScope.REQUEST:
+        if (resolutionCtx == null) {
+          const msg =
+            `Binding "${this.key}" in context "${ctx.name}" cannot` +
+            ` be resolved in scope "${this.scope}"`;
+          if (options.optional) {
+            debug(msg);
+            return undefined;
+          }
+          throw new Error(msg);
+        }
+    }
+
+    const ownerCtx = ctx.getOwnerContext(this.key);
+    if (ownerCtx != null && !ownerCtx.isVisibleTo(resolutionCtx!)) {
+      const msg =
+        `Resolution context "${resolutionCtx?.name}" does not have ` +
+        `visibility to binding "${this.key} (scope:${this.scope})" in context "${ownerCtx.name}"`;
+      if (options.optional) {
+        debug(msg);
+        return undefined;
+      }
+      throw new Error(msg);
+    }
+    return resolutionCtx;
+  }
+
   /**
    * Lock the binding so that it cannot be rebound
    */
@@ -855,7 +942,7 @@ export class Binding<T = BoundValue> extends EventEmitter {
    * easy to read.
    * @param key - Binding key
    */
-  static bind<T = unknown>(key: BindingAddress<T>): Binding<T> {
+  static bind<V = unknown>(key: BindingAddress<V>): Binding<V> {
     return new Binding(key);
   }
 
@@ -868,13 +955,13 @@ export class Binding<T = BoundValue> extends EventEmitter {
    *   .to({port: 3000});
    * ```
    *
-   * @typeParam T Generic type for the configuration value (not the binding to
+   * @typeParam V Generic type for the configuration value (not the binding to
    * be configured)
    *
    * @param key - Key for the binding to be configured
    */
-  static configure<T = unknown>(key: BindingAddress): Binding<T> {
-    return new Binding(BindingKey.buildKeyForConfig<T>(key)).tag({
+  static configure<V = unknown>(key: BindingAddress): Binding<V> {
+    return new Binding(BindingKey.buildKeyForConfig<V>(key)).tag({
       [ContextTags.CONFIGURATION_FOR]: key.toString(),
     });
   }

package/src/context-view.ts

@@ -45,7 +45,8 @@ export interface ContextViewEvent<T> extends ContextEvent {
  * - 'refresh': when the view is refreshed as bindings are added/removed
  * - 'resolve': when the cached values are resolved and updated
  */
-export class ContextView<T = unknown> extends EventEmitter
+export class ContextView<T = unknown>
+  extends EventEmitter
   implements ContextObserver {
   /**
    * An array of cached bindings that matches the binding filter
@@ -250,7 +251,7 @@ export class ContextView<T = unknown> extends EventEmitter
    */
   on(
     eventName: 'bind',
-    listener: <T>(event: ContextViewEvent<T>) => void,
+    listener: <V>(event: ContextViewEvent<V>) => void,
   ): this;
 
   /**
@@ -261,7 +262,7 @@ export class ContextView<T = unknown> extends EventEmitter
    */
   on(
     eventName: 'unbind',
-    listener: <T>(event: ContextViewEvent<T> & {cachedValue?: T}) => void,
+    listener: <V>(event: ContextViewEvent<V> & {cachedValue?: V}) => void,
   ): this;
 
   /**
@@ -281,7 +282,7 @@ export class ContextView<T = unknown> extends EventEmitter
    * @param listener The listener function to call when the event is emitted.
    */
   // eslint-disable-next-line @typescript-eslint/unified-signatures
-  on(eventName: 'refresh', listener: <T>(result: T[]) => void): this;
+  on(eventName: 'refresh', listener: <V>(result: V[]) => void): this;
 
   /**
    * The "close" event is emitted when the view is closed (stopped observing
@@ -310,7 +311,7 @@ export class ContextView<T = unknown> extends EventEmitter
    */
   once(
     eventName: 'bind',
-    listener: <T>(event: ContextViewEvent<T>) => void,
+    listener: <V>(event: ContextViewEvent<V>) => void,
   ): this;
 
   /**
@@ -321,7 +322,7 @@ export class ContextView<T = unknown> extends EventEmitter
    */
   once(
     eventName: 'unbind',
-    listener: <T>(event: ContextViewEvent<T> & {cachedValue?: T}) => void,
+    listener: <V>(event: ContextViewEvent<V> & {cachedValue?: V}) => void,
   ): this;
 
   /**
@@ -341,7 +342,7 @@ export class ContextView<T = unknown> extends EventEmitter
    * @param listener The listener function to call when the event is emitted.
    */
   // eslint-disable-next-line @typescript-eslint/unified-signatures
-  once(eventName: 'refresh', listener: <T>(result: T[]) => void): this;
+  once(eventName: 'refresh', listener: <V>(result: V[]) => void): this;
 
   /**
    * The "close" event is emitted when the view is closed (stopped observing

package/src/context.ts

@@ -5,7 +5,12 @@
 
 import debugFactory, {Debugger} from 'debug';
 import {EventEmitter} from 'events';
-import {Binding, BindingInspectOptions, BindingTag} from './binding';
+import {
+  Binding,
+  BindingInspectOptions,
+  BindingScope,
+  BindingTag,
+} from './binding';
 import {
   ConfigurationResolver,
   DefaultConfigurationResolver,
@@ -91,6 +96,11 @@ export class Context extends EventEmitter {
    */
   protected _debug: Debugger;
 
+  /**
+   * Scope for binding resolution
+   */
+  scope: BindingScope = BindingScope.CONTEXT;
+
   /**
    * Create a new context.
    *
@@ -467,17 +477,102 @@ export class Context extends EventEmitter {
   }
 
   /**
-   * Get the owning context for a binding key
-   * @param key - Binding key
+   * Get the owning context for a binding or its key
+   * @param keyOrBinding - Binding object or key
    */
-  getOwnerContext(key: BindingAddress): Context | undefined {
-    if (this.contains(key)) return this;
+  getOwnerContext(
+    keyOrBinding: BindingAddress | Readonly<Binding<unknown>>,
+  ): Context | undefined {
+    let key: BindingAddress;
+    if (keyOrBinding instanceof Binding) {
+      key = keyOrBinding.key;
+    } else {
+      key = keyOrBinding as BindingAddress;
+    }
+    if (this.contains(key)) {
+      if (keyOrBinding instanceof Binding) {
+        // Check if the contained binding is the same
+        if (this.registry.get(key.toString()) === keyOrBinding) {
+          return this;
+        }
+        return undefined;
+      }
+      return this;
+    }
     if (this._parent) {
       return this._parent.getOwnerContext(key);
     }
     return undefined;
   }
 
+  /**
+   * Get the context matching the scope
+   * @param scope - Binding scope
+   */
+  getScopedContext(
+    scope:
+      | BindingScope.APPLICATION
+      | BindingScope.SERVER
+      | BindingScope.REQUEST,
+  ): Context | undefined {
+    if (this.scope === scope) return this;
+    if (this._parent) {
+      return this._parent.getScopedContext(scope);
+    }
+    return undefined;
+  }
+
+  /**
+   * Locate the resolution context for the given binding. Only bindings in the
+   * resolution context and its ancestors are visible as dependencies to resolve
+   * the given binding
+   * @param binding - Binding object
+   */
+  getResolutionContext(
+    binding: Readonly<Binding<unknown>>,
+  ): Context | undefined {
+    let resolutionCtx: Context | undefined;
+    switch (binding.scope) {
+      case BindingScope.SINGLETON:
+        // Use the owner context
+        return this.getOwnerContext(binding.key);
+      case BindingScope.TRANSIENT:
+      case BindingScope.CONTEXT:
+        // Use the current context
+        return this;
+      case BindingScope.REQUEST:
+        resolutionCtx = this.getScopedContext(binding.scope);
+        if (resolutionCtx != null) {
+          return resolutionCtx;
+        } else {
+          // If no `REQUEST` scope exists in the chain, fall back to the current
+          // context
+          this.debug(
+            'No context is found for binding "%s (scope=%s)". Fall back to the current context.',
+            binding.key,
+            binding.scope,
+          );
+          return this;
+        }
+      default:
+        // Use the scoped context
+        return this.getScopedContext(binding.scope);
+    }
+  }
+
+  /**
+   * Check if this context is visible (same or ancestor) to the given one
+   * @param ctx - Another context object
+   */
+  isVisibleTo(ctx: Context) {
+    let current: Context | undefined = ctx;
+    while (current != null) {
+      if (current === this) return true;
+      current = current._parent;
+    }
+    return false;
+  }
+
   /**
    * Find bindings using a key pattern or filter function
    * @param pattern - A filter function, a regexp or a wildcard pattern with

package/src/inject.ts

@@ -11,6 +11,7 @@ import {
   MetadataMap,
   ParameterDecoratorFactory,
   PropertyDecoratorFactory,
+  Reflector,
 } from '@loopback/metadata';
 import {Binding, BindingTag} from './binding';
 import {
@@ -26,17 +27,20 @@ import {BindingCreationPolicy, Context} from './context';
 import {ContextView, createViewGetter} from './context-view';
 import {JSONObject} from './json-types';
 import {ResolutionOptions, ResolutionSession} from './resolution-session';
-import {BoundValue, ValueOrPromise} from './value-promise';
+import {BoundValue, Constructor, ValueOrPromise} from './value-promise';
 
-const PARAMETERS_KEY = MetadataAccessor.create<Injection, ParameterDecorator>(
-  'inject:parameters',
-);
-const PROPERTIES_KEY = MetadataAccessor.create<Injection, PropertyDecorator>(
-  'inject:properties',
-);
+const INJECT_PARAMETERS_KEY = MetadataAccessor.create<
+  Injection,
+  ParameterDecorator
+>('inject:parameters');
+
+const INJECT_PROPERTIES_KEY = MetadataAccessor.create<
+  Injection,
+  PropertyDecorator
+>('inject:properties');
 
 // A key to cache described argument injections
-const METHODS_KEY = MetadataAccessor.create<Injection, MethodDecorator>(
+const INJECT_METHODS_KEY = MetadataAccessor.create<Injection, MethodDecorator>(
   'inject:methods',
 );
 
@@ -151,7 +155,7 @@ export function inject(
       const paramDecorator: ParameterDecorator = ParameterDecoratorFactory.createDecorator<
         Injection
       >(
-        PARAMETERS_KEY,
+        INJECT_PARAMETERS_KEY,
         {
           target,
           member,
@@ -187,7 +191,7 @@ export function inject(
       const propDecorator: PropertyDecorator = PropertyDecoratorFactory.createDecorator<
         Injection
       >(
-        PROPERTIES_KEY,
+        INJECT_PROPERTIES_KEY,
         {
           target,
           member,
@@ -574,7 +578,7 @@ export function describeInjectedArguments(
   // Try to read from cache
   const cache =
     MetadataInspector.getAllMethodMetadata<Readonly<Injection>[]>(
-      METHODS_KEY,
+      INJECT_METHODS_KEY,
       target,
       {
         ownMetadataOnly: true,
@@ -596,7 +600,7 @@ export function describeInjectedArguments(
   }
   meta =
     MetadataInspector.getAllParameterMetadata<Readonly<Injection>>(
-      PARAMETERS_KEY,
+      INJECT_PARAMETERS_KEY,
       target,
       method,
       options,
@@ -605,7 +609,7 @@ export function describeInjectedArguments(
   // Cache the result
   cache[method] = meta;
   MetadataInspector.defineMetadata<MetadataMap<Readonly<Injection>[]>>(
-    METHODS_KEY,
+    INJECT_METHODS_KEY,
     cache,
     target,
   );
@@ -623,7 +627,7 @@ export function inspectTargetType(injection: Readonly<Injection>) {
       injection.target,
       injection.member!,
     );
-    return designType.parameterTypes[
+    return designType?.parameterTypes?.[
       injection.methodDescriptorOrParameterIndex as number
     ];
   }
@@ -706,7 +710,7 @@ export function describeInjectedProperties(
 ): MetadataMap<Readonly<Injection>> {
   const metadata =
     MetadataInspector.getAllPropertyMetadata<Readonly<Injection>>(
-      PROPERTIES_KEY,
+      INJECT_PROPERTIES_KEY,
       target,
     ) ?? {};
   return metadata;
@@ -774,3 +778,21 @@ function inspectInjection(injection: Readonly<Injection<unknown>>) {
   }
   return descriptor;
 }
+
+/**
+ * Check if the given class has `@inject` or other decorations that map to
+ * `@inject`.
+ *
+ * @param cls - Class with possible `@inject` decorations
+ */
+export function hasInjections(cls: Constructor<unknown>): boolean {
+  return (
+    MetadataInspector.getClassMetadata(INJECT_PARAMETERS_KEY, cls) != null ||
+    Reflector.getMetadata(INJECT_PARAMETERS_KEY.toString(), cls.prototype) !=
+      null ||
+    MetadataInspector.getAllPropertyMetadata(
+      INJECT_PROPERTIES_KEY,
+      cls.prototype,
+    ) != null
+  );
+}

package/src/interceptor-chain.ts

@@ -29,6 +29,7 @@ export type Next = () => ValueOrPromise<NonVoid>;
  * It serves as the base interface for various types of interceptors, such
  * as method invocation interceptor or request/response processing interceptor.
  *
+ * @remarks
  * 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.

package/src/interceptor.ts

@@ -14,7 +14,7 @@ import {
 import assert from 'assert';
 import debugFactory from 'debug';
 import {Binding, BindingTemplate} from './binding';
-import {bind} from './binding-decorator';
+import {injectable} from './binding-decorator';
 import {
   BindingFromClassOptions,
   BindingSpec,
@@ -159,7 +159,7 @@ export function asGlobalInterceptor(group?: string): BindingTemplate {
  * @param specs - Extra binding specs
  */
 export function globalInterceptor(group?: string, ...specs: BindingSpec[]) {
-  return bind(asGlobalInterceptor(group), ...specs);
+  return injectable(asGlobalInterceptor(group), ...specs);
 }
 
 /**

package/src/resolver.ts

@@ -6,7 +6,6 @@
 import {DecoratorFactory} from '@loopback/metadata';
 import assert from 'assert';
 import debugModule from 'debug';
-import {BindingScope} from './binding';
 import {isBindingAddress} from './binding-filter';
 import {BindingAddress} from './binding-key';
 import {Context} from './context';
@@ -98,11 +97,8 @@ function resolveContext(
   session?: ResolutionSession,
 ) {
   const currentBinding = session?.currentBinding;
-  if (
-    currentBinding == null ||
-    currentBinding.scope !== BindingScope.SINGLETON
-  ) {
-    // No current binding or its scope is not `SINGLETON`
+  if (currentBinding == null) {
+    // No current binding
     return ctx;
   }
 
@@ -113,9 +109,9 @@ function resolveContext(
     typeof injection.methodDescriptorOrParameterIndex !== 'number';
 
   if (isConstructorOrPropertyInjection) {
-    // Set context to the owner context of the current binding for constructor
-    // or property injections against a singleton
-    ctx = ctx.getOwnerContext(currentBinding.key)!;
+    // Set context to the resolution context of the current binding for
+    // constructor or property injections against a singleton
+    ctx = ctx.getResolutionContext(currentBinding)!;
   }
   return ctx;
 }

package/src/value-promise.ts

@@ -94,7 +94,7 @@ export function getDeepProperty<OUT = BoundValue, IN = BoundValue>(
  */
 export function resolveMap<T, V>(
   map: MapObject<T>,
-  resolver: (val: T, key: string, map: MapObject<T>) => ValueOrPromise<V>,
+  resolver: (val: T, key: string, values: MapObject<T>) => ValueOrPromise<V>,
 ): ValueOrPromise<MapObject<V>> {
   const result: MapObject<V> = {};
   let asyncResolvers: PromiseLike<void>[] | undefined = undefined;
@@ -156,7 +156,7 @@ export function resolveMap<T, V>(
  */
 export function resolveList<T, V>(
   list: T[],
-  resolver: (val: T, index: number, list: T[]) => ValueOrPromise<V>,
+  resolver: (val: T, index: number, values: T[]) => ValueOrPromise<V>,
 ): ValueOrPromise<V[]> {
   const result: V[] = new Array<V>(list.length);
   let asyncResolvers: PromiseLike<void>[] | undefined = undefined;
@@ -302,8 +302,8 @@ export function transformValueOrPromise<T, V>(
 /**
  * A utility to generate uuid v4
  *
- * @deprecated Use [uuid](https://www.npmjs.com/package/uuid) or
- * [hyperid](https://www.npmjs.com/package/hyperid) instead.
+ * @deprecated Use `generateUniqueId`, [uuid](https://www.npmjs.com/package/uuid)
+ * or [hyperid](https://www.npmjs.com/package/hyperid) instead.
  */
 export function uuid() {
   return uuidv4();