@loopback/context 4.0.0-alpha.6 → 4.0.0

package/src/binding-filter.ts

@@ -0,0 +1,250 @@
+// Copyright IBM Corp. 2019,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, BindingTag} from './binding';
+import {BindingAddress} from './binding-key';
+import {MapObject} from './value-promise';
+
+/**
+ * A function that filters bindings. It returns `true` to select a given
+ * binding.
+ *
+ * @remarks
+ * Originally, we allowed filters to be tied with a single value type.
+ * This actually does not make much sense - the filter function is typically
+ * invoked on all bindings to find those ones matching the given criteria.
+ * Filters must be prepared to handle bindings of any value type. We learned
+ * about this problem after enabling TypeScript's `strictFunctionTypes` check.
+ * This aspect is resolved by typing the input argument as `Binding<unknown>`.
+ *
+ * Ideally, `BindingFilter` should be declared as a type guard as follows:
+ * ```ts
+ * export type BindingFilterGuard<ValueType = unknown> = (
+ *   binding: Readonly<Binding<unknown>>,
+ * ) => binding is Readonly<Binding<ValueType>>;
+ * ```
+ *
+ * But TypeScript treats the following types as incompatible and does not accept
+ * type 1 for type 2.
+ *
+ * 1. `(binding: Readonly<Binding<unknown>>) => boolean`
+ * 2. `(binding: Readonly<Binding<unknown>>) => binding is Readonly<Binding<ValueType>>`
+ *
+ * If we described BindingFilter as a type-guard, then all filter implementations
+ * would have to be explicitly typed as type-guards too, which would make it
+ * tedious to write quick filter functions like `b => b.key.startsWith('services')`.
+ *
+ * To keep things simple and easy to use, we use `boolean` as the return type
+ * of a binding filter function.
+ */
+export interface BindingFilter {
+  (binding: Readonly<Binding<unknown>>): boolean;
+}
+
+/**
+ * Select binding(s) by key or a filter function
+ */
+export type BindingSelector<ValueType = unknown> =
+  | BindingAddress<ValueType>
+  | BindingFilter;
+
+/**
+ * Check if an object is a `BindingKey` by duck typing
+ * @param selector Binding selector
+ */
+function isBindingKey(selector: BindingSelector) {
+  if (selector == null || typeof selector !== 'object') return false;
+  return (
+    typeof selector.key === 'string' &&
+    typeof selector.deepProperty === 'function'
+  );
+}
+
+/**
+ * Type guard for binding address
+ * @param bindingSelector - Binding key or filter function
+ */
+export function isBindingAddress(
+  bindingSelector: BindingSelector,
+): bindingSelector is BindingAddress {
+  return (
+    typeof bindingSelector !== 'function' &&
+    (typeof bindingSelector === 'string' ||
+      // See https://github.com/loopbackio/loopback-next/issues/4570
+      // `bindingSelector instanceof BindingKey` is not always reliable as the
+      // `@loopback/context` module might be loaded from multiple locations if
+      // `npm install` does not dedupe or there are mixed versions in the tree
+      isBindingKey(bindingSelector))
+  );
+}
+
+/**
+ * Binding filter function that holds a binding tag pattern. `Context.find()`
+ * uses the `bindingTagPattern` to optimize the matching of bindings by tag to
+ * avoid expensive check for all bindings.
+ */
+export interface BindingTagFilter extends BindingFilter {
+  /**
+   * A special property on the filter function to provide access to the binding
+   * tag pattern which can be utilized to optimize the matching of bindings by
+   * tag in a context.
+   */
+  bindingTagPattern: BindingTag | RegExp;
+}
+
+/**
+ * Type guard for BindingTagFilter
+ * @param filter - A BindingFilter function
+ */
+export function isBindingTagFilter(
+  filter?: BindingFilter,
+): filter is BindingTagFilter {
+  if (filter == null || !('bindingTagPattern' in filter)) return false;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const tagPattern = (filter as any).bindingTagPattern;
+  return (
+    tagPattern instanceof RegExp ||
+    typeof tagPattern === 'string' ||
+    typeof tagPattern === 'object'
+  );
+}
+
+/**
+ * A function to check if a given tag value is matched for `filterByTag`
+ */
+export interface TagValueMatcher {
+  /**
+   * Check if the given tag value matches the search criteria
+   * @param tagValue - Tag value from the binding
+   * @param tagName - Tag name
+   * @param tagMap - Tag map from the binding
+   */
+  (tagValue: unknown, tagName: string, tagMap: MapObject<unknown>): boolean;
+}
+
+/**
+ * A symbol that can be used to match binding tags by name regardless of the
+ * value.
+ *
+ * @example
+ *
+ * The following code matches bindings with tag `{controller: 'A'}` or
+ * `{controller: 'controller'}`. But if the tag name 'controller' does not
+ * exist for a binding, the binding will NOT be included.
+ *
+ * ```ts
+ * ctx.findByTag({controller: ANY_TAG_VALUE})
+ * ```
+ */
+export const ANY_TAG_VALUE: TagValueMatcher = (tagValue, tagName, tagMap) =>
+  tagName in tagMap;
+
+/**
+ * Create a tag value matcher function that returns `true` if the target tag
+ * value equals to the item value or is an array that includes the item value.
+ * @param itemValues - A list of tag item value
+ */
+export function includesTagValue(...itemValues: unknown[]): TagValueMatcher {
+  return tagValue => {
+    return itemValues.some(
+      itemValue =>
+        // The tag value equals the item value
+        tagValue === itemValue ||
+        // The tag value contains the item value
+        (Array.isArray(tagValue) && tagValue.includes(itemValue)),
+    );
+  };
+}
+
+/**
+ * Create a binding filter for the tag pattern
+ * @param tagPattern - Binding tag name, regexp, or object
+ */
+export function filterByTag(tagPattern: BindingTag | RegExp): BindingTagFilter {
+  let filter: BindingFilter;
+  let regex: RegExp | undefined = undefined;
+  if (tagPattern instanceof RegExp) {
+    // RegExp for tag names
+    regex = tagPattern;
+  }
+  if (
+    typeof tagPattern === 'string' &&
+    (tagPattern.includes('*') || tagPattern.includes('?'))
+  ) {
+    // Wildcard tag name
+    regex = wildcardToRegExp(tagPattern);
+  }
+
+  if (regex != null) {
+    // RegExp or wildcard match
+    filter = b => b.tagNames.some(t => regex!.test(t));
+  } else if (typeof tagPattern === 'string') {
+    // Plain tag string match
+    filter = b => b.tagNames.includes(tagPattern);
+  } else {
+    // Match tag name/value pairs
+    const tagMap = tagPattern as MapObject<unknown>;
+    filter = b => {
+      for (const t in tagMap) {
+        if (!matchTagValue(tagMap[t], t, b.tagMap)) return false;
+      }
+      // All tag name/value pairs match
+      return true;
+    };
+  }
+  // Set up binding tag for the filter
+  const tagFilter = filter as BindingTagFilter;
+  tagFilter.bindingTagPattern = regex ?? tagPattern;
+  return tagFilter;
+}
+
+function matchTagValue(
+  tagValueOrMatcher: unknown,
+  tagName: string,
+  tagMap: MapObject<unknown>,
+) {
+  const tagValue = tagMap[tagName];
+  if (tagValue === tagValueOrMatcher) return true;
+
+  if (typeof tagValueOrMatcher === 'function') {
+    return (tagValueOrMatcher as TagValueMatcher)(tagValue, tagName, tagMap);
+  }
+  return false;
+}
+
+/**
+ * Create a binding filter from key pattern
+ * @param keyPattern - Binding key/wildcard, regexp, or a filter function
+ */
+export function filterByKey(
+  keyPattern?: string | RegExp | BindingFilter,
+): BindingFilter {
+  if (typeof keyPattern === 'string') {
+    const regex = wildcardToRegExp(keyPattern);
+    return binding => regex.test(binding.key);
+  } else if (keyPattern instanceof RegExp) {
+    return binding => keyPattern.test(binding.key);
+  } else if (typeof keyPattern === 'function') {
+    return keyPattern;
+  }
+  return () => true;
+}
+
+/**
+ * Convert a wildcard pattern to RegExp
+ * @param pattern - A wildcard string with `*` and `?` as special characters.
+ * - `*` matches zero or more characters except `.` and `:`
+ * - `?` matches exactly one character except `.` and `:`
+ */
+function wildcardToRegExp(pattern: string): RegExp {
+  // Escape reserved chars for RegExp:
+  // `- \ ^ $ + . ( ) | { } [ ] :`
+  let regexp = pattern.replace(/[\-\[\]\/\{\}\(\)\+\.\\\^\$\|\:]/g, '\\$&');
+  // Replace wildcard chars `*` and `?`
+  // `*` matches zero or more characters except `.` and `:`
+  // `?` matches one character except `.` and `:`
+  regexp = regexp.replace(/\*/g, '[^.:]*').replace(/\?/g, '[^.:]');
+  return new RegExp(`^${regexp}$`);
+}

package/src/binding-inspector.ts

@@ -0,0 +1,371 @@
+// Copyright IBM Corp. 2018,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 {MetadataAccessor, MetadataInspector} from '@loopback/metadata';
+import debugFactory from 'debug';
+import {
+  Binding,
+  BindingScope,
+  BindingTag,
+  BindingTemplate,
+  DynamicValueProviderClass,
+  isDynamicValueProviderClass,
+} from './binding';
+import {BindingAddress} from './binding-key';
+import {ContextTags} from './keys';
+import {Provider} from './provider';
+import {Constructor} from './value-promise';
+
+const debug = debugFactory('loopback:context:binding-inspector');
+
+/**
+ * Binding metadata from `@injectable`
+ *
+ * @typeParam T - Value type
+ */
+export type BindingMetadata<T = unknown> = {
+  /**
+   * An array of template functions to configure a binding
+   */
+  templates: BindingTemplate<T>[];
+  /**
+   * The target class where binding metadata is decorated
+   */
+  target: Constructor<T>;
+};
+
+/**
+ * Metadata key for binding metadata
+ */
+export const BINDING_METADATA_KEY = MetadataAccessor.create<
+  BindingMetadata,
+  ClassDecorator
+>('binding.metadata');
+
+/**
+ * An object to configure binding scope and tags
+ */
+export type BindingScopeAndTags = {
+  scope?: BindingScope;
+  tags?: BindingTag | BindingTag[];
+};
+
+/**
+ * Specification of parameters for `@injectable()`
+ */
+export type BindingSpec<T = unknown> = BindingTemplate<T> | BindingScopeAndTags;
+
+/**
+ * Check if a class implements `Provider` interface
+ * @param cls - A class
+ *
+ * @typeParam T - Value type
+ */
+export function isProviderClass<T>(
+  cls: unknown,
+): cls is Constructor<Provider<T>> {
+  return (
+    typeof cls === 'function' && typeof cls.prototype?.value === 'function'
+  );
+}
+
+/**
+ * A factory function to create a template function to bind the target class
+ * as a `Provider`.
+ * @param target - Target provider class
+ *
+ * @typeParam T - Value type
+ */
+export function asProvider<T>(
+  target: Constructor<Provider<T>>,
+): BindingTemplate<T> {
+  return function bindAsProvider(binding) {
+    binding.toProvider(target).tag(ContextTags.PROVIDER, {
+      [ContextTags.TYPE]: ContextTags.PROVIDER,
+    });
+  };
+}
+
+/**
+ * A factory function to create a template function to bind the target class
+ * as a class or `Provider`.
+ * @param target - Target class, which can be an implementation of `Provider`
+ * or `DynamicValueProviderClass`
+ *
+ * @typeParam T - Value type
+ */
+export function asClassOrProvider<T>(
+  target: Constructor<T | Provider<T>> | DynamicValueProviderClass<T>,
+): BindingTemplate<T> {
+  // Add a template to bind to a class or provider
+  return function bindAsClassOrProvider(binding) {
+    if (isProviderClass(target)) {
+      asProvider(target)(binding);
+    } else if (isDynamicValueProviderClass<T>(target)) {
+      binding.toDynamicValue(target).tag(ContextTags.DYNAMIC_VALUE_PROVIDER, {
+        [ContextTags.TYPE]: ContextTags.DYNAMIC_VALUE_PROVIDER,
+      });
+    } else {
+      binding.toClass(target as Constructor<T>);
+    }
+  };
+}
+
+/**
+ * Convert binding scope and tags as a template function
+ * @param scopeAndTags - Binding scope and tags
+ *
+ * @typeParam T - Value type
+ */
+export function asBindingTemplate<T = unknown>(
+  scopeAndTags: BindingScopeAndTags,
+): BindingTemplate<T> {
+  return function applyBindingScopeAndTag(binding) {
+    if (scopeAndTags.scope) {
+      binding.inScope(scopeAndTags.scope);
+    }
+    if (scopeAndTags.tags) {
+      if (Array.isArray(scopeAndTags.tags)) {
+        binding.tag(...scopeAndTags.tags);
+      } else {
+        binding.tag(scopeAndTags.tags);
+      }
+    }
+  };
+}
+
+/**
+ * Get binding metadata for a class
+ * @param target - The target class
+ *
+ * @typeParam T - Value type
+ */
+export function getBindingMetadata<T = unknown>(
+  target: Function,
+): BindingMetadata<T> | undefined {
+  return MetadataInspector.getClassMetadata<BindingMetadata<T>>(
+    BINDING_METADATA_KEY,
+    target,
+  );
+}
+
+/**
+ * A binding template function to delete `name` and `key` tags
+ */
+export function removeNameAndKeyTags(binding: Binding<unknown>) {
+  if (binding.tagMap) {
+    delete binding.tagMap.name;
+    delete binding.tagMap.key;
+  }
+}
+
+/**
+ * Get the binding template for a class with binding metadata
+ *
+ * @param cls - A class with optional `@injectable`
+ *
+ * @typeParam T - Value type
+ */
+export function bindingTemplateFor<T>(
+  cls: Constructor<T | Provider<T>> | DynamicValueProviderClass<T>,
+  options?: BindingFromClassOptions,
+): BindingTemplate<T> {
+  const spec = getBindingMetadata(cls);
+  debug('class %s has binding metadata', cls.name, spec);
+  const templateFunctions = spec?.templates ?? [];
+  if (spec?.target !== cls) {
+    // Make sure the subclass is used as the binding source
+    templateFunctions.push(asClassOrProvider(cls) as BindingTemplate<unknown>);
+  }
+  return function applyBindingTemplatesFromMetadata(binding) {
+    for (const t of templateFunctions) {
+      binding.apply(t);
+    }
+    if (spec?.target !== cls) {
+      // Remove name/key tags inherited from base classes
+      binding.apply(removeNameAndKeyTags);
+    }
+    if (options != null) {
+      applyClassBindingOptions(binding, options);
+    }
+  };
+}
+
+/**
+ * Mapping artifact types to binding key namespaces (prefixes).
+ *
+ * @example
+ * ```ts
+ * {
+ *   repository: 'repositories'
+ * }
+ * ```
+ */
+export type TypeNamespaceMapping = {[name: string]: string};
+
+export const DEFAULT_TYPE_NAMESPACES: TypeNamespaceMapping = {
+  class: 'classes',
+  provider: 'providers',
+  dynamicValueProvider: 'dynamicValueProviders',
+};
+
+/**
+ * Options to customize the binding created from a class
+ */
+export type BindingFromClassOptions = {
+  /**
+   * Binding key
+   */
+  key?: BindingAddress;
+  /**
+   * Artifact type, such as `server`, `controller`, `repository` or `service`
+   */
+  type?: string;
+  /**
+   * Artifact name, such as `my-rest-server` and `my-controller`. It
+   * overrides the name tag
+   */
+  name?: string;
+  /**
+   * Namespace for the binding key, such as `servers` and `controllers`. It
+   * overrides the default namespace or namespace tag
+   */
+  namespace?: string;
+  /**
+   * Mapping artifact type to binding key namespaces
+   */
+  typeNamespaceMapping?: TypeNamespaceMapping;
+  /**
+   * Default namespace if the binding does not have an explicit namespace
+   */
+  defaultNamespace?: string;
+  /**
+   * Default scope if the binding does not have an explicit scope
+   */
+  defaultScope?: BindingScope;
+};
+
+/**
+ * Create a binding from a class with decorated metadata. The class is attached
+ * to the binding as follows:
+ * - `binding.toClass(cls)`: if `cls` is a plain class such as `MyController`
+ * - `binding.toProvider(cls)`: if `cls` is a value provider class with a
+ * prototype method `value()`
+ * - `binding.toDynamicValue(cls)`: if `cls` is a dynamic value provider class
+ * with a static method `value()`
+ *
+ * @param cls - A class. It can be either a plain class, a value provider class,
+ * or a dynamic value provider class
+ * @param options - Options to customize the binding key
+ *
+ * @typeParam T - Value type
+ */
+export function createBindingFromClass<T>(
+  cls: Constructor<T | Provider<T>> | DynamicValueProviderClass<T>,
+  options: BindingFromClassOptions = {},
+): Binding<T> {
+  debug('create binding from class %s with options', cls.name, options);
+  try {
+    const templateFn = bindingTemplateFor(cls, options);
+    const key = buildBindingKey(cls, options);
+    const binding = Binding.bind<T>(key).apply(templateFn);
+    return binding;
+  } catch (err) {
+    err.message += ` (while building binding for class ${cls.name})`;
+    throw err;
+  }
+}
+
+function applyClassBindingOptions<T>(
+  binding: Binding<T>,
+  options: BindingFromClassOptions,
+) {
+  if (options.name) {
+    binding.tag({name: options.name});
+  }
+  if (options.type) {
+    binding.tag({type: options.type}, options.type);
+  }
+  if (options.defaultScope) {
+    binding.applyDefaultScope(options.defaultScope);
+  }
+}
+
+/**
+ * Find/infer binding key namespace for a type
+ * @param type - Artifact type, such as `controller`, `datasource`, or `server`
+ * @param typeNamespaces - An object mapping type names to namespaces
+ */
+function getNamespace(type: string, typeNamespaces = DEFAULT_TYPE_NAMESPACES) {
+  if (type in typeNamespaces) {
+    return typeNamespaces[type];
+  } else {
+    // Return the plural form
+    return `${type}s`;
+  }
+}
+
+/**
+ * Build the binding key for a class with optional binding metadata.
+ * The binding key is resolved in the following steps:
+ *
+ * 1. Check `options.key`, if it exists, return it
+ * 2. Check if the binding metadata has `key` tag, if yes, return its tag value
+ * 3. Identify `namespace` and `name` to form the binding key as
+ * `<namespace>.<name>`.
+ *   - namespace
+ *     - `options.namespace`
+ *     - `namespace` tag value
+ *     - Map `options.type` or `type` tag value to a namespace, for example,
+ *       'controller` to 'controller'.
+ *   - name
+ *     - `options.name`
+ *     - `name` tag value
+ *     - the class name
+ *
+ * @param cls - A class to be bound
+ * @param options - Options to customize how to build the key
+ *
+ * @typeParam T - Value type
+ */
+function buildBindingKey<T>(
+  cls: Constructor<T | Provider<T>>,
+  options: BindingFromClassOptions = {},
+) {
+  if (options.key) return options.key;
+
+  const templateFn = bindingTemplateFor(cls);
+  // Create a temporary binding
+  const bindingTemplate = new Binding('template').apply(templateFn);
+  // Is there a `key` tag?
+  let key: string = bindingTemplate.tagMap[ContextTags.KEY];
+  if (key) return key;
+
+  let namespace =
+    options.namespace ??
+    bindingTemplate.tagMap[ContextTags.NAMESPACE] ??
+    options.defaultNamespace;
+  if (!namespace) {
+    const namespaces = Object.assign(
+      {},
+      DEFAULT_TYPE_NAMESPACES,
+      options.typeNamespaceMapping,
+    );
+    // Derive the key from type + name
+    let type = options.type ?? bindingTemplate.tagMap[ContextTags.TYPE];
+    if (!type) {
+      type =
+        bindingTemplate.tagNames.find(t => namespaces[t] != null) ??
+        ContextTags.CLASS;
+    }
+    namespace = getNamespace(type, namespaces);
+  }
+
+  const name =
+    options.name ?? (bindingTemplate.tagMap[ContextTags.NAME] || cls.name);
+  key = `${namespace}.${name}`;
+
+  return key;
+}