@loopback/metadata 4.0.0-alpha.6 → 4.0.0

package/src/index.ts

@@ -1,8 +1,28 @@
-// Copyright IBM Corp. 2017. All Rights Reserved.
+// Copyright IBM Corp. 2017,2020. All Rights Reserved.
 // Node module: @loopback/metadata
 // This file is licensed under the MIT License.
 // License text available at https://opensource.org/licenses/MIT
 
-export * from './reflect';
+/**
+ * A package with utilities to help developers implement
+ * {@link https://www.typescriptlang.org/docs/handbook/decorators.html |TypeScript decorators},
+ * define/merge metadata, and inspect metadata.
+ *
+ * @remarks
+ * Utilities:
+ *
+ * - Reflector: Wrapper of
+ *   {@link https://github.com/rbuckton/reflect-metadata | reflect-metadata}.
+ * - Decorator factories: A set of factories for class/method/property/parameter
+ *   decorators to apply metadata to a given class and its static or instance
+ *   members.
+ * - MetadataInspector: High level APIs to inspect a class and/or its members to
+ *   get metadata applied by decorators.
+ *
+ * @packageDocumentation
+ */
+
 export * from './decorator-factory';
 export * from './inspector';
+export * from './reflect';
+export * from './types';

package/src/inspector.ts

@@ -1,10 +1,18 @@
-// Copyright IBM Corp. 2017,2018. All Rights Reserved.
+// Copyright IBM Corp. 2017,2019. All Rights Reserved.
 // Node module: @loopback/metadata
 // This file is licensed under the MIT License.
 // License text available at https://opensource.org/licenses/MIT
+import debugModule from 'debug';
+import {DecoratorFactory} from './decorator-factory';
+import {NamespacedReflect, Reflector} from './reflect';
+import {
+  DecoratorType,
+  DesignTimeMethodMetadata,
+  MetadataKey,
+  MetadataMap,
+} from './types';
 
-import {Reflector, NamespacedReflect} from './reflect';
-import {MetadataMap} from './decorator-factory';
+const debug = debugModule('loopback:metadata:inspector');
 
 /**
  * TypeScript reflector without a namespace. The TypeScript compiler can be
@@ -14,44 +22,6 @@ import {MetadataMap} from './decorator-factory';
  */
 const TSReflector = new NamespacedReflect();
 
-/**
- * Design time metadata for a method.
- *
- * @example
- * ```ts
- * class MyController
- * {
- *   myMethod(x: string, y: number, z: MyClass): boolean {
- *     // ...
- *     return true;
- *   }
- * }
- * ```
- *
- * The `myMethod` above has design-time metadata as follows:
- * ```ts
- * {
- *   type: Function,
- *   parameterTypes: [String, Number, MyClass],
- *   returnType: Boolean
- * }
- * ```
- */
-export interface DesignTimeMethodMetadata {
-  /**
-   * Type of the method itself. It is `Function`
-   */
-  type: Function;
-  /**
-   * An array of parameter types
-   */
-  parameterTypes: Function[];
-  /**
-   * Return type
-   */
-  returnType: Function;
-}
-
 /**
  * Options for inspection
  */
@@ -82,185 +52,188 @@ export class MetadataInspector {
 
   /**
    * Get the metadata associated with the given key for a given class
-   * @param key Metadata key
-   * @param target Class that contains the metadata
-   * @param options Options for inspection
+   * @param key - Metadata key
+   * @param target - Class that contains the metadata
+   * @param options - Options for inspection
    */
   static getClassMetadata<T>(
-    key: string,
+    key: MetadataKey<T, ClassDecorator>,
     target: Function,
     options?: InspectionOptions,
   ): T | undefined {
-    return options && options.ownMetadataOnly
-      ? Reflector.getOwnMetadata(key, target)
-      : Reflector.getMetadata(key, target);
+    return options?.ownMetadataOnly
+      ? Reflector.getOwnMetadata(key.toString(), target)
+      : Reflector.getMetadata(key.toString(), target);
   }
 
   /**
    * Define metadata for the given target
-   * @param key Metadata key
-   * @param value Metadata value
-   * @param target Target for the metadata
-   * @param member Optional property or method name
+   * @param key - Metadata key
+   * @param value - Metadata value
+   * @param target - Target for the metadata
+   * @param member - Optional property or method name
    */
   static defineMetadata<T>(
-    key: string,
+    key: MetadataKey<T, DecoratorType>,
     value: T,
     target: Object,
-    member?: string | symbol,
+    member?: string,
   ) {
-    Reflector.defineMetadata(key, value, target, member);
+    Reflector.defineMetadata(key.toString(), value, target, member);
   }
 
   /**
    * Get the metadata associated with the given key for all methods of the
    * target class or prototype
-   * @param key Metadata key
-   * @param target Class for static methods or prototype for instance methods
-   * @param options Options for inspection
+   * @param key - Metadata key
+   * @param target - Class for static methods or prototype for instance methods
+   * @param options - Options for inspection
    */
   static getAllMethodMetadata<T>(
-    key: string,
+    key: MetadataKey<T, MethodDecorator>,
     target: Object,
     options?: InspectionOptions,
   ): MetadataMap<T> | undefined {
-    return options && options.ownMetadataOnly
-      ? Reflector.getOwnMetadata(key, target)
-      : Reflector.getMetadata(key, target);
+    return options?.ownMetadataOnly
+      ? Reflector.getOwnMetadata(key.toString(), target)
+      : Reflector.getMetadata(key.toString(), target);
   }
 
   /**
    * Get the metadata associated with the given key for a given method of the
    * target class or prototype
-   * @param key Metadata key
-   * @param target Class for static methods or prototype for instance methods
-   * @param methodName Method name. If not present, default to '' to use
+   * @param key - Metadata key
+   * @param target - Class for static methods or prototype for instance methods
+   * @param methodName - Method name. If not present, default to '' to use
    * the constructor
-   * @param options Options for inspection
+   * @param options - Options for inspection
    */
   static getMethodMetadata<T>(
-    key: string,
+    key: MetadataKey<T, MethodDecorator>,
     target: Object,
-    methodName?: string | symbol,
+    methodName?: string,
     options?: InspectionOptions,
   ): T | undefined {
-    methodName = methodName || '';
-    const meta: MetadataMap<T> =
-      options && options.ownMetadataOnly
-        ? Reflector.getOwnMetadata(key, target)
-        : Reflector.getMetadata(key, target);
-    return meta && meta[methodName];
+    methodName = methodName ?? '';
+    const meta: MetadataMap<T> = options?.ownMetadataOnly
+      ? Reflector.getOwnMetadata(key.toString(), target)
+      : Reflector.getMetadata(key.toString(), target);
+    return meta?.[methodName];
   }
 
   /**
    * Get the metadata associated with the given key for all properties of the
    * target class or prototype
-   * @param key Metadata key
-   * @param target Class for static methods or prototype for instance methods
-   * @param options Options for inspection
+   * @param key - Metadata key
+   * @param target - Class for static methods or prototype for instance methods
+   * @param options - Options for inspection
    */
   static getAllPropertyMetadata<T>(
-    key: string,
+    key: MetadataKey<T, PropertyDecorator>,
     target: Object,
     options?: InspectionOptions,
   ): MetadataMap<T> | undefined {
-    return options && options.ownMetadataOnly
-      ? Reflector.getOwnMetadata(key, target)
-      : Reflector.getMetadata(key, target);
+    return options?.ownMetadataOnly
+      ? Reflector.getOwnMetadata(key.toString(), target)
+      : Reflector.getMetadata(key.toString(), target);
   }
 
   /**
    * Get the metadata associated with the given key for a given property of the
    * target class or prototype
-   * @param key Metadata key
-   * @param target Class for static properties or prototype for instance
+   * @param key - Metadata key
+   * @param target - Class for static properties or prototype for instance
    * properties
-   * @param propertyName Property name
-   * @param options Options for inspection
+   * @param propertyName - Property name
+   * @param options - Options for inspection
    */
   static getPropertyMetadata<T>(
-    key: string,
+    key: MetadataKey<T, PropertyDecorator>,
     target: Object,
-    propertyName: string | symbol,
+    propertyName: string,
     options?: InspectionOptions,
   ): T | undefined {
-    const meta: MetadataMap<T> =
-      options && options.ownMetadataOnly
-        ? Reflector.getOwnMetadata(key, target)
-        : Reflector.getMetadata(key, target);
-    return meta && meta[propertyName];
+    const meta: MetadataMap<T> = options?.ownMetadataOnly
+      ? Reflector.getOwnMetadata(key.toString(), target)
+      : Reflector.getMetadata(key.toString(), target);
+    return meta?.[propertyName];
   }
 
   /**
    * Get the metadata associated with the given key for all parameters of a
    * given method
-   * @param key Metadata key
-   * @param target Class for static methods or prototype for instance methods
-   * @param methodName Method name. If not present, default to '' to use
+   * @param key - Metadata key
+   * @param target - Class for static methods or prototype for instance methods
+   * @param methodName - Method name. If not present, default to '' to use
    * the constructor
-   * @param options Options for inspection
+   * @param options - Options for inspection
    */
   static getAllParameterMetadata<T>(
-    key: string,
+    key: MetadataKey<T, ParameterDecorator>,
     target: Object,
-    methodName?: string | symbol,
+    methodName?: string,
     options?: InspectionOptions,
   ): T[] | undefined {
-    methodName = methodName || '';
-    const meta: MetadataMap<T[]> =
-      options && options.ownMetadataOnly
-        ? Reflector.getOwnMetadata(key, target)
-        : Reflector.getMetadata(key, target);
-    return meta && meta[methodName];
+    methodName = methodName ?? '';
+    const meta: MetadataMap<T[]> = options?.ownMetadataOnly
+      ? Reflector.getOwnMetadata(key.toString(), target)
+      : Reflector.getMetadata(key.toString(), target);
+    return meta?.[methodName];
   }
 
   /**
    * Get the metadata associated with the given key for a parameter of a given
    * method by index
-   * @param key Metadata key
-   * @param target Class for static methods or prototype for instance methods
-   * @param methodName Method name. If not present, default to '' to use
+   * @param key - Metadata key
+   * @param target - Class for static methods or prototype for instance methods
+   * @param methodName - Method name. If not present, default to '' to use
    * the constructor
-   * @param index Index of the parameter, starting with 0
-   * @param options Options for inspection
+   * @param index - Index of the parameter, starting with 0
+   * @param options - Options for inspection
    */
   static getParameterMetadata<T>(
-    key: string,
+    key: MetadataKey<T, ParameterDecorator>,
     target: Object,
-    methodName: string | symbol,
+    methodName: string,
     index: number,
     options?: InspectionOptions,
   ): T | undefined {
     methodName = methodName || '';
-    const meta: MetadataMap<T[]> =
-      options && options.ownMetadataOnly
-        ? Reflector.getOwnMetadata(key, target)
-        : Reflector.getMetadata(key, target);
-    const params = meta && meta[methodName];
-    return params && params[index];
+    const meta: MetadataMap<T[]> = options?.ownMetadataOnly
+      ? Reflector.getOwnMetadata(key.toString(), target)
+      : Reflector.getMetadata(key.toString(), target);
+    const params = meta?.[methodName];
+    return params?.[index];
   }
 
   /**
    * Get TypeScript design time type for a property
-   * @param target Class or prototype
-   * @param propertyName Property name
+   * @param target - Class or prototype
+   * @param propertyName - Property name
+   * @returns Design time metadata. The return value is `undefined` when:
+   * - The property has type `undefined`, `null`
+   * - The TypeScript project has not enabled the compiler option `emitDecoratorMetadata`.
+   * - The code is written in vanilla JavaScript.
    */
   static getDesignTypeForProperty(
     target: Object,
-    propertyName: string | symbol,
-  ): Function {
+    propertyName: string,
+  ): Function | undefined {
     return TSReflector.getMetadata('design:type', target, propertyName);
   }
 
   /**
-   * Get TypeScript design time type for a method
-   * @param target Class or prototype
-   * @param methodName Method name
+   * Get TypeScript design time type for a method.
+   * @param target - Class or prototype
+   * @param methodName - Method name
+   * @returns Design time metadata. The return value is `undefined`
+   * in projects that do not enable `emitDecoratorMetadata`
+   * in TypeScript compiler options or are written in vanilla JavaScript.
    */
   static getDesignTypeForMethod(
     target: Object,
-    methodName: string | symbol,
-  ): DesignTimeMethodMetadata {
+    methodName: string,
+  ): DesignTimeMethodMetadata | undefined {
     const type = TSReflector.getMetadata('design:type', target, methodName);
     const parameterTypes = TSReflector.getMetadata(
       'design:paramtypes',
@@ -272,6 +245,25 @@ export class MetadataInspector {
       target,
       methodName,
     );
+
+    if (
+      type === undefined &&
+      parameterTypes === undefined &&
+      returnType === undefined
+    ) {
+      /* istanbul ignore next */
+      if (debug.enabled) {
+        const targetName = DecoratorFactory.getTargetName(target, methodName);
+        debug(
+          'No design-time type metadata found while inspecting %s. ' +
+            'Did you forget to enable TypeScript compiler option `emitDecoratorMetadata`?',
+          targetName,
+        );
+      }
+
+      return undefined;
+    }
+
     return {
       type,
       parameterTypes,

package/src/reflect.ts

@@ -1,18 +1,18 @@
-// Copyright IBM Corp. 2017. All Rights Reserved.
+// Copyright IBM Corp. 2017,2019. All Rights Reserved.
 // Node module: @loopback/metadata
 // This file is licensed under the MIT License.
 // License text available at https://opensource.org/licenses/MIT
 
 import 'reflect-metadata';
 
-/* tslint:disable:no-any */
+/* eslint-disable @typescript-eslint/no-explicit-any */
 
 /*
  * namespaced wrapper to handle reflect api
  */
 export class NamespacedReflect {
   /**
-   * @param namespace : namespace to bind this reflect context
+   * @param namespace - Namespace to bind this reflect context
    */
   constructor(private namespace?: string) {}
 
@@ -28,7 +28,7 @@ export class NamespacedReflect {
     metadataKey: string,
     metadataValue: any,
     target: Object,
-    propertyKey?: string | symbol,
+    propertyKey?: string,
   ) {
     metadataKey = this.getMetadataKey(metadataKey);
     if (propertyKey) {
@@ -41,11 +41,7 @@ export class NamespacedReflect {
   /**
    * lookup metadata from a target object and its prototype chain
    */
-  getMetadata(
-    metadataKey: string,
-    target: Object,
-    propertyKey?: string | symbol,
-  ): any {
+  getMetadata(metadataKey: string, target: Object, propertyKey?: string): any {
     metadataKey = this.getMetadataKey(metadataKey);
     if (propertyKey) {
       return Reflect.getMetadata(metadataKey, target, propertyKey);
@@ -59,7 +55,7 @@ export class NamespacedReflect {
   getOwnMetadata(
     metadataKey: string,
     target: Object,
-    propertyKey?: string | symbol,
+    propertyKey?: string,
   ): any {
     metadataKey = this.getMetadataKey(metadataKey);
     if (propertyKey) {
@@ -70,14 +66,14 @@ export class NamespacedReflect {
 
   /**
    * Check if the target has corresponding metadata
-   * @param metadataKey Key
-   * @param target Target
-   * @param propertyKey Optional property key
+   * @param metadataKey - Key
+   * @param target - Target
+   * @param propertyKey - Optional property key
    */
   hasMetadata(
     metadataKey: string,
     target: Object,
-    propertyKey?: string | symbol,
+    propertyKey?: string,
   ): boolean {
     metadataKey = this.getMetadataKey(metadataKey);
     if (propertyKey) {
@@ -89,7 +85,7 @@ export class NamespacedReflect {
   hasOwnMetadata(
     metadataKey: string,
     target: Object,
-    propertyKey?: string | symbol,
+    propertyKey?: string,
   ): boolean {
     metadataKey = this.getMetadataKey(metadataKey);
     if (propertyKey) {
@@ -101,7 +97,7 @@ export class NamespacedReflect {
   deleteMetadata(
     metadataKey: string,
     target: Object,
-    propertyKey?: string | symbol,
+    propertyKey?: string,
   ): boolean {
     metadataKey = this.getMetadataKey(metadataKey);
     if (propertyKey) {
@@ -110,7 +106,7 @@ export class NamespacedReflect {
     return Reflect.deleteMetadata(metadataKey, target);
   }
 
-  getMetadataKeys(target: Object, propertyKey?: string | symbol): string[] {
+  getMetadataKeys(target: Object, propertyKey?: string): string[] {
     let keys: string[];
     if (propertyKey) {
       keys = Reflect.getMetadataKeys(target, propertyKey);
@@ -131,7 +127,7 @@ export class NamespacedReflect {
     return metaKeys;
   }
 
-  getOwnMetadataKeys(target: Object, propertyKey?: string | symbol): string[] {
+  getOwnMetadataKeys(target: Object, propertyKey?: string): string[] {
     let keys: string[];
     if (propertyKey) {
       keys = Reflect.getOwnMetadataKeys(target, propertyKey);
@@ -152,6 +148,18 @@ export class NamespacedReflect {
     return metaKeys;
   }
 
+  decorate(
+    decorators: (PropertyDecorator | MethodDecorator)[],
+    target: Object,
+    targetKey?: string | symbol,
+    descriptor?: PropertyDescriptor,
+  ): PropertyDescriptor | Function;
+
+  decorate(
+    decorators: ClassDecorator[],
+    target: Object,
+  ): PropertyDescriptor | Function;
+
   decorate(
     decorators: (PropertyDecorator | MethodDecorator)[] | ClassDecorator[],
     target: Object,
@@ -159,13 +167,17 @@ export class NamespacedReflect {
     descriptor?: PropertyDescriptor,
   ): PropertyDescriptor | Function {
     if (targetKey) {
-      return Reflect.decorate(decorators, target, targetKey, descriptor);
+      return Reflect.decorate(
+        <(PropertyDecorator | MethodDecorator)[]>decorators,
+        target,
+        targetKey,
+        descriptor,
+      );
     } else {
       return Reflect.decorate(<ClassDecorator[]>decorators, <Function>target);
     }
   }
 
-  /* tslint:disable-next-line:no-any */
   metadata(
     metadataKey: string,
     metadataValue: any,
@@ -178,5 +190,4 @@ export class NamespacedReflect {
   }
 }
 
-/* tslint:disable-next-line:variable-name */
 export const Reflector = new NamespacedReflect('loopback');

package/src/types.ts

@@ -0,0 +1,94 @@
+// Copyright IBM Corp. 2018,2019. All Rights Reserved.
+// Node module: @loopback/metadata
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/licenses/MIT
+
+/**
+ * Decorator function types
+ */
+export type DecoratorType =
+  | ClassDecorator
+  | PropertyDecorator
+  | MethodDecorator
+  | ParameterDecorator;
+
+/**
+ * A strongly-typed metadata accessor via reflection
+ * @typeParam T - Type of the metadata value
+ * @typeParam D - Type of the decorator
+ */
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+export class MetadataAccessor<T, D extends DecoratorType = DecoratorType> {
+  private constructor(public readonly key: string) {}
+
+  toString() {
+    return this.key;
+  }
+
+  /**
+   * Create a strongly-typed metadata accessor
+   * @param key - The metadata key
+   * @typeParam V - Type of the metadata value
+   * @typeParam DT - Type of the decorator
+   */
+  static create<V, DT extends DecoratorType>(key: string) {
+    return new MetadataAccessor<V, DT>(key);
+  }
+}
+
+/**
+ * Key for metadata access via reflection
+ * @typeParam T - Type of the metadata value
+ * @typeParam D - Type of the decorator
+ */
+export type MetadataKey<T, D extends DecoratorType> =
+  | MetadataAccessor<T, D>
+  | string;
+
+/**
+ * An object mapping keys to corresponding metadata
+ */
+export interface MetadataMap<T> {
+  [propertyOrMethodName: string]: T;
+}
+
+/**
+ * Design time metadata for a method.
+ *
+ * @example
+ * ```ts
+ * class MyController
+ * {
+ *   myMethod(x: string, y: number, z: MyClass): boolean {
+ *     // ...
+ *     return true;
+ *   }
+ * }
+ * ```
+ *
+ * The `myMethod` above has design-time metadata as follows:
+ * ```ts
+ * {
+ *   type: Function,
+ *   parameterTypes: [String, Number, MyClass],
+ *   returnType: Boolean
+ * }
+ * ```
+ */
+export interface DesignTimeMethodMetadata {
+  /**
+   * Type of the method itself. It is `Function` for methods, `undefined` for the constructor.
+   */
+  type: Function | undefined;
+
+  /**
+   * An array of parameter types.
+   */
+
+  parameterTypes: Function[];
+
+  /**
+   * Return type, may be `undefined` (e.g. for constructors).
+   */
+  returnType: Function | undefined;
+}