@loopback/context 4.0.0-alpha.6 → 4.0.0

package/src/resolver.ts

@@ -0,0 +1,282 @@
+// Copyright IBM Corp. 2017,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 {DecoratorFactory} from '@loopback/metadata';
+import assert from 'assert';
+import debugModule from 'debug';
+import {isBindingAddress} from './binding-filter';
+import {BindingAddress} from './binding-key';
+import {Context} from './context';
+import {
+  describeInjectedArguments,
+  describeInjectedProperties,
+  Injection,
+} from './inject';
+import {
+  ResolutionError,
+  ResolutionOptions,
+  ResolutionSession,
+} from './resolution-session';
+import {
+  BoundValue,
+  Constructor,
+  MapObject,
+  resolveList,
+  resolveMap,
+  transformValueOrPromise,
+  ValueOrPromise,
+} from './value-promise';
+
+const debug = debugModule('loopback:context:resolver');
+const getTargetName = DecoratorFactory.getTargetName;
+
+/**
+ * Create an instance of a class which constructor has arguments
+ * decorated with `@inject`.
+ *
+ * The function returns a class when all dependencies were
+ * resolved synchronously, or a Promise otherwise.
+ *
+ * @param ctor - The class constructor to call.
+ * @param ctx - The context containing values for `@inject` resolution
+ * @param session - Optional session for binding and dependency resolution
+ * @param nonInjectedArgs - Optional array of args for non-injected parameters
+ */
+export function instantiateClass<T>(
+  ctor: Constructor<T>,
+  ctx: Context,
+  session?: ResolutionSession,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  nonInjectedArgs?: any[],
+): ValueOrPromise<T> {
+  /* istanbul ignore if */
+  if (debug.enabled) {
+    debug('Instantiating %s', getTargetName(ctor));
+    if (nonInjectedArgs?.length) {
+      debug('Non-injected arguments:', nonInjectedArgs);
+    }
+  }
+  const argsOrPromise = resolveInjectedArguments(
+    ctor,
+    '',
+    ctx,
+    session,
+    nonInjectedArgs,
+  );
+  const propertiesOrPromise = resolveInjectedProperties(ctor, ctx, session);
+  const inst: ValueOrPromise<T> = transformValueOrPromise(
+    argsOrPromise,
+    args => {
+      /* istanbul ignore if */
+      if (debug.enabled) {
+        debug('Injected arguments for %s():', ctor.name, args);
+      }
+      return new ctor(...args);
+    },
+  );
+  return transformValueOrPromise(propertiesOrPromise, props => {
+    /* istanbul ignore if */
+    if (debug.enabled) {
+      debug('Injected properties for %s:', ctor.name, props);
+    }
+    return transformValueOrPromise(inst, obj => Object.assign(obj, props));
+  });
+}
+
+/**
+ * If the scope of current binding is `SINGLETON`, reset the context
+ * to be the one that owns the current binding to make sure a singleton
+ * does not have dependencies injected from child contexts unless the
+ * injection is for method (excluding constructor) parameters.
+ */
+function resolveContext(
+  ctx: Context,
+  injection: Readonly<Injection>,
+  session?: ResolutionSession,
+) {
+  const currentBinding = session?.currentBinding;
+  if (currentBinding == null) {
+    // No current binding
+    return ctx;
+  }
+
+  const isConstructorOrPropertyInjection =
+    // constructor injection
+    !injection.member ||
+    // property injection
+    typeof injection.methodDescriptorOrParameterIndex !== 'number';
+
+  if (isConstructorOrPropertyInjection) {
+    // Set context to the resolution context of the current binding for
+    // constructor or property injections against a singleton
+    ctx = ctx.getResolutionContext(currentBinding)!;
+  }
+  return ctx;
+}
+
+/**
+ * Resolve the value or promise for a given injection
+ * @param ctx - Context
+ * @param injection - Descriptor of the injection
+ * @param session - Optional session for binding and dependency resolution
+ */
+function resolve<T>(
+  ctx: Context,
+  injection: Readonly<Injection>,
+  session?: ResolutionSession,
+): ValueOrPromise<T> {
+  /* istanbul ignore if */
+  if (debug.enabled) {
+    debug(
+      'Resolving an injection:',
+      ResolutionSession.describeInjection(injection),
+    );
+  }
+
+  ctx = resolveContext(ctx, injection, session);
+  const resolved = ResolutionSession.runWithInjection(
+    s => {
+      if (injection.resolve) {
+        // A custom resolve function is provided
+        return injection.resolve(ctx, injection, s);
+      } else {
+        // Default to resolve the value from the context by binding key
+        assert(
+          isBindingAddress(injection.bindingSelector),
+          'The binding selector must be an address (string or BindingKey)',
+        );
+        const key = injection.bindingSelector as BindingAddress;
+        const options: ResolutionOptions = {
+          session: s,
+          ...injection.metadata,
+        };
+        return ctx.getValueOrPromise(key, options);
+      }
+    },
+    injection,
+    session,
+  );
+  return resolved;
+}
+
+/**
+ * Given a function with arguments decorated with `@inject`,
+ * return the list of arguments resolved using the values
+ * bound in `ctx`.
+
+ * The function returns an argument array when all dependencies were
+ * resolved synchronously, or a Promise otherwise.
+ *
+ * @param target - The class for constructor injection or prototype for method
+ * injection
+ * @param method - The method name. If set to '', the constructor will
+ * be used.
+ * @param ctx - The context containing values for `@inject` resolution
+ * @param session - Optional session for binding and dependency resolution
+ * @param nonInjectedArgs - Optional array of args for non-injected parameters
+ */
+export function resolveInjectedArguments(
+  target: object,
+  method: string,
+  ctx: Context,
+  session?: ResolutionSession,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  nonInjectedArgs?: any[],
+): ValueOrPromise<BoundValue[]> {
+  /* istanbul ignore if */
+  if (debug.enabled) {
+    debug('Resolving injected arguments for %s', getTargetName(target, method));
+  }
+  const targetWithMethods = <{[method: string]: Function}>target;
+  if (method) {
+    assert(
+      typeof targetWithMethods[method] === 'function',
+      `Method ${method} not found`,
+    );
+  }
+  // NOTE: the array may be sparse, i.e.
+  //   Object.keys(injectedArgs).length !== injectedArgs.length
+  // Example value:
+  //   [ , 'key1', , 'key2']
+  const injectedArgs = describeInjectedArguments(target, method);
+  const extraArgs = nonInjectedArgs ?? [];
+
+  let argLength = DecoratorFactory.getNumberOfParameters(target, method);
+
+  // Please note `injectedArgs` contains `undefined` for non-injected args
+  const numberOfInjected = injectedArgs.filter(i => i != null).length;
+  if (argLength < numberOfInjected + extraArgs.length) {
+    /**
+     * `Function.prototype.length` excludes the rest parameter and only includes
+     * parameters before the first one with a default value. For example,
+     * `hello(@inject('name') name: string = 'John')` gives 0 for argLength
+     */
+    argLength = numberOfInjected + extraArgs.length;
+  }
+
+  let nonInjectedIndex = 0;
+  return resolveList(new Array(argLength), (val, ix) => {
+    // The `val` argument is not used as the resolver only uses `injectedArgs`
+    // and `extraArgs` to return the new value
+    const injection = ix < injectedArgs.length ? injectedArgs[ix] : undefined;
+    if (
+      injection == null ||
+      (!injection.bindingSelector && !injection.resolve)
+    ) {
+      if (nonInjectedIndex < extraArgs.length) {
+        // Set the argument from the non-injected list
+        return extraArgs[nonInjectedIndex++];
+      } else {
+        const name = getTargetName(target, method, ix);
+        throw new ResolutionError(
+          `The argument '${name}' is not decorated for dependency injection ` +
+            'but no value was supplied by the caller. Did you forget to apply ' +
+            '@inject() to the argument?',
+          {context: ctx, options: {session}},
+        );
+      }
+    }
+
+    return resolve(
+      ctx,
+      injection,
+      // Clone the session so that multiple arguments can be resolved in parallel
+      ResolutionSession.fork(session),
+    );
+  });
+}
+
+/**
+ * Given a class with properties decorated with `@inject`,
+ * return the map of properties resolved using the values
+ * bound in `ctx`.
+
+ * The function returns an argument array when all dependencies were
+ * resolved synchronously, or a Promise otherwise.
+ *
+ * @param constructor - The class for which properties should be resolved.
+ * @param ctx - The context containing values for `@inject` resolution
+ * @param session - Optional session for binding and dependency resolution
+ */
+export function resolveInjectedProperties(
+  constructor: Function,
+  ctx: Context,
+  session?: ResolutionSession,
+): ValueOrPromise<MapObject<BoundValue>> {
+  /* istanbul ignore if */
+  if (debug.enabled) {
+    debug('Resolving injected properties for %s', getTargetName(constructor));
+  }
+  const injectedProperties = describeInjectedProperties(constructor.prototype);
+
+  return resolveMap(injectedProperties, injection =>
+    resolve(
+      ctx,
+      injection,
+      // Clone the session so that multiple properties can be resolved in parallel
+      ResolutionSession.fork(session),
+    ),
+  );
+}

package/src/unique-id.ts

@@ -0,0 +1,24 @@
+// 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 hyperid from 'hyperid';
+
+/**
+ * Generate a (globally) unique identifier in a very fast way.
+ * Please note the ids ARE NOT formatted as UUID and have variable length.
+ * The format of generated values may change in the future.
+ *
+ * @internal
+ */
+export const generateUniqueId = hyperid({
+  fixedLength: false,
+  urlSafe: true,
+});
+
+/**
+ * A regular expression for testing values generated by generateUniqueId.
+ * @internal
+ */
+export const UNIQUE_ID_PATTERN = /[A-Za-z0-9-_]+-\d+/;

package/src/value-promise.ts

@@ -0,0 +1,318 @@
+// 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
+
+/**
+ * This module contains types for values and/or promises as well as a set of
+ * utility methods to handle values and/or promises.
+ */
+
+import {v4 as uuidv4} from 'uuid';
+/**
+ * A class constructor accepting arbitrary arguments.
+ */
+export type Constructor<T> =
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  new (...args: any[]) => T;
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type BoundValue = any;
+
+/**
+ * Representing a value or promise. This type is used to represent results of
+ * synchronous/asynchronous resolution of values.
+ *
+ * Note that we are using PromiseLike instead of native Promise to describe
+ * the asynchronous variant. This allows producers of async values to use
+ * any Promise implementation (e.g. Bluebird) instead of native Promises
+ * provided by JavaScript runtime.
+ */
+export type ValueOrPromise<T> = T | PromiseLike<T>;
+
+export type MapObject<T> = Record<string, T>;
+
+/**
+ * Check whether a value is a Promise-like instance.
+ * Recognizes both native promises and third-party promise libraries.
+ *
+ * @param value - The value to check.
+ */
+export function isPromiseLike<T>(
+  value: T | PromiseLike<T> | undefined,
+): value is PromiseLike<T> {
+  if (!value) return false;
+  if (typeof value !== 'object' && typeof value !== 'function') return false;
+  return typeof (value as PromiseLike<T>).then === 'function';
+}
+
+/**
+ * Get nested properties of an object by path
+ * @param value - Value of the source object
+ * @param path - Path to the property
+ */
+export function getDeepProperty<OUT = BoundValue, IN = BoundValue>(
+  value: IN,
+  path: string,
+): OUT | undefined {
+  let result: BoundValue = value;
+  const props = path.split('.').filter(Boolean);
+  for (const p of props) {
+    if (result == null) {
+      return undefined;
+    }
+    result = result[p];
+  }
+  return <OUT>result;
+}
+
+/**
+ * Resolve entries of an object into a new object with the same keys. If one or
+ * more entries of the source object are resolved to a promise by the `resolver`
+ * function, this method returns a promise which will be resolved to the new
+ * object with fully resolved entries.
+ *
+ * @example
+ *
+ * - Example 1: resolve all entries synchronously
+ * ```ts
+ * const result = resolveMap({a: 'x', b: 'y'}, v => v.toUpperCase());
+ * ```
+ * The `result` will be `{a: 'X', b: 'Y'}`.
+ *
+ * - Example 2: resolve one or more entries asynchronously
+ * ```ts
+ * const result = resolveMap({a: 'x', b: 'y'}, v =>
+ *   Promise.resolve(v.toUpperCase()),
+ * );
+ * ```
+ * The `result` will be a promise of `{a: 'X', b: 'Y'}`.
+ *
+ * @param map - The original object containing the source entries
+ * @param resolver - A function resolves an entry to a value or promise. It will
+ * be invoked with the property value, the property name, and the source object.
+ */
+export function resolveMap<T, V>(
+  map: MapObject<T>,
+  resolver: (val: T, key: string, values: MapObject<T>) => ValueOrPromise<V>,
+): ValueOrPromise<MapObject<V>> {
+  const result: MapObject<V> = {};
+  let asyncResolvers: PromiseLike<void>[] | undefined = undefined;
+
+  const setter = (key: string) => (val: V) => {
+    if (val !== undefined) {
+      // Only set the value if it's not undefined so that the default value
+      // for a key will be honored
+      result[key] = val;
+    }
+  };
+
+  for (const key in map) {
+    const valueOrPromise = resolver(map[key], key, map);
+    if (isPromiseLike(valueOrPromise)) {
+      if (!asyncResolvers) asyncResolvers = [];
+      asyncResolvers.push(valueOrPromise.then(setter(key)));
+    } else {
+      if (valueOrPromise !== undefined) {
+        // Only set the value if it's not undefined so that the default value
+        // for a key will be honored
+        result[key] = valueOrPromise;
+      }
+    }
+  }
+
+  if (asyncResolvers) {
+    return Promise.all(asyncResolvers).then(() => result);
+  } else {
+    return result;
+  }
+}
+
+/**
+ * Resolve entries of an array into a new array with the same indexes. If one or
+ * more entries of the source array are resolved to a promise by the `resolver`
+ * function, this method returns a promise which will be resolved to the new
+ * array with fully resolved entries.
+ *
+ * @example
+ *
+ * - Example 1: resolve all entries synchronously
+ * ```ts
+ * const result = resolveList(['a', 'b'], v => v.toUpperCase());
+ * ```
+ * The `result` will be `['A', 'B']`.
+ *
+ * - Example 2: resolve one or more entries asynchronously
+ * ```ts
+ * const result = resolveList(['a', 'b'], v =>
+ *   Promise.resolve(v.toUpperCase()),
+ * );
+ * ```
+ * The `result` will be a promise of `['A', 'B']`.
+ *
+ * @param list - The original array containing the source entries
+ * @param resolver - A function resolves an entry to a value or promise. It will
+ * be invoked with the property value, the property index, and the source array.
+ */
+export function resolveList<T, V>(
+  list: T[],
+  resolver: (val: T, index: number, values: T[]) => ValueOrPromise<V>,
+): ValueOrPromise<V[]> {
+  const result: V[] = new Array<V>(list.length);
+  let asyncResolvers: PromiseLike<void>[] | undefined = undefined;
+
+  const setter = (index: number) => (val: V) => {
+    result[index] = val;
+  };
+
+  for (let ix = 0; ix < list.length; ix++) {
+    const valueOrPromise = resolver(list[ix], ix, list);
+    if (isPromiseLike(valueOrPromise)) {
+      if (!asyncResolvers) asyncResolvers = [];
+      asyncResolvers.push(valueOrPromise.then(setter(ix)));
+    } else {
+      result[ix] = valueOrPromise;
+    }
+  }
+
+  if (asyncResolvers) {
+    return Promise.all(asyncResolvers).then(() => result);
+  } else {
+    return result;
+  }
+}
+
+/**
+ * Try to run an action that returns a promise or a value
+ * @param action - A function that returns a promise or a value
+ * @param finalAction - A function to be called once the action
+ * is fulfilled or rejected (synchronously or asynchronously)
+ *
+ *  @typeParam T - Type for the return value
+ */
+export function tryWithFinally<T>(
+  action: () => ValueOrPromise<T>,
+  finalAction: () => void,
+): ValueOrPromise<T> {
+  return tryCatchFinally(action, undefined, finalAction);
+}
+
+/**
+ * Try to run an action that returns a promise or a value with error and final
+ * actions to mimic `try {} catch(err) {} finally {}` for a value or promise.
+ *
+ * @param action - A function that returns a promise or a value
+ * @param errorAction - A function to be called once the action
+ * is rejected (synchronously or asynchronously). It must either return a new
+ * value or throw an error.
+ * @param finalAction - A function to be called once the action
+ * is fulfilled or rejected (synchronously or asynchronously)
+ *
+ * @typeParam T - Type for the return value
+ */
+export function tryCatchFinally<T>(
+  action: () => ValueOrPromise<T>,
+  errorAction: (err: unknown) => T | never = err => {
+    throw err;
+  },
+  finalAction: () => void = () => {},
+): ValueOrPromise<T> {
+  let result: ValueOrPromise<T>;
+  try {
+    result = action();
+  } catch (err) {
+    result = reject(err);
+  }
+  if (isPromiseLike(result)) {
+    return result.then(resolve, reject);
+  }
+
+  return resolve(result);
+
+  function resolve(value: T) {
+    try {
+      return value;
+    } finally {
+      finalAction();
+    }
+  }
+
+  function reject(err: unknown): T | never {
+    try {
+      return errorAction(err);
+    } finally {
+      finalAction();
+    }
+  }
+}
+
+/**
+ * Resolve an iterator of source values into a result until the evaluator
+ * returns `true`
+ * @param source - The iterator of source values
+ * @param resolver - The resolve function that maps the source value to a result
+ * @param evaluator - The evaluate function that decides when to stop
+ */
+export function resolveUntil<T, V>(
+  source: Iterator<T>,
+  resolver: (sourceVal: T) => ValueOrPromise<V | undefined>,
+  evaluator: (sourceVal: T, targetVal: V | undefined) => boolean,
+): ValueOrPromise<V | undefined> {
+  // Do iteration in loop for synchronous values to avoid stack overflow
+  // eslint-disable-next-line no-constant-condition
+  while (true) {
+    const next = source.next();
+    if (next.done) return undefined; // End of the iterator
+    const sourceVal = next.value;
+    const valueOrPromise = resolver(sourceVal);
+    if (isPromiseLike(valueOrPromise)) {
+      return valueOrPromise.then(v => {
+        if (evaluator(sourceVal, v)) {
+          return v;
+        } else {
+          return resolveUntil(source, resolver, evaluator);
+        }
+      });
+    } else {
+      if (evaluator(sourceVal, valueOrPromise)) {
+        return valueOrPromise;
+      }
+      // Continue with the while loop
+    }
+  }
+}
+
+/**
+ * Transform a value or promise with a function that produces a new value or
+ * promise
+ * @param valueOrPromise - The value or promise
+ * @param transformer - A function that maps the source value to a value or promise
+ */
+export function transformValueOrPromise<T, V>(
+  valueOrPromise: ValueOrPromise<T>,
+  transformer: (val: T) => ValueOrPromise<V>,
+): ValueOrPromise<V> {
+  if (isPromiseLike(valueOrPromise)) {
+    return valueOrPromise.then(transformer);
+  } else {
+    return transformer(valueOrPromise);
+  }
+}
+
+/**
+ * A utility to generate uuid v4
+ *
+ * @deprecated Use `generateUniqueId`, [uuid](https://www.npmjs.com/package/uuid)
+ * or [hyperid](https://www.npmjs.com/package/hyperid) instead.
+ */
+export function uuid() {
+  return uuidv4();
+}
+
+/**
+ * A regular expression for testing uuid v4 PATTERN
+ * @deprecated This pattern is an internal helper used by unit-tests, we are no
+ * longer using it.
+ */
+export const UUID_PATTERN =
+  /[0-9A-F]{8}-[0-9A-F]{4}-[4][0-9A-F]{3}-[89AB][0-9A-F]{3}-[0-9A-F]{12}/i;

package/index.d.ts

@@ -1,6 +0,0 @@
-// Copyright IBM Corp. 2017. All Rights Reserved.
-// Node module: @loopback/context
-// 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/testlab
-// 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');