express-route-versioning-middleware/readme.md

Middleware for versioning functions for express routers. Use 'accept-version' header on request. Does not dictate express.Request, express.Response, or express.NextFunction types

# Express Route Versioning Middleware

[![ExpressRouteVersioning Test](https://github.com/spies36/ExpressRouteVersioning/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/spies36/ExpressRouteVersioning/actions/workflows/test.yml)

No more versioning routes by adding parameters to the url or adding to the path name. Simply add `accept-version: versionNumber` to the request headers and let your middleware choose the correct function.

## Why use this version

This version does not dictate your express.Request, express.Response, or NextFunction types for the RouteHandler. So if you have a middleware before/after that adjusts response.locals to a strict type this will play nicely in TS.

**Supports Express 5.1.0!**

## Usage

**Version numbers must be in ascending order**

Basic express usage

```
import express, { Request, Response, NextFunction } from 'express';
import { routeVersionHandler } from 'express-route-versioning-middleware';

const app = express();
const router = express.Router();

app.use(router);

//curl --header "accept-version: 0.1.5" localhost:8081/doThings
//Will hit testFunc2
router.get('/doThings', routeVersionHandler({
    '0.0.0': testFunc1,
    '0.1.0': testFunc2,
    '1.2.3': testFunc3
}));

```

Same example but with middleware for auth before route versioning.

```
//curl --header "accept-version: 0.1.5" localhost:8081/doThings
//Will hit testFunc2 with fancyAuthMiddleware's next()
router.get('/doThings', fancyAuthMiddleware, routeVersionHandler({
    '0.0.0': testFunc1,
    '0.1.0': testFunc2,
    '1.2.3': testFunc3
}));

```

## Versioning Logic

Run the highest version function where requester's version is >= function version

In simple terms

```
'minimumVersionRequired': functionToCall
```

Examples:

```
routeVersionHandler({
    '0.0.0': testFunc1,
    '0.1.0': testFunc2,
    '1.0.0': testFunc3,
    '1.2.3': testFunc4
})

testFunc1
curl --header "accept-version: 0.0.0" localhost:8081/doThings

testFunc1
curl --header "accept-version: 0.0.999" localhost:8081/doThings

testFunc3
curl --header "accept-version: 1.2.2" localhost:8081/doThings

testFunc4
curl --header "accept-version: 1.2.3" localhost:8081/doThings

```

Version Information

- 1.x.x Supports Express ^4.x.x
- 2.x.x Supports Express ^5.x.x