express-version-api 1.0.1 → 1.0.6

package/LICENSE

@@ -1,21 +1,23 @@
-MIT License
-
-Copyright (c) 2024 Braian Quintian
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+# MIT License
+
+Copyright (c) 2025 Braian Quintian
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+For more information, see <https://github.com/Braian-Quintian/express-version-api>

package/README.md

@@ -1,146 +1,162 @@
-# Express version api
-
-[![MIT License](https://img.shields.io/badge/License-MIT-green.svg)](https://github.com/Braian-Quintian/express-version-routes?tab=MIT-1-ov-file#readme)
-
-Express version api is a simple library that allows you to create versioned routes in your Express.js application. It provides a middleware function that allows you to define different route handlers based on the requested API version. This can be useful when you need to maintain multiple versions of an API and serve different responses based on the version number specified by the client.
-
-**🛑Note:** This library is intended for personal use and experimentation, and is **_not recommended_** for production environments or widespread adoption.
-
-# 🚧 Under Development 🚧
-
-**This library is actively being developed. Improvements and new features are added regularly. As such, there's no stable version and changes are frequent. Please consider this when using the library.**
-
-## Installation
-
-```bash
-npm install express-version-api
-```
-
-## Disclaimer
-
-**⚠️ Disclaimer: This library is intended for personal use and experimentation. While it is released under the MIT license, allowing anyone to use and modify it, please note the following considerations:**
-
-- **Not Recommended for Production:** This library is designed for educational and personal use. It is not optimized for production environments or widespread adoption. Use in production settings is discouraged.
-
-- **Limited Support and Maintenance:** As this is a personal project, there may be limited ongoing support or maintenance. Contributors are welcome, but please manage expectations accordingly.
-
-- **Not a Replacement for Established Libraries:** This library is not intended to replace established or widely used libraries for API versioning in production applications. Consider using dedicated solutions with robust community support for production environments.
-
----
-
-## Usage
-
-> You can use the `versionApi` middleware to create versioned routes in your Express.js application. The `versionApi` middleware accepts an object with the following properties:
-
-- `version` (string): The version of the API.
-- `function` (function): The function that will be called when the route is accessed.
-
-> Follows semver versioning format. Supports '^, ~' symbols for matching version numbers.
-
-### Example basic:
-
-```javascript
-const express = require("express");
-const versionApi = require("express-version-api");
-const app = express();
-
-// Define your route with versioned handlers
-app.get(
-  "/api",
-  versionApi({
-    "1.0.0": functionV1, // Route handler for API version 1.0.0
-    "2.0.0": functionV2, // Route handler for API version 2.0.0
-  })
-);
-
-// Handler for version 1.0.0
-function functionV1(req, res) {
-  res.send("This is version 1.0.0"); // Sends a response for API version 1.0.0
-}
-
-// Handler for version 2.0.0
-function functionV2(req, res) {
-  res.send("This is version 2.0.0"); // Sends a response for API version 2.0.0
-}
-
-app.listen(3000, () => {
-  console.log("Server is running on port 3000");
-});
-```
-
-### Example using '^, ~' semver symbols:
-
-> The `^` symbol is used to match the specified version and any minor or patch updates. The `~` symbol is used to match the specified version and any patch updates.
-
-**Caret Operator** **_(^)_**: Matches the specified version and any minor or patch updates. For example, `^1.0.0` will match `1.0.0`, `1.1.0`, `1.1.1`, etc., but not `2.0.0`.
-
-**Tilde Operator** **_(~)_**: Matches the specified version and any patch updates. For example, ~1.0.0 will match `1.0.0`, `1.0.1`, `1.0.2`, etc., but not `1.1.0`.
-
-```javascript
-const express = require("express");
-const versionApi = require("express-version-api");
-const app = express();
-
-// Define your route with versioned handlers
-app.get(
-  "/api",
-  versionApi({
-    "^1.0.0": functionV1, // Route handler for API version 1.X.X Caret Operator
-    "~2.0.0": functionV2, // Route handler for API version 2.0.X Tilde Operator
-  })
-);
-
-// Handler for version 1.0.0
-function functionV1(req, res) {
-  res.send("This is version 1.0.0"); // Sends a response for API version 1.X.X
-}
-
-// Handler for version 2.0.0
-function functionV2(req, res) {
-  res.send("This is version 2.0.0"); // Sends a response for API version 2.0.X
-}
-
-app.listen(3000, () => {
-  console.log("Server is running on port 3000");
-});
-```
-
-### Versioning via Headers
-
-To specify the desired API version, clients should include the `Accept-Version` header in their requests with the version number they want to access. Here's an example of how to set the Accept-Version header using curl:
-
-```bash
-curl -H "Accept-Version: 1.0.0" http://localhost:3000/api
-```
-
-In this example, the server will invoke functionV1 when the request specifies Accept-Version: 1.0.0 and functionV2 when Accept-Version: 2.0.0 is specified.
-
-Make sure to handle the Accept-Version header appropriately in your middleware or route handlers to serve the correct API version based on client preferences.
-
-## Running Tests
-
-This library uses Jest for testing. To run the tests, you can use the following command:
-
-```bash
-  npm run test
-```
-
----
-
-## Roadmap
-
-- Added support for semver features🌟
-- Enhanced support for APIs starting with v1🌟
-- Add more integrations and examples🌟
-
-### Development Status
-
-This library is currently under active development. We are continuously working on improving and adding new features to enhance its functionality.
-
-## Contributing
-
-We welcome contributions! If you're interested in improving this library or adding new features, we'd love to receive your contributions.
-
-## Feedback
-
-If you have any feedback, please reach out to us at bquintian.developer@gmail.com
+# 📦 express-version-api
+
+[![npm version](https://img.shields.io/npm/v/express-version-api.svg)](https://www.npmjs.com/package/express-version-api)
+[![Build Status](https://img.shields.io/github/actions/workflow/status/Braian-Quintian/express-version-api/test.yml)](https://github.com/Braian-Quintian/express-version-api/actions)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](./LICENSE)
+[![Coverage Status](https://img.shields.io/codecov/c/github/Braian-Quintian/express-version-api)](https://codecov.io/gh/Braian-Quintian/express-version-api)
+[![Node.js](https://img.shields.io/badge/node-%3E=14.0.0-brightgreen)](https://nodejs.org)
+
+> 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
+
+```bash
+npm install express-version-api
+```
+
+---
+
+## 🚀 Quick Usage
+
+```js
+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`  |
+
+```js
+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:
+
+```bash
+curl -H "Accept-Version: 1.0.0" http://localhost:3000/api
+```
+
+---
+
+## 🧪 Running Tests
+
+```bash
+npm run test
+```
+
+Tests are powered by [Jest](https://jestjs.io/) and [Supertest](https://github.com/visionmedia/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.
+
+```js
+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: [bquintian.developer@gmail.com](mailto:bquintian.developer@gmail.com)
+
+---
+
+## 🛡 License
+
+This project is licensed under the MIT License - see the [LICENSE](./LICENSE) file for details.

package/dist/cjs/index.js

@@ -0,0 +1,11 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = void 0;
+// Main entry point of the library.
+// Re-exports the default export from lib.ts to support both ESM and CommonJS.
+var lib_1 = require("./lib");
+Object.defineProperty(exports, "default", { enumerable: true, get: function () { return __importDefault(lib_1).default; } });
+//# sourceMappingURL=index.js.map

package/dist/cjs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;;;;AAAA,mCAAmC;AACnC,8EAA8E;AAC9E,6BAAgC;AAAvB,+GAAA,OAAO,OAAA"}

package/dist/cjs/lib.js

@@ -0,0 +1,209 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findLatestVersion = exports.versioningMiddleware = exports.executeDefaultHandler = exports.executeVersionHandler = exports.extractVersionFromRequest = void 0;
+/**
+ * Attempts to extract a semantic version string from an Express request.
+ *
+ * This function checks the `Request` object for a version identifier in the following order:
+ * 1. `req.version` — typically set by middleware.
+ * 2. `req.headers['accept-version']` — often provided by clients via HTTP headers.
+ *
+ * If no version is found, it returns `false`.
+ *
+ * @param req - The Express request object.
+ * @returns The version string (e.g., "1.0.0"), or `false` if none is provided.
+ *
+ * @example
+ * ```ts
+ * const version = extractVersionFromRequest(req);
+ * if (!version) {
+ *   res.status(422).send("No version provided");
+ * }
+ * ```
+ */
+const extractVersionFromRequest = (req) => {
+    const sources = [req.version, req.headers["accept-version"]];
+    for (const source of sources) {
+        if (typeof source === "string")
+            return source;
+    }
+    return false;
+};
+exports.extractVersionFromRequest = extractVersionFromRequest;
+/**
+ * Executes a version handler if the client version matches the handler's semantic key.
+ *
+ * Determines compatibility between the given `handlerKey` (e.g., "^1", "~2.1", "3.0.0")
+ * and the `clientVersion` (e.g., "2.1.3") using simplified semantic version matching:
+ *
+ * - `^1` matches any version starting with "1" (e.g., "1.0.0", "1.9.5")
+ * - `~2.1` matches versions like "2.1.x" (e.g., "2.1.0", "2.1.9")
+ * - `"3.0.0"` matches exactly "3.0.0"
+ *
+ * If a match is found, the associated handler from `versionHandlers` is invoked.
+ *
+ * @param handlerKey - The version key used for comparison (e.g., "^1", "~2.1", "3.0.0").
+ * @param clientVersion - The version string from the client request (e.g., "2.1.3").
+ * @param versionHandlers - A mapping of version keys to Express request handlers.
+ * @param req - The Express request object.
+ * @param res - The Express response object.
+ * @param next - The Express next middleware function.
+ * @returns `true` if a compatible handler was executed, `false` otherwise.
+ */
+const executeVersionHandler = (handlerKey, clientVersion, versionHandlers, req, res, next) => {
+    const [clientMajor = "0", clientMinor = "0", clientPatch = "0"] = clientVersion.split(".");
+    let targetVersion;
+    let requestedVersion;
+    if (handlerKey.startsWith("~")) {
+        // "~2.1" → match major.minor
+        targetVersion = handlerKey.slice(1).split(".").slice(0, 2).join(".");
+        requestedVersion = `${clientMajor}.${clientMinor}`;
+    }
+    else if (handlerKey.startsWith("^")) {
+        // "^1" → match major only
+        targetVersion = handlerKey.slice(1).split(".")[0];
+        requestedVersion = clientMajor;
+    }
+    else {
+        // Exact match: "2.1.3"
+        targetVersion = handlerKey;
+        requestedVersion = `${clientMajor}.${clientMinor}.${clientPatch}`;
+    }
+    const handler = versionHandlers[handlerKey];
+    if (requestedVersion === targetVersion && typeof handler === "function") {
+        void handler(req, res, next);
+        return true;
+    }
+    return false;
+};
+exports.executeVersionHandler = executeVersionHandler;
+/**
+ * Executes the default handler when no version match is found.
+ *
+ * Priority order:
+ * 1. If a `defaultHandler` is provided, it is invoked immediately.
+ * 2. Otherwise, it tries to find and execute the handler for the latest version available.
+ * 3. If none is found, it responds with HTTP 422 and an optional custom error message.
+ *
+ * This ensures that version-based routing gracefully degrades to a default behavior
+ * or returns an informative error if no handler can be determined.
+ *
+ * @param defaultHandler - Optional fallback Express handler.
+ * @param versionHandlers - A map of version keys to handlers.
+ * @param keys - An array of version keys from the versionHandlers object.
+ * @param req - Express request object.
+ * @param res - Express response object.
+ * @param next - Express next middleware function.
+ * @param notFoundMessage - Optional custom error message for 422 responses.
+ */
+const executeDefaultHandler = (defaultHandler, versionHandlers, keys, req, res, next, notFoundMessage = "Unprocessable Entity: No valid version handler available.") => {
+    if (defaultHandler) {
+        void defaultHandler(req, res, next);
+        return;
+    }
+    if (keys.length === 0) {
+        res.status(422).send(notFoundMessage);
+        return;
+    }
+    const latestVersionKey = (0, exports.findLatestVersion)(keys);
+    const fallbackHandler = latestVersionKey ? versionHandlers[latestVersionKey] : undefined;
+    if (fallbackHandler) {
+        void fallbackHandler(req, res, next);
+    }
+    else {
+        res.status(422).send(notFoundMessage);
+    }
+};
+exports.executeDefaultHandler = executeDefaultHandler;
+/**
+ * Middleware for handling version-based routing in Express.
+ *
+ * This middleware inspects the incoming request for a semantic version (e.g., "1.0.0", "~2.1", "^3")
+ * and delegates the request to the appropriate handler defined in `versionHandlers`.
+ *
+ * Matching priority:
+ * 1. If a version is found in the request, attempt to match a handler.
+ * 2. If no match is found, invoke the `defaultHandler` (if provided).
+ * 3. If no default handler exists, fall back to the latest version handler.
+ * 4. If none is available, respond with HTTP 422.
+ *
+ * @param versionHandlers - A map of semantic version keys to Express handlers.
+ * @param defaultHandler - Optional fallback handler if no version matches.
+ * @returns An Express middleware function.
+ *
+ * @example
+ * ```ts
+ * app.use(
+ *   versioningMiddleware({
+ *     "^1": handlerForV1,
+ *     "~2.1": handlerForV2_1,
+ *     "3.0.0": handlerForV3
+ *   })
+ * );
+ * ```
+ */
+const versioningMiddleware = (versionHandlers, defaultHandler) => {
+    if (!versionHandlers ||
+        typeof versionHandlers !== "object" ||
+        Array.isArray(versionHandlers)) {
+        throw new Error("Invalid argument: 'versionHandlers' must be a non-array object.");
+    }
+    return (req, res, next) => {
+        const clientVersion = (0, exports.extractVersionFromRequest)(req);
+        const handlerKeys = Object.keys(versionHandlers);
+        // No version provided by the client
+        if (!clientVersion) {
+            res.status(422).send("Unprocessable Entity: No version provided.");
+            return;
+        }
+        // Try to match a handler by version
+        for (const handlerKey of handlerKeys) {
+            const matched = (0, exports.executeVersionHandler)(handlerKey, clientVersion, versionHandlers, req, res, next);
+            if (matched)
+                return;
+        }
+        // Fallback to default or latest handler
+        (0, exports.executeDefaultHandler)(defaultHandler, versionHandlers, handlerKeys, req, res, next);
+    };
+};
+exports.versioningMiddleware = versioningMiddleware;
+/**
+ * Determines the latest semantic version from a list of version strings.
+ *
+ * This function removes any leading semantic operators (`^`, `~`) and
+ * compares versions based on major, minor, and patch numbers.
+ *
+ * @param versions - An array of version keys, possibly including "^" or "~" prefixes.
+ * @returns The latest normalized version string (e.g. "3.2.0"), or `null` if the array is empty.
+ *
+ * @example
+ * ```ts
+ * const latest = findLatestVersion(["^1", "~2.3", "3.0.0"]);
+ * latest === "3.0.0"
+ * ```
+ */
+const findLatestVersion = (versions) => {
+    if (!Array.isArray(versions) || versions.length === 0) {
+        return null;
+    }
+    const normalize = (version) => {
+        const cleaned = version.replace(/^[\^~]/, "");
+        const parts = cleaned.split(".").map((n) => parseInt(n, 10));
+        while (parts.length < 3)
+            parts.push(0); // pad missing parts with 0
+        return parts.slice(0, 3);
+    };
+    const sorted = [...versions].sort((a, b) => {
+        const [aMajor, aMinor, aPatch] = normalize(a);
+        const [bMajor, bMinor, bPatch] = normalize(b);
+        if (aMajor !== bMajor)
+            return bMajor - aMajor;
+        if (aMinor !== bMinor)
+            return bMinor - aMinor;
+        return bPatch - aPatch;
+    });
+    return sorted.length > 0 ? sorted[0].replace(/^[\^~]/, "") : null;
+};
+exports.findLatestVersion = findLatestVersion;
+exports.default = exports.versioningMiddleware;
+//# sourceMappingURL=lib.js.map

package/dist/cjs/lib.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lib.js","sourceRoot":"","sources":["../../src/lib.ts"],"names":[],"mappings":"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"}

package/dist/esm/index.js

@@ -0,0 +1,4 @@
+// Main entry point of the library.
+// Re-exports the default export from lib.ts to support both ESM and CommonJS.
+export { default } from "./lib";
+//# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,mCAAmC;AACnC,8EAA8E;AAC9E,OAAO,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC"}

package/dist/esm/lib.js

@@ -0,0 +1,201 @@
+/**
+ * Attempts to extract a semantic version string from an Express request.
+ *
+ * This function checks the `Request` object for a version identifier in the following order:
+ * 1. `req.version` — typically set by middleware.
+ * 2. `req.headers['accept-version']` — often provided by clients via HTTP headers.
+ *
+ * If no version is found, it returns `false`.
+ *
+ * @param req - The Express request object.
+ * @returns The version string (e.g., "1.0.0"), or `false` if none is provided.
+ *
+ * @example
+ * ```ts
+ * const version = extractVersionFromRequest(req);
+ * if (!version) {
+ *   res.status(422).send("No version provided");
+ * }
+ * ```
+ */
+export const extractVersionFromRequest = (req) => {
+    const sources = [req.version, req.headers["accept-version"]];
+    for (const source of sources) {
+        if (typeof source === "string")
+            return source;
+    }
+    return false;
+};
+/**
+ * Executes a version handler if the client version matches the handler's semantic key.
+ *
+ * Determines compatibility between the given `handlerKey` (e.g., "^1", "~2.1", "3.0.0")
+ * and the `clientVersion` (e.g., "2.1.3") using simplified semantic version matching:
+ *
+ * - `^1` matches any version starting with "1" (e.g., "1.0.0", "1.9.5")
+ * - `~2.1` matches versions like "2.1.x" (e.g., "2.1.0", "2.1.9")
+ * - `"3.0.0"` matches exactly "3.0.0"
+ *
+ * If a match is found, the associated handler from `versionHandlers` is invoked.
+ *
+ * @param handlerKey - The version key used for comparison (e.g., "^1", "~2.1", "3.0.0").
+ * @param clientVersion - The version string from the client request (e.g., "2.1.3").
+ * @param versionHandlers - A mapping of version keys to Express request handlers.
+ * @param req - The Express request object.
+ * @param res - The Express response object.
+ * @param next - The Express next middleware function.
+ * @returns `true` if a compatible handler was executed, `false` otherwise.
+ */
+export const executeVersionHandler = (handlerKey, clientVersion, versionHandlers, req, res, next) => {
+    const [clientMajor = "0", clientMinor = "0", clientPatch = "0"] = clientVersion.split(".");
+    let targetVersion;
+    let requestedVersion;
+    if (handlerKey.startsWith("~")) {
+        // "~2.1" → match major.minor
+        targetVersion = handlerKey.slice(1).split(".").slice(0, 2).join(".");
+        requestedVersion = `${clientMajor}.${clientMinor}`;
+    }
+    else if (handlerKey.startsWith("^")) {
+        // "^1" → match major only
+        targetVersion = handlerKey.slice(1).split(".")[0];
+        requestedVersion = clientMajor;
+    }
+    else {
+        // Exact match: "2.1.3"
+        targetVersion = handlerKey;
+        requestedVersion = `${clientMajor}.${clientMinor}.${clientPatch}`;
+    }
+    const handler = versionHandlers[handlerKey];
+    if (requestedVersion === targetVersion && typeof handler === "function") {
+        void handler(req, res, next);
+        return true;
+    }
+    return false;
+};
+/**
+ * Executes the default handler when no version match is found.
+ *
+ * Priority order:
+ * 1. If a `defaultHandler` is provided, it is invoked immediately.
+ * 2. Otherwise, it tries to find and execute the handler for the latest version available.
+ * 3. If none is found, it responds with HTTP 422 and an optional custom error message.
+ *
+ * This ensures that version-based routing gracefully degrades to a default behavior
+ * or returns an informative error if no handler can be determined.
+ *
+ * @param defaultHandler - Optional fallback Express handler.
+ * @param versionHandlers - A map of version keys to handlers.
+ * @param keys - An array of version keys from the versionHandlers object.
+ * @param req - Express request object.
+ * @param res - Express response object.
+ * @param next - Express next middleware function.
+ * @param notFoundMessage - Optional custom error message for 422 responses.
+ */
+export const executeDefaultHandler = (defaultHandler, versionHandlers, keys, req, res, next, notFoundMessage = "Unprocessable Entity: No valid version handler available.") => {
+    if (defaultHandler) {
+        void defaultHandler(req, res, next);
+        return;
+    }
+    if (keys.length === 0) {
+        res.status(422).send(notFoundMessage);
+        return;
+    }
+    const latestVersionKey = findLatestVersion(keys);
+    const fallbackHandler = latestVersionKey ? versionHandlers[latestVersionKey] : undefined;
+    if (fallbackHandler) {
+        void fallbackHandler(req, res, next);
+    }
+    else {
+        res.status(422).send(notFoundMessage);
+    }
+};
+/**
+ * Middleware for handling version-based routing in Express.
+ *
+ * This middleware inspects the incoming request for a semantic version (e.g., "1.0.0", "~2.1", "^3")
+ * and delegates the request to the appropriate handler defined in `versionHandlers`.
+ *
+ * Matching priority:
+ * 1. If a version is found in the request, attempt to match a handler.
+ * 2. If no match is found, invoke the `defaultHandler` (if provided).
+ * 3. If no default handler exists, fall back to the latest version handler.
+ * 4. If none is available, respond with HTTP 422.
+ *
+ * @param versionHandlers - A map of semantic version keys to Express handlers.
+ * @param defaultHandler - Optional fallback handler if no version matches.
+ * @returns An Express middleware function.
+ *
+ * @example
+ * ```ts
+ * app.use(
+ *   versioningMiddleware({
+ *     "^1": handlerForV1,
+ *     "~2.1": handlerForV2_1,
+ *     "3.0.0": handlerForV3
+ *   })
+ * );
+ * ```
+ */
+export const versioningMiddleware = (versionHandlers, defaultHandler) => {
+    if (!versionHandlers ||
+        typeof versionHandlers !== "object" ||
+        Array.isArray(versionHandlers)) {
+        throw new Error("Invalid argument: 'versionHandlers' must be a non-array object.");
+    }
+    return (req, res, next) => {
+        const clientVersion = extractVersionFromRequest(req);
+        const handlerKeys = Object.keys(versionHandlers);
+        // No version provided by the client
+        if (!clientVersion) {
+            res.status(422).send("Unprocessable Entity: No version provided.");
+            return;
+        }
+        // Try to match a handler by version
+        for (const handlerKey of handlerKeys) {
+            const matched = executeVersionHandler(handlerKey, clientVersion, versionHandlers, req, res, next);
+            if (matched)
+                return;
+        }
+        // Fallback to default or latest handler
+        executeDefaultHandler(defaultHandler, versionHandlers, handlerKeys, req, res, next);
+    };
+};
+/**
+ * Determines the latest semantic version from a list of version strings.
+ *
+ * This function removes any leading semantic operators (`^`, `~`) and
+ * compares versions based on major, minor, and patch numbers.
+ *
+ * @param versions - An array of version keys, possibly including "^" or "~" prefixes.
+ * @returns The latest normalized version string (e.g. "3.2.0"), or `null` if the array is empty.
+ *
+ * @example
+ * ```ts
+ * const latest = findLatestVersion(["^1", "~2.3", "3.0.0"]);
+ * latest === "3.0.0"
+ * ```
+ */
+export const findLatestVersion = (versions) => {
+    if (!Array.isArray(versions) || versions.length === 0) {
+        return null;
+    }
+    const normalize = (version) => {
+        const cleaned = version.replace(/^[\^~]/, "");
+        const parts = cleaned.split(".").map((n) => parseInt(n, 10));
+        while (parts.length < 3)
+            parts.push(0); // pad missing parts with 0
+        return parts.slice(0, 3);
+    };
+    const sorted = [...versions].sort((a, b) => {
+        const [aMajor, aMinor, aPatch] = normalize(a);
+        const [bMajor, bMinor, bPatch] = normalize(b);
+        if (aMajor !== bMajor)
+            return bMajor - aMajor;
+        if (aMinor !== bMinor)
+            return bMinor - aMinor;
+        return bPatch - aPatch;
+    });
+    return sorted.length > 0 ? sorted[0].replace(/^[\^~]/, "") : null;
+};
+export default versioningMiddleware;
+//# sourceMappingURL=lib.js.map

package/dist/esm/lib.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lib.js","sourceRoot":"","sources":["../../src/lib.ts"],"names":[],"mappings":"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"}

package/dist/types/index.d.ts

@@ -0,0 +1 @@
+export { default } from "./lib";

package/dist/types/lib.d.ts

@@ -0,0 +1,137 @@
+import { type Request, type Response, type NextFunction, type RequestHandler } from "express";
+/**
+ * An object that maps semantic version strings to specific request handlers.
+ *
+ * This is the core input to the `versioningMiddleware` function. Each key must be a valid
+ * version string, such as `"1.0.0"`, `"^1"`, or `"~2.1"`. These prefixes (`^` and `~`) allow
+ * matching of major/minor version ranges, similar to how they work in `package.json`.
+ *
+ * The value for each key is an Express-compatible handler that should respond to requests
+ * targeting that version.
+ *
+ * @example
+ * ```ts
+ * const handlers: VersionHandlers = {
+ *   "^1": (req, res) => res.send("v1.x handler"),
+ *   "~2.1": (req, res) => res.send("v2.1.x handler"),
+ *   "3.0.0": (req, res) => res.send("exact v3.0.0 handler"),
+ * };
+ * ```
+ */
+export interface VersionHandlers {
+    [version: string]: RequestHandler;
+}
+/**
+ * An extended Express `Request` object that optionally includes a `version` property.
+ * This allows support for custom middleware.
+ */
+interface VersionedRequest extends Request {
+    version?: string;
+}
+/**
+ * Attempts to extract a semantic version string from an Express request.
+ *
+ * This function checks the `Request` object for a version identifier in the following order:
+ * 1. `req.version` — typically set by middleware.
+ * 2. `req.headers['accept-version']` — often provided by clients via HTTP headers.
+ *
+ * If no version is found, it returns `false`.
+ *
+ * @param req - The Express request object.
+ * @returns The version string (e.g., "1.0.0"), or `false` if none is provided.
+ *
+ * @example
+ * ```ts
+ * const version = extractVersionFromRequest(req);
+ * if (!version) {
+ *   res.status(422).send("No version provided");
+ * }
+ * ```
+ */
+export declare const extractVersionFromRequest: (req: VersionedRequest) => string | false;
+/**
+ * Executes a version handler if the client version matches the handler's semantic key.
+ *
+ * Determines compatibility between the given `handlerKey` (e.g., "^1", "~2.1", "3.0.0")
+ * and the `clientVersion` (e.g., "2.1.3") using simplified semantic version matching:
+ *
+ * - `^1` matches any version starting with "1" (e.g., "1.0.0", "1.9.5")
+ * - `~2.1` matches versions like "2.1.x" (e.g., "2.1.0", "2.1.9")
+ * - `"3.0.0"` matches exactly "3.0.0"
+ *
+ * If a match is found, the associated handler from `versionHandlers` is invoked.
+ *
+ * @param handlerKey - The version key used for comparison (e.g., "^1", "~2.1", "3.0.0").
+ * @param clientVersion - The version string from the client request (e.g., "2.1.3").
+ * @param versionHandlers - A mapping of version keys to Express request handlers.
+ * @param req - The Express request object.
+ * @param res - The Express response object.
+ * @param next - The Express next middleware function.
+ * @returns `true` if a compatible handler was executed, `false` otherwise.
+ */
+export declare const executeVersionHandler: (handlerKey: string, clientVersion: string, versionHandlers: VersionHandlers, req: Request, res: Response, next: NextFunction) => boolean;
+/**
+ * Executes the default handler when no version match is found.
+ *
+ * Priority order:
+ * 1. If a `defaultHandler` is provided, it is invoked immediately.
+ * 2. Otherwise, it tries to find and execute the handler for the latest version available.
+ * 3. If none is found, it responds with HTTP 422 and an optional custom error message.
+ *
+ * This ensures that version-based routing gracefully degrades to a default behavior
+ * or returns an informative error if no handler can be determined.
+ *
+ * @param defaultHandler - Optional fallback Express handler.
+ * @param versionHandlers - A map of version keys to handlers.
+ * @param keys - An array of version keys from the versionHandlers object.
+ * @param req - Express request object.
+ * @param res - Express response object.
+ * @param next - Express next middleware function.
+ * @param notFoundMessage - Optional custom error message for 422 responses.
+ */
+export declare const executeDefaultHandler: (defaultHandler: RequestHandler | undefined, versionHandlers: VersionHandlers, keys: string[], req: Request, res: Response, next: NextFunction, notFoundMessage?: string) => void;
+/**
+ * Middleware for handling version-based routing in Express.
+ *
+ * This middleware inspects the incoming request for a semantic version (e.g., "1.0.0", "~2.1", "^3")
+ * and delegates the request to the appropriate handler defined in `versionHandlers`.
+ *
+ * Matching priority:
+ * 1. If a version is found in the request, attempt to match a handler.
+ * 2. If no match is found, invoke the `defaultHandler` (if provided).
+ * 3. If no default handler exists, fall back to the latest version handler.
+ * 4. If none is available, respond with HTTP 422.
+ *
+ * @param versionHandlers - A map of semantic version keys to Express handlers.
+ * @param defaultHandler - Optional fallback handler if no version matches.
+ * @returns An Express middleware function.
+ *
+ * @example
+ * ```ts
+ * app.use(
+ *   versioningMiddleware({
+ *     "^1": handlerForV1,
+ *     "~2.1": handlerForV2_1,
+ *     "3.0.0": handlerForV3
+ *   })
+ * );
+ * ```
+ */
+export declare const versioningMiddleware: (versionHandlers: VersionHandlers, defaultHandler?: RequestHandler) => RequestHandler;
+/**
+ * Determines the latest semantic version from a list of version strings.
+ *
+ * This function removes any leading semantic operators (`^`, `~`) and
+ * compares versions based on major, minor, and patch numbers.
+ *
+ * @param versions - An array of version keys, possibly including "^" or "~" prefixes.
+ * @returns The latest normalized version string (e.g. "3.2.0"), or `null` if the array is empty.
+ *
+ * @example
+ * ```ts
+ * const latest = findLatestVersion(["^1", "~2.3", "3.0.0"]);
+ * latest === "3.0.0"
+ * ```
+ */
+export declare const findLatestVersion: (versions: string[]) => string | null;
+export default versioningMiddleware;

package/package.json

@@ -1,41 +1,62 @@
 {
   "name": "express-version-api",
-  "description": "Middleware for versioning routes/APIs in Express.js using ECMAScript 6. Note: This library is intended for personal use and experimentation, and is not recommended for production environments or widespread adoption.",
-  "version": "1.0.1",
+  "version": "1.0.6",
+  "description": "Middleware for versioning routes/APIs in Express.js using semantic versioning like ^1.0 or ~1.2.",
   "author": "Braian Quintian",
   "license": "MIT",
-  "homepage": "https://github.com/Braian-Quintian/express-version-routes?tab=readme-ov-file",
+  "homepage": "https://github.com/Braian-Quintian/express-version-api#readme",
   "repository": {
     "type": "git",
-    "url": "https://github.com/Braian-Quintian/express-version-api"
+    "url": "git+https://github.com/Braian-Quintian/express-version-api.git"
   },
   "bugs": {
-    "url": "https://github.com/Braian-Quintian/express-version-routes/issues"
+    "url": "https://github.com/Braian-Quintian/express-version-api/issues"
+  },
+  "main": "dist/cjs/index.js",
+  "module": "dist/esm/index.js",
+  "types": "dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "require": "./dist/cjs/index.js",
+      "import": "./dist/esm/index.js",
+      "types": "./dist/types/index.d.ts"
+    }
   },
-  "main": "dist/index.js",
   "engines": {
     "node": ">=20.0.0"
   },
+  "files": [
+    "dist"
+  ],
   "scripts": {
-    "build": "npx tsc",
-    "test": "jest --verbose"
+    "build:esm": "tsc --project tsconfig.esm.json",
+    "build:cjs": "tsc --project tsconfig.cjs.json",
+    "build": "npm run build:esm && npm run build:cjs",
+    "clean": "rm -rf dist",
+    "prepare": "npm run clean && npm run build",
+    "lint": "eslint src --ext .ts",
+    "test": "jest --config jest.config.ts --verbose"
   },
   "keywords": [
-    "routes",
+    "express",
+    "versioning",
     "api",
-    "version",
-    "versioning"
-  ],
-  "files": [
-    "dist"
+    "routes",
+    "middleware",
+    "semver"
   ],
   "devDependencies": {
-    "@types/express": "^4.17.21",
-    "@types/jest": "^29.5.12",
-    "@types/supertest": "^6.0.2",
-    "express": "^4.19.2",
-    "jest": "^29.7.0",
-    "supertest": "^7.0.0",
-    "ts-jest": "^29.1.2"
+    "@eslint/js": "^9.30.1",
+    "@types/express": "^5.0.3",
+    "@types/jest": "^30.0.0",
+    "@types/supertest": "^6.0.3",
+    "eslint": "^9.30.1",
+    "express": "5.1.0",
+    "jest": "^30.0.4",
+    "supertest": "^7.1.1",
+    "ts-jest": "^29.4.0",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.8.3",
+    "typescript-eslint": "^8.35.1"
   }
 }

package/dist/index.d.ts

@@ -1,2 +0,0 @@
-import versionApi from "./lib";
-export default versionApi;

package/dist/index.js

@@ -1,8 +0,0 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-const lib_1 = __importDefault(require("./lib"));
-module.exports = lib_1.default;
-exports.default = lib_1.default;

package/dist/lib.d.ts

@@ -1,15 +0,0 @@
-/**
- * Interface for version handlers.
- * Each key is a version string and the value is a function to handle requests for that version.
- */
-interface VersionHandlers {
-    [key: string]: (req: any, res: any, next: any) => void;
-}
-/**
- * Main middleware that handles version-based routing logic.
- * @param {VersionHandlers} versionHandlers - The object containing all version handlers.
- * @param {((req: any, res: any, next: any) => void) | undefined} defaultHandler - The default handler function.
- * @returns {((req: any, res: any, next: any) => void)} - The middleware function.
- */
-declare const versioningMiddleware: (versionHandlers: VersionHandlers, defaultHandler?: (req: any, res: any, next: any) => void) => ((req: any, res: any, next: any) => void);
-export default versioningMiddleware;

package/dist/lib.js

@@ -1,147 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-/**
- * Extracts the version from the request object.
- * @param {any} req - The request object.
- * @returns {string | boolean} - The version string if it exists, otherwise false.
- */
-const extractVersionFromRequest = (req) => {
-    return req
-        ? req.version
-            ? String(req.version)
-            : req.headers["accept-version"]
-        : false;
-};
-/**
- * Executes the corresponding version handler if there is a version match.
- * @param {string} handlerKey - The key of the handler to execute.
- * @param {string} clientVersion - The version from the client's request.
- * @param {VersionHandlers} versionHandlers - The object containing all version handlers.
- * @param {any} req - The request object.
- * @param {any} res - The response object.
- * @param {any} next - The next middleware function.
- * @returns {boolean} - True if a matching version handler was executed, otherwise false.
- */
-const executeVersionHandler = (handlerKey, clientVersion, versionHandlers, req, res, next) => {
-    let tempKey;
-    let versionArray = clientVersion.split(".");
-    let tempVersion;
-    if (handlerKey[0] === "~") {
-        // Handling versions using '~'
-        tempKey = handlerKey.substring(1).split(".").slice(0, 2).join(".");
-        versionArray[1] = versionArray[1] || "0";
-        tempVersion = versionArray.slice(0, 2).join(".");
-    }
-    else if (handlerKey[0] === "^") {
-        // Handling versions using '^'
-        tempKey = handlerKey.substring(1).split(".").slice(0, 1).join(".");
-        tempVersion = versionArray.slice(0, 1).join(".");
-    }
-    else {
-        // Standard version handling
-        tempKey = handlerKey;
-        versionArray[1] = versionArray[1] || "0";
-        versionArray[2] = versionArray[2] || "0";
-        tempVersion = versionArray.join(".");
-    }
-    if (tempKey === tempVersion && versionHandlers[handlerKey]) {
-        // Call the corresponding version handler if there is a match
-        versionHandlers[handlerKey].call(this, req, res, next);
-        return true;
-    }
-    return false;
-};
-/**
- * Executes the default handler if no matching version is found.
- * @param {((req: any, res: any, next: any) => void) | undefined} defaultHandler - The default handler function.
- * @param {VersionHandlers} versionHandlers - The object containing all version handlers.
- * @param {string[]} keys - The keys of all version handlers.
- * @param {any} req - The request object.
- * @param {any} res - The response object.
- * @param {any} next - The next middleware function.
- */
-const executeDefaultHandler = (defaultHandler, versionHandlers, keys, req, res, next) => {
-    // Check if there is a defaultHandler defined and execute it if it exists
-    if (defaultHandler) {
-        defaultHandler(req, res, next);
-    }
-    else {
-        // If there is no defaultHandler, determine the most recent version
-        const latestVersionKey = findLatestVersion(keys);
-        // If the latest version is found and there is a handler for that version, execute it
-        if (latestVersionKey && versionHandlers[latestVersionKey]) {
-            versionHandlers[latestVersionKey](req, res, next);
-        }
-        else {
-            // If no valid version is found to handle the request, respond with a 422 error
-            res.status(422).send("Unprocessable Entity: No valid handler found for this request.");
-        }
-    }
-};
-/**
- * Main middleware that handles version-based routing logic.
- * @param {VersionHandlers} versionHandlers - The object containing all version handlers.
- * @param {((req: any, res: any, next: any) => void) | undefined} defaultHandler - The default handler function.
- * @returns {((req: any, res: any, next: any) => void)} - The middleware function.
- */
-const versioningMiddleware = (versionHandlers, defaultHandler) => {
-    if (!versionHandlers ||
-        typeof versionHandlers !== "object" ||
-        Array.isArray(versionHandlers)) {
-        throw new Error("Invalid argument: 'versionHandlers' must be a non-array object.");
-    }
-    else {
-        return (req, res, next) => {
-            const clientVersion = extractVersionFromRequest(req);
-            const keys = Object.keys(versionHandlers);
-            if (!clientVersion) {
-                // Execute the default handler if no version is provided
-                return res.status(422).send("Unprocessable Entity: No version provided.");
-            }
-            for (let i = 0; i < keys.length; i++) {
-                const handlerKey = keys[i];
-                if (executeVersionHandler(handlerKey, clientVersion, versionHandlers, req, res, next)) {
-                    return;
-                }
-            }
-            // If no matching version is found, execute the default handler
-            executeDefaultHandler(defaultHandler, versionHandlers, keys, req, res, next);
-        };
-    }
-};
-/**
- * Finds the latest version among an array of versions.
- * @param {string[]} versions - The array of version strings.
- * @returns {string | null} - The latest version string, or null if the array is empty.
- */
-const findLatestVersion = (versions) => {
-    // Find the latest version among an array of versions
-    if (!versions || versions.length === 0) {
-        return null;
-    }
-    const processedVersions = versions.map((version) => {
-        // Process versions by removing special characters and padding with zeros
-        const versionArr = version.replace(/[\^~]/g, "").split(".");
-        for (let i = 0; i < 2; i++) {
-            versionArr[i] = versionArr[i] || "0";
-        }
-        return versionArr;
-    });
-    // Sort processed versions to find the latest one
-    processedVersions.sort((v1Arr, v2Arr) => {
-        for (let i = 0; i < 2; i++) {
-            if (Number(v1Arr[i]) > Number(v2Arr[i])) {
-                return 1;
-            }
-            else if (Number(v1Arr[i]) < Number(v2Arr[i])) {
-                return -1;
-            }
-        }
-        return 0;
-    });
-    return processedVersions[processedVersions.length - 1].join(".");
-};
-// Exporta la función para CommonJS
-module.exports = versioningMiddleware;
-// Exporta la función como default para ES6 modules
-exports.default = versioningMiddleware;