@loopback/context 4.0.0-alpha.8 → 4.1.0

package/src/binding-key.ts

@@ -0,0 +1,136 @@
+// 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 {generateUniqueId} from './unique-id';
+
+export type BindingAddress<T = unknown> = string | BindingKey<T>;
+
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+export class BindingKey<ValueType> {
+  static readonly PROPERTY_SEPARATOR = '#';
+
+  /**
+   * Create a new key for a binding bound to a value of type `ValueType`.
+   *
+   * @example
+   *
+   * ```ts
+   * BindingKey.create<string>('application.name');
+   * BindingKey.create<number>('config', 'rest.port);
+   * BindingKey.create<number>('config#rest.port');
+   * ```
+   *
+   * @param key - The binding key. When propertyPath is not provided, the key
+   *   is allowed to contain propertyPath as encoded via `BindingKey#toString()`
+   * @param propertyPath - Optional path to a deep property of the bound value.
+   */
+  public static create<V>(key: string, propertyPath?: string): BindingKey<V> {
+    // TODO(bajtos) allow chaining of propertyPaths, e.g.
+    //   BindingKey.create('config#rest', 'port')
+    // should create {key: 'config', path: 'rest.port'}
+    if (propertyPath) {
+      BindingKey.validate(key);
+      return new BindingKey<V>(key, propertyPath);
+    }
+
+    return BindingKey.parseKeyWithPath(key);
+  }
+
+  private constructor(
+    public readonly key: string,
+    public readonly propertyPath?: string,
+  ) {}
+
+  toString() {
+    return this.propertyPath
+      ? `${this.key}${BindingKey.PROPERTY_SEPARATOR}${this.propertyPath}`
+      : this.key;
+  }
+
+  /**
+   * Get a binding address for retrieving a deep property of the object
+   * bound to the current binding key.
+   *
+   * @param propertyPath - A dot-separated path to a (deep) property, e.g. "server.port".
+   */
+  deepProperty<PropertyValueType>(propertyPath: string) {
+    // TODO(bajtos) allow chaining of propertyPaths, e.g.
+    //   BindingKey.create('config', 'rest').deepProperty('port')
+    // should create {key: 'config', path: 'rest.port'}
+    return BindingKey.create<PropertyValueType>(this.key, propertyPath);
+  }
+
+  /**
+   * Validate the binding key format. Please note that `#` is reserved.
+   * Returns a string representation of the binding key.
+   *
+   * @param key - Binding key, such as `a`, `a.b`, `a:b`, or `a/b`
+   */
+  static validate<T>(key: BindingAddress<T>): string {
+    if (!key) throw new Error('Binding key must be provided.');
+    key = key.toString();
+    if (key.includes(BindingKey.PROPERTY_SEPARATOR)) {
+      throw new Error(
+        `Binding key ${key} cannot contain` +
+          ` '${BindingKey.PROPERTY_SEPARATOR}'.`,
+      );
+    }
+    return key;
+  }
+
+  /**
+   * Parse a string containing both the binding key and the path to the deeply
+   * nested property to retrieve.
+   *
+   * @param keyWithPath - The key with an optional path,
+   *  e.g. "application.instance" or "config#rest.port".
+   */
+  static parseKeyWithPath<T>(keyWithPath: BindingAddress<T>): BindingKey<T> {
+    if (typeof keyWithPath !== 'string') {
+      return BindingKey.create<T>(keyWithPath.key, keyWithPath.propertyPath);
+    }
+
+    const index = keyWithPath.indexOf(BindingKey.PROPERTY_SEPARATOR);
+    if (index === -1) {
+      return new BindingKey<T>(keyWithPath);
+    }
+
+    return BindingKey.create<T>(
+      keyWithPath.substr(0, index).trim(),
+      keyWithPath.substr(index + 1),
+    );
+  }
+
+  /**
+   * Name space for configuration binding keys
+   */
+  static CONFIG_NAMESPACE = '$config';
+
+  /**
+   * Build a binding key for the configuration of the given binding.
+   * The format is `<key>:$config`
+   *
+   * @param key - Key of the target binding to be configured
+   */
+  static buildKeyForConfig<T>(key: BindingAddress = ''): BindingAddress<T> {
+    const suffix = BindingKey.CONFIG_NAMESPACE;
+    const bindingKey = key ? `${key}:${suffix}` : suffix;
+    return bindingKey;
+  }
+
+  /**
+   * Generate a universally unique binding key.
+   *
+   * Please note the format of they generated key is not specified, you must
+   * not rely on any specific formatting (e.g. UUID style).
+   *
+   * @param namespace - Namespace for the binding
+   */
+  static generate<T>(namespace = ''): BindingKey<T> {
+    const prefix = namespace ? `${namespace}.` : '';
+    const name = generateUniqueId();
+    return BindingKey.create(`${prefix}${name}`);
+  }
+}

package/src/binding-sorter.ts

@@ -0,0 +1,124 @@
+// Copyright IBM Corp. 2019. 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';
+
+/**
+ * Compare function to sort an array of bindings.
+ * It is used by `Array.prototype.sort()`.
+ *
+ * @example
+ * ```ts
+ * const compareByKey: BindingComparator = (a, b) => a.key.localeCompare(b.key);
+ * ```
+ */
+export interface BindingComparator {
+  /**
+   * Compare two bindings
+   * @param bindingA - First binding
+   * @param bindingB - Second binding
+   * @returns A number to determine order of bindingA and bindingB
+   * - 0 leaves bindingA and bindingB unchanged
+   * - <0 bindingA comes before bindingB
+   * - >0 bindingA comes after bindingB
+   */
+  (
+    bindingA: Readonly<Binding<unknown>>,
+    bindingB: Readonly<Binding<unknown>>,
+  ): number;
+}
+
+/**
+ * Creates a binding compare function to sort bindings by tagged phase name.
+ *
+ * @remarks
+ * Two bindings are compared as follows:
+ *
+ * 1. Get values for the given tag as `phase` for bindings, if the tag is not
+ * present, default `phase` to `''`.
+ * 2. If both bindings have `phase` value in `orderOfPhases`, honor the order
+ * specified by `orderOfPhases`.
+ * 3. If a binding's `phase` does not exist in `orderOfPhases`, it comes before
+ * the one with `phase` exists in `orderOfPhases`.
+ * 4. If both bindings have `phase` value outside of `orderOfPhases`, they are
+ * ordered by phase names alphabetically and symbol values come before string
+ * values.
+ *
+ * @param phaseTagName - Name of the binding tag for phase
+ * @param orderOfPhases - An array of phase names as the predefined order
+ */
+export function compareBindingsByTag(
+  phaseTagName = 'phase',
+  orderOfPhases: (string | symbol)[] = [],
+): BindingComparator {
+  return (a: Readonly<Binding<unknown>>, b: Readonly<Binding<unknown>>) => {
+    return compareByOrder(
+      a.tagMap[phaseTagName],
+      b.tagMap[phaseTagName],
+      orderOfPhases,
+    );
+  };
+}
+
+/**
+ * Compare two values by the predefined order
+ *
+ * @remarks
+ *
+ * The comparison is performed as follows:
+ *
+ * 1. If both values are included in `order`, they are sorted by their indexes in
+ * `order`.
+ * 2. The value included in `order` comes after the value not included in `order`.
+ * 3. If neither values are included in `order`, they are sorted:
+ *   - symbol values come before string values
+ *   - alphabetical order for two symbols or two strings
+ *
+ * @param a - First value
+ * @param b - Second value
+ * @param order - An array of values as the predefined order
+ */
+export function compareByOrder(
+  a: string | symbol | undefined | null,
+  b: string | symbol | undefined | null,
+  order: (string | symbol)[] = [],
+) {
+  a = a ?? '';
+  b = b ?? '';
+  const i1 = order.indexOf(a);
+  const i2 = order.indexOf(b);
+  if (i1 !== -1 || i2 !== -1) {
+    // Honor the order
+    return i1 - i2;
+  } else {
+    // Neither value is in the pre-defined order
+
+    // symbol comes before string
+    if (typeof a === 'symbol' && typeof b === 'string') return -1;
+    if (typeof a === 'string' && typeof b === 'symbol') return 1;
+
+    // both a and b are symbols or both a and b are strings
+    if (typeof a === 'symbol') a = a.toString();
+    if (typeof b === 'symbol') b = b.toString();
+    return a < b ? -1 : a > b ? 1 : 0;
+  }
+}
+
+/**
+ * Sort bindings by phase names denoted by a tag and the predefined order
+ *
+ * @param bindings - An array of bindings
+ * @param phaseTagName - Tag name for phase, for example, we can use the value
+ * `'a'` of tag `order` as the phase name for `binding.tag({order: 'a'})`.
+ *
+ * @param orderOfPhases - An array of phase names as the predefined order
+ */
+export function sortBindingsByPhase<T = unknown>(
+  bindings: Readonly<Binding<T>>[],
+  phaseTagName?: string,
+  orderOfPhases?: (string | symbol)[],
+) {
+  return bindings.sort(compareBindingsByTag(phaseTagName, orderOfPhases));
+}