@loopback/context 1.25.0 → 2.1.1

package/src/context.ts

@@ -6,22 +6,25 @@
 import debugFactory from 'debug';
 import {EventEmitter} from 'events';
 import {v1 as uuidv1} from 'uuid';
-import {Binding, BindingTag} from './binding';
+import {Binding, BindingInspectOptions, BindingTag} from './binding';
 import {
   ConfigurationResolver,
   DefaultConfigurationResolver,
 } from './binding-config';
-import {BindingFilter, filterByKey, filterByTag} from './binding-filter';
+import {
+  BindingFilter,
+  filterByKey,
+  filterByTag,
+  isBindingTagFilter,
+} from './binding-filter';
 import {BindingAddress, BindingKey} from './binding-key';
 import {BindingComparator} from './binding-sorter';
-import {
-  ContextEventObserver,
-  ContextEventType,
-  ContextObserver,
-  Notification,
-  Subscription,
-} from './context-observer';
+import {ContextEvent} from './context-event';
+import {ContextEventObserver, ContextObserver} from './context-observer';
+import {ContextSubscriptionManager, Subscription} from './context-subscription';
+import {ContextTagIndexer} from './context-tag-indexer';
 import {ContextView} from './context-view';
+import {JSONObject} from './json-types';
 import {ContextBindings} from './keys';
 import {
   asResolutionOptions,
@@ -36,21 +39,6 @@ import {
   ValueOrPromise,
 } from './value-promise';
 
-/**
- * Polyfill Symbol.asyncIterator as required by TypeScript for Node 8.x.
- * See https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-3.html
- */
-if (!Symbol.asyncIterator) {
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  (Symbol as any).asyncIterator = Symbol.for('Symbol.asyncIterator');
-}
-/**
- * WARNING: This following import must happen after the polyfill. The
- * `auto-import` by an IDE such as VSCode may move the import before the
- * polyfill. It must be then fixed manually.
- */
-import {iterator, multiple} from 'p-event';
-
 const debug = debugFactory('loopback:context');
 
 /**
@@ -68,41 +56,24 @@ export class Context extends EventEmitter {
   protected readonly registry: Map<string, Binding> = new Map();
 
   /**
-   * Parent context
-   */
-  protected _parent?: Context;
-
-  protected configResolver: ConfigurationResolver;
-
-  /**
-   * Event listeners for parent context keyed by event names. It keeps track
-   * of listeners from this context against its parent so that we can remove
-   * these listeners when this context is closed.
+   * Indexer for bindings by tag
    */
-  protected _parentEventListeners:
-    | Map<
-        string,
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        (...args: any[]) => void
-      >
-    | undefined;
+  protected readonly tagIndexer: ContextTagIndexer;
 
   /**
-   * A list of registered context observers. The Set will be created when the
-   * first observer is added.
+   * Manager for observer subscriptions
    */
-  protected observers: Set<ContextEventObserver> | undefined;
+  readonly subscriptionManager: ContextSubscriptionManager;
 
   /**
-   * Internal counter for pending notification events which are yet to be
-   * processed by observers.
+   * Parent context
    */
-  private pendingNotifications = 0;
+  protected _parent?: Context;
 
   /**
-   * Queue for background notifications for observers
+   * Configuration resolver
    */
-  private notificationQueue: AsyncIterableIterator<Notification> | undefined;
+  protected configResolver: ConfigurationResolver;
 
   /**
    * Create a new context.
@@ -128,12 +99,34 @@ export class Context extends EventEmitter {
    */
   constructor(_parent?: Context | string, name?: string) {
     super();
+    // The number of listeners can grow with the number of child contexts
+    // For example, each request can add a listener to the RestServer and the
+    // listener is removed when the request processing is finished.
+    // See https://github.com/strongloop/loopback-next/issues/4363
+    this.setMaxListeners(Infinity);
     if (typeof _parent === 'string') {
       name = _parent;
       _parent = undefined;
     }
     this._parent = _parent;
-    this.name = name ?? uuidv1();
+    this.name = name ?? this.generateName();
+    this.tagIndexer = new ContextTagIndexer(this);
+    this.subscriptionManager = new ContextSubscriptionManager(this);
+  }
+
+  private generateName() {
+    const id = uuidv1();
+    let prefix = `${this.constructor.name}-`;
+    if (prefix === 'Context-') prefix = '';
+    return `${prefix}${id}`;
+  }
+
+  /**
+   * @internal
+   * Getter for ContextSubscriptionManager
+   */
+  get parent() {
+    return this._parent;
   }
 
   /**
@@ -141,8 +134,7 @@ export class Context extends EventEmitter {
    * as the prefix
    * @param args - Arguments for the debug
    */
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  private _debug(...args: any[]) {
+  private _debug(...args: unknown[]) {
     /* istanbul ignore if */
     if (!debug.enabled) return;
     const formatter = args.shift();
@@ -154,176 +146,22 @@ export class Context extends EventEmitter {
   }
 
   /**
-   * Set up an internal listener to notify registered observers asynchronously
-   * upon `bind` and `unbind` events. This method will be called lazily when
-   * the first observer is added.
-   */
-  private setupEventHandlersIfNeeded() {
-    if (this.notificationQueue != null) return;
-
-    this.addParentEventListener('bind');
-    this.addParentEventListener('unbind');
-
-    // The following are two async functions. Returned promises are ignored as
-    // they are long-running background tasks.
-    this.startNotificationTask().catch(err => {
-      this.handleNotificationError(err);
-    });
-
-    let ctx = this._parent;
-    while (ctx) {
-      ctx.setupEventHandlersIfNeeded();
-      ctx = ctx._parent;
-    }
-  }
-
-  /**
-   * Add an event listener to its parent context so that this context will
-   * be notified of parent events, such as `bind` or `unbind`.
-   * @param event - Event name
+   * A strongly-typed method to emit context events
+   * @param type Event type
+   * @param event Context event
    */
-  private addParentEventListener(event: string) {
-    if (this._parent == null) return;
-
-    // Keep track of parent event listeners so that we can remove them
-    this._parentEventListeners = this._parentEventListeners ?? new Map();
-    if (this._parentEventListeners.has(event)) return;
-
-    const parentEventListener = (
-      binding: Readonly<Binding<unknown>>,
-      context: Context,
-    ) => {
-      // Propagate the event to this context only if the binding key does not
-      // exist in this context. The parent binding is shadowed if there is a
-      // binding with the same key in this one.
-      if (this.contains(binding.key)) {
-        this._debug(
-          'Event %s %s is not re-emitted from %s to %s',
-          event,
-          binding.key,
-          context.name,
-          this.name,
-        );
-        return;
-      }
-      this._debug(
-        'Re-emitting %s %s from %s to %s',
-        event,
-        binding.key,
-        context.name,
-        this.name,
-      );
-      this.emit(event, binding, context);
-    };
-    this._parentEventListeners.set(event, parentEventListener);
-    // Listen on the parent context events
-    this._parent.on(event, parentEventListener);
+  emitEvent<T extends ContextEvent>(type: string, event: T) {
+    this.emit(type, event);
   }
 
   /**
-   * Handle errors caught during the notification of observers
-   * @param err - Error
+   * Emit an `error` event
+   * @param err Error
    */
-  private handleNotificationError(err: unknown) {
-    // Bubbling up the error event over the context chain
-    // until we find an error listener
-    // eslint-disable-next-line @typescript-eslint/no-this-alias
-    let ctx: Context | undefined = this;
-    while (ctx) {
-      if (ctx.listenerCount('error') === 0) {
-        // No error listener found, try its parent
-        ctx = ctx._parent;
-        continue;
-      }
-      this._debug('Emitting error to context %s', ctx.name, err);
-      ctx.emit('error', err);
-      return;
-    }
-    // No context with error listeners found
-    this._debug('No error handler is configured for the context chain', err);
-    // Let it crash now by emitting an error event
+  emitError(err: unknown) {
     this.emit('error', err);
   }
 
-  /**
-   * Start a background task to listen on context events and notify observers
-   */
-  private startNotificationTask() {
-    // Set up listeners on `bind` and `unbind` for notifications
-    this.setupNotification('bind', 'unbind');
-
-    // Create an async iterator for the `notification` event as a queue
-    this.notificationQueue = iterator(this, 'notification');
-
-    return this.processNotifications();
-  }
-
-  /**
-   * Process notification events as they arrive on the queue
-   */
-  private async processNotifications() {
-    const events = this.notificationQueue;
-    if (events == null) return;
-    for await (const {eventType, binding, context, observers} of events) {
-      // The loop will happen asynchronously upon events
-      try {
-        // The execution of observers happen in the Promise micro-task queue
-        await this.notifyObservers(eventType, binding, context, observers);
-        this.pendingNotifications--;
-        this._debug(
-          'Observers notified for %s of binding %s',
-          eventType,
-          binding.key,
-        );
-        this.emit('observersNotified', {eventType, binding});
-      } catch (err) {
-        this.pendingNotifications--;
-        this._debug('Error caught from observers', err);
-        // Errors caught from observers. Emit it to the current context.
-        // If no error listeners are registered, crash the process.
-        this.emit('error', err);
-      }
-    }
-  }
-
-  /**
-   * Listen on given event types and emit `notification` event. This method
-   * merge multiple event types into one for notification.
-   * @param eventTypes - Context event types
-   */
-  private setupNotification(...eventTypes: ContextEventType[]) {
-    for (const eventType of eventTypes) {
-      this.on(eventType, (binding, context) => {
-        // No need to schedule notifications if no observers are present
-        if (!this.observers || this.observers.size === 0) return;
-        // Track pending events
-        this.pendingNotifications++;
-        // Take a snapshot of current observers to ensure notifications of this
-        // event will only be sent to current ones. Emit a new event to notify
-        // current context observers.
-        this.emit('notification', {
-          eventType,
-          binding,
-          context,
-          observers: new Set(this.observers),
-        });
-      });
-    }
-  }
-
-  /**
-   * Wait until observers are notified for all of currently pending notification
-   * events.
-   *
-   * This method is for test only to perform assertions after observers are
-   * notified for relevant events.
-   */
-  protected async waitUntilPendingNotificationsDone(timeout?: number) {
-    const count = this.pendingNotifications;
-    if (count === 0) return;
-    await multiple(this, 'observersNotified', {count, timeout});
-  }
-
   /**
    * Create a binding with the given key in the context. If a locked binding
    * already exists with the same key, an error will be thrown.
@@ -357,9 +195,13 @@ export class Context extends EventEmitter {
     this.registry.set(key, binding);
     if (existingBinding !== binding) {
       if (existingBinding != null) {
-        this.emit('unbind', existingBinding, this);
+        this.emitEvent('unbind', {
+          binding: existingBinding,
+          context: this,
+          type: 'unbind',
+        });
       }
-      this.emit('bind', binding, this);
+      this.emitEvent('bind', {binding, context: this, type: 'bind'});
     }
     return this;
   }
@@ -505,7 +347,7 @@ export class Context extends EventEmitter {
     if (binding?.isLocked)
       throw new Error(`Cannot unbind key "${key}" of a locked binding`);
     this.registry.delete(key);
-    this.emit('unbind', binding, this);
+    this.emitEvent('unbind', {binding, context: this, type: 'unbind'});
     return true;
   }
 
@@ -514,10 +356,7 @@ export class Context extends EventEmitter {
    * @param observer - Context observer instance or function
    */
   subscribe(observer: ContextEventObserver): Subscription {
-    this.observers = this.observers ?? new Set();
-    this.setupEventHandlersIfNeeded();
-    this.observers.add(observer);
-    return new ContextSubscription(this, observer);
+    return this.subscriptionManager.subscribe(observer);
   }
 
   /**
@@ -525,8 +364,7 @@ export class Context extends EventEmitter {
    * @param observer - Context event observer
    */
   unsubscribe(observer: ContextEventObserver): boolean {
-    if (!this.observers) return false;
-    return this.observers.delete(observer);
+    return this.subscriptionManager.unsubscribe(observer);
   }
 
   /**
@@ -540,20 +378,8 @@ export class Context extends EventEmitter {
    */
   close() {
     this._debug('Closing context...');
-    this.observers = undefined;
-    if (this.notificationQueue != null) {
-      // Cancel the notification iterator
-      this.notificationQueue.return!(undefined).catch(err => {
-        this.handleNotificationError(err);
-      });
-      this.notificationQueue = undefined;
-    }
-    if (this._parent && this._parentEventListeners) {
-      for (const [event, listener] of this._parentEventListeners) {
-        this._parent.removeListener(event, listener);
-      }
-      this._parentEventListeners = undefined;
-    }
+    this.subscriptionManager.close();
+    this.tagIndexer.close();
   }
 
   /**
@@ -561,8 +387,7 @@ export class Context extends EventEmitter {
    * @param observer - Context observer
    */
   isSubscribed(observer: ContextObserver) {
-    if (!this.observers) return false;
-    return this.observers.has(observer);
+    return this.subscriptionManager.isSubscribed(observer);
   }
 
   /**
@@ -579,34 +404,6 @@ export class Context extends EventEmitter {
     return view;
   }
 
-  /**
-   * Publish an event to the registered observers. Please note the
-   * notification is queued and performed asynchronously so that we allow fluent
-   * APIs such as `ctx.bind('key').to(...).tag(...);` and give observers the
-   * fully populated binding.
-   *
-   * @param eventType - Event names: `bind` or `unbind`
-   * @param binding - Binding bound or unbound
-   * @param context - Owner context
-   * @param observers - Current set of context observers
-   */
-  protected async notifyObservers(
-    eventType: ContextEventType,
-    binding: Readonly<Binding<unknown>>,
-    context: Context,
-    observers = this.observers,
-  ) {
-    if (!observers || observers.size === 0) return;
-
-    for (const observer of observers) {
-      if (typeof observer === 'function') {
-        await observer(eventType, binding, context);
-      } else if (!observer.filter || observer.filter(binding)) {
-        await observer.observe(eventType, binding, context);
-      }
-    }
-  }
-
   /**
    * Check if a binding exists with the given key in the local context without
    * delegating to the parent context
@@ -658,6 +455,11 @@ export class Context extends EventEmitter {
   find<ValueType = BoundValue>(
     pattern?: string | RegExp | BindingFilter,
   ): Readonly<Binding<ValueType>>[] {
+    // Optimize if the binding filter is for tags
+    if (typeof pattern === 'function' && isBindingTagFilter(pattern)) {
+      return this._findByTagIndex(pattern.bindingTagPattern);
+    }
+
     const bindings: Readonly<Binding<ValueType>>[] = [];
     const filter = filterByKey(pattern);
 
@@ -689,6 +491,18 @@ export class Context extends EventEmitter {
     return this.find(filterByTag(tagFilter));
   }
 
+  /**
+   * Find bindings by tag leveraging indexes
+   * @param tag - Tag name pattern or name/value pairs
+   */
+  protected _findByTagIndex<ValueType = BoundValue>(
+    tag: BindingTag | RegExp,
+  ): Readonly<Binding<ValueType>>[] {
+    const currentBindings = this.tagIndexer.findByTagIndex(tag);
+    const parentBindings = this._parent && this._parent?._findByTagIndex(tag);
+    return this._mergeWithParent(currentBindings, parentBindings);
+  }
+
   protected _mergeWithParent<ValueType>(
     childList: Readonly<Binding<ValueType>>[],
     parentList?: Readonly<Binding<ValueType>>[],
@@ -968,8 +782,8 @@ export class Context extends EventEmitter {
   /**
    * Create a plain JSON object for the context
    */
-  toJSON(): object {
-    const bindings: Record<string, object> = {};
+  toJSON(): JSONObject {
+    const bindings: JSONObject = {};
     for (const [k, v] of this.registry) {
       bindings[k] = v.toJSON();
     }
@@ -979,39 +793,39 @@ export class Context extends EventEmitter {
   /**
    * Inspect the context and dump out a JSON object representing the context
    * hierarchy
+   * @param options - Options for inspect
    */
   // TODO(rfeng): Evaluate https://nodejs.org/api/util.html#util_custom_inspection_functions_on_objects
-  inspect(): object {
-    const json: Record<string, unknown> = {
+  inspect(options: ContextInspectOptions = {}): JSONObject {
+    options = {
+      includeParent: true,
+      includeInjections: false,
+      ...options,
+    };
+    const bindings: JSONObject = {};
+    for (const [k, v] of this.registry) {
+      bindings[k] = v.inspect(options);
+    }
+    const json: JSONObject = {
       name: this.name,
-      bindings: this.toJSON(),
+      bindings,
     };
+    if (!options.includeParent) return json;
     if (this._parent) {
-      json.parent = this._parent.inspect();
+      json.parent = this._parent.inspect(options);
     }
     return json;
   }
 }
 
 /**
- * An implementation of `Subscription` interface for context events
+ * Options for context.inspect()
  */
-class ContextSubscription implements Subscription {
-  constructor(
-    protected context: Context,
-    protected observer: ContextEventObserver,
-  ) {}
-
-  private _closed = false;
-
-  unsubscribe() {
-    this.context.unsubscribe(this.observer);
-    this._closed = true;
-  }
-
-  get closed() {
-    return this._closed;
-  }
+export interface ContextInspectOptions extends BindingInspectOptions {
+  /**
+   * The flag to control if parent context should be inspected
+   */
+  includeParent?: boolean;
 }
 
 /**

package/src/index.ts

@@ -12,7 +12,9 @@ export * from './binding-inspector';
 export * from './binding-key';
 export * from './binding-sorter';
 export * from './context';
+export * from './context-event';
 export * from './context-observer';
+export * from './context-subscription';
 export * from './context-view';
 export * from './inject';
 export * from './inject-config';
@@ -25,3 +27,4 @@ export * from './provider';
 export * from './resolution-session';
 export * from './resolver';
 export * from './value-promise';
+export * from './json-types';

package/src/inject.ts

@@ -18,11 +18,13 @@ import {
   BindingSelector,
   filterByTag,
   isBindingAddress,
+  isBindingTagFilter,
 } from './binding-filter';
 import {BindingAddress} from './binding-key';
 import {BindingComparator} from './binding-sorter';
 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';
 
@@ -698,3 +700,66 @@ export function describeInjectedProperties(
     ) ?? {};
   return metadata;
 }
+
+/**
+ * Inspect injections for a binding created with `toClass` or `toProvider`
+ * @param binding - Binding object
+ */
+export function inspectInjections(binding: Readonly<Binding<unknown>>) {
+  const json: JSONObject = {};
+  const ctor = binding.valueConstructor ?? binding.providerConstructor;
+  if (ctor == null) return json;
+  const constructorInjections = describeInjectedArguments(ctor, '').map(
+    inspectInjection,
+  );
+  if (constructorInjections.length) {
+    json.constructorArguments = constructorInjections;
+  }
+  const propertyInjections = describeInjectedProperties(ctor.prototype);
+  const properties: JSONObject = {};
+  for (const p in propertyInjections) {
+    properties[p] = inspectInjection(propertyInjections[p]);
+  }
+  if (Object.keys(properties).length) {
+    json.properties = properties;
+  }
+  return json;
+}
+
+/**
+ * Inspect an injection
+ * @param injection - Injection information
+ */
+function inspectInjection(injection: Readonly<Injection<unknown>>) {
+  const injectionInfo = ResolutionSession.describeInjection(injection);
+  const descriptor: JSONObject = {};
+  if (injectionInfo.targetName) {
+    descriptor.targetName = injectionInfo.targetName;
+  }
+  if (isBindingAddress(injectionInfo.bindingSelector)) {
+    // Binding key
+    descriptor.bindingKey = injectionInfo.bindingSelector.toString();
+  } else if (isBindingTagFilter(injectionInfo.bindingSelector)) {
+    // Binding tag filter
+    descriptor.bindingTagPattern = JSON.parse(
+      JSON.stringify(injectionInfo.bindingSelector.bindingTagPattern),
+    );
+  } else {
+    // Binding filter function
+    descriptor.bindingFilter =
+      injectionInfo.bindingSelector?.name ?? '<function>';
+  }
+  // Inspect metadata
+  if (injectionInfo.metadata) {
+    if (
+      injectionInfo.metadata.decorator &&
+      injectionInfo.metadata.decorator !== '@inject'
+    ) {
+      descriptor.decorator = injectionInfo.metadata.decorator;
+    }
+    if (injectionInfo.metadata.optional) {
+      descriptor.optional = injectionInfo.metadata.optional;
+    }
+  }
+  return descriptor;
+}

package/src/interceptor.ts

@@ -15,7 +15,6 @@ import assert from 'assert';
 import debugFactory from 'debug';
 import {Binding, BindingTemplate} from './binding';
 import {bind} from './binding-decorator';
-import {filterByTag} from './binding-filter';
 import {BindingSpec} from './binding-inspector';
 import {sortBindingsByPhase} from './binding-sorter';
 import {Context} from './context';
@@ -47,12 +46,14 @@ export class InterceptedInvocationContext extends InvocationContext {
    * ContextTags.GLOBAL_INTERCEPTOR)
    */
   getGlobalInterceptorBindingKeys(): string[] {
-    const bindings: Readonly<Binding<Interceptor>>[] = this.find(
-      binding =>
-        filterByTag(ContextTags.GLOBAL_INTERCEPTOR)(binding) &&
-        // Only include interceptors that match the source type of the invocation
-        this.applicableTo(binding),
+    let bindings: Readonly<Binding<Interceptor>>[] = this.findByTag(
+      ContextTags.GLOBAL_INTERCEPTOR,
     );
+    bindings = bindings.filter(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);
     debug('Global interceptor binding keys:', keys);

package/src/invocation.ts

@@ -55,9 +55,7 @@ export class InvocationContext extends Context {
    * @param args - An array of arguments
    */
   constructor(
-    // Make `parent` public so that the interceptor can add bindings to
-    // the request context, for example, tracing id
-    public readonly parent: Context,
+    parent: Context,
     public readonly target: object,
     public readonly methodName: string,
     public readonly args: InvocationArgs,