@loopback/metadata 4.0.0-alpha.6 → 4.0.0

package/src/decorator-factory.ts

@@ -1,21 +1,15 @@
-// Copyright IBM Corp. 2017,2018. 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
 
+import debugModule from 'debug';
+import _ from 'lodash';
 import {Reflector} from './reflect';
-import * as _ from 'lodash';
-import * as debugModule from 'debug';
+import {DecoratorType, MetadataKey, MetadataMap} from './types';
 const debug = debugModule('loopback:metadata:decorator');
 
-// tslint:disable:no-any
-
-/**
- * An object mapping keys to corresponding metadata
- */
-export interface MetadataMap<T> {
-  [propertyOrMethodName: string]: T;
-}
+/* eslint-disable @typescript-eslint/no-explicit-any */
 
 /**
  * Options for a decorator
@@ -34,18 +28,15 @@ export interface DecoratorOptions {
    * Default to `true`.
    */
   cloneInputSpec?: boolean;
+
+  /**
+   * Name of the decorator for debugging purpose, such as `@inject`
+   */
+  decoratorName?: string;
+
   [name: string]: any;
 }
 
-/**
- * Decorator function types
- */
-export type DecoratorType =
-  | ClassDecorator
-  | PropertyDecorator
-  | MethodDecorator
-  | ParameterDecorator;
-
 /**
  * Base factory class for decorator functions
  *
@@ -71,8 +62,10 @@ export type DecoratorType =
 export class DecoratorFactory<
   T, // Type of the metadata spec for individual class/method/property/parameter
   M extends T | MetadataMap<T> | MetadataMap<T[]>, // Type of the metadata
-  D extends DecoratorType // Type of the decorator
+  D extends DecoratorType, // Type of the decorator
 > {
+  protected decoratorName: string;
+
   /**
    * A constant to reference the target of a decoration
    */
@@ -80,27 +73,32 @@ export class DecoratorFactory<
 
   /**
    * Construct a new class decorator factory
-   * @param key Metadata key
-   * @param spec Metadata object from the decorator function
-   * @param options Options for the decorator. Default to
+   * @param key - Metadata key
+   * @param spec - Metadata object from the decorator function
+   * @param options - Options for the decorator. Default to
    * `{allowInheritance: true}` if not provided
    */
   constructor(
     protected key: string,
     protected spec: T,
-    protected options?: DecoratorOptions,
+    protected options: DecoratorOptions = {},
   ) {
     this.options = Object.assign(
-      {allowInheritance: true, cloneInputSpec: true},
+      {
+        allowInheritance: true,
+        cloneInputSpec: true,
+      },
       options,
     );
+    const defaultDecoratorName = this.constructor.name.replace(/Factory$/, '');
+    this.decoratorName = this.options.decoratorName ?? defaultDecoratorName;
     if (this.options.cloneInputSpec) {
       this.spec = DecoratorFactory.cloneDeep(spec);
     }
   }
 
   protected allowInheritance(): boolean {
-    return !!(this.options && this.options.allowInheritance);
+    return !!this.options?.allowInheritance;
   }
 
   /**
@@ -108,12 +106,12 @@ export class DecoratorFactory<
    * metadata into the spec if `allowInheritance` is set to `true`. To customize
    * the behavior, this method can be overridden by sub classes.
    *
-   * @param inheritedMetadata Metadata from base classes for the member
+   * @param inheritedMetadata - Metadata from base classes for the member
    */
   protected inherit(inheritedMetadata: T | undefined | null): T {
     if (!this.allowInheritance()) return this.spec;
     if (inheritedMetadata == null) return this.spec;
-    if (this.spec == undefined) return inheritedMetadata;
+    if (this.spec == null) return inheritedMetadata;
     if (typeof inheritedMetadata !== 'object') return this.spec;
     if (Array.isArray(inheritedMetadata) || Array.isArray(this.spec)) {
       // For arrays, we don't merge
@@ -123,20 +121,24 @@ export class DecoratorFactory<
   }
 
   /**
-   * Get the qualified name of a decoration target. For example:
-   * ```
-   * class MyClass
-   * MyClass.constructor[0] // First parameter of the constructor
-   * MyClass.myStaticProperty
-   * MyClass.myStaticMethod()
-   * MyClass.myStaticMethod[0] // First parameter of the myStaticMethod
-   * MyClass.prototype.myProperty
-   * MyClass.prototype.myMethod()
-   * MyClass.prototype.myMethod[1] // Second parameter of myMethod
-   * ```
-   * @param target Class or prototype of a class
-   * @param member Optional property/method name
-   * @param descriptorOrIndex Optional method descriptor or parameter index
+   * Get the qualified name of a decoration target.
+   *
+   * @remarks
+   *
+   * Example of target names:
+   *
+   * - class MyClass
+   * - MyClass.constructor[0] // First parameter of the constructor
+   * - MyClass.myStaticProperty
+   * - MyClass.myStaticMethod()
+   * - MyClass.myStaticMethod[0] // First parameter of the myStaticMethod
+   * - MyClass.prototype.myProperty
+   * - MyClass.prototype.myMethod()
+   * - MyClass.prototype.myMethod[1] // Second parameter of myMethod
+   *
+   * @param target - Class or prototype of a class
+   * @param member - Optional property/method name
+   * @param descriptorOrIndex - Optional method descriptor or parameter index
    */
   static getTargetName(
     target: Object,
@@ -150,38 +152,43 @@ export class DecoratorFactory<
     if (member == null && descriptorOrIndex == null) {
       return `class ${name}`;
     }
-    if (member == null) member = 'constructor';
+    if (member == null || member === '') member = 'constructor';
+
+    const memberAccessor =
+      typeof member === 'symbol' ? '[' + member.toString() + ']' : '.' + member;
+
     if (typeof descriptorOrIndex === 'number') {
       // Parameter
-      name = `${name}.${member}[${descriptorOrIndex}]`;
+      name = `${name}${memberAccessor}[${descriptorOrIndex}]`;
     } else if (descriptorOrIndex != null) {
-      name = `${name}.${member}()`;
+      name = `${name}${memberAccessor}()`;
     } else {
-      name = `${name}.${member}`;
+      name = `${name}${memberAccessor}`;
     }
     return name;
   }
 
   /**
    * Get the number of parameters for a given constructor or method
-   * @param target Class or the prototype
-   * @param member Method name
+   * @param target - Class or the prototype
+   * @param member - Method name
    */
-  static getNumberOfParameters(target: Object, member?: string | symbol) {
-    if (target instanceof Function && !member) {
+  static getNumberOfParameters(target: Object, member?: string) {
+    if (typeof target === 'function' && !member) {
       // constructor
       return target.length;
     } else {
       // target[member] is a function
-      return (<{[methodName: string]: Function}>target)[member!].length;
+      const method = (<{[methodName: string]: Function}>target)[member!];
+      return method.length;
     }
   }
 
   /**
    * Set a reference to the target class or prototype for a given spec if
    * it's an object
-   * @param spec Metadata spec
-   * @param target Target of the decoration. It is a class or the prototype of
+   * @param spec - Metadata spec
+   * @param target - Target of the decoration. It is a class or the prototype of
    * a class.
    */
   withTarget(spec: T, target: Object) {
@@ -190,6 +197,8 @@ export class DecoratorFactory<
       Object.defineProperty(spec, DecoratorFactory.TARGET, {
         value: target,
         enumerable: false,
+        // Make sure it won't be redefined on the same object
+        configurable: false,
       });
     }
     return spec;
@@ -197,7 +206,7 @@ export class DecoratorFactory<
 
   /**
    * Get the optional decoration target of a given spec
-   * @param spec Metadata spec
+   * @param spec - Metadata spec
    */
   getTarget(spec: T) {
     if (typeof spec === 'object' && spec != null) {
@@ -216,10 +225,10 @@ export class DecoratorFactory<
    *
    * It MUST be overridden by subclasses to process inherited metadata.
    *
-   * @param inheritedMetadata Metadata inherited from the base classes
-   * @param target Decoration target
-   * @param member Optional property or method
-   * @param descriptorOrIndex Optional parameter index or method descriptor
+   * @param inheritedMetadata - Metadata inherited from the base classes
+   * @param target - Decoration target
+   * @param member - Optional property or method
+   * @param descriptorOrIndex - Optional parameter index or method descriptor
    */
   protected mergeWithInherited(
     inheritedMetadata: M,
@@ -227,7 +236,9 @@ export class DecoratorFactory<
     member?: string | symbol,
     descriptorOrIndex?: TypedPropertyDescriptor<any> | number,
   ): M {
-    throw new Error('mergeWithInherited() is not implemented');
+    throw new Error(
+      `mergeWithInherited() is not implemented for ${this.decoratorName}`,
+    );
   }
 
   /**
@@ -238,10 +249,10 @@ export class DecoratorFactory<
    *
    * It MUST be overridden by subclasses to process own metadata.
    *
-   * @param ownMetadata Own Metadata exists locally on the target
-   * @param target Decoration target
-   * @param member Optional property or method
-   * @param descriptorOrIndex Optional parameter index or method descriptor
+   * @param ownMetadata - Own Metadata exists locally on the target
+   * @param target - Decoration target
+   * @param member - Optional property or method
+   * @param descriptorOrIndex - Optional parameter index or method descriptor
    */
   protected mergeWithOwn(
     ownMetadata: M,
@@ -249,7 +260,31 @@ export class DecoratorFactory<
     member?: string | symbol,
     descriptorOrIndex?: TypedPropertyDescriptor<any> | number,
   ): M {
-    throw new Error('mergeWithOwn() is not implemented');
+    throw new Error(
+      `mergeWithOwn() is not implemented for ${this.decoratorName}`,
+    );
+  }
+
+  /**
+   * Create an error to report if the decorator is applied to the target more
+   * than once
+   * @param target - Decoration target
+   * @param member - Optional property or method
+   * @param descriptorOrIndex - Optional parameter index or method descriptor
+   */
+  protected duplicateDecorationError(
+    target: Object,
+    member?: string | symbol,
+    descriptorOrIndex?: TypedPropertyDescriptor<any> | number,
+  ) {
+    const targetName = DecoratorFactory.getTargetName(
+      target,
+      member,
+      descriptorOrIndex,
+    );
+    return new Error(
+      `${this.decoratorName} cannot be applied more than once on ${targetName}`,
+    );
   }
 
   /**
@@ -257,14 +292,14 @@ export class DecoratorFactory<
    * implement this method.
    */
   create(): D {
-    throw new Error('create() is not implemented');
+    throw new Error(`create() is not implemented for ${this.decoratorName}`);
   }
 
   /**
    * Base implementation of the decorator function
-   * @param target Decorator target
-   * @param member Optional property or method
-   * @param descriptorOrIndex Optional method descriptor or parameter index
+   * @param target - Decorator target
+   * @param member - Optional property or method
+   * @param descriptorOrIndex - Optional method descriptor or parameter index
    */
   protected decorate(
     target: Object,
@@ -284,12 +319,14 @@ export class DecoratorFactory<
         Reflector.getMetadata(this.key, target),
       );
       meta = this.mergeWithInherited(meta, target, member, descriptorOrIndex);
+      /* istanbul ignore if  */
       if (debug.enabled) {
         debug('%s: %j', targetName, meta);
       }
       Reflector.defineMetadata(this.key, meta, target);
     } else {
       meta = this.mergeWithOwn(meta, target, member, descriptorOrIndex);
+      /* istanbul ignore if  */
       if (debug.enabled) {
         debug('%s: %j', targetName, meta);
       }
@@ -299,30 +336,50 @@ export class DecoratorFactory<
 
   /**
    * Create a decorator function
-   * @param key Metadata key
-   * @param spec Metadata object from the decorator function
-   * @param options Options for the decorator
+   * @param key - Metadata key
+   * @param spec - Metadata object from the decorator function
+   * @param options - Options for the decorator
    */
   protected static _createDecorator<
-    T,
-    M extends T | MetadataMap<T> | MetadataMap<T[]>,
-    D extends DecoratorType
-  >(key: string, spec: T, options?: DecoratorOptions): D {
-    const inst = new this<T, M, D>(key, spec, options);
+    S,
+    MT extends S | MetadataMap<S> | MetadataMap<S[]>,
+    DT extends DecoratorType,
+  >(key: MetadataKey<S, DT>, spec: S, options?: DecoratorOptions): DT {
+    const inst = new this<S, MT, DT>(key.toString(), spec, options);
     return inst.create();
   }
 
-  static cloneDeep<T>(val: T): T {
+  // See https://github.com/lodash/lodash/blob/master/.internal/baseClone.js
+  private static _cloneableTypes = [
+    Object,
+    Array,
+    Set,
+    Map,
+    RegExp,
+    Date,
+    Buffer,
+    ArrayBuffer,
+    Float32Array,
+    Float64Array,
+    Int8Array,
+    Int16Array,
+    Int32Array,
+    Uint8Array,
+    Uint8ClampedArray,
+    Uint16Array,
+    Uint32Array,
+  ];
+
+  static cloneDeep<V>(val: Readonly<V>): V {
     if (typeof val !== 'object') return val;
     return _.cloneDeepWith(val, v => {
-      // Do not clone functions
-      if (typeof v === 'function') return v;
+      if (typeof v !== 'object') return v;
+      if (v == null) return v;
       if (
-        v &&
-        typeof v.constructor === 'function' &&
-        v.constructor.prototype === v
+        v.constructor != null &&
+        !DecoratorFactory._cloneableTypes.includes(v.constructor)
       ) {
-        // Do not clone class prototype
+        // Do not clone instances of classes/constructors, such as Date
         return v;
       }
       return undefined;
@@ -341,7 +398,7 @@ export class ClassDecoratorFactory<T> extends DecoratorFactory<
   protected mergeWithInherited(
     inheritedMetadata: T,
     target: Object,
-    member?: string | symbol,
+    member?: string,
     descriptorOrIndex?: TypedPropertyDescriptor<any> | number,
   ) {
     return this.withTarget(<T>this.inherit(inheritedMetadata), target);
@@ -350,14 +407,11 @@ export class ClassDecoratorFactory<T> extends DecoratorFactory<
   protected mergeWithOwn(
     ownMetadata: T,
     target: Object,
-    member?: string | symbol,
+    member?: string,
     descriptorOrIndex?: TypedPropertyDescriptor<any> | number,
   ) {
     if (ownMetadata != null) {
-      throw new Error(
-        'Decorator cannot be applied more than once on ' +
-          DecoratorFactory.getTargetName(target),
-      );
+      throw this.duplicateDecorationError(target, member, descriptorOrIndex);
     }
     return this.withTarget(this.spec, target);
   }
@@ -368,12 +422,16 @@ export class ClassDecoratorFactory<T> extends DecoratorFactory<
 
   /**
    * Create a class decorator function
-   * @param key Metadata key
-   * @param spec Metadata object from the decorator function
-   * @param options Options for the decorator
+   * @param key - Metadata key
+   * @param spec - Metadata object from the decorator function
+   * @param options - Options for the decorator
    */
-  static createDecorator<T>(key: string, spec: T, options?: DecoratorOptions) {
-    return super._createDecorator<T, T, ClassDecorator>(key, spec, options);
+  static createDecorator<S>(
+    key: MetadataKey<S, ClassDecorator>,
+    spec: S,
+    options?: DecoratorOptions,
+  ) {
+    return super._createDecorator<S, S, ClassDecorator>(key, spec, options);
   }
 }
 
@@ -388,7 +446,7 @@ export class PropertyDecoratorFactory<T> extends DecoratorFactory<
   protected mergeWithInherited(
     inheritedMetadata: MetadataMap<T>,
     target: Object,
-    propertyName?: string | symbol,
+    propertyName?: string,
     descriptorOrIndex?: TypedPropertyDescriptor<any> | number,
   ) {
     inheritedMetadata = inheritedMetadata || {};
@@ -403,14 +461,15 @@ export class PropertyDecoratorFactory<T> extends DecoratorFactory<
   protected mergeWithOwn(
     ownMetadata: MetadataMap<T>,
     target: Object,
-    propertyName?: string | symbol,
+    propertyName?: string,
     descriptorOrParameterIndex?: TypedPropertyDescriptor<any> | number,
   ) {
     ownMetadata = ownMetadata || {};
     if (ownMetadata[propertyName!] != null) {
-      const targetName = DecoratorFactory.getTargetName(target, propertyName);
-      throw new Error(
-        'Decorator cannot be applied more than once on ' + targetName,
+      throw this.duplicateDecorationError(
+        target,
+        propertyName,
+        descriptorOrParameterIndex,
       );
     }
     ownMetadata[propertyName!] = this.withTarget(this.spec, target);
@@ -424,12 +483,16 @@ export class PropertyDecoratorFactory<T> extends DecoratorFactory<
 
   /**
    * Create a property decorator function
-   * @param key Metadata key
-   * @param spec Metadata object from the decorator function
-   * @param options Options for the decorator
+   * @param key - Metadata key
+   * @param spec - Metadata object from the decorator function
+   * @param options - Options for the decorator
    */
-  static createDecorator<T>(key: string, spec: T, options?: DecoratorOptions) {
-    return super._createDecorator<T, MetadataMap<T>, PropertyDecorator>(
+  static createDecorator<S>(
+    key: MetadataKey<S, PropertyDecorator>,
+    spec: S,
+    options?: DecoratorOptions,
+  ) {
+    return super._createDecorator<S, MetadataMap<S>, PropertyDecorator>(
       key,
       spec,
       options,
@@ -448,7 +511,7 @@ export class MethodDecoratorFactory<T> extends DecoratorFactory<
   protected mergeWithInherited(
     inheritedMetadata: MetadataMap<T>,
     target: Object,
-    methodName?: string | symbol,
+    methodName?: string,
     methodDescriptor?: TypedPropertyDescriptor<any> | number,
   ) {
     inheritedMetadata = inheritedMetadata || {};
@@ -463,16 +526,13 @@ export class MethodDecoratorFactory<T> extends DecoratorFactory<
   protected mergeWithOwn(
     ownMetadata: MetadataMap<T>,
     target: Object,
-    methodName?: string | symbol,
+    methodName?: string,
     methodDescriptor?: TypedPropertyDescriptor<any> | number,
   ) {
     ownMetadata = ownMetadata || {};
     const methodMeta = ownMetadata[methodName!];
     if (this.getTarget(methodMeta) === target) {
-      throw new Error(
-        'Decorator cannot be applied more than once on ' +
-          DecoratorFactory.getTargetName(target, methodName, methodDescriptor),
-      );
+      throw this.duplicateDecorationError(target, methodName, methodDescriptor);
     }
     // Set the method metadata
     ownMetadata[methodName!] = this.withTarget(this.spec, target);
@@ -489,12 +549,16 @@ export class MethodDecoratorFactory<T> extends DecoratorFactory<
 
   /**
    * Create a method decorator function
-   * @param key Metadata key
-   * @param spec Metadata object from the decorator function
-   * @param options Options for the decorator
+   * @param key - Metadata key
+   * @param spec - Metadata object from the decorator function
+   * @param options - Options for the decorator
    */
-  static createDecorator<T>(key: string, spec: T, options?: DecoratorOptions) {
-    return super._createDecorator<T, MetadataMap<T>, MethodDecorator>(
+  static createDecorator<S>(
+    key: MetadataKey<S, MethodDecorator>,
+    spec: S,
+    options?: DecoratorOptions,
+  ) {
+    return super._createDecorator<S, MetadataMap<S>, MethodDecorator>(
       key,
       spec,
       options,
@@ -513,7 +577,7 @@ export class ParameterDecoratorFactory<T> extends DecoratorFactory<
   private getOrInitMetadata(
     meta: MetadataMap<T[]>,
     target: Object,
-    methodName?: string | symbol,
+    methodName?: string,
   ) {
     const method = methodName ? methodName : '';
     let methodMeta = meta[method];
@@ -530,7 +594,7 @@ export class ParameterDecoratorFactory<T> extends DecoratorFactory<
   protected mergeWithInherited(
     inheritedMetadata: MetadataMap<T[]>,
     target: Object,
-    methodName?: string | symbol,
+    methodName?: string,
     parameterIndex?: TypedPropertyDescriptor<any> | number,
   ) {
     inheritedMetadata = inheritedMetadata || {};
@@ -550,7 +614,7 @@ export class ParameterDecoratorFactory<T> extends DecoratorFactory<
   protected mergeWithOwn(
     ownMetadata: MetadataMap<T[]>,
     target: Object,
-    methodName?: string | symbol,
+    methodName?: string,
     parameterIndex?: TypedPropertyDescriptor<any> | number,
   ) {
     ownMetadata = ownMetadata || {};
@@ -558,10 +622,7 @@ export class ParameterDecoratorFactory<T> extends DecoratorFactory<
     const methodMeta = this.getOrInitMetadata(ownMetadata, target, methodName);
     const index = parameterIndex as number;
     if (this.getTarget(methodMeta[index]) === target) {
-      throw new Error(
-        'Decorator cannot be applied more than once on ' +
-          DecoratorFactory.getTargetName(target, methodName, parameterIndex),
-      );
+      throw this.duplicateDecorationError(target, methodName, parameterIndex);
     }
     // Set the parameter metadata
     methodMeta[index] = this.withTarget(
@@ -581,12 +642,16 @@ export class ParameterDecoratorFactory<T> extends DecoratorFactory<
 
   /**
    * Create a parameter decorator function
-   * @param key Metadata key
-   * @param spec Metadata object from the decorator function
-   * @param options Options for the decorator
+   * @param key - Metadata key
+   * @param spec - Metadata object from the decorator function
+   * @param options - Options for the decorator
    */
-  static createDecorator<T>(key: string, spec: T, options?: DecoratorOptions) {
-    return super._createDecorator<T, MetadataMap<T[]>, ParameterDecorator>(
+  static createDecorator<S>(
+    key: MetadataKey<S, ParameterDecorator>,
+    spec: S,
+    options?: DecoratorOptions,
+  ) {
+    return super._createDecorator<S, MetadataMap<S[]>, ParameterDecorator>(
       key,
       spec,
       options,
@@ -595,8 +660,11 @@ export class ParameterDecoratorFactory<T> extends DecoratorFactory<
 }
 
 /**
- * Factory for method level parameter decorator. For example, the following
- * code uses `@param` to declare two parameters for `greet()`.
+ * Factory for method level parameter decorator.
+ *
+ * @example
+ * For example, the following code uses `@param` to declare two parameters for
+ * `greet()`.
  * ```ts
  * class MyController {
  *   @param('name') // Parameter 0
@@ -618,7 +686,7 @@ export class MethodParameterDecoratorFactory<T> extends DecoratorFactory<
    */
   private getParameterIndex(
     target: Object,
-    methodName?: string | symbol,
+    methodName?: string,
     methodDescriptor?: TypedPropertyDescriptor<any> | number,
   ) {
     const numOfParams = DecoratorFactory.getNumberOfParameters(
@@ -641,7 +709,7 @@ export class MethodParameterDecoratorFactory<T> extends DecoratorFactory<
         methodDescriptor,
       );
       throw new Error(
-        `The decorator is used more than ${numOfParams} time(s) on ${method}`,
+        `${this.decoratorName} is used more than ${numOfParams} time(s) on ${method}`,
       );
     }
     return index;
@@ -650,7 +718,7 @@ export class MethodParameterDecoratorFactory<T> extends DecoratorFactory<
   protected mergeWithInherited(
     inheritedMetadata: MetadataMap<T[]>,
     target: Object,
-    methodName?: string | symbol,
+    methodName?: string,
     methodDescriptor?: TypedPropertyDescriptor<any> | number,
   ) {
     inheritedMetadata = inheritedMetadata || {};
@@ -679,13 +747,13 @@ export class MethodParameterDecoratorFactory<T> extends DecoratorFactory<
   protected mergeWithOwn(
     ownMetadata: MetadataMap<T[]>,
     target: Object,
-    methodName?: string | symbol,
+    methodName?: string,
     methodDescriptor?: TypedPropertyDescriptor<any> | number,
   ) {
     ownMetadata = ownMetadata || {};
     const index = this.getParameterIndex(target, methodName, methodDescriptor);
 
-    let params =
+    const params =
       ownMetadata[methodName!] || new Array(index + 1).fill(undefined);
     params[index] = this.withTarget(<T>this.inherit(params[index]), target);
     ownMetadata[methodName!] = params;
@@ -709,15 +777,96 @@ export class MethodParameterDecoratorFactory<T> extends DecoratorFactory<
 
   /**
    * Create a method decorator function
-   * @param key Metadata key
-   * @param spec Metadata object from the decorator function
-   * @param options Options for the decorator
+   * @param key - Metadata key
+   * @param spec - Metadata object from the decorator function
+   * @param options - Options for the decorator
    */
-  static createDecorator<T>(key: string, spec: T, options?: DecoratorOptions) {
-    return super._createDecorator<T, MetadataMap<T[]>, MethodDecorator>(
+  static createDecorator<S>(
+    key: MetadataKey<S, MethodDecorator>,
+    spec: S,
+    options?: DecoratorOptions,
+  ) {
+    return super._createDecorator<S, MetadataMap<S[]>, MethodDecorator>(
       key,
       spec,
       options,
     );
   }
 }
+
+/**
+ *  Factory for an append-array of method-level decorators
+ *  The `@response` metadata for a method is an array.
+ *  Each item in the array should be a single value, containing
+ *  a response code and a single spec or Model.  This should allow:
+ *
+ * @example
+ * ```ts
+ *  @response(200, MyFirstModel)
+ *  @response(403, [NotAuthorizedReasonOne, NotAuthorizedReasonTwo])
+ *  @response(404, NotFoundOne)
+ *  @response(404, NotFoundTwo)
+ *  @response(409, {schema: {}})
+ *  public async myMethod() {}
+ * ```
+ *
+ * In the case that a ResponseObject is passed, it becomes the
+ * default for description/content, and if possible, further Models are
+ * incorporated as a `oneOf: []` array.
+ *
+ * In the case that a ReferenceObject is passed, it and it alone is used, since
+ * references can be external and we cannot `oneOf` their content.
+ *
+ * The factory creates and updates an array of items T[], and the getter
+ * provides the values as that array.
+ */
+export class MethodMultiDecoratorFactory<T> extends MethodDecoratorFactory<
+  T[]
+> {
+  protected mergeWithInherited(
+    inheritedMetadata: MetadataMap<T[]>,
+    target: Object,
+    methodName?: string,
+  ) {
+    inheritedMetadata = inheritedMetadata || {};
+
+    inheritedMetadata[methodName!] = this._mergeArray(
+      inheritedMetadata[methodName!],
+      this.withTarget(this.spec, target),
+    );
+
+    return inheritedMetadata;
+  }
+
+  protected mergeWithOwn(
+    ownMetadata: MetadataMap<T[]>,
+    target: Object,
+    methodName?: string,
+    methodDescriptor?: TypedPropertyDescriptor<any> | number,
+  ) {
+    ownMetadata = ownMetadata || {};
+    ownMetadata[methodName!] = this._mergeArray(
+      ownMetadata[methodName!],
+      this.withTarget(this.spec, target),
+    );
+    return ownMetadata;
+  }
+
+  private _mergeArray(result: T[], methodMeta: T | T[]) {
+    if (!result) {
+      if (Array.isArray(methodMeta)) {
+        result = methodMeta;
+      } else {
+        result = [methodMeta];
+      }
+    } else {
+      if (Array.isArray(methodMeta)) {
+        result.push(...methodMeta);
+      } else {
+        result.push(methodMeta);
+      }
+    }
+
+    return result;
+  }
+}