@loopback/context 1.25.0 → 2.1.1

package/src/binding.ts

@@ -4,9 +4,12 @@
 // License text available at https://opensource.org/licenses/MIT
 
 import debugFactory from 'debug';
+import {EventEmitter} from 'events';
 import {BindingAddress, BindingKey} from './binding-key';
 import {Context} from './context';
+import {inspectInjections} from './inject';
 import {createProxyWithInterceptors} from './interception-proxy';
+import {JSONObject} from './json-types';
 import {ContextTags} from './keys';
 import {Provider} from './provider';
 import {
@@ -139,6 +142,34 @@ export type BindingTag = TagMap | string;
  */
 export type BindingTemplate<T = unknown> = (binding: Binding<T>) => void;
 
+/**
+ * Information for a binding event
+ */
+export type BindingEvent = {
+  /**
+   * Event type
+   */
+  type: string;
+  /**
+   * Source binding that emits the event
+   */
+  binding: Readonly<Binding<unknown>>;
+  /**
+   * Operation that triggers the event
+   */
+  operation: string;
+};
+
+/**
+ * Event listeners for binding events
+ */
+export type BindingEventListener = (
+  /**
+   * Binding event
+   */
+  event: BindingEvent,
+) => void;
+
 type ValueGetter<T> = (
   ctx: Context,
   options: ResolutionOptions,
@@ -148,7 +179,7 @@ type ValueGetter<T> = (
  * Binding represents an entry in the `Context`. Each binding has a key and a
  * corresponding value getter.
  */
-export class Binding<T = BoundValue> {
+export class Binding<T = BoundValue> extends EventEmitter {
   /**
    * Key of the binding
    */
@@ -181,6 +212,7 @@ export class Binding<T = BoundValue> {
 
   private _valueConstructor?: Constructor<T>;
   private _providerConstructor?: Constructor<Provider<T>>;
+  private _alias?: BindingAddress<T>;
 
   /**
    * For bindings bound via `toClass()`, this property contains the constructor
@@ -199,6 +231,7 @@ export class Binding<T = BoundValue> {
   }
 
   constructor(key: BindingAddress<T>, public isLocked: boolean = false) {
+    super();
     BindingKey.validate(key);
     this.key = key.toString();
   }
@@ -324,6 +357,15 @@ export class Binding<T = BoundValue> {
     return this;
   }
 
+  /**
+   * Emit a `changed` event
+   * @param operation - Operation that makes changes
+   */
+  private emitChangedEvent(operation: string) {
+    const event: BindingEvent = {binding: this, operation, type: 'changed'};
+    this.emit('changed', event);
+  }
+
   /**
    * Tag the binding with names or name/value objects. A tag has a name and
    * an optional value. If not supplied, the tag name is used as the value.
@@ -362,6 +404,7 @@ export class Binding<T = BoundValue> {
         Object.assign(this.tagMap, t);
       }
     }
+    this.emitChangedEvent('tag');
     return this;
   }
 
@@ -379,6 +422,7 @@ export class Binding<T = BoundValue> {
   inScope(scope: BindingScope): this {
     if (this._scope !== scope) this._clearCache();
     this._scope = scope;
+    this.emitChangedEvent('scope');
     return this;
   }
 
@@ -409,6 +453,7 @@ export class Binding<T = BoundValue> {
       }
       return getValue(ctx, options);
     };
+    this.emitChangedEvent('value');
   }
 
   /**
@@ -553,6 +598,7 @@ export class Binding<T = BoundValue> {
       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);
     });
@@ -591,8 +637,8 @@ export class Binding<T = BoundValue> {
   /**
    * Convert to a plain JSON object
    */
-  toJSON(): object {
-    const json: Record<string, unknown> = {
+  toJSON(): JSONObject {
+    const json: JSONObject = {
       key: this.key,
       scope: this.scope,
       tags: this.tagMap,
@@ -607,6 +653,26 @@ export class Binding<T = BoundValue> {
     if (this._providerConstructor != null) {
       json.providerConstructor = this._providerConstructor.name;
     }
+    if (this._alias != null) {
+      json.alias = this._alias.toString();
+    }
+    return json;
+  }
+
+  /**
+   * Inspect the binding to return a json representation of the binding information
+   * @param options - Options to control what information should be included
+   */
+  inspect(options: BindingInspectOptions = {}): JSONObject {
+    options = {
+      includeInjections: false,
+      ...options,
+    };
+    const json = this.toJSON();
+    if (options.includeInjections) {
+      const injections = inspectInjections(this);
+      if (Object.keys(injections).length) json.injections = injections;
+    }
     return json;
   }
 
@@ -641,6 +707,16 @@ export class Binding<T = BoundValue> {
   }
 }
 
+/**
+ * Options for binding.inspect()
+ */
+export interface BindingInspectOptions {
+  /**
+   * The flag to control if injections should be inspected
+   */
+  includeInjections?: boolean;
+}
+
 function createInterceptionProxyFromInstance<T>(
   instOrPromise: ValueOrPromise<T>,
   context: Context,

package/src/context-event.ts

@@ -0,0 +1,30 @@
+// Copyright IBM Corp. 2020. All Rights Reserved.
+// Node module: @loopback/context
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/licenses/MIT
+
+import {Binding} from './binding';
+import {Context} from './context';
+
+/**
+ * Events emitted by a context
+ */
+export type ContextEvent = {
+  /**
+   * Source context that emits the event
+   */
+  context: Context;
+  /**
+   * Binding that is being added/removed/updated
+   */
+  binding: Readonly<Binding<unknown>>;
+  /**
+   * Event type
+   */
+  type: string; // 'bind' or 'unbind'
+};
+
+/**
+ * Synchronous listener for context events
+ */
+export type ContextEventListener = (event: ContextEvent) => void;

package/src/context-observer.ts

@@ -5,8 +5,8 @@
 
 import {Binding} from './binding';
 import {BindingFilter} from './binding-filter';
-import {ValueOrPromise} from './value-promise';
 import {Context} from './context';
+import {ValueOrPromise} from './value-promise';
 
 /**
  * Context event types. We support `bind` and `unbind` for now but
@@ -48,40 +48,3 @@ export interface ContextObserver {
  * Context event observer type - An instance of `ContextObserver` or a function
  */
 export type ContextEventObserver = ContextObserver | ContextObserverFn;
-
-/**
- * Subscription of context events. It's modeled after
- * https://github.com/tc39/proposal-observable.
- */
-export interface Subscription {
-  /**
-   * unsubscribe
-   */
-  unsubscribe(): void;
-  /**
-   * Is the subscription closed?
-   */
-  closed: boolean;
-}
-
-/**
- * Event data for observer notifications
- */
-export type Notification = {
-  /**
-   * Context event type - bind/unbind
-   */
-  eventType: ContextEventType;
-  /**
-   * Binding added/removed
-   */
-  binding: Readonly<Binding<unknown>>;
-  /**
-   * Owner context for the binding
-   */
-  context: Context;
-  /**
-   * A snapshot of observers when the original event is emitted
-   */
-  observers: Set<ContextEventObserver>;
-};

package/src/context-subscription.ts

@@ -0,0 +1,403 @@
+// Copyright IBM Corp. 2020. All Rights Reserved.
+// Node module: @loopback/context
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/licenses/MIT
+
+import debugFactory from 'debug';
+import {EventEmitter} from 'events';
+import {Context} from './context';
+import {ContextEvent, ContextEventListener} from './context-event';
+import {
+  ContextEventObserver,
+  ContextEventType,
+  ContextObserver,
+} from './context-observer';
+const debug = debugFactory('loopback:context:subscription');
+
+/**
+ * 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';
+
+/**
+ * Subscription of context events. It's modeled after
+ * https://github.com/tc39/proposal-observable.
+ */
+export interface Subscription {
+  /**
+   * unsubscribe
+   */
+  unsubscribe(): void;
+  /**
+   * Is the subscription closed?
+   */
+  closed: boolean;
+}
+
+/**
+ * Event data for observer notifications
+ */
+export interface Notification extends ContextEvent {
+  /**
+   * A snapshot of observers when the original event is emitted
+   */
+  observers: Set<ContextEventObserver>;
+}
+
+/**
+ * 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;
+  }
+}
+
+/**
+ * Manager for context observer subscriptions
+ */
+export class ContextSubscriptionManager extends EventEmitter {
+  /**
+   * A listener to watch parent context events
+   */
+  protected _parentContextEventListener?: ContextEventListener;
+
+  /**
+   * A list of registered context observers. The Set will be created when the
+   * first observer is added.
+   */
+  protected _observers: Set<ContextEventObserver> | undefined;
+
+  /**
+   * Internal counter for pending notification events which are yet to be
+   * processed by observers.
+   */
+  private pendingNotifications = 0;
+
+  /**
+   * Queue for background notifications for observers
+   */
+  private notificationQueue: AsyncIterableIterator<Notification> | undefined;
+
+  constructor(protected readonly context: Context) {
+    super();
+    this.setMaxListeners(Infinity);
+  }
+
+  /**
+   * @internal
+   */
+  get parentContextEventListener() {
+    return this._parentContextEventListener;
+  }
+
+  /**
+   * @internal
+   */
+  get observers() {
+    return this._observers;
+  }
+
+  /**
+   * Wrap the debug statement so that it always print out the context name
+   * as the prefix
+   * @param args - Arguments for the debug
+   */
+  private _debug(...args: unknown[]) {
+    /* istanbul ignore if */
+    if (!debug.enabled) return;
+    const formatter = args.shift();
+    if (typeof formatter === 'string') {
+      debug(`[%s] ${formatter}`, this.context.name, ...args);
+    } else {
+      debug('[%s] ', this.context.name, formatter, ...args);
+    }
+  }
+
+  /**
+   * 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;
+
+    if (this.context.parent != null) {
+      /**
+       * Add an event listener to its parent context so that this context will
+       * be notified of parent events, such as `bind` or `unbind`.
+       */
+      this._parentContextEventListener = event => {
+        this.handleParentEvent(event);
+      };
+
+      // Listen on the parent context events
+      this.context.parent.on('bind', this._parentContextEventListener!);
+      this.context.parent.on('unbind', this._parentContextEventListener!);
+    }
+
+    // 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.context.parent;
+    while (ctx) {
+      ctx.subscriptionManager.setupEventHandlersIfNeeded();
+      ctx = ctx.parent;
+    }
+  }
+
+  private handleParentEvent(event: ContextEvent) {
+    const {binding, context, type} = event;
+    // 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.context.contains(binding.key)) {
+      this._debug(
+        'Event %s %s is not re-emitted from %s to %s',
+        type,
+        binding.key,
+        context.name,
+        this.context.name,
+      );
+      return;
+    }
+    this._debug(
+      'Re-emitting %s %s from %s to %s',
+      type,
+      binding.key,
+      context.name,
+      this.context.name,
+    );
+    this.context.emitEvent(type, event);
+  }
+
+  /**
+   * A strongly-typed method to emit context events
+   * @param type Event type
+   * @param event Context event
+   */
+  private emitEvent<T extends ContextEvent>(type: string, event: T) {
+    this.emit(type, event);
+  }
+
+  /**
+   * Emit an `error` event
+   * @param err Error
+   */
+  private 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();
+  }
+
+  /**
+   * 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 event - Context event
+   * @param observers - Current set of context observers
+   */
+  protected async notifyObservers(
+    event: ContextEvent,
+    observers = this._observers,
+  ) {
+    if (!observers || observers.size === 0) return;
+
+    const {type, binding, context} = event;
+    for (const observer of observers) {
+      if (typeof observer === 'function') {
+        await observer(type, binding, context);
+      } else if (!observer.filter || observer.filter(binding)) {
+        await observer.observe(type, binding, context);
+      }
+    }
+  }
+
+  /**
+   * Process notification events as they arrive on the queue
+   */
+  private async processNotifications() {
+    const events = this.notificationQueue;
+    if (events == null) return;
+    for await (const {type, 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({type, binding, context}, observers);
+        this.pendingNotifications--;
+        this._debug(
+          'Observers notified for %s of binding %s',
+          type,
+          binding.key,
+        );
+        this.emitEvent('observersNotified', {type, binding, context});
+      } 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.emitError(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 type of eventTypes) {
+      this.context.on(type, ({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.emitEvent('notification', {
+          type,
+          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.
+   */
+  async waitUntilPendingNotificationsDone(timeout?: number) {
+    const count = this.pendingNotifications;
+    if (count === 0) return;
+    await multiple(this, 'observersNotified', {count, timeout});
+  }
+
+  /**
+   * Add a context event observer to the context
+   * @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.context, observer);
+  }
+
+  /**
+   * Remove the context event observer from the context
+   * @param observer - Context event observer
+   */
+  unsubscribe(observer: ContextEventObserver): boolean {
+    if (!this._observers) return false;
+    return this._observers.delete(observer);
+  }
+
+  /**
+   * Check if an observer is subscribed to this context
+   * @param observer - Context observer
+   */
+  isSubscribed(observer: ContextObserver) {
+    if (!this._observers) return false;
+    return this._observers.has(observer);
+  }
+
+  /**
+   * Handle errors caught during the notification of observers
+   * @param err - Error
+   */
+  private handleNotificationError(err: unknown) {
+    // Bubbling up the error event over the context chain
+    // until we find an error listener
+    let ctx: Context | undefined = this.context;
+    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.emitError(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
+    this.context.emitError(err);
+  }
+
+  /**
+   * Close the context: clear observers, stop notifications, and remove event
+   * listeners from its parent context.
+   *
+   * @remarks
+   * This method MUST be called to avoid memory leaks once a context object is
+   * no longer needed and should be recycled. An example is the `RequestContext`,
+   * which is created per request.
+   */
+  close() {
+    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.context.parent && this._parentContextEventListener) {
+      this.context.parent.removeListener(
+        'bind',
+        this._parentContextEventListener,
+      );
+      this.context.parent.removeListener(
+        'unbind',
+        this._parentContextEventListener,
+      );
+      this._parentContextEventListener = undefined;
+    }
+  }
+}