# CustomVersioningOptions

**Kind:** Interface

**Source:** [`packages/common/interfaces/version-options.interface.ts`](https://github.com/nestjs/nest/blob/master/packages/common/interfaces/version-options.interface.ts#L76)

**Part of:** [Common](subsystem-packages-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

| Property | Type |
|---|---|
| `type` | `VersioningType.CUSTOM` |
| `extractor` | `(request: unknown) => string | string[]` |

## 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.