CustomVersioningOptions

Kind: Interface

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

Part of: Common

CustomVersioningOptions configures custom API version extraction for requests. It is used when VersioningType.CUSTOM is selected, allowing applications to define how one or more version values are read from an incoming request.

Properties

Diagram

mermaid
graph LR
  Request[Incoming Request] --> Extractor[Custom extractor function]
  Extractor --> Versions[string or string array]
  Options[CustomVersioningOptions] --> Type[VersioningType.CUSTOM]
  Options --> Extractor
  Versions --> Router[Version-aware route matching]

Usage

ts
import { VersioningType } from '@nestjs/common';
import type { CustomVersioningOptions } from '@nestjs/common';

const versioningOptions: CustomVersioningOptions = {
  type: VersioningType.CUSTOM,
  extractor: (request) => {
    const headers = request as { headers?: Record<string, string | undefined> };

    // Read a version such as: x-api-version: 2
    return headers.headers?.['x-api-version'] ?? '1';
  },
};

// Example application integration:
// app.enableVersioning(versioningOptions);

AI Coding Instructions

• Always set type to VersioningType.CUSTOM; this interface is specifically for custom extraction strategies.
• Ensure extractor returns a string or string[]; return an array when a request may map to multiple supported versions.
• Keep extractors defensive because request is typed as unknown; safely narrow or cast the request before accessing headers, URLs, or metadata.
• Return version values in the same format used by route version declarations to ensure version-aware routing matches correctly.
• Avoid throwing from the extractor for missing version data; return a fallback version or an empty result according to the application's versioning policy.