📦 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:

1. Use defaultHandler if defined
2. Otherwise, fallback to the latest available handler
3. 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: [email protected]

🛡 License

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