express-version-api 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+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.

package/README.md

@@ -0,0 +1,146 @@
+# 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

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,8 @@
+"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

@@ -0,0 +1,15 @@
+/**
+ * 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

@@ -0,0 +1,147 @@
+"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;

package/package.json

@@ -0,0 +1,41 @@
+{
+  "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",
+  "author": "Braian Quintian",
+  "license": "MIT",
+  "homepage": "https://github.com/Braian-Quintian/express-version-routes?tab=readme-ov-file",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Braian-Quintian/express-version-api"
+  },
+  "bugs": {
+    "url": "https://github.com/Braian-Quintian/express-version-routes/issues"
+  },
+  "main": "dist/index.js",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "build": "npx tsc",
+    "test": "jest --verbose"
+  },
+  "keywords": [
+    "routes",
+    "api",
+    "version",
+    "versioning"
+  ],
+  "files": [
+    "dist"
+  ],
+  "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"
+  }
+}