@loopback/core 2.4.1 → 2.7.0

package/src/application.ts

@@ -5,16 +5,20 @@
 
 import {
   Binding,
+  BindingFromClassOptions,
   BindingScope,
   Constructor,
   Context,
   createBindingFromClass,
+  Interceptor,
+  InterceptorBindingOptions,
   JSONObject,
   Provider,
+  registerInterceptor,
 } from '@loopback/context';
 import assert from 'assert';
 import debugFactory from 'debug';
-import pEvent from 'p-event';
+import {once} from 'events';
 import {Component, mountComponent} from './component';
 import {CoreBindings, CoreTags} from './keys';
 import {
@@ -145,13 +149,16 @@ export class Application extends Context implements LifeCycleObserver {
    * app.controller(MyController).lock();
    * ```
    */
-  controller<T>(controllerCtor: ControllerClass<T>, name?: string): Binding<T> {
-    this.debug('Adding controller %s', name ?? controllerCtor.name);
+  controller<T>(
+    controllerCtor: ControllerClass<T>,
+    nameOrOptions?: string | BindingFromClassOptions,
+  ): Binding<T> {
+    this.debug('Adding controller %s', nameOrOptions ?? controllerCtor.name);
     const binding = createBindingFromClass(controllerCtor, {
-      name,
       namespace: CoreBindings.CONTROLLERS,
       type: CoreTags.CONTROLLER,
       defaultScope: BindingScope.TRANSIENT,
+      ...toOptions(nameOrOptions),
     });
     this.add(binding);
     return binding;
@@ -171,20 +178,20 @@ export class Application extends Context implements LifeCycleObserver {
    * ```
    *
    * @param server - The server constructor.
-   * @param name - Optional override for key name.
+   * @param nameOrOptions - Optional override for name or options.
    * @returns Binding for the server class
    *
    */
   public server<T extends Server>(
     ctor: Constructor<T>,
-    name?: string,
+    nameOrOptions?: string | BindingFromClassOptions,
   ): Binding<T> {
-    this.debug('Adding server %s', name ?? ctor.name);
+    this.debug('Adding server %s', nameOrOptions ?? ctor.name);
     const binding = createBindingFromClass(ctor, {
-      name,
       namespace: CoreBindings.SERVERS,
       type: CoreTags.SERVER,
       defaultScope: BindingScope.SINGLETON,
+      ...toOptions(nameOrOptions),
     }).apply(asLifeCycleObserver);
     this.add(binding);
     return binding;
@@ -278,7 +285,7 @@ export class Application extends Context implements LifeCycleObserver {
   }
 
   protected async awaitState(state: string) {
-    await pEvent(this, state);
+    await once(this, state);
   }
 
   /**
@@ -332,7 +339,8 @@ export class Application extends Context implements LifeCycleObserver {
    * controllers, providers, and servers from the component.
    *
    * @param componentCtor - The component class to add.
-   * @param name - Optional component name, default to the class name
+   * @param nameOrOptions - Optional component name or options, default to the
+   * class name
    *
    * @example
    * ```ts
@@ -351,14 +359,14 @@ export class Application extends Context implements LifeCycleObserver {
    */
   public component<T extends Component = Component>(
     componentCtor: Constructor<T>,
-    name?: string,
+    nameOrOptions?: string | BindingFromClassOptions,
   ) {
-    this.debug('Adding component: %s', name ?? componentCtor.name);
+    this.debug('Adding component: %s', nameOrOptions ?? componentCtor.name);
     const binding = createBindingFromClass(componentCtor, {
-      name,
       namespace: CoreBindings.COMPONENTS,
       type: CoreTags.COMPONENT,
       defaultScope: BindingScope.SINGLETON,
+      ...toOptions(nameOrOptions),
     });
     if (isLifeCycleObserverClass(componentCtor)) {
       binding.apply(asLifeCycleObserver);
@@ -383,18 +391,18 @@ export class Application extends Context implements LifeCycleObserver {
   /**
    * Register a life cycle observer class
    * @param ctor - A class implements LifeCycleObserver
-   * @param name - Optional name for the life cycle observer
+   * @param nameOrOptions - Optional name or options for the life cycle observer
    */
   public lifeCycleObserver<T extends LifeCycleObserver>(
     ctor: Constructor<T>,
-    name?: string,
+    nameOrOptions?: string | BindingFromClassOptions,
   ): Binding<T> {
-    this.debug('Adding life cycle observer %s', name ?? ctor.name);
+    this.debug('Adding life cycle observer %s', nameOrOptions ?? ctor.name);
     const binding = createBindingFromClass(ctor, {
-      name,
       namespace: CoreBindings.LIFE_CYCLE_OBSERVERS,
       type: CoreTags.LIFE_CYCLE_OBSERVER,
       defaultScope: BindingScope.SINGLETON,
+      ...toOptions(nameOrOptions),
     }).apply(asLifeCycleObserver);
     this.add(binding);
     return binding;
@@ -443,15 +451,28 @@ export class Application extends Context implements LifeCycleObserver {
    * ```
    */
   public service<S>(
-    cls: Constructor<S> | Constructor<Provider<S>>,
-    name?: string | ServiceOptions,
+    cls: Constructor<S | Provider<S>>,
+    nameOrOptions?: string | ServiceOptions,
   ): Binding<S> {
-    const options = typeof name === 'string' ? {name} : name;
+    const options = toOptions(nameOrOptions);
     const binding = createServiceBinding(cls, options);
     this.add(binding);
     return binding;
   }
 
+  /**
+   * Register an interceptor
+   * @param interceptor - An interceptor function or provider class
+   * @param nameOrOptions - Binding name or options
+   */
+  public interceptor(
+    interceptor: Interceptor | Constructor<Provider<Interceptor>>,
+    nameOrOptions?: string | InterceptorBindingOptions,
+  ) {
+    const options = toOptions(nameOrOptions);
+    return registerInterceptor(this, interceptor, options);
+  }
+
   /**
    * Set up signals that are captured to shutdown the application
    */
@@ -532,6 +553,17 @@ export class Application extends Context implements LifeCycleObserver {
   }
 }
 
+/**
+ * Normalize name or options to `BindingFromClassOptions`
+ * @param nameOrOptions - Name or options for binding from class
+ */
+function toOptions(nameOrOptions?: string | BindingFromClassOptions) {
+  if (typeof nameOrOptions === 'string') {
+    return {name: nameOrOptions};
+  }
+  return nameOrOptions ?? {};
+}
+
 /**
  * Options to set up application shutdown
  */

package/src/extension-point.ts

@@ -227,11 +227,13 @@ function inferExtensionPointName(
 /**
  * A factory function to create binding filter for extensions of a named
  * extension point
- * @param extensionPointName - Name of the extension point
+ * @param extensionPointNames - A list of names of extension points
  */
-export function extensionFilter(extensionPointName: string): BindingFilter {
+export function extensionFilter(
+  ...extensionPointNames: string[]
+): BindingFilter {
   return filterByTag({
-    [CoreTags.EXTENSION_FOR]: includesTagValue(extensionPointName),
+    [CoreTags.EXTENSION_FOR]: includesTagValue(...extensionPointNames),
   });
 }
 

package/src/index.ts

@@ -24,5 +24,6 @@ export * from './extension-point';
 export * from './keys';
 export * from './lifecycle';
 export * from './lifecycle-registry';
+export * from './mixin-target';
 export * from './server';
 export * from './service';

package/src/keys.ts

@@ -30,9 +30,9 @@ export namespace CoreBindings {
   /**
    * Binding key for application configuration
    */
-  export const APPLICATION_CONFIG = BindingKey.create<ApplicationConfig>(
-    'application.config',
-  );
+  export const APPLICATION_CONFIG: BindingKey<ApplicationConfig> = BindingKey.create<
+    ApplicationConfig
+  >('application.config');
 
   /**
    * Binding key for the content of `package.json`
@@ -60,9 +60,9 @@ export namespace CoreBindings {
    * Binding key for the controller class resolved in the current request
    * context
    */
-  export const CONTROLLER_CLASS = BindingKey.create<ControllerClass>(
-    'controller.current.ctor',
-  );
+  export const CONTROLLER_CLASS: BindingKey<ControllerClass> = BindingKey.create<
+    ControllerClass
+  >('controller.current.ctor');
 
   /**
    * Binding key for the controller method resolved in the current request

package/src/lifecycle.ts

@@ -7,6 +7,7 @@ import {
   bind,
   Binding,
   BindingSpec,
+  BindingTagFilter,
   Constructor,
   filterByTag,
   ValueOrPromise,
@@ -62,7 +63,7 @@ export function asLifeCycleObserver<T = unknown>(binding: Binding<T>) {
  * Find all life cycle observer bindings. By default, a binding tagged with
  * `CoreTags.LIFE_CYCLE_OBSERVER`. It's used as `BindingFilter`.
  */
-export const lifeCycleObserverFilter = filterByTag(
+export const lifeCycleObserverFilter: BindingTagFilter = filterByTag(
   CoreTags.LIFE_CYCLE_OBSERVER,
 );
 

package/src/mixin-target.ts

@@ -0,0 +1,70 @@
+// Copyright IBM Corp. 2017,2020. All Rights Reserved.
+// Node module: @loopback/core
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/licenses/MIT
+
+import {Constructor} from '@loopback/context';
+
+/**
+ * A replacement for `typeof Target` to be used in mixin class definitions.
+ * This is a workaround for TypeScript limitation described in
+ * - https://github.com/microsoft/TypeScript/issues/17293
+ * - https://github.com/microsoft/TypeScript/issues/17744
+ * - https://github.com/microsoft/TypeScript/issues/36060
+ *
+ * @example
+ *
+ * ```ts
+ * export function MyMixin<T extends MixinTarget<Application>>(superClass: T) {
+ *   return class extends superClass {
+ *     // contribute new class members
+ *   }
+ * };
+ * ```
+ *
+ * TypeScript does not allow class mixins to access protected members from
+ * the base class. You can use the following approach as a workaround:
+ *
+ * ```ts
+ * // @ts-ignore
+ * (this as unknown as {YourBaseClass}).protectedMember
+ * ```
+ *
+ * The directive `@ts-ignore` suppresses compiler error about accessing
+ * a protected member from outside. Unfortunately, it also disables other
+ * compile-time checks (e.g. to verify that a protected method was invoked
+ * with correct arguments, and so on). This is the same behavior you
+ * would get by using `Constructor<any>` instead of `MixinTarget<Application>`.
+ * The major improvement is that TypeScript can still infer the return
+ * type of the protected member, therefore `any` is NOT introduced to subsequent
+ * code.
+ *
+ * TypeScript also does not allow mixin class to overwrite a method inherited
+ * from a mapped type, see https://github.com/microsoft/TypeScript/issues/38496
+ * As a workaround, use `@ts-ignore` to disable the error.
+ *
+ * ```ts
+ * export function RepositoryMixin<T extends MixinTarget<Application>>(
+ * superClass: T,
+ * ) {
+ *   return class extends superClass {
+ *    // @ts-ignore
+ *    public component<C extends Component = Component>(
+ *      componentCtor: Constructor<C>,
+ *      nameOrOptions?: string | BindingFromClassOptions,
+ *    ) {
+ *      const binding = super.component(componentCtor, nameOrOptions);
+ *      // ...
+ *      return binding;
+ *    }
+ * }
+ * ```
+ */
+export type MixinTarget<T extends object> = Constructor<
+  {
+    // Enumerate only public members to avoid the following compiler error:
+    //   Property '(name)' of exported class expression
+    //   may not be private or protected.ts(4094)
+    [P in keyof T]: T[P];
+  }
+>;

package/src/service.ts

@@ -6,6 +6,7 @@
 import {
   Binding,
   BindingFilter,
+  BindingFromClassOptions,
   BindingTemplate,
   bindingTemplateFor,
   Constructor,
@@ -31,10 +32,9 @@ export type ServiceInterface = string | symbol | Function;
 /**
  * Options to register a service binding
  */
-export type ServiceOptions = {
-  name?: string;
+export interface ServiceOptions extends BindingFromClassOptions {
   interface?: ServiceInterface;
-};
+}
 
 /**
  * `@service` injects a service instance that matches the class or interface.
@@ -142,7 +142,7 @@ export function filterByServiceInterface(
  * @param options - Service options
  */
 export function createServiceBinding<S>(
-  cls: Constructor<S> | Constructor<Provider<S>>,
+  cls: Constructor<S | Provider<S>>,
   options: ServiceOptions = {},
 ): Binding<S> {
   let name = options.name;
@@ -162,6 +162,7 @@ export function createServiceBinding<S>(
   const binding = createBindingFromClass(cls, {
     name,
     type: CoreTags.SERVICE,
+    ...options,
   }).apply(asService(options.interface ?? cls));
   return binding;
 }

package/index.js

@@ -1,6 +0,0 @@
-// Copyright IBM Corp. 2017,2020. All Rights Reserved.
-// Node module: @loopback/core
-// This file is licensed under the MIT License.
-// License text available at https://opensource.org/licenses/MIT
-
-module.exports = require('./dist');