{"_id":"@braian-quintian/express-version-api","_rev":"2-81584950a694b96cbeb2be560f976c16","name":"@braian-quintian/express-version-api","dist-tags":{"latest":"1.0.5"},"versions":{"1.1.0":{"name":"@braian-quintian/express-version-api","version":"1.1.0","keywords":["express","versioning","api","routes","middleware","semver"],"author":{"name":"Braian Quintian"},"license":"MIT","_id":"@braian-quintian/express-version-api@1.1.0","maintainers":[{"name":"braian-quintian","email":"bquintianromero@gmail.com"}],"homepage":"https://github.com/Braian-Quintian/express-version-api#readme","bugs":{"url":"https://github.com/Braian-Quintian/express-version-api/issues"},"dist":{"shasum":"9ab08b9d09988123ee1585a01fad6a83f8b4bd5d","tarball":"https://registry.npmjs.org/@braian-quintian/express-version-api/-/express-version-api-1.1.0.tgz","fileCount":13,"integrity":"sha512-zerFS0s9ewOj2z/8b0R9k+A9gPK13bc9x4oo5l4j/VSZFjTcwlbbaUNYsVF8w/FtgySNsAlbvn6cUiOpG1/lpQ==","signatures":[{"sig":"MEUCIQCRwnCDiGYc/VCG0f6xmpQZq/uN0+48UVpp1egdLZZq+wIgS6yC2z+kN1I93Cjv6nT5A2C5mv8FwH9U34/sK+1LQlw=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":38709},"main":"dist/cjs/index.js","types":"dist/types/index.d.ts","module":"dist/esm/index.js","engines":{"node":">=20.0.0"},"exports":{".":{"types":"./dist/types/index.d.ts","import":"./dist/esm/index.js","require":"./dist/cjs/index.js"}},"gitHead":"a9702809d9e859d690959765ad5e93e2596184e0","scripts":{"lint":"eslint src --ext .ts","test":"jest --config jest.config.ts --verbose","build":"npm run build:esm && npm run build:cjs","clean":"rm -rf dist","prepare":"npm run clean && npm run build","build:cjs":"tsc --project tsconfig.cjs.json","build:esm":"tsc --project tsconfig.esm.json"},"_npmUser":{"name":"braian-quintian","email":"bquintianromero@gmail.com"},"repository":{"url":"git+https://github.com/Braian-Quintian/express-version-api.git","type":"git"},"_npmVersion":"10.8.2","description":"Middleware for versioning routes/APIs in Express.js using semantic versioning like ^1.0 or ~1.2.","directories":{},"_nodeVersion":"20.19.3","_hasShrinkwrap":false,"devDependencies":{"jest":"^30.0.4","eslint":"^9.30.1","express":"5.1.0","ts-jest":"^29.4.0","ts-node":"^10.9.2","supertest":"^7.1.1","@eslint/js":"^9.30.1","typescript":"^5.8.3","@types/jest":"^30.0.0","@types/express":"^5.0.3","@types/supertest":"^6.0.3","typescript-eslint":"^8.35.1"},"_npmOperationalInternal":{"tmp":"tmp/express-version-api_1.1.0_1752366077049_0.36150672481845914","host":"s3://npm-registry-packages-npm-production"}},"1.0.5":{"name":"@braian-quintian/express-version-api","version":"1.0.5","description":"Middleware for versioning routes/APIs in Express.js using semantic versioning like ^1.0 or ~1.2.","author":{"name":"Braian Quintian"},"license":"MIT","homepage":"https://github.com/Braian-Quintian/express-version-api#readme","repository":{"type":"git","url":"git+https://github.com/Braian-Quintian/express-version-api.git"},"bugs":{"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"}},"engines":{"node":">=20.0.0"},"scripts":{"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":["express","versioning","api","routes","middleware","semver"],"devDependencies":{"@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"},"_id":"@braian-quintian/express-version-api@1.0.5","gitHead":"51c0f48bab24d04e5e5103ff6a9d4a0343b40b60","_nodeVersion":"20.19.3","_npmVersion":"10.8.2","dist":{"integrity":"sha512-rk9NNfF5ernPXc+sbrSIGlqMXhOpsZYS9DZUcNnPh2PVQnwJl5DAAmu4Ylq5szKFL9k/0V3iTX+/a2sawkt2uA==","shasum":"f7264ab9b6296d48c316aa33b3b724eba8df5f74","tarball":"https://registry.npmjs.org/@braian-quintian/express-version-api/-/express-version-api-1.0.5.tgz","fileCount":13,"unpackedSize":38713,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIDIQGT0orMiwaTweD+zhoY4aLdCRGO5EjKBHgt6VZz8lAiACQKzvmqJKnNmbtUB+6tKxMKH+3ikLwocRf3RNNX8zbw=="}]},"_npmUser":{"name":"braian-quintian","email":"bquintianromero@gmail.com"},"directories":{},"maintainers":[{"name":"braian-quintian","email":"bquintianromero@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/express-version-api_1.0.5_1752366478128_0.7747815274419014"},"_hasShrinkwrap":false}},"time":{"created":"2025-07-13T00:21:16.876Z","modified":"2025-07-13T00:27:58.507Z","1.1.0":"2025-07-13T00:21:17.240Z","1.0.5":"2025-07-13T00:27:58.313Z"},"bugs":{"url":"https://github.com/Braian-Quintian/express-version-api/issues"},"author":{"name":"Braian Quintian"},"license":"MIT","homepage":"https://github.com/Braian-Quintian/express-version-api#readme","keywords":["express","versioning","api","routes","middleware","semver"],"repository":{"type":"git","url":"git+https://github.com/Braian-Quintian/express-version-api.git"},"description":"Middleware for versioning routes/APIs in Express.js using semantic versioning like ^1.0 or ~1.2.","maintainers":[{"name":"braian-quintian","email":"bquintianromero@gmail.com"}],"readme":"# 📦 express-version-api\n\n[![npm version](https://img.shields.io/npm/v/express-version-api.svg)](https://www.npmjs.com/package/express-version-api)\n[![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)\n[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](./LICENSE)\n[![Coverage Status](https://img.shields.io/codecov/c/github/Braian-Quintian/express-version-api)](https://codecov.io/gh/Braian-Quintian/express-version-api)\n[![Node.js](https://img.shields.io/badge/node-%3E=14.0.0-brightgreen)](https://nodejs.org)\n\n> Versioned routing middleware for Express.js based on semantic versioning (`semver`).\n\n---\n\n**⚠️ NOTE:** This package is intended for personal use and experimentation. It is **not recommended** for production use.\n\n---\n\n## 🚧 Project Status\n\nThis library is under **active development**. Features and improvements are being added frequently. Use at your own discretion in unstable environments.\n\n---\n\n## ✨ Features\n\n- ✅ Version-based routing (`^`, `~`, exact versions)\n- ✅ Automatic fallback to default or latest version\n- ✅ Fully compatible with Express middleware\n- ✅ Well-tested with Jest and Supertest\n\n---\n\n## 📦 Installation\n\n```bash\nnpm install express-version-api\n```\n\n---\n\n## 🚀 Quick Usage\n\n```js\nconst express = require(\"express\");\nconst versionApi = require(\"express-version-api\");\nconst app = express();\n\nconst handlerV1 = (req, res) => res.send(\"This is version 1.0.0\");\nconst handlerV2 = (req, res) => res.send(\"This is version 2.0.0\");\n\napp.get(\n  \"/api\",\n  versionApi({\n    \"1.0.0\": handlerV1,\n    \"2.0.0\": handlerV2,\n  })\n);\n\napp.listen(3000, () => {\n  console.log(\"Server running on port 3000\");\n});\n```\n\n---\n\n## 🎯 Semver Support (`^`, `~`)\n\n| Symbol | Matches                    | Example Matches    |\n| ------ | -------------------------- | ------------------ |\n| `^`    | Major-compatible (`1.x.x`) | `^1.0.0` → `1.2.3` |\n| `~`    | Minor-compatible (`2.1.x`) | `~2.1.0` → `2.1.4` |\n| Exact  | Exact version only         | `3.0.0` → `3.0.0`  |\n\n```js\napp.get(\n  \"/api\",\n  versionApi({\n    \"^1.0.0\": handlerV1,\n    \"~2.1.0\": handlerV2,\n    \"3.0.0\": handlerV3,\n  })\n);\n```\n\n---\n\n## 📥 Version Header\n\nClients should include the `Accept-Version` HTTP header in requests:\n\n```bash\ncurl -H \"Accept-Version: 1.0.0\" http://localhost:3000/api\n```\n\n---\n\n## 🧪 Running Tests\n\n```bash\nnpm run test\n```\n\nTests are powered by [Jest](https://jestjs.io/) and [Supertest](https://github.com/visionmedia/supertest). Full coverage is included.\n\n---\n\n## 🧩 API\n\n### `versionApi(handlers, defaultHandler?)`\n\n- `handlers`: Object with semver-style version strings as keys and Express handlers as values.\n- `defaultHandler`: Optional fallback if no version matches.\n\n```js\napp.get(\n  \"/api\",\n  versionApi({\n    \"^1.0.0\": v1Handler,\n    \"~2.0.0\": v2Handler,\n    \"3.0.0\": v3Handler,\n  }, fallbackHandler)\n);\n```\n\n---\n\n## 🔄 Fallback Strategy\n\nIf the version is not matched:\n\n1. Use `defaultHandler` if defined\n2. Otherwise, fallback to the latest available handler\n3. If no handler matches, return `422 Unprocessable Entity`\n\n---\n\n## 📚 Examples\n\nCheck the `test/` directory for integration examples and how `^`, `~` and fallbacks work in practice.\n\n---\n\n## 🛣️ Roadmap\n\n- [x] Basic versioning with `^`, `~`, exact\n- [x] Default and latest fallback\n- [ ] Advanced semver range support (planned)\n- [ ] Improved validation and DX\n- [ ] Full ESM and CJS dual package\n- [ ] Typed handler inference with TypeScript\n\n---\n\n## 🤝 Contributing\n\nContributions, issues, and feature requests are welcome!\nContact: [bquintian.developer@gmail.com](mailto:bquintian.developer@gmail.com)\n\n---\n\n## 🛡 License\n\nThis project is licensed under the MIT License - see the [LICENSE](./LICENSE) file for details.\n","readmeFilename":"README.md"}