express-version-api 1.0.6 → 2.0.4

package/CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [2.0.0] - 2026-02-27
+
+### Removed
+
+- Removed deprecated `createVersionMiddleware` API.
+- Removed CommonJS default export path; CJS now uses named exports only.
+
+### Changed
+
+- `test:types` now validates `test-types/**/*.test-d.ts` and runs in `validate`/CI.
+- CI now targets `develop` and `main`, and PR checks use the actual base branch.
+- `npm test` no longer writes coverage artifacts by default.
+- Pre-commit hook now runs `lint-staged`.
+- TypeScript incremental metadata moved outside publish output.
+- Removed unused dev dependencies: `@types/semver`, `ts-node`.
+- Updated README and package docs to match runtime behavior.
+
+### Fixed
+
+- `fallbackStrategy` is now validated at config resolution.
+- Async `defaultHandler` errors are forwarded to Express `next(error)`.
+- Caret matching for `0.x` follows semver-compatible constraints.
+- `missingVersionMessage` from config is now applied in responses.
+- Path extraction is stable with global/sticky regex (`lastIndex` handling).
+- `req.versionInfo.source` now preserves the original extraction source in fallback paths.
+
+## [1.0.6] - 2025-02-01
+
+### Added
+
+- Stable baseline release published to npm.

package/README.md

@@ -1,162 +1,224 @@
-# 📦 express-version-api
+# 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)
+[![npm downloads](https://img.shields.io/npm/dm/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/ci.yml?branch=develop)](https://github.com/Braian-Quintian/express-version-api/actions)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)
 
-> Versioned routing middleware for Express.js based on semantic versioning (`semver`).
+Version-aware middleware for Express.js with semantic version matching.
 
----
-
-**⚠️ 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
+## Installation
 
 ```bash
 npm install express-version-api
 ```
 
----
+Requirements:
 
-## 🚀 Quick Usage
+- Node.js >= 18
+- Express >= 4
 
-```js
-const express = require("express");
-const versionApi = require("express-version-api");
-const app = express();
+## Quick Start
 
-const handlerV1 = (req, res) => res.send("This is version 1.0.0");
-const handlerV2 = (req, res) => res.send("This is version 2.0.0");
+```ts
+import express from 'express';
+import { versioningMiddleware } from 'express-version-api';
 
-app.get(
-  "/api",
-  versionApi({
-    "1.0.0": handlerV1,
-    "2.0.0": handlerV2,
+const app = express();
+
+app.use(
+  '/api',
+  versioningMiddleware({
+    '^1': (_req, res) => {
+      res.json({ version: '1.x' });
+    },
+    '^2': (_req, res) => {
+      res.json({ version: '2.x' });
+    },
+    '3.0.0': (_req, res) => {
+      res.json({ version: '3.0.0' });
+    },
   })
 );
+```
 
-app.listen(3000, () => {
-  console.log("Server running on port 3000");
-});
+Request examples:
+
+```bash
+curl -H "Accept-Version: 1.2.0" http://localhost:3000/api
+curl -H "Accept-Version: 2.5.1" http://localhost:3000/api
+curl -H "Accept-Version: 3.0.0" http://localhost:3000/api
 ```
 
----
+## Import Modes
 
-## 🎯 Semver Support (`^`, `~`)
+ESM:
+
+```ts
+import versioningMiddleware, { parseVersion } from 'express-version-api';
+```
 
-| 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`  |
+CommonJS:
 
 ```js
-app.get(
-  "/api",
-  versionApi({
-    "^1.0.0": handlerV1,
-    "~2.1.0": handlerV2,
-    "3.0.0": handlerV3,
-  })
-);
+const { versioningMiddleware, parseVersion } = require('express-version-api');
 ```
 
----
+## Matching Rules
 
-## 📥 Version Header
+Supported handler keys:
 
-Clients should include the `Accept-Version` HTTP header in requests:
+- Exact: `1.2.3`
+- Caret: `^1.2.3`
+- Tilde: `~1.2.3`
 
-```bash
-curl -H "Accept-Version: 1.0.0" http://localhost:3000/api
-```
+Priority when multiple handlers match:
 
----
+1. Exact
+2. Tilde
+3. Caret
 
-## 🧪 Running Tests
+Notes:
 
-```bash
-npm run test
-```
-
-Tests are powered by [Jest](https://jestjs.io/) and [Supertest](https://github.com/visionmedia/supertest). Full coverage is included.
+- Caret behavior for `0.x` follows semver-compatible constraints.
+- Versions like `1`, `1.2`, and `1.2.3` are accepted.
 
----
+## Version Extraction
 
-## 🧩 API
+Default extraction order:
 
-### `versionApi(handlers, defaultHandler?)`
+1. Header: `accept-version`
+2. Query: `v`
 
-- `handlers`: Object with semver-style version strings as keys and Express handlers as values.
-- `defaultHandler`: Optional fallback if no version matches.
+You can configure `header`, `query`, `path`, or `custom` sources.
 
-```js
-app.get(
-  "/api",
-  versionApi({
-    "^1.0.0": v1Handler,
-    "~2.0.0": v2Handler,
-    "3.0.0": v3Handler,
-  }, fallbackHandler)
+```ts
+versioningMiddleware(
+  {
+    '^1': v1Handler,
+    '^2': v2Handler,
+  },
+  {
+    extraction: {
+      sources: ['header', 'query', 'path', 'custom'],
+      header: { name: 'x-api-version' },
+      query: { name: 'version' },
+      path: { pattern: /\/api\/v(\d+(?:\.\d+)?(?:\.\d+)?)\// },
+      custom: (req) => (req.hostname.startsWith('v2.') ? '2.0.0' : undefined),
+    },
+  }
 );
 ```
 
----
+## Configuration
+
+Defaults:
+
+- `requireVersion: true`
+- `fallbackStrategy: 'default'`
+- `attachVersionInfo: true`
+- `validateHandlers: true`
+- `errorResponse.missingVersionStatus: 422`
+- `errorResponse.versionNotFoundStatus: 422`
+- `errorResponse.missingVersionMessage: 'API version is required'`
+
+```ts
+interface VersioningOptions {
+  extraction?: {
+    sources?: Array<'header' | 'query' | 'path' | 'custom'>;
+    header?: { name?: string };
+    query?: { name?: string };
+    path?: { pattern?: RegExp };
+    custom?: (req: Request) => string | undefined;
+  };
+  requireVersion?: boolean;
+  fallbackStrategy?: 'latest' | 'none' | 'default';
+  defaultHandler?: RequestHandler;
+  validateHandlers?: boolean;
+  attachVersionInfo?: boolean;
+  errorResponse?: {
+    missingVersionStatus?: number;
+    versionNotFoundStatus?: number;
+    missingVersionMessage?: string;
+    versionNotFoundMessage?: string | ((version: string) => string);
+    includeRequestedVersion?: boolean;
+    onError?: (
+      error: VersioningError,
+      req: Request,
+      res: Response,
+      next: NextFunction
+    ) => boolean | undefined;
+  };
+}
+```
 
-## 🔄 Fallback Strategy
+## Fallback Strategies
 
-If the version is not matched:
+- `none`: return `VERSION_NOT_FOUND` error.
+- `latest`: execute the highest available version handler.
+- `default`: execute `defaultHandler` when provided; otherwise falls back to `latest`.
 
-1. Use `defaultHandler` if defined
-2. Otherwise, fallback to the latest available handler
-3. If no handler matches, return `422 Unprocessable Entity`
+## Error Handling
 
----
+Error codes:
 
-## 📚 Examples
+- `MISSING_VERSION`
+- `INVALID_VERSION_FORMAT`
+- `VERSION_NOT_FOUND`
+- `INVALID_CONFIGURATION`
+- `INVALID_HANDLER`
 
-Check the `test/` directory for integration examples and how `^`, `~` and fallbacks work in practice.
+Default error response shape:
 
----
+```json
+{
+  "error": "VERSION_NOT_FOUND",
+  "message": "No handler found for the requested API version",
+  "requestedVersion": "99.0.0",
+  "availableVersions": ["^1", "^2"]
+}
+```
+
+## Version Info Metadata
+
+When `attachVersionInfo` is enabled, the middleware sets `req.versionInfo`:
+
+```ts
+{
+  requested: string;
+  matched: string;
+  source: 'header' | 'query' | 'path' | 'custom';
+}
+```
+
+## API
 
-## 🛣️ Roadmap
+Main exports:
 
-- [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
+- `versioningMiddleware`
+- `parseVersion`
+- `parseVersionRange`
+- `versionSatisfies`
+- `compareVersions`
+- `findLatestVersion`
+- `isValidVersion`
+- `isValidVersionRange`
+- `normalizeVersion`
+- `VersioningError`
+- `DEFAULT_CONFIG`
 
----
+## Breaking Changes (v2.0.0)
 
-## 🤝 Contributing
+- Removed legacy `createVersionMiddleware` API.
+- CommonJS consumers must use named exports (no default export in CJS).
 
-Contributions, issues, and feature requests are welcome!
-Contact: [bquintian.developer@gmail.com](mailto:bquintian.developer@gmail.com)
+## Development
 
----
+```bash
+npm install
+npm run validate
+```
 
-## 🛡 License
+## License
 
-This project is licensed under the MIT License - see the [LICENSE](./LICENSE) file for details.
+MIT