feat(common/core): api versioning

adding the ability to have different versions of routes to support changing applications that still need to support legacy consumers

closes nestjs#5065

Author: rich-w-lee

packages/common/constants.ts

@@ -28,3 +28,4 @@ export const HEADERS_METADATA = '__headers__';
 export const REDIRECT_METADATA = '__redirect__';
 export const RESPONSE_PASSTHROUGH_METADATA = '__responsePassthrough__';
 export const SSE_METADATA = '__sse__';
+export const VERSION_METADATA = '__version__';

packages/common/decorators/core/controller.decorator.ts

@@ -2,16 +2,18 @@ import {
   HOST_METADATA,
   PATH_METADATA,
   SCOPE_OPTIONS_METADATA,
+  VERSION_METADATA,
 } from '../../constants';
 import { ScopeOptions } from '../../interfaces/scope-options.interface';
+import { VersionOptions } from '../../interfaces/version-options.interface';
 import { isString, isUndefined } from '../../utils/shared.utils';
 
 /**
  * Interface defining options that can be passed to `@Controller()` decorator
  *
  * @publicApi
  */
-export interface ControllerOptions extends ScopeOptions {
+export interface ControllerOptions extends ScopeOptions, VersionOptions {
   /**
    * Specifies an optional `route path prefix`.  The prefix is pre-pended to the
    * path specified in any request decorator in the class.
@@ -97,10 +99,14 @@ export function Controller(prefix: string | string[]): ClassDecorator;
  * more details.
  * - `prefix` - string that defines a `route path prefix`.  The prefix
  * is pre-pended to the path specified in any request decorator in the class.
+ * - `version` - string, array of strings, or Symbol that defines the version
+ * of all routes in the class. [See Versioning](https://docs.nestjs.com/techniques/versioning)
+ * for more details.
  *
  * @see [Routing](https://docs.nestjs.com/controllers#routing)
  * @see [Controllers](https://docs.nestjs.com/controllers)
  * @see [Microservices](https://docs.nestjs.com/microservices/basics#request-response)
+ * @see [Versioning](https://docs.nestjs.com/techniques/versioning)
  *
  * @publicApi
  */
@@ -128,11 +134,15 @@ export function Controller(options: ControllerOptions): ClassDecorator;
  * more details.
  * - `prefix` - string that defines a `route path prefix`.  The prefix
  * is pre-pended to the path specified in any request decorator in the class.
+ * - `version` - string, array of strings, or Symbol that defines the version
+ * of all routes in the class. [See Versioning](https://docs.nestjs.com/techniques/versioning)
+ * for more details.
  *
  * @see [Routing](https://docs.nestjs.com/controllers#routing)
  * @see [Controllers](https://docs.nestjs.com/controllers)
  * @see [Microservices](https://docs.nestjs.com/microservices/basics#request-response)
  * @see [Scope](https://docs.nestjs.com/fundamentals/injection-scopes#usage)
+ * @see [Versioning](https://docs.nestjs.com/techniques/versioning)
  *
  * @publicApi
  */
@@ -141,19 +151,23 @@ export function Controller(
 ): ClassDecorator {
   const defaultPath = '/';
 
-  const [path, host, scopeOptions] = isUndefined(prefixOrOptions)
-    ? [defaultPath, undefined, undefined]
+  const [path, host, scopeOptions, versionOptions] = isUndefined(
+    prefixOrOptions,
+  )
+    ? [defaultPath, undefined, undefined, undefined]
     : isString(prefixOrOptions) || Array.isArray(prefixOrOptions)
-    ? [prefixOrOptions, undefined, undefined]
+    ? [prefixOrOptions, undefined, undefined, undefined]
     : [
         prefixOrOptions.path || defaultPath,
         prefixOrOptions.host,
         { scope: prefixOrOptions.scope },
+        prefixOrOptions.version,
       ];
 
   return (target: object) => {
     Reflect.defineMetadata(PATH_METADATA, path, target);
     Reflect.defineMetadata(HOST_METADATA, host, target);
     Reflect.defineMetadata(SCOPE_OPTIONS_METADATA, scopeOptions, target);
+    Reflect.defineMetadata(VERSION_METADATA, versionOptions, target);
   };
 }

packages/common/decorators/core/index.ts

@@ -11,3 +11,4 @@ export * from './use-guards.decorator';
 export * from './use-interceptors.decorator';
 export * from './use-pipes.decorator';
 export * from './apply-decorators';
+export * from './version.decorator';

packages/common/decorators/core/version.decorator.ts

@@ -0,0 +1,18 @@
+import { VERSION_METADATA } from '../../constants';
+import { VersionValue } from '../../interfaces/version-options.interface';
+
+/**
+ * Sets the version of the endpoint to the passed version
+ *
+ * @publicApi
+ */
+export function Version(version: VersionValue): MethodDecorator {
+  return (
+    target: any,
+    key: string | symbol,
+    descriptor: TypedPropertyDescriptor<any>,
+  ) => {
+    Reflect.defineMetadata(VERSION_METADATA, version, descriptor.value);
+    return descriptor;
+  };
+}

packages/common/enums/index.ts

@@ -1,3 +1,4 @@
 export * from './request-method.enum';
 export * from './http-status.enum';
 export * from './shutdown-signal.enum';
+export * from './version-type.enum';

packages/common/enums/version-type.enum.ts

@@ -0,0 +1,8 @@
+/**
+ * @publicApi
+ */
+export enum VersioningType {
+  URI,
+  HEADER,
+  MEDIA_TYPE,
+}

packages/common/index.ts

@@ -52,6 +52,8 @@ export {
   Type,
   ValidationError,
   ValueProvider,
+  VersioningOptions,
+  VERSION_NEUTRAL,
   WebSocketAdapter,
   WsExceptionFilter,
   WsMessageHandler,

packages/common/interfaces/index.ts

@@ -25,3 +25,4 @@ export * from './nest-microservice.interface';
 export * from './scope-options.interface';
 export * from './type.interface';
 export * from './websockets/web-socket-adapter.interface';
+export * from './version-options.interface';

packages/common/interfaces/nest-application.interface.ts

@@ -13,6 +13,7 @@ import {
 } from './index';
 import { INestApplicationContext } from './nest-application-context.interface';
 import { WebSocketAdapter } from './websockets/web-socket-adapter.interface';
+import { VersioningOptions } from './version-options.interface';
 
 /**
  * Interface defining the core NestApplication object.
@@ -35,6 +36,14 @@ export interface INestApplication extends INestApplicationContext {
    */
   enableCors(options?: CorsOptions | CorsOptionsDelegate<any>): void;
 
+  /**
+   * Enables Versioning for the application.
+   *
+   * @param {VersioningOptions} options
+   * @returns {this}
+   */
+  enableVersioning(options: VersioningOptions): this;
+
   /**
    * Starts the application.
    *

packages/common/interfaces/version-options.interface.ts

@@ -0,0 +1,62 @@
+import { VersioningType } from '../enums/version-type.enum';
+
+/**
+ * Indicates that this will work for any version passed in the request, or no version.
+ *
+ * @publicApi
+ */
+export const VERSION_NEUTRAL = Symbol('VERSION_NEUTRAL');
+
+export type VersionValue = string | string[] | typeof VERSION_NEUTRAL;
+
+/**
+ * @publicApi
+ */
+export interface VersionOptions {
+  /**
+   * Specifies an optional API Version. When configured, methods
+   * withing the controller will only be routed if the request version
+   * matches the specified value.
+   *
+   * @see [Versioning](https://docs.nestjs.com/techniques/versioning)
+   */
+  version?: VersionValue;
+}
+
+export interface HeaderVersioningOptions {
+  type: VersioningType.HEADER;
+  /**
+   * The name of the Request Header that contains the version.
+   */
+  header: string;
+}
+
+export interface UriVersioningOptions {
+  type: VersioningType.URI;
+  /**
+   * Optional prefix that will prepend the version within the URI.
+   *
+   * Defaults to `v`.
+   *
+   * Ex. Assuming a version of `1`, for `/api/v1/route`, `v` is the prefix.
+   */
+  prefix?: string | false;
+}
+
+export interface MediaTypeVersioningOptions {
+  type: VersioningType.MEDIA_TYPE;
+  /**
+   * The key within the Media Type Header to determine the version from.
+   *
+   * Ex. For `application/json;v=1`, the key is `v=`.
+   */
+  key: string;
+}
+
+/**
+ * @publicApi
+ */
+export type VersioningOptions =
+  | HeaderVersioningOptions
+  | UriVersioningOptions
+  | MediaTypeVersioningOptions;