@loopback/context 1.23.5 → 2.0.0

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';
@@ -11,16 +11,18 @@ 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 {ContextBindings} from './keys';
 import {
@@ -36,21 +38,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 +55,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 +98,27 @@ 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 ?? uuidv1();
+    this.tagIndexer = new ContextTagIndexer(this);
+    this.subscriptionManager = new ContextSubscriptionManager(this);
+  }
+
+  /**
+   * @internal
+   * Getter for ContextSubscriptionManager
+   */
+  get parent() {
+    return this._parent;
   }
 
   /**
@@ -141,8 +126,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 +138,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.
+   * A strongly-typed method to emit context events
+   * @param type Event type
+   * @param event Context event
    */
-  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
-   */
-  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.
@@ -350,16 +180,20 @@ 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`);
     }
     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;
   }
@@ -502,10 +336,10 @@ 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);
+    this.emitEvent('unbind', {binding, context: this, type: 'unbind'});
     return true;
   }
 
@@ -514,10 +348,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 +356,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 +370,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 +379,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 +396,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 +447,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 +483,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>>[],
@@ -885,7 +691,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,33 +774,28 @@ 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 json;
+    return bindings;
   }
-}
 
-/**
- * An implementation of `Subscription` interface for context events
- */
-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;
+  /**
+   * 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

@@ -12,16 +12,18 @@ 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 './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;
 }