@loopback/core 4.0.0-alpha.8 → 4.0.1

package/src/component.ts

@@ -0,0 +1,155 @@
+// Copyright IBM Corp. and LoopBack contributors 2017,2019. 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,
+  BoundValue,
+  Constructor,
+  createBindingFromClass,
+  Provider,
+} from '@loopback/context';
+import {
+  Application,
+  ControllerClass,
+  ServiceOrProviderClass,
+} from './application';
+import {LifeCycleObserver} from './lifecycle';
+import {Server} from './server';
+
+/**
+ * A map of provider classes to be bound to a context
+ */
+export interface ProviderMap {
+  [key: string]: Constructor<Provider<BoundValue>>;
+}
+
+/**
+ * A map of classes to be bound to a context
+ */
+export interface ClassMap {
+  [key: string]: Constructor<BoundValue>;
+}
+
+/**
+ * A component declares a set of artifacts so that they can be contributed to
+ * an application as a group
+ */
+export interface Component {
+  /**
+   * An array of controller classes
+   */
+  controllers?: ControllerClass[];
+
+  /**
+   * A map of providers to be bound to the application context
+   *
+   * @example
+   * ```ts
+   * {
+   *   'authentication.strategies.ldap': LdapStrategyProvider
+   * }
+   * ```
+   */
+  providers?: ProviderMap;
+
+  /**
+   * A map of classes to be bound to the application context.
+   *
+   * @example
+   * ```ts
+   * {
+   *   'rest.body-parsers.xml': XmlBodyParser
+   * }
+   * ```
+   */
+  classes?: ClassMap;
+
+  /**
+   * A map of name/class pairs for servers
+   */
+  servers?: {
+    [name: string]: Constructor<Server>;
+  };
+
+  lifeCycleObservers?: Constructor<LifeCycleObserver>[];
+
+  /**
+   * An array of service or provider classes
+   */
+  services?: ServiceOrProviderClass[];
+
+  /**
+   * An array of bindings to be aded to the application context.
+   *
+   * @example
+   * ```ts
+   * const bindingX = Binding.bind('x').to('Value X');
+   * this.bindings = [bindingX]
+   * ```
+   */
+  bindings?: Binding[];
+
+  /**
+   * Other properties
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  [prop: string]: any;
+}
+
+/**
+ * Mount a component to an Application.
+ *
+ * @param app - Application
+ * @param component - Component instance
+ */
+export function mountComponent(app: Application, component: Component) {
+  if (component.classes) {
+    for (const classKey in component.classes) {
+      const binding = createBindingFromClass(component.classes[classKey], {
+        key: classKey,
+      });
+      app.add(binding);
+    }
+  }
+
+  if (component.providers) {
+    for (const providerKey in component.providers) {
+      const binding = createBindingFromClass(component.providers[providerKey], {
+        key: providerKey,
+      });
+      app.add(binding);
+    }
+  }
+
+  if (component.bindings) {
+    for (const binding of component.bindings) {
+      app.add(binding);
+    }
+  }
+
+  if (component.controllers) {
+    for (const controllerCtor of component.controllers) {
+      app.controller(controllerCtor);
+    }
+  }
+
+  if (component.servers) {
+    for (const serverKey in component.servers) {
+      app.server(component.servers[serverKey], serverKey);
+    }
+  }
+
+  if (component.lifeCycleObservers) {
+    for (const observer of component.lifeCycleObservers) {
+      app.lifeCycleObserver(observer);
+    }
+  }
+
+  if (component.services) {
+    for (const service of component.services) {
+      app.service(service);
+    }
+  }
+}

package/src/extension-point.ts

@@ -0,0 +1,312 @@
+// 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 {
+  asResolutionOptions,
+  assertTargetType,
+  Binding,
+  BindingFilter,
+  BindingFromClassOptions,
+  BindingSpec,
+  BindingTemplate,
+  Constructor,
+  Context,
+  ContextTags,
+  ContextView,
+  createBindingFromClass,
+  createViewGetter,
+  filterByTag,
+  includesTagValue,
+  inject,
+  injectable,
+  Injection,
+  InjectionMetadata,
+  ResolutionSession,
+} from '@loopback/context';
+import {CoreTags} from './keys';
+
+/**
+ * Decorate a class as a named extension point. If the decoration is not
+ * present, the name of the class will be used.
+ *
+ * @example
+ * ```ts
+ * import {extensionPoint} from '@loopback/core';
+ *
+ * @extensionPoint(GREETER_EXTENSION_POINT_NAME)
+ * export class GreetingService {
+ *   // ...
+ * }
+ * ```
+ *
+ * @param name - Name of the extension point
+ */
+export function extensionPoint(name: string, ...specs: BindingSpec[]) {
+  return injectable({tags: {[CoreTags.EXTENSION_POINT]: name}}, ...specs);
+}
+
+/**
+ * Shortcut to inject extensions for the given extension point.
+ *
+ * @example
+ * ```ts
+ * import {Getter} from '@loopback/context';
+ * import {extensionPoint, extensions} from '@loopback/core';
+ *
+ * @extensionPoint(GREETER_EXTENSION_POINT_NAME)
+ * export class GreetingService {
+ *  constructor(
+ *    @extensions() // Inject extensions for the extension point
+ *    private getGreeters: Getter<Greeter[]>,
+ *    // ...
+ * ) {
+ *   // ...
+ * }
+ * ```
+ *
+ * @param extensionPointName - Name of the extension point. If not supplied, we
+ * use the `name` tag from the extension point binding or the class name of the
+ * extension point class. If a class needs to inject extensions from multiple
+ * extension points, use different `extensionPointName` for different types of
+ * extensions.
+ * @param metadata - Optional injection metadata
+ */
+export function extensions(
+  extensionPointName?: string,
+  metadata?: InjectionMetadata,
+) {
+  return inject(
+    '',
+    {...metadata, decorator: '@extensions'},
+    (ctx, injection, session) => {
+      assertTargetType(injection, Function, 'Getter function');
+      const bindingFilter = filterByExtensionPoint(
+        injection,
+        session,
+        extensionPointName,
+      );
+      return createViewGetter(
+        ctx,
+        bindingFilter,
+        injection.metadata.bindingComparator,
+        {...metadata, ...asResolutionOptions(session)},
+      );
+    },
+  );
+}
+
+export namespace extensions {
+  /**
+   * Inject a `ContextView` for extensions of the extension point. The view can
+   * then be listened on events such as `bind`, `unbind`, or `refresh` to react
+   * on changes of extensions.
+   *
+   * @example
+   * ```ts
+   * import {extensionPoint, extensions} from '@loopback/core';
+   *
+   * @extensionPoint(GREETER_EXTENSION_POINT_NAME)
+   * export class GreetingService {
+   *  constructor(
+   *    @extensions.view() // Inject a context view for extensions of the extension point
+   *    private greetersView: ContextView<Greeter>,
+   *    // ...
+   * ) {
+   *   // ...
+   * }
+   * ```
+   * @param extensionPointName - Name of the extension point. If not supplied, we
+   * use the `name` tag from the extension point binding or the class name of the
+   * extension point class. If a class needs to inject extensions from multiple
+   * extension points, use different `extensionPointName` for different types of
+   * extensions.
+   * @param metadata - Optional injection metadata
+   */
+  export function view(
+    extensionPointName?: string,
+    metadata?: InjectionMetadata,
+  ) {
+    return inject(
+      '',
+      {...metadata, decorator: '@extensions.view'},
+      (ctx, injection, session) => {
+        assertTargetType(injection, ContextView);
+        const bindingFilter = filterByExtensionPoint(
+          injection,
+          session,
+          extensionPointName,
+        );
+        return ctx.createView(
+          bindingFilter,
+          injection.metadata.bindingComparator,
+          metadata,
+        );
+      },
+    );
+  }
+
+  /**
+   * Inject an array of resolved extension instances for the extension point.
+   * The list is a snapshot of registered extensions when the injection is
+   * fulfilled. Extensions added or removed afterward won't impact the list.
+   *
+   * @example
+   * ```ts
+   * import {extensionPoint, extensions} from '@loopback/core';
+   *
+   * @extensionPoint(GREETER_EXTENSION_POINT_NAME)
+   * export class GreetingService {
+   *  constructor(
+   *    @extensions.list() // Inject an array of extensions for the extension point
+   *    private greeters: Greeter[],
+   *    // ...
+   * ) {
+   *   // ...
+   * }
+   * ```
+   * @param extensionPointName - Name of the extension point. If not supplied, we
+   * use the `name` tag from the extension point binding or the class name of the
+   * extension point class. If a class needs to inject extensions from multiple
+   * extension points, use different `extensionPointName` for different types of
+   * extensions.
+   * @param metadata - Optional injection metadata
+   */
+  export function list(
+    extensionPointName?: string,
+    metadata?: InjectionMetadata,
+  ) {
+    return inject(
+      '',
+      {...metadata, decorator: '@extensions.instances'},
+      (ctx, injection, session) => {
+        assertTargetType(injection, Array);
+        const bindingFilter = filterByExtensionPoint(
+          injection,
+          session,
+          extensionPointName,
+        );
+        const viewForExtensions = new ContextView(
+          ctx,
+          bindingFilter,
+          injection.metadata.bindingComparator,
+        );
+        return viewForExtensions.resolve({
+          ...metadata,
+          ...asResolutionOptions(session),
+        });
+      },
+    );
+  }
+}
+
+/**
+ * Create a binding filter for `@extensions.*`
+ * @param injection - Injection object
+ * @param session - Resolution session
+ * @param extensionPointName - Extension point name
+ */
+function filterByExtensionPoint(
+  injection: Readonly<Injection<unknown>>,
+  session: ResolutionSession,
+  extensionPointName?: string,
+) {
+  extensionPointName =
+    extensionPointName ??
+    inferExtensionPointName(injection.target, session.currentBinding);
+  return extensionFilter(extensionPointName);
+}
+
+/**
+ * Infer the extension point name from binding tags/class name
+ * @param injectionTarget - Target class or prototype
+ * @param currentBinding - Current binding
+ */
+function inferExtensionPointName(
+  injectionTarget: object,
+  currentBinding?: Readonly<Binding<unknown>>,
+): string {
+  if (currentBinding) {
+    const name =
+      currentBinding.tagMap[CoreTags.EXTENSION_POINT] ||
+      currentBinding.tagMap[ContextTags.NAME];
+
+    if (name) return name;
+  }
+
+  let target: Function;
+  if (typeof injectionTarget === 'function') {
+    // Constructor injection
+    target = injectionTarget;
+  } else {
+    // Injection on the prototype
+    target = injectionTarget.constructor;
+  }
+  return target.name;
+}
+
+/**
+ * A factory function to create binding filter for extensions of a named
+ * extension point
+ * @param extensionPointNames - A list of names of extension points
+ */
+export function extensionFilter(
+  ...extensionPointNames: string[]
+): BindingFilter {
+  return filterByTag({
+    [CoreTags.EXTENSION_FOR]: includesTagValue(...extensionPointNames),
+  });
+}
+
+/**
+ * A factory function to create binding template for extensions of the given
+ * extension point
+ * @param extensionPointNames - Names of the extension point
+ */
+export function extensionFor(
+  ...extensionPointNames: string[]
+): BindingTemplate {
+  return binding => {
+    if (extensionPointNames.length === 0) return;
+    let extensionPoints = binding.tagMap[CoreTags.EXTENSION_FOR];
+    // Normalize extensionPoints to string[]
+    if (extensionPoints == null) {
+      extensionPoints = [];
+    } else if (typeof extensionPoints === 'string') {
+      extensionPoints = [extensionPoints];
+    }
+
+    // Add extension points
+    for (const extensionPointName of extensionPointNames) {
+      if (!extensionPoints.includes(extensionPointName)) {
+        extensionPoints.push(extensionPointName);
+      }
+    }
+    if (extensionPoints.length === 1) {
+      // Keep the value as string for backward compatibility
+      extensionPoints = extensionPoints[0];
+    }
+    binding.tag({[CoreTags.EXTENSION_FOR]: extensionPoints});
+  };
+}
+
+/**
+ * Register an extension for the given extension point to the context
+ * @param context - Context object
+ * @param extensionPointName - Name of the extension point
+ * @param extensionClass - Class or a provider for an extension
+ * @param options - Options Options for the creation of binding from class
+ */
+export function addExtension(
+  context: Context,
+  extensionPointName: string,
+  extensionClass: Constructor<unknown>,
+  options?: BindingFromClassOptions,
+) {
+  const binding = createBindingFromClass(extensionClass, options).apply(
+    extensionFor(extensionPointName),
+  );
+  context.add(binding);
+  return binding;
+}

package/src/index.ts

@@ -0,0 +1,29 @@
+// 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
+
+/**
+ * The core foundation for LoopBack 4. It can also serve as the platform to
+ * build large-scale Node.js applications and frameworks.
+ *
+ * @remarks
+ * For examples of how to leverage `@loopback/core` to build composable and
+ * extensible projects, check out the
+ * {@link https://loopback.io/doc/en/lb4/core-tutorial.html | core tutorial}.
+ *
+ * @packageDocumentation
+ */
+
+// Re-export public Core API coming from dependencies
+export * from '@loopback/context';
+// Export APIs
+export * from './application';
+export * from './component';
+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

@@ -0,0 +1,144 @@
+// 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 {BindingKey} from '@loopback/context';
+import {
+  Application,
+  ApplicationConfig,
+  ApplicationMetadata,
+  ControllerClass,
+} from './application';
+import {
+  LifeCycleObserverOptions,
+  LifeCycleObserverRegistry,
+} from './lifecycle-registry';
+
+/**
+ * Namespace for core binding keys
+ */
+export namespace CoreBindings {
+  // application
+  /**
+   * Binding key for application instance itself
+   */
+  export const APPLICATION_INSTANCE = BindingKey.create<Application>(
+    'application.instance',
+  );
+
+  /**
+   * Binding key for application configuration
+   */
+  export const APPLICATION_CONFIG: BindingKey<ApplicationConfig> =
+    BindingKey.create<ApplicationConfig>('application.config');
+
+  /**
+   * Binding key for the content of `package.json`
+   */
+  export const APPLICATION_METADATA = BindingKey.create<ApplicationMetadata>(
+    'application.metadata',
+  );
+
+  // server
+  /**
+   * Binding key for servers
+   */
+  export const SERVERS = 'servers';
+
+  // component
+  /**
+   * Binding key for components
+   */
+  export const COMPONENTS = 'components';
+
+  // controller
+  export const CONTROLLERS = 'controllers';
+
+  /**
+   * Binding key for the controller class resolved in the current request
+   * context
+   */
+  export const CONTROLLER_CLASS: BindingKey<ControllerClass> =
+    BindingKey.create<ControllerClass>('controller.current.ctor');
+
+  /**
+   * Binding key for the controller method resolved in the current request
+   * context
+   */
+  export const CONTROLLER_METHOD_NAME = BindingKey.create<string>(
+    'controller.current.operation',
+  );
+
+  /**
+   * Binding key for the controller method metadata resolved in the current
+   * request context
+   */
+  export const CONTROLLER_METHOD_META = 'controller.method.meta';
+
+  /**
+   * Binding key for the controller instance resolved in the current request
+   * context
+   */
+  export const CONTROLLER_CURRENT = BindingKey.create('controller.current');
+
+  export const LIFE_CYCLE_OBSERVERS = 'lifeCycleObservers';
+  /**
+   * Binding key for life cycle observer options
+   */
+  export const LIFE_CYCLE_OBSERVER_REGISTRY =
+    BindingKey.create<LifeCycleObserverRegistry>('lifeCycleObserver.registry');
+
+  /**
+   * Binding key for life cycle observer options
+   */
+  export const LIFE_CYCLE_OBSERVER_OPTIONS =
+    BindingKey.create<LifeCycleObserverOptions>('lifeCycleObserver.options');
+}
+
+export namespace CoreTags {
+  /**
+   * Binding tag for components
+   */
+  export const COMPONENT = 'component';
+
+  /**
+   * Binding tag for servers
+   */
+  export const SERVER = 'server';
+
+  /**
+   * Binding tag for controllers
+   */
+  export const CONTROLLER = 'controller';
+
+  /**
+   * Binding tag for services
+   */
+  export const SERVICE = 'service';
+  /**
+   * Binding tag for the service interface
+   */
+  export const SERVICE_INTERFACE = 'serviceInterface';
+
+  /**
+   * Binding tag for life cycle observers
+   */
+  export const LIFE_CYCLE_OBSERVER = 'lifeCycleObserver';
+
+  /**
+   * Binding tag for group name of life cycle observers
+   */
+  export const LIFE_CYCLE_OBSERVER_GROUP = 'lifeCycleObserverGroup';
+
+  /**
+   * Binding tag for extensions to specify name of the extension point that an
+   * extension contributes to.
+   */
+  export const EXTENSION_FOR = 'extensionFor';
+
+  /**
+   * Binding tag for an extension point to specify name of the extension point
+   */
+  export const EXTENSION_POINT = 'extensionPoint';
+}