express-version-api 1.0.6 → 2.0.5

package/CHANGELOG.md

@@ -0,0 +1,63 @@
+# 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.4] - 2026-02-27
+
+### Added
+
+- Added `jsr.json` configuration and JSR package metadata.
+- Added JSR publication support for `@braian-quintian/express-version-api`.
+
+### Changed
+
+- Updated repository documentation to match the current runtime behavior and exports.
+- Hardened release automation to validate npm authentication before publish.
+
+### Fixed
+
+- Fixed `.npmrc` token interpolation to use `NODE_AUTH_TOKEN` in CI.
+- Fixed GitHub Packages publication flow by using scoped package publish in workflow.
+
+## [2.0.3] - 2026-02-27
+
+### Changed
+
+- Updated release workflow with explicit npm authentication verification.
+
+## [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,303 @@
-# 📦 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 APIs with semantic version matching.
 
----
+## Why use this
 
-**⚠️ NOTE:** This package is intended for personal use and experimentation. It is **not recommended** for production use.
+- Routes requests by semantic version (`exact`, `~`, `^`).
+- Supports extraction from header, query, path, or custom function.
+- Handles missing or unmatched versions with configurable fallback strategies.
+- Exposes `req.versionInfo` metadata for observability and debugging.
+- Fully typed for TypeScript projects.
 
----
+## Installation
 
-## 🚧 Project Status
+### npm
 
-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
-
----
+```bash
+npm install express-version-api
+```
 
-## 📦 Installation
+### JSR
 
 ```bash
-npm install express-version-api
+deno add jsr:@braian-quintian/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';
+
+const app = express();
 
 app.get(
-  "/api",
-  versionApi({
-    "1.0.0": handlerV1,
-    "2.0.0": handlerV2,
+  '/api/users',
+  versioningMiddleware({
+    '^1': (_req, res) => res.json({ version: '1.x', users: [] }),
+    '^2': (_req, res) => res.json({ version: '2.x', users: [], meta: { total: 0 } }),
+    '3.0.0': (_req, res) => res.json({ version: '3.0.0', users: [], paging: null }),
   })
 );
 
-app.listen(3000, () => {
-  console.log("Server running on port 3000");
+app.use((error, _req, res, _next) => {
+  res.status(500).json({ error: error.message });
 });
 ```
 
----
+Request examples:
 
-## 🎯 Semver Support (`^`, `~`)
+```bash
+curl -H "Accept-Version: 1.2.0" http://localhost:3000/api/users
+curl -H "Accept-Version: 2.5.1" http://localhost:3000/api/users
+curl -H "Accept-Version: 3.0.0" http://localhost:3000/api/users
+```
 
-| 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`  |
+## Import Modes
+
+ESM (default + named):
+
+```ts
+import versioningMiddleware, { parseVersion } from 'express-version-api';
+```
+
+CommonJS (named only):
 
 ```js
-app.get(
-  "/api",
-  versionApi({
-    "^1.0.0": handlerV1,
-    "~2.1.0": handlerV2,
-    "3.0.0": handlerV3,
-  })
-);
+const { versioningMiddleware, parseVersion } = require('express-version-api');
 ```
 
----
+## Version Matching Rules
 
-## 📥 Version Header
+Supported handler keys:
 
-Clients should include the `Accept-Version` HTTP header in requests:
+- Exact: `1.2.3`
+- Caret: `^1`, `^1.2`, `^1.2.3`
+- Tilde: `~1.2`, `~1.2.3`
 
-```bash
-curl -H "Accept-Version: 1.0.0" http://localhost:3000/api
+Matching priority when multiple handlers match:
+
+1. Exact
+2. Tilde
+3. Caret
+
+Semantics:
+
+- Exact: must match the same `major.minor.patch`.
+- Tilde (`~`): same major and minor, patch must be `>=` requested patch.
+- Caret (`^`): semver-compatible range.
+- Caret with `0.x` follows strict semver-compatible behavior.
+
+Examples:
+
+- `^1.2.3` matches `1.2.3`, `1.3.0`, `1.9.9`, but not `2.0.0`.
+- `^0.2.3` matches `0.2.3` to `0.2.x`, but not `0.3.0`.
+- `~2.1.4` matches `2.1.4` to `2.1.x`, but not `2.2.0`.
+
+## How Version Extraction Works
+
+The middleware resolves version in this order:
+
+1. `req.version` if already set by upstream middleware (source = `custom`)
+2. Configured extraction sources in order (`extraction.sources`)
+
+Default source order:
+
+1. Header: `accept-version`
+2. Query: `v`
+
+You can configure `header`, `query`, `path`, and `custom` extractors.
+
+```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),
+    },
+  }
+);
 ```
 
----
+## Fallback Strategies
 
-## 🧪 Running Tests
+Fallback is used when no handler matches, and also when version is missing with `requireVersion: false`.
 
-```bash
-npm run test
+- `none`: respond with `VERSION_NOT_FOUND`.
+- `latest`: execute the handler with the highest available version.
+- `default`: execute `defaultHandler` if provided, otherwise fallback to `latest`.
+
+```ts
+versioningMiddleware(handlers, {
+  fallbackStrategy: 'default',
+  defaultHandler: (_req, res) => {
+    res.status(200).json({ fallback: true });
+  },
+});
 ```
 
-Tests are powered by [Jest](https://jestjs.io/) and [Supertest](https://github.com/visionmedia/supertest). Full coverage is included.
+## Error Handling
 
----
+Error codes emitted by the middleware:
 
-## 🧩 API
+- `MISSING_VERSION`
+- `INVALID_VERSION_FORMAT`
+- `VERSION_NOT_FOUND`
+- `INVALID_CONFIGURATION`
+- `INVALID_HANDLER`
 
-### `versionApi(handlers, defaultHandler?)`
+Default status codes:
 
-- `handlers`: Object with semver-style version strings as keys and Express handlers as values.
-- `defaultHandler`: Optional fallback if no version matches.
+- Missing version: `422`
+- Version not found: `422`
+- Invalid version format: `400`
 
-```js
-app.get(
-  "/api",
-  versionApi({
-    "^1.0.0": v1Handler,
-    "~2.0.0": v2Handler,
-    "3.0.0": v3Handler,
-  }, fallbackHandler)
-);
+Default response shape:
+
+```json
+{
+  "error": "VERSION_NOT_FOUND",
+  "message": "No handler found for the requested API version",
+  "requestedVersion": "99.0.0",
+  "availableVersions": ["^1", "^2"]
+}
+```
+
+Configure custom messages/statuses and override handling via `onError`:
+
+```ts
+versioningMiddleware(handlers, {
+  errorResponse: {
+    missingVersionStatus: 400,
+    missingVersionMessage: 'Version header is required',
+    versionNotFoundMessage: (version) => `Version ${version} is not supported`,
+    onError: (error, _req, res) => {
+      if (error.code === 'INVALID_VERSION_FORMAT') {
+        res.status(400).json({ code: error.code, detail: error.message });
+        return true;
+      }
+      return false;
+    },
+  },
+});
 ```
 
----
+## Request Metadata (`req.versionInfo`)
 
-## 🔄 Fallback Strategy
+When `attachVersionInfo` is `true`, the middleware adds:
 
-If the version is not matched:
+```ts
+{
+  requested: string;
+  matched: string;
+  source: 'header' | 'query' | 'path' | 'custom';
+}
+```
+
+Notes:
+
+- `source` preserves the real extraction source, including fallback scenarios.
+- When no version was provided and fallback is used, `versionInfo` is not attached because `requested` is undefined.
+
+## Runtime Defaults
+
+```ts
+{
+  extraction: {
+    sources: ['header', 'query'],
+    header: { name: 'accept-version' },
+    query: { name: 'v' },
+    path: { pattern: /\/v(\d+(?:\.\d+)?(?:\.\d+)?)\// },
+    custom: undefined
+  },
+  errorResponse: {
+    missingVersionStatus: 422,
+    versionNotFoundStatus: 422,
+    missingVersionMessage: 'API version is required',
+    versionNotFoundMessage: 'No handler found for the requested API version',
+    includeRequestedVersion: true,
+    onError: undefined
+  },
+  fallbackStrategy: 'default',
+  defaultHandler: undefined,
+  validateHandlers: true,
+  attachVersionInfo: true,
+  requireVersion: true
+}
+```
 
-1. Use `defaultHandler` if defined
-2. Otherwise, fallback to the latest available handler
-3. If no handler matches, return `422 Unprocessable Entity`
+## Public API
 
----
+Main middleware:
 
-## 📚 Examples
+- `versioningMiddleware`
 
-Check the `test/` directory for integration examples and how `^`, `~` and fallbacks work in practice.
+Error helpers:
 
----
+- `VersioningError`
+- `createMissingVersionError`
+- `createVersionNotFoundError`
+- `createInvalidVersionFormatError`
+- `createInvalidHandlerError`
+- `createInvalidConfigurationError`
+- `isVersioningError`
+- `hasErrorCode`
 
-## 🛣️ Roadmap
+Version utilities:
 
-- [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
+- `parseVersion`
+- `parseVersionRange`
+- `versionSatisfies`
+- `compareVersions`
+- `findLatestVersion`
+- `isValidVersion`
+- `isValidVersionRange`
+- `normalizeVersion`
 
----
+Config export:
 
-## 🤝 Contributing
+- `DEFAULT_CONFIG`
+
+## Breaking Changes (v2)
+
+- Removed legacy `createVersionMiddleware` API.
+- CommonJS default export was removed; CJS must use named imports.
+
+## Development
+
+```bash
+npm install
+npm run validate
+```
 
-Contributions, issues, and feature requests are welcome!
-Contact: [bquintian.developer@gmail.com](mailto:bquintian.developer@gmail.com)
+Main scripts:
 
----
+- `npm run typecheck`
+- `npm run lint`
+- `npm run format:check`
+- `npm run test`
+- `npm run test:coverage`
+- `npm run build`
+- `npm run test:types`
 
-## 🛡 License
+## License
 
-This project is licensed under the MIT License - see the [LICENSE](./LICENSE) file for details.
+MIT