express-version-api 2.0.4 → 2.0.5

package/CHANGELOG.md

@@ -7,6 +7,29 @@ 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

package/README.md

@@ -5,14 +5,30 @@
 [![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)
 
-Version-aware middleware for Express.js with semantic version matching.
+Version-aware middleware for Express.js APIs with semantic version matching.
+
+## Why use this
+
+- 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
 
+### npm
+
 ```bash
 npm install express-version-api
 ```
 
+### JSR
+
+```bash
+deno add jsr:@braian-quintian/express-version-api
+```
+
 Requirements:
 
 - Node.js >= 18
@@ -26,71 +42,82 @@ import { versioningMiddleware } from 'express-version-api';
 
 const app = express();
 
-app.use(
-  '/api',
+app.get(
+  '/api/users',
   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' });
-    },
+    '^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.use((error, _req, res, _next) => {
+  res.status(500).json({ error: error.message });
+});
 ```
 
 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
+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
 ```
 
 ## Import Modes
 
-ESM:
+ESM (default + named):
 
 ```ts
 import versioningMiddleware, { parseVersion } from 'express-version-api';
 ```
 
-CommonJS:
+CommonJS (named only):
 
 ```js
 const { versioningMiddleware, parseVersion } = require('express-version-api');
 ```
 
-## Matching Rules
+## Version Matching Rules
 
 Supported handler keys:
 
 - Exact: `1.2.3`
-- Caret: `^1.2.3`
-- Tilde: `~1.2.3`
+- Caret: `^1`, `^1.2`, `^1.2.3`
+- Tilde: `~1.2`, `~1.2.3`
 
-Priority when multiple handlers match:
+Matching priority when multiple handlers match:
 
 1. Exact
 2. Tilde
 3. Caret
 
-Notes:
+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.
 
-- Caret behavior for `0.x` follows semver-compatible constraints.
-- Versions like `1`, `1.2`, and `1.2.3` are accepted.
+Examples:
 
-## Version Extraction
+- `^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`.
 
-Default extraction order:
+## 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`, or `custom` sources.
+You can configure `header`, `query`, `path`, and `custom` extractors.
 
 ```ts
 versioningMiddleware(
@@ -110,57 +137,26 @@ versioningMiddleware(
 );
 ```
 
-## Configuration
+## Fallback Strategies
 
-Defaults:
+Fallback is used when no handler matches, and also when version is missing with `requireVersion: false`.
 
-- `requireVersion: true`
-- `fallbackStrategy: 'default'`
-- `attachVersionInfo: true`
-- `validateHandlers: true`
-- `errorResponse.missingVersionStatus: 422`
-- `errorResponse.versionNotFoundStatus: 422`
-- `errorResponse.missingVersionMessage: 'API version is required'`
+- `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
-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;
-  };
-}
+versioningMiddleware(handlers, {
+  fallbackStrategy: 'default',
+  defaultHandler: (_req, res) => {
+    res.status(200).json({ fallback: true });
+  },
+});
 ```
 
-## Fallback Strategies
-
-- `none`: return `VERSION_NOT_FOUND` error.
-- `latest`: execute the highest available version handler.
-- `default`: execute `defaultHandler` when provided; otherwise falls back to `latest`.
-
 ## Error Handling
 
-Error codes:
+Error codes emitted by the middleware:
 
 - `MISSING_VERSION`
 - `INVALID_VERSION_FORMAT`
@@ -168,7 +164,13 @@ Error codes:
 - `INVALID_CONFIGURATION`
 - `INVALID_HANDLER`
 
-Default error response shape:
+Default status codes:
+
+- Missing version: `422`
+- Version not found: `422`
+- Invalid version format: `400`
+
+Default response shape:
 
 ```json
 {
@@ -179,9 +181,28 @@ Default error response shape:
 }
 ```
 
-## Version Info Metadata
+Configure custom messages/statuses and override handling via `onError`:
 
-When `attachVersionInfo` is enabled, the middleware sets `req.versionInfo`:
+```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`)
+
+When `attachVersionInfo` is `true`, the middleware adds:
 
 ```ts
 {
@@ -191,11 +212,57 @@ When `attachVersionInfo` is enabled, the middleware sets `req.versionInfo`:
 }
 ```
 
-## API
+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
 
-Main exports:
+```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
+}
+```
+
+## Public API
+
+Main middleware:
 
 - `versioningMiddleware`
+
+Error helpers:
+
+- `VersioningError`
+- `createMissingVersionError`
+- `createVersionNotFoundError`
+- `createInvalidVersionFormatError`
+- `createInvalidHandlerError`
+- `createInvalidConfigurationError`
+- `isVersioningError`
+- `hasErrorCode`
+
+Version utilities:
+
 - `parseVersion`
 - `parseVersionRange`
 - `versionSatisfies`
@@ -204,13 +271,15 @@ Main exports:
 - `isValidVersion`
 - `isValidVersionRange`
 - `normalizeVersion`
-- `VersioningError`
+
+Config export:
+
 - `DEFAULT_CONFIG`
 
-## Breaking Changes (v2.0.0)
+## Breaking Changes (v2)
 
 - Removed legacy `createVersionMiddleware` API.
-- CommonJS consumers must use named exports (no default export in CJS).
+- CommonJS default export was removed; CJS must use named imports.
 
 ## Development
 
@@ -219,6 +288,16 @@ npm install
 npm run validate
 ```
 
+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
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "express-version-api",
-  "version": "2.0.4",
+  "version": "2.0.5",
   "description": "Middleware for versioning routes/APIs in Express.js using semantic versioning like ^1.0 or ~1.2.",
   "author": "Braian Quintian <bquintian.developer@gmail.com>",
   "license": "MIT",