@loopback/core 4.0.0-alpha.9 → 4.0.2

package/src/lifecycle-registry.ts

@@ -0,0 +1,268 @@
+// Copyright IBM Corp. and LoopBack contributors 2018,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 {
+  Binding,
+  Context,
+  ContextView,
+  inject,
+  invokeMethod,
+  sortBindingsByPhase,
+} from '@loopback/context';
+import debugFactory from 'debug';
+import {CoreBindings, CoreTags} from './keys';
+import {LifeCycleObserver, lifeCycleObserverFilter} from './lifecycle';
+const debug = debugFactory('loopback:core:lifecycle');
+
+/**
+ * A group of life cycle observers
+ */
+export type LifeCycleObserverGroup = {
+  /**
+   * Observer group name
+   */
+  group: string;
+  /**
+   * Bindings for observers within the group
+   */
+  bindings: Readonly<Binding<LifeCycleObserver>>[];
+};
+
+export type LifeCycleObserverOptions = {
+  /**
+   * Control the order of observer groups for notifications. For example,
+   * with `['datasource', 'server']`, the observers in `datasource` group are
+   * notified before those in `server` group during `start`. Please note that
+   * observers are notified in the reverse order during `stop`.
+   */
+  orderedGroups: string[];
+  /**
+   * Override and disable lifecycle observer groups. This setting applies to
+   * both ordered groups (i.e. those defined in `orderedGroups`) and unordered
+   * groups.
+   */
+  disabledGroups?: string[];
+  /**
+   * Notify observers of the same group in parallel, default to `true`
+   */
+  parallel?: boolean;
+};
+
+export const DEFAULT_ORDERED_GROUPS = ['server'];
+
+/**
+ * A context-based registry for life cycle observers
+ */
+export class LifeCycleObserverRegistry implements LifeCycleObserver {
+  constructor(
+    @inject.context()
+    protected readonly context: Context,
+    @inject.view(lifeCycleObserverFilter)
+    protected readonly observersView: ContextView<LifeCycleObserver>,
+    @inject(CoreBindings.LIFE_CYCLE_OBSERVER_OPTIONS, {optional: true})
+    protected readonly options: LifeCycleObserverOptions = {
+      parallel: true,
+      orderedGroups: DEFAULT_ORDERED_GROUPS,
+    },
+  ) {}
+
+  setOrderedGroups(groups: string[]) {
+    this.options.orderedGroups = groups;
+  }
+
+  /**
+   * Get observer groups ordered by the group
+   */
+  public getObserverGroupsByOrder(): LifeCycleObserverGroup[] {
+    const bindings = this.observersView.bindings;
+    const groups = this.sortObserverBindingsByGroup(bindings);
+    if (debug.enabled) {
+      debug(
+        'Observer groups: %j',
+        groups.map(g => ({
+          group: g.group,
+          bindings: g.bindings.map(b => b.key),
+        })),
+      );
+    }
+    return groups;
+  }
+
+  /**
+   * Get the group for a given life cycle observer binding
+   * @param binding - Life cycle observer binding
+   */
+  protected getObserverGroup(
+    binding: Readonly<Binding<LifeCycleObserver>>,
+  ): string {
+    // First check if there is an explicit group name in the tag
+    let group = binding.tagMap[CoreTags.LIFE_CYCLE_OBSERVER_GROUP];
+    if (!group) {
+      // Fall back to a tag that matches one of the groups
+      group = this.options.orderedGroups.find(g => binding.tagMap[g] === g);
+    }
+    group = group || '';
+    debug(
+      'Binding %s is configured with observer group %s',
+      binding.key,
+      group,
+    );
+    return group;
+  }
+
+  /**
+   * Sort the life cycle observer bindings so that we can start/stop them
+   * in the right order. By default, we can start other observers before servers
+   * and stop them in the reverse order
+   * @param bindings - Life cycle observer bindings
+   */
+  protected sortObserverBindingsByGroup(
+    bindings: Readonly<Binding<LifeCycleObserver>>[],
+  ) {
+    // Group bindings in a map
+    const groupMap: Map<string, Readonly<Binding<LifeCycleObserver>>[]> =
+      new Map();
+    sortBindingsByPhase(
+      bindings,
+      CoreTags.LIFE_CYCLE_OBSERVER_GROUP,
+      this.options.orderedGroups,
+    );
+    for (const binding of bindings) {
+      const group = this.getObserverGroup(binding);
+      let bindingsInGroup = groupMap.get(group);
+      if (bindingsInGroup == null) {
+        bindingsInGroup = [];
+        groupMap.set(group, bindingsInGroup);
+      }
+      bindingsInGroup.push(binding);
+    }
+    // Create an array for group entries
+    const groups: LifeCycleObserverGroup[] = [];
+    for (const [group, bindingsInGroup] of groupMap) {
+      groups.push({group, bindings: bindingsInGroup});
+    }
+    return groups;
+  }
+
+  /**
+   * Notify an observer group of the given event
+   * @param group - A group of bindings for life cycle observers
+   * @param event - Event name
+   */
+  protected async notifyObservers(
+    observers: LifeCycleObserver[],
+    bindings: Readonly<Binding<LifeCycleObserver>>[],
+    event: keyof LifeCycleObserver,
+  ) {
+    if (!this.options.parallel) {
+      let index = 0;
+      for (const observer of observers) {
+        debug(
+          'Invoking %s observer for binding %s',
+          event,
+          bindings[index].key,
+        );
+        index++;
+        await this.invokeObserver(observer, event);
+      }
+      return;
+    }
+
+    // Parallel invocation
+    const notifiers = observers.map((observer, index) => {
+      debug('Invoking %s observer for binding %s', event, bindings[index].key);
+      return this.invokeObserver(observer, event);
+    });
+    await Promise.all(notifiers);
+  }
+
+  /**
+   * Invoke an observer for the given event
+   * @param observer - A life cycle observer
+   * @param event - Event name
+   */
+  protected async invokeObserver(
+    observer: LifeCycleObserver,
+    event: keyof LifeCycleObserver,
+  ) {
+    if (typeof observer[event] === 'function') {
+      // Supply `undefined` for legacy callback function expected by
+      // DataSource.stop()
+      await invokeMethod(observer, event, this.context, [undefined], {
+        skipInterceptors: true,
+      });
+    }
+  }
+
+  /**
+   * Emit events to the observer groups
+   * @param events - Event names
+   * @param groups - Observer groups
+   */
+  protected async notifyGroups(
+    events: (keyof LifeCycleObserver)[],
+    groups: LifeCycleObserverGroup[],
+    reverse = false,
+  ) {
+    const observers = await this.observersView.values();
+    const bindings = this.observersView.bindings;
+    const found = observers.some(observer =>
+      events.some(e => typeof observer[e] === 'function'),
+    );
+    if (!found) return;
+    if (reverse) {
+      // Do not reverse the original `groups` in place
+      groups = [...groups].reverse();
+    }
+    for (const group of groups) {
+      if (this.options.disabledGroups?.includes(group.group)) {
+        debug('Notification skipped (Group is disabled): %s', group.group);
+        continue;
+      }
+      const observersForGroup: LifeCycleObserver[] = [];
+      const bindingsInGroup = reverse
+        ? group.bindings.reverse()
+        : group.bindings;
+      for (const binding of bindingsInGroup) {
+        const index = bindings.indexOf(binding);
+        observersForGroup.push(observers[index]);
+      }
+
+      for (const event of events) {
+        debug('Beginning notification %s of %s...', event);
+        await this.notifyObservers(observersForGroup, group.bindings, event);
+        debug('Finished notification %s of %s', event);
+      }
+    }
+  }
+
+  /**
+   * Notify all life cycle observers by group of `init`
+   */
+  public async init(): Promise<void> {
+    debug('Initializing the %s...');
+    const groups = this.getObserverGroupsByOrder();
+    await this.notifyGroups(['init'], groups);
+  }
+
+  /**
+   * Notify all life cycle observers by group of `start`
+   */
+  public async start(): Promise<void> {
+    debug('Starting the %s...');
+    const groups = this.getObserverGroupsByOrder();
+    await this.notifyGroups(['start'], groups);
+  }
+
+  /**
+   * Notify all life cycle observers by group of `stop`
+   */
+  public async stop(): Promise<void> {
+    debug('Stopping the %s...');
+    const groups = this.getObserverGroupsByOrder();
+    // Stop in the reverse order
+    await this.notifyGroups(['stop'], groups, true);
+  }
+}

package/src/lifecycle.ts

@@ -0,0 +1,90 @@
+// Copyright IBM Corp. and LoopBack contributors 2018,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 {
+  Binding,
+  BindingSpec,
+  BindingTagFilter,
+  Constructor,
+  filterByTag,
+  injectable,
+  ValueOrPromise,
+} from '@loopback/context';
+import {CoreTags} from './keys';
+
+/**
+ * Observers to handle life cycle init/start/stop events
+ */
+export interface LifeCycleObserver {
+  /**
+   * The method to be invoked during `init`. It will only be called at most once
+   * for a given application instance.
+   */
+  init?(...injectedArgs: unknown[]): ValueOrPromise<void>;
+  /**
+   * The method to be invoked during `start`
+   */
+  start?(...injectedArgs: unknown[]): ValueOrPromise<void>;
+  /**
+   * The method to be invoked during `stop`
+   */
+  stop?(...injectedArgs: unknown[]): ValueOrPromise<void>;
+}
+
+const lifeCycleMethods: (keyof LifeCycleObserver)[] = ['init', 'start', 'stop'];
+
+/**
+ * Test if an object implements LifeCycleObserver
+ * @param obj - An object
+ */
+export function isLifeCycleObserver(obj: object): obj is LifeCycleObserver {
+  const candidate = obj as Partial<LifeCycleObserver>;
+  return lifeCycleMethods.some(m => typeof candidate[m] === 'function');
+}
+
+/**
+ * Test if a class implements LifeCycleObserver
+ * @param ctor - A class
+ */
+export function isLifeCycleObserverClass(
+  ctor: Constructor<unknown>,
+): ctor is Constructor<LifeCycleObserver> {
+  return ctor.prototype && isLifeCycleObserver(ctor.prototype);
+}
+
+/**
+ * A `BindingTemplate` function to configure the binding as life cycle observer
+ * by tagging it with `CoreTags.LIFE_CYCLE_OBSERVER`.
+ *
+ * @param binding - Binding object
+ */
+export function asLifeCycleObserver<T = unknown>(binding: Binding<T>) {
+  return binding.tag(CoreTags.LIFE_CYCLE_OBSERVER);
+}
+
+/**
+ * Find all life cycle observer bindings. By default, a binding tagged with
+ * `CoreTags.LIFE_CYCLE_OBSERVER`. It's used as `BindingFilter`.
+ */
+export const lifeCycleObserverFilter: BindingTagFilter = filterByTag(
+  CoreTags.LIFE_CYCLE_OBSERVER,
+);
+
+/**
+ * Sugar decorator to mark a class as life cycle observer
+ * @param group - Optional observer group name
+ * @param specs - Optional bindings specs
+ */
+export function lifeCycleObserver(group = '', ...specs: BindingSpec[]) {
+  return injectable(
+    asLifeCycleObserver,
+    {
+      tags: {
+        [CoreTags.LIFE_CYCLE_OBSERVER_GROUP]: group,
+      },
+    },
+    ...specs,
+  );
+}

package/src/mixin-target.ts

@@ -0,0 +1,69 @@
+// Copyright IBM Corp. and LoopBack contributors 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
+ * // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+ * // @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/server.ts

@@ -0,0 +1,22 @@
+// Copyright IBM Corp. and LoopBack contributors 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 {LifeCycleObserver} from './lifecycle';
+
+/**
+ * Defines the requirements to implement a Server for LoopBack applications:
+ * start() : Promise<void>
+ * stop() : Promise<void>
+ * It is recommended that each Server implementation creates its own child
+ * Context, which inherits from the parent Application context. This way,
+ * any Server-specific bindings will remain local to the Server instance,
+ * and will avoid polluting its parent module scope.
+ */
+export interface Server extends LifeCycleObserver {
+  /**
+   * Tells whether the server is listening for connections or not
+   */
+  readonly listening: boolean;
+}

package/src/service.ts

@@ -0,0 +1,211 @@
+// Copyright IBM Corp. and LoopBack contributors 2019,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 {
+  Binding,
+  BindingFilter,
+  BindingFromClassOptions,
+  BindingTemplate,
+  bindingTemplateFor,
+  ContextTags,
+  ContextView,
+  createBindingFromClass,
+  DecoratorFactory,
+  inject,
+  InjectionMetadata,
+  isDynamicValueProviderClass,
+  isProviderClass,
+  MetadataInspector,
+  transformValueOrPromise,
+} from '@loopback/context';
+import {ServiceOrProviderClass} from './application';
+import {CoreTags} from './keys';
+
+/**
+ * Representing an interface for services. In TypeScript, the `interface` does
+ * not have reflections at runtime. We use a string, a symbol or a Function as
+ * the type for the service interface.
+ */
+export type ServiceInterface = string | symbol | Function;
+
+/**
+ * Options to register a service binding
+ */
+export interface ServiceOptions extends BindingFromClassOptions {
+  interface?: ServiceInterface;
+}
+
+/**
+ * `@service` injects a service instance that matches the class or interface.
+ *
+ * @param serviceInterface - Interface for the service. It can be in one of the
+ * following forms:
+ *
+ * - A class, such as MyService
+ * - A string that identifies the interface, such as `'MyService'`
+ * - A symbol that identifies the interface, such as `Symbol('MyService')`
+ *
+ * If not provided, the value is inferred from the design:type of the parameter
+ * or property
+ *
+ * @example
+ * ```ts
+ *
+ * const ctx = new Context();
+ * ctx.bind('my-service').toClass(MyService);
+ * ctx.bind('logger').toClass(Logger);
+ *
+ * export class MyController {
+ *   constructor(@service(MyService) private myService: MyService) {}
+ *
+ *   @service()
+ *   private logger: Logger;
+ * }
+ *
+ * ctx.bind('my-controller').toClass(MyController);
+ * await myController = ctx.get<MyController>('my-controller');
+ * ```
+ */
+export function service(
+  serviceInterface?: ServiceInterface,
+  metadata?: InjectionMetadata,
+) {
+  return inject(
+    '',
+    {decorator: '@service', ...metadata},
+    (ctx, injection, session) => {
+      let serviceType = serviceInterface;
+      if (!serviceType) {
+        if (typeof injection.methodDescriptorOrParameterIndex === 'number') {
+          serviceType = MetadataInspector.getDesignTypeForMethod(
+            injection.target,
+            injection.member!,
+          )?.parameterTypes[injection.methodDescriptorOrParameterIndex];
+        } else {
+          serviceType = MetadataInspector.getDesignTypeForProperty(
+            injection.target,
+            injection.member!,
+          );
+        }
+      }
+      if (serviceType === undefined) {
+        const targetName = DecoratorFactory.getTargetName(
+          injection.target,
+          injection.member,
+          injection.methodDescriptorOrParameterIndex,
+        );
+        const msg =
+          `No design-time type metadata found while inspecting ${targetName}. ` +
+          'You can either use `@service(ServiceClass)` or ensure `emitDecoratorMetadata` is enabled in your TypeScript configuration. ' +
+          'Run `tsc --showConfig` to print the final TypeScript configuration of your project.';
+        throw new Error(msg);
+      }
+
+      if (serviceType === Object || serviceType === Array) {
+        throw new Error(
+          'Service class cannot be inferred from design type. Use @service(ServiceClass).',
+        );
+      }
+      const view = new ContextView(ctx, filterByServiceInterface(serviceType));
+      const result = view.resolve({
+        optional: metadata?.optional,
+        asProxyWithInterceptors: metadata?.asProxyWithInterceptors,
+        session,
+      });
+
+      const serviceTypeName =
+        typeof serviceType === 'string'
+          ? serviceType
+          : typeof serviceType === 'symbol'
+          ? serviceType.toString()
+          : serviceType.name;
+      return transformValueOrPromise(result, values => {
+        if (values.length === 1) return values[0];
+        if (values.length >= 1) {
+          throw new Error(
+            `More than one bindings found for ${serviceTypeName}`,
+          );
+        } else {
+          if (metadata?.optional) {
+            return undefined;
+          }
+          throw new Error(
+            `No binding found for ${serviceTypeName}. Make sure a service ` +
+              `binding is created in context ${ctx.name} with serviceInterface (${serviceTypeName}).`,
+          );
+        }
+      });
+    },
+  );
+}
+
+/**
+ * Create a binding filter by service class
+ * @param serviceInterface - Service class matching the one used by `binding.toClass()`
+ * @param options - Options to control if subclasses should be skipped for matching
+ */
+export function filterByServiceInterface(
+  serviceInterface: ServiceInterface,
+): BindingFilter {
+  return binding =>
+    binding.valueConstructor === serviceInterface ||
+    binding.tagMap[CoreTags.SERVICE_INTERFACE] === serviceInterface;
+}
+
+/**
+ * Create a service binding from a class or provider
+ * @param cls - Service class or provider
+ * @param options - Service options
+ */
+export function createServiceBinding<S>(
+  cls: ServiceOrProviderClass<S>,
+  options: ServiceOptions = {},
+): Binding<S> {
+  let name = options.name;
+  if (!name && isProviderClass(cls)) {
+    // Trim `Provider` from the default service name
+    // This is needed to keep backward compatibility
+    const templateFn = bindingTemplateFor(cls);
+    const template = Binding.bind<S>('template').apply(templateFn);
+    if (
+      template.tagMap[ContextTags.PROVIDER] &&
+      !template.tagMap[ContextTags.NAME]
+    ) {
+      // The class is a provider and no `name` tag is found
+      name = cls.name.replace(/Provider$/, '');
+    }
+  }
+  if (!name && isDynamicValueProviderClass(cls)) {
+    // Trim `Provider` from the default service name
+    const templateFn = bindingTemplateFor(cls);
+    const template = Binding.bind<S>('template').apply(templateFn);
+    if (
+      template.tagMap[ContextTags.DYNAMIC_VALUE_PROVIDER] &&
+      !template.tagMap[ContextTags.NAME]
+    ) {
+      // The class is a provider and no `name` tag is found
+      name = cls.name.replace(/Provider$/, '');
+    }
+  }
+  const binding = createBindingFromClass(cls, {
+    name,
+    type: CoreTags.SERVICE,
+    ...options,
+  }).apply(asService(options.interface ?? cls));
+  return binding;
+}
+
+/**
+ * Create a binding template for a service interface
+ * @param serviceInterface - Service interface
+ */
+export function asService(serviceInterface: ServiceInterface): BindingTemplate {
+  return function serviceTemplate(binding: Binding) {
+    binding.tag({
+      [ContextTags.TYPE]: CoreTags.SERVICE,
+      [CoreTags.SERVICE_INTERFACE]: serviceInterface,
+    });
+  };
+}

package/index.d.ts

@@ -1,6 +0,0 @@
-// Copyright IBM Corp. 2017. All Rights Reserved.
-// Node module: @loopback/core
-// This file is licensed under the MIT License.
-// License text available at https://opensource.org/licenses/MIT
-
-export * from './lib';

package/index.js

@@ -1,9 +0,0 @@
-// Copyright IBM Corp. 2017. All Rights Reserved.
-// Node module: @loopback/core
-// This file is licensed under the MIT License.
-// License text available at https://opensource.org/licenses/MIT
-
-const nodeMajorVersion = +process.versions.node.split('.')[0];
-module.exports = nodeMajorVersion >= 7 ?
-  require('./lib') :
-  require('./lib6');