📦 express-version-api

Versioned routing middleware for Express.js based on semantic versioning (semver).

⚠️ NOTE: This package is intended for personal use and experimentation. It is not recommended for production use.

🚧 Project Status

This library is under active development. Features and improvements are being added frequently. Use at your own discretion in unstable environments.

✨ Features

✅ Version-based routing (^, ~, exact versions)
✅ Automatic fallback to default or latest version
✅ Fully compatible with Express middleware
✅ Well-tested with Jest and Supertest

📦 Installation

npm install express-version-api

🚀 Quick Usage

const express = require("express");
const versionApi = require("express-version-api");
const app = express();

const handlerV1 = (req, res) => res.send("This is version 1.0.0");
const handlerV2 = (req, res) => res.send("This is version 2.0.0");

app.get(
  "/api",
  versionApi({
    "1.0.0": handlerV1,
    "2.0.0": handlerV2,
  })
);

app.listen(3000, () => {
  console.log("Server running on port 3000");
});

🎯 Semver Support (`^`, `~`)

Symbol	Matches	Example Matches
`^`	Major-compatible (`1.x.x`)	`^1.0.0` → `1.2.3`
`~`	Minor-compatible (`2.1.x`)	`~2.1.0` → `2.1.4`
Exact	Exact version only	`3.0.0` → `3.0.0`

app.get(
  "/api",
  versionApi({
    "^1.0.0": handlerV1,
    "~2.1.0": handlerV2,
    "3.0.0": handlerV3,
  })
);

📥 Version Header

Clients should include the Accept-Version HTTP header in requests:

curl -H "Accept-Version: 1.0.0" http://localhost:3000/api

🧪 Running Tests

npm run test

Tests are powered by Jest and Supertest. Full coverage is included.

🧩 API

`versionApi(handlers, defaultHandler?)`

handlers: Object with semver-style version strings as keys and Express handlers as values.
defaultHandler: Optional fallback if no version matches.

app.get(
  "/api",
  versionApi({
    "^1.0.0": v1Handler,
    "~2.0.0": v2Handler,
    "3.0.0": v3Handler,
  }, fallbackHandler)
);

🔄 Fallback Strategy

If the version is not matched:

Use defaultHandler if defined
Otherwise, fallback to the latest available handler
If no handler matches, return 422 Unprocessable Entity

📚 Examples

Check the test/ directory for integration examples and how ^, ~ and fallbacks work in practice.

🛣️ Roadmap

[x] Basic versioning with ^, ~, exact
[x] Default and latest fallback
[ ] Advanced semver range support (planned)
[ ] Improved validation and DX
[ ] Full ESM and CJS dual package
[ ] Typed handler inference with TypeScript

🤝 Contributing

Contributions, issues, and feature requests are welcome! Contact: bquintian.developer@gmail.com

🛡 License

This project is licensed under the MIT License - see the LICENSE file for details.