http-proxy-middleware 3.0.0-beta.0 → 3.0.0

package/README.md

@@ -1,13 +1,13 @@
 # http-proxy-middleware
 
-[![GitHub Workflow Status (branch)](https://img.shields.io/github/workflow/status/chimurai/http-proxy-middleware/CI/master?style=flat-square)](https://github.com/chimurai/http-proxy-middleware/actions?query=branch%3Amaster)
-[![Coveralls](https://img.shields.io/coveralls/chimurai/http-proxy-middleware.svg?style=flat-square)](https://coveralls.io/r/chimurai/http-proxy-middleware)
-[![dependency Status](https://snyk.io/test/npm/http-proxy-middleware/badge.svg?style=flat-square)](https://snyk.io/test/npm/http-proxy-middleware)
-[![npm](https://img.shields.io/npm/v/http-proxy-middleware?color=%23CC3534&style=flat-square)](https://www.npmjs.com/package/http-proxy-middleware)
+[![GitHub Workflow Status (with branch)](https://img.shields.io/github/actions/workflow/status/chimurai/http-proxy-middleware/ci.yml?branch=master&logo=github-actions&logoColor=white&style=flat-square)](https://github.com/chimurai/http-proxy-middleware/actions/workflows/ci.yml?query=branch%3Amaster)
+[![Coveralls](https://img.shields.io/coveralls/chimurai/http-proxy-middleware.svg?style=flat-square&logo=coveralls)](https://coveralls.io/r/chimurai/http-proxy-middleware)
+[![Known Vulnerabilities](https://snyk.io/test/github/chimurai/http-proxy-middleware/badge.svg)](https://snyk.io/test/github/chimurai/http-proxy-middleware)
+[![npm](https://img.shields.io/npm/v/http-proxy-middleware?color=%23CC3534&style=flat-square&logo=npm)](https://www.npmjs.com/package/http-proxy-middleware)
 
 Node.js proxying made simple. Configure proxy middleware with ease for [connect](https://github.com/senchalabs/connect), [express](https://github.com/expressjs/express), [next.js](https://github.com/vercel/next.js) and [many more](#compatible-servers).
 
-Powered by the popular Nodejitsu [`http-proxy`](https://github.com/nodejitsu/node-http-proxy). [![GitHub stars](https://img.shields.io/github/stars/nodejitsu/node-http-proxy.svg?style=social&label=Star)](https://github.com/nodejitsu/node-http-proxy)
+Powered by the popular Nodejitsu [`http-proxy`](https://github.com/http-party/node-http-proxy). [![GitHub stars](https://img.shields.io/github/stars/http-party/node-http-proxy.svg?style=social&label=Star)](https://github.com/http-party/node-http-proxy)
 
 ## ⚠️ Note <!-- omit in toc -->
 
@@ -39,13 +39,13 @@ app.use(
   createProxyMiddleware({
     target: 'http://www.example.org/secret',
     changeOrigin: true,
-  })
+  }),
 );
 
 app.listen(3000);
 
 // proxy and change the base path from "/api" to "/secret"
-// http://localhost:3000/api/foo/bar -> http://www.example.org/secret/foo/bar
+// http://127.0.0.1:3000/api/foo/bar -> http://www.example.org/secret/foo/bar
 ```
 
 ```typescript
@@ -61,13 +61,13 @@ app.use(
   createProxyMiddleware({
     target: 'http://www.example.org/api',
     changeOrigin: true,
-  })
+  }),
 );
 
 app.listen(3000);
 
 // proxy and keep the same base path "/api"
-// http://localhost:3000/api/foo/bar -> http://www.example.org/api/foo/bar
+// http://127.0.0.1:3000/api/foo/bar -> http://www.example.org/api/foo/bar
 ```
 
 _All_ `http-proxy` [options](https://github.com/nodejitsu/node-http-proxy#options) can be used, along with some extra `http-proxy-middleware` [options](#options).
@@ -81,7 +81,7 @@ _All_ `http-proxy` [options](https://github.com/nodejitsu/node-http-proxy#option
 - [Express Server Example](#express-server-example)
   - [app.use(path, proxy)](#appusepath-proxy)
 - [Options](#options)
-  - [`pathFilter` (string, []string, glob, []glob, function)](#pathfilter-string-string-glob-glob-function)
+  - [`pathFilter` (string, \[\]string, glob, \[\]glob, function)](#pathfilter-string-string-glob-glob-function)
   - [`pathRewrite` (object/function)](#pathrewrite-objectfunction)
   - [`router` (object/function)](#router-objectfunction)
   - [`plugins` (Array)](#plugins-array)
@@ -93,6 +93,7 @@ _All_ `http-proxy` [options](https://github.com/nodejitsu/node-http-proxy#option
   - [External WebSocket upgrade](#external-websocket-upgrade)
 - [Intercept and manipulate requests](#intercept-and-manipulate-requests)
 - [Intercept and manipulate responses](#intercept-and-manipulate-responses)
+- [Node.js 17+: ECONNREFUSED issue with IPv6 and localhost (#705)](#nodejs-17-econnrefused-issue-with-ipv6-and-localhost-705)
 - [Debugging](#debugging)
 - [Working examples](#working-examples)
 - [Recipes](#recipes)
@@ -140,15 +141,12 @@ const { createProxyMiddleware } = require('http-proxy-middleware');
 
 const app = express();
 
-// proxy middleware options
-/** @type {import('http-proxy-middleware/dist/types').Options} */
-const options = {
+// create the proxy
+/** @type {import('http-proxy-middleware/dist/types').RequestHandler<express.Request, express.Response>} */
+const exampleProxy = createProxyMiddleware({
   target: 'http://www.example.org/api', // target host with the same base path
   changeOrigin: true, // needed for virtual hosted sites
-};
-
-// create the proxy
-const exampleProxy = createProxyMiddleware(options);
+});
 
 // mount `exampleProxy` in web server
 app.use('/api', exampleProxy);
@@ -166,7 +164,7 @@ app.use(
     target: 'http://www.example.org/api',
     changeOrigin: true,
     pathFilter: '/api/proxy-only-this-path',
-  })
+  }),
 );
 ```
 
@@ -257,22 +255,22 @@ Re-target `option.target` for specific requests.
 // Use `host` and/or `path` to match requests. First match will be used.
 // The order of the configuration matters.
 router: {
-    'integration.localhost:3000' : 'http://localhost:8001',  // host only
-    'staging.localhost:3000'     : 'http://localhost:8002',  // host only
-    'localhost:3000/api'         : 'http://localhost:8003',  // host + path
-    '/rest'                      : 'http://localhost:8004'   // path only
+    'integration.localhost:3000' : 'http://127.0.0.1:8001',  // host only
+    'staging.localhost:3000'     : 'http://127.0.0.1:8002',  // host only
+    'localhost:3000/api'         : 'http://127.0.0.1:8003',  // host + path
+    '/rest'                      : 'http://127.0.0.1:8004'   // path only
 }
 
 // Custom router function (string target)
 router: function(req) {
-    return 'http://localhost:8004';
+    return 'http://127.0.0.1:8004';
 }
 
 // Custom router function (target object)
 router: function(req) {
     return {
         protocol: 'https:', // The : is required
-        host: 'localhost',
+        host: '127.0.0.1',
         port: 8004
     };
 }
@@ -488,10 +486,10 @@ The following options are provided by the underlying [http-proxy](https://github
       req,
       res,
       {
-        target: 'http://localhost:4003/',
+        target: 'http://127.0.0.1:4003/',
         buffer: streamify(req.rawBody),
       },
-      next
+      next,
     );
   };
   ```
@@ -573,6 +571,21 @@ const proxy = createProxyMiddleware({
 
 Check out [interception recipes](https://github.com/chimurai/http-proxy-middleware/blob/master/recipes/response-interceptor.md#readme) for more examples.
 
+## Node.js 17+: ECONNREFUSED issue with IPv6 and localhost ([#705](https://github.com/chimurai/http-proxy-middleware/issues/705))
+
+Node.js 17+ no longer prefers IPv4 over IPv6 for DNS lookups.
+E.g. It's **not** guaranteed that `localhost` will be resolved to `127.0.0.1` – it might just as well be `::1` (or some other IP address).
+
+If your target server only accepts IPv4 connections, trying to proxy to `localhost` will fail if resolved to `::1` (IPv6).
+
+Ways to solve it:
+
+- Change `target: "http://localhost"` to `target: "http://127.0.0.1"` (IPv4).
+- Change the target server to (also) accept IPv6 connections.
+- Add this flag when running `node`: `node index.js --dns-result-order=ipv4first`. (Not recommended.)
+
+> Note: There’s a thing called [Happy Eyeballs](https://en.wikipedia.org/wiki/Happy_Eyeballs) which means connecting to both IPv4 and IPv6 in parallel, which Node.js doesn’t have, but explains why for example `curl` can connect.
+
 ## Debugging
 
 Configure the `DEBUG` environment variable enable debug logging.

package/dist/configuration.d.ts

@@ -1,2 +1,2 @@
 import { Options } from './types';
-export declare function verifyConfig(options: Options): void;
+export declare function verifyConfig<TReq, TRes>(options: Options<TReq, TRes>): void;

package/dist/errors.js

@@ -7,4 +7,4 @@ var ERRORS;
     ERRORS["ERR_CONTEXT_MATCHER_GENERIC"] = "[HPM] Invalid context. Expecting something like: \"/api\" or [\"/api\", \"/ajax\"]";
     ERRORS["ERR_CONTEXT_MATCHER_INVALID_ARRAY"] = "[HPM] Invalid pathFilter. Expecting something like: [\"/api\", \"/ajax\"] or [\"/api/**\", \"!**.html\"]";
     ERRORS["ERR_PATH_REWRITER_CONFIG"] = "[HPM] Invalid pathRewrite config. Expecting object with pathRewrite config or a rewrite function";
-})(ERRORS = exports.ERRORS || (exports.ERRORS = {}));
+})(ERRORS || (exports.ERRORS = ERRORS = {}));

package/dist/get-plugins.d.ts

@@ -1,2 +1,2 @@
 import type { Options, Plugin } from './types';
-export declare function getPlugins(options: Options): Plugin[];
+export declare function getPlugins<TReq, TRes>(options: Options<TReq, TRes>): Plugin<TReq, TRes>[];

package/dist/get-plugins.js

@@ -3,13 +3,12 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.getPlugins = void 0;
 const default_1 = require("./plugins/default");
 function getPlugins(options) {
-    var _a, _b;
     // don't load default errorResponsePlugin if user has specified their own
-    const maybeErrorResponsePlugin = !!((_a = options.on) === null || _a === void 0 ? void 0 : _a.error) ? [] : [default_1.errorResponsePlugin];
+    const maybeErrorResponsePlugin = !!options.on?.error ? [] : [default_1.errorResponsePlugin];
     const defaultPlugins = !!options.ejectPlugins
         ? [] // no default plugins when ejecting
         : [default_1.debugProxyErrorsPlugin, default_1.proxyEventsPlugin, default_1.loggerPlugin, ...maybeErrorResponsePlugin];
-    const userPlugins = (_b = options.plugins) !== null && _b !== void 0 ? _b : [];
+    const userPlugins = options.plugins ?? [];
     return [...defaultPlugins, ...userPlugins];
 }
 exports.getPlugins = getPlugins;

package/dist/handlers/fix-request-body.d.ts

@@ -1,7 +1,9 @@
 /// <reference types="node" />
 import type * as http from 'http';
-import type { Request } from '../types';
+export type BodyParserLikeRequest = http.IncomingMessage & {
+    body: any;
+};
 /**
  * Fix proxied body if bodyParser is involved.
  */
-export declare function fixRequestBody(proxyReq: http.ClientRequest, req: Request): void;
+export declare function fixRequestBody<TReq = http.IncomingMessage>(proxyReq: http.ClientRequest, req: TReq): void;

package/dist/handlers/response-interceptor.d.ts

@@ -1,6 +1,7 @@
 /// <reference types="node" />
+/// <reference types="node" />
 import type * as http from 'http';
-declare type Interceptor = (buffer: Buffer, proxyRes: http.IncomingMessage, req: http.IncomingMessage, res: http.ServerResponse) => Promise<Buffer | string>;
+type Interceptor<TReq = http.IncomingMessage, TRes = http.ServerResponse> = (buffer: Buffer, proxyRes: TReq, req: TReq, res: TRes) => Promise<Buffer | string>;
 /**
  * Intercept responses from upstream.
  * Automatically decompress (deflate, gzip, brotli).
@@ -8,5 +9,5 @@ declare type Interceptor = (buffer: Buffer, proxyRes: http.IncomingMessage, req:
  *
  * NOTE: must set options.selfHandleResponse=true (prevent automatic call of res.end())
  */
-export declare function responseInterceptor(interceptor: Interceptor): (proxyRes: http.IncomingMessage, req: http.IncomingMessage, res: http.ServerResponse) => Promise<void>;
+export declare function responseInterceptor<TReq extends http.IncomingMessage = http.IncomingMessage, TRes extends http.ServerResponse = http.ServerResponse>(interceptor: Interceptor<TReq, TRes>): (proxyRes: TReq, req: TReq, res: TRes) => Promise<void>;
 export {};

package/dist/http-proxy-middleware.d.ts

@@ -1,11 +1,11 @@
 import type { RequestHandler, Options } from './types';
-export declare class HttpProxyMiddleware {
+export declare class HttpProxyMiddleware<TReq, TRes> {
     private wsInternalSubscribed;
     private serverOnCloseSubscribed;
     private proxyOptions;
     private proxy;
     private pathRewriter;
-    constructor(options: Options);
+    constructor(options: Options<TReq, TRes>);
     middleware: RequestHandler;
     private registerPlugins;
     private catchUpgradeRequest;

package/dist/http-proxy-middleware.js

@@ -14,8 +14,7 @@ class HttpProxyMiddleware {
         this.wsInternalSubscribed = false;
         this.serverOnCloseSubscribed = false;
         // https://github.com/Microsoft/TypeScript/wiki/'this'-in-TypeScript#red-flags-for-this
-        this.middleware = async (req, res, next) => {
-            var _a, _b;
+        this.middleware = (async (req, res, next) => {
             if (this.shouldProxy(this.proxyOptions.pathFilter, req)) {
                 try {
                     const activeProxyOptions = await this.prepareProxyRequest(req);
@@ -37,7 +36,7 @@ class HttpProxyMiddleware {
              * req.socket: node >= 13
              * req.connection: node < 13 (Remove this when node 12/13 support is dropped)
              */
-            const server = (_b = (((_a = req.socket) !== null && _a !== void 0 ? _a : req.connection))) === null || _b === void 0 ? void 0 : _b.server;
+            const server = (req.socket ?? req.connection)?.server;
             if (server && !this.serverOnCloseSubscribed) {
                 server.on('close', () => {
                     (0, debug_1.Debug)('server close signal received: closing proxy server');
@@ -49,7 +48,7 @@ class HttpProxyMiddleware {
                 // use initial request to access the server object to subscribe to http upgrade event
                 this.catchUpgradeRequest(server);
             }
-        };
+        });
         this.catchUpgradeRequest = (server) => {
             if (!this.wsInternalSubscribed) {
                 (0, debug_1.Debug)('subscribing to server upgrade event');

package/dist/index.d.ts

@@ -1,5 +1,7 @@
-import type { Options, RequestHandler } from './types';
-export declare function createProxyMiddleware(options: Options): RequestHandler;
+/// <reference types="node" />
+import type { Options, RequestHandler, NextFunction } from './types';
+import type * as http from 'http';
+export declare function createProxyMiddleware<TReq = http.IncomingMessage, TRes = http.ServerResponse, TNext = NextFunction>(options: Options<TReq, TRes>): RequestHandler<TReq, TRes, TNext>;
 export * from './handlers';
 export type { Filter, Options, RequestHandler } from './types';
 /**

package/dist/legacy/create-proxy-middleware.d.ts

@@ -1,11 +1,13 @@
+/// <reference types="node" />
 import { Filter, RequestHandler } from '../types';
 import { LegacyOptions } from './types';
+import type * as http from 'http';
 /**
  * @deprecated
  * This function is deprecated and will be removed in a future version.
  *
  * Use {@link createProxyMiddleware} instead.
  */
-export declare function legacyCreateProxyMiddleware(shortHand: string): RequestHandler;
-export declare function legacyCreateProxyMiddleware(legacyOptions: LegacyOptions): RequestHandler;
-export declare function legacyCreateProxyMiddleware(legacyContext: Filter, legacyOptions: LegacyOptions): RequestHandler;
+export declare function legacyCreateProxyMiddleware<TReq = http.IncomingMessage, TRes = http.ServerResponse>(shortHand: string): RequestHandler<TReq, TRes>;
+export declare function legacyCreateProxyMiddleware<TReq = http.IncomingMessage, TRes = http.ServerResponse>(legacyOptions: LegacyOptions<TReq, TRes>): RequestHandler<TReq, TRes>;
+export declare function legacyCreateProxyMiddleware<TReq = http.IncomingMessage, TRes = http.ServerResponse>(legacyContext: Filter<TReq>, legacyOptions: LegacyOptions<TReq, TRes>): RequestHandler<TReq, TRes>;

package/dist/legacy/options-adapter.d.ts

@@ -3,4 +3,4 @@ import { LegacyOptions } from './types';
 /**
  * Convert {@link LegacyOptions legacy Options} to new {@link Options}
  */
-export declare function legacyOptionsAdapter(legacyContext: Filter | LegacyOptions, legacyOptions: LegacyOptions): Options;
+export declare function legacyOptionsAdapter<TReq, TRes>(legacyContext: Filter<TReq> | LegacyOptions<TReq, TRes>, legacyOptions: LegacyOptions<TReq, TRes>): Options<TReq, TRes>;

package/dist/legacy/options-adapter.js

@@ -18,12 +18,15 @@ const proxyEventMap = {
  * Convert {@link LegacyOptions legacy Options} to new {@link Options}
  */
 function legacyOptionsAdapter(legacyContext, legacyOptions) {
-    let options;
+    let options = {};
     let logger;
     // https://github.com/chimurai/http-proxy-middleware/pull/716
     if (typeof legacyContext === 'string' && !!url.parse(legacyContext).host) {
         throw new Error(`Shorthand syntax is removed from legacyCreateProxyMiddleware().
-      Please use "legacyCreateProxyMiddleware({ target: 'http://www.example.org' })" instead.`);
+      Please use "legacyCreateProxyMiddleware({ target: 'http://www.example.org' })" instead.
+
+      More details: https://github.com/chimurai/http-proxy-middleware/blob/master/MIGRATION.md#removed-shorthand-usage
+      `);
     }
     // detect old "context" argument and convert to "options.pathFilter"
     // https://github.com/chimurai/http-proxy-middleware/pull/722/files#diff-a2a171449d862fe29692ce031981047d7ab755ae7f84c707aef80701b3ea0c80L4
@@ -37,13 +40,16 @@ function legacyOptionsAdapter(legacyContext, legacyOptions) {
         pathFilter: '${legacyContext}',
       }
 
-      More details: https://github.com/chimurai/http-proxy-middleware/blob/master/MIGRATION.md
+      More details: https://github.com/chimurai/http-proxy-middleware/blob/master/MIGRATION.md#removed-context-argument
       `);
     }
     else if (legacyContext && !legacyOptions) {
         options = { ...legacyContext };
         logger = getLegacyLogger(options);
     }
+    else {
+        logger = getLegacyLogger({});
+    }
     // map old event names to new event names
     // https://github.com/chimurai/http-proxy-middleware/pull/745/files#diff-c54113cf61ec99691748a3890bfbeb00e10efb3f0a76f03a0fd9ec49072e410aL48-L53
     Object.entries(proxyEventMap).forEach(([legacyEventName, proxyEventName]) => {
@@ -59,7 +65,7 @@ function legacyOptionsAdapter(legacyContext, legacyOptions) {
           },
         }
 
-        More details: https://github.com/chimurai/http-proxy-middleware/blob/master/MIGRATION.md
+        More details: https://github.com/chimurai/http-proxy-middleware/blob/master/MIGRATION.md#refactored-proxy-events
         `);
         }
     });
@@ -77,7 +83,7 @@ function legacyOptionsAdapter(legacyContext, legacyOptions) {
         logger: console,
       }
 
-      More details: https://github.com/chimurai/http-proxy-middleware/blob/master/MIGRATION.md
+      More details: https://github.com/chimurai/http-proxy-middleware/blob/master/MIGRATION.md#removed-logprovider-and-loglevel-options
       `);
     }
     return options;

package/dist/legacy/types.d.ts

@@ -1,10 +1,12 @@
+/// <reference types="node" />
+import type * as http from 'http';
 import { Options } from '..';
 /**
  * @deprecated
  *
  * Will be removed in a future version.
  */
-export interface LegacyOptions extends Options {
+export interface LegacyOptions<TReq = http.IncomingMessage, TRes = http.ServerResponse> extends Options<TReq, TRes> {
     /**
      * @deprecated
      * Use `on.error` instead.

package/dist/path-filter.d.ts

@@ -1,2 +1,4 @@
-import type { Filter, Request } from './types';
-export declare function matchPathFilter(pathFilter: Filter, uri: string, req: Request): boolean;
+/// <reference types="node" />
+import type { Filter } from './types';
+import type * as http from 'http';
+export declare function matchPathFilter<TReq = http.IncomingMessage>(pathFilter: Filter<TReq> | undefined, uri: string | undefined, req: http.IncomingMessage): boolean;

package/dist/path-filter.js

@@ -39,7 +39,7 @@ exports.matchPathFilter = matchPathFilter;
  */
 function matchSingleStringPath(pathFilter, uri) {
     const pathname = getUrlPathName(uri);
-    return pathname.indexOf(pathFilter) === 0;
+    return pathname?.indexOf(pathFilter) === 0;
 }
 function matchSingleGlobPath(pattern, uri) {
     const pathname = getUrlPathName(uri);

package/dist/plugins/default/error-response-plugin.js

@@ -8,7 +8,7 @@ const errorResponsePlugin = (proxyServer, options) => {
         if (!req && !res) {
             throw err; // "Error: Must provide a proper URL as target"
         }
-        if (res.writeHead && !res.headersSent) {
+        if ('writeHead' in res && !res.headersSent) {
             const statusCode = (0, status_code_1.getStatusCode)(err.code);
             res.writeHead(statusCode);
         }

package/dist/plugins/default/logger-plugin.js

@@ -5,10 +5,9 @@ const logger_1 = require("../../logger");
 const loggerPlugin = (proxyServer, options) => {
     const logger = (0, logger_1.getLogger)(options);
     proxyServer.on('error', (err, req, res, target) => {
-        var _a;
-        const hostname = (_a = req === null || req === void 0 ? void 0 : req.headers) === null || _a === void 0 ? void 0 : _a.host;
-        const requestHref = `${hostname}${req === null || req === void 0 ? void 0 : req.url}`;
-        const targetHref = `${target === null || target === void 0 ? void 0 : target.href}`; // target is undefined when websocket errors
+        const hostname = req?.headers?.host;
+        const requestHref = `${hostname}${req?.url}`;
+        const targetHref = `${target?.href}`; // target is undefined when websocket errors
         const errorMessage = '[HPM] Error occurred while proxying request %s to %s [%s] (%s)';
         const errReference = 'https://nodejs.org/api/errors.html#errors_common_system_errors'; // link to Node Common Systems Errors page
         logger.error(errorMessage, requestHref, targetHref, err.code || err, errReference);
@@ -21,9 +20,9 @@ const loggerPlugin = (proxyServer, options) => {
      * ```
      */
     proxyServer.on('proxyRes', (proxyRes, req, res) => {
-        var _a;
         // BrowserSync uses req.originalUrl
-        const originalUrl = (_a = req.originalUrl) !== null && _a !== void 0 ? _a : `${req.baseUrl}${req.path}`;
+        // Next.js doesn't have req.baseUrl
+        const originalUrl = req.originalUrl ?? `${req.baseUrl || ''}${req.url}`;
         const exchange = `[HPM] ${req.method} ${originalUrl} -> ${proxyRes.req.protocol}//${proxyRes.req.host}${proxyRes.req.path} [${proxyRes.statusCode}]`;
         logger.info(exchange);
     });

package/dist/types.d.ts

@@ -3,40 +3,57 @@
  * https://github.com/DefinitelyTyped/DefinitelyTyped/blob/6f529c6c67a447190f86bfbf894d1061e41e07b7/types/http-proxy-middleware/index.d.ts
  */
 /// <reference types="node" />
+/// <reference types="node" />
+/// <reference types="node" />
+/// <reference types="node" />
 import type * as http from 'http';
 import type * as httpProxy from 'http-proxy';
 import type * as net from 'net';
-export declare type Request<T = http.IncomingMessage> = T;
-export declare type Response<T = http.ServerResponse> = T;
-export declare type NextFunction<T = (err?: any) => void> = T;
-export interface RequestHandler {
-    (req: Request, res: Response, next?: NextFunction): void | Promise<void>;
-    upgrade?: (req: Request, socket: net.Socket, head: any) => void;
+export type NextFunction<T = (err?: any) => void> = T;
+export interface RequestHandler<TReq = http.IncomingMessage, TRes = http.ServerResponse, TNext = NextFunction> {
+    (req: TReq, res: TRes, next?: TNext): void | Promise<void>;
+    upgrade: (req: http.IncomingMessage, socket: net.Socket, head: Buffer) => void;
+}
+export type Filter<TReq = http.IncomingMessage> = string | string[] | ((pathname: string, req: TReq) => boolean);
+export interface Plugin<TReq = http.IncomingMessage, TRes = http.ServerResponse> {
+    (proxyServer: httpProxy<TReq, TRes>, options: Options<TReq, TRes>): void;
 }
-export declare type Filter = string | string[] | ((pathname: string, req: Request) => boolean);
-export declare type Plugin = (proxyServer: httpProxy, options: Options) => void;
-export declare type OnProxyEvent = {
-    error?: httpProxy.ErrorCallback;
-    proxyReq?: httpProxy.ProxyReqCallback;
-    proxyReqWs?: httpProxy.ProxyReqWsCallback;
-    proxyRes?: httpProxy.ProxyResCallback;
+export interface OnProxyEvent<TReq = http.IncomingMessage, TRes = http.ServerResponse> {
+    error?: httpProxy.ErrorCallback<Error, TReq, TRes>;
+    proxyReq?: httpProxy.ProxyReqCallback<http.ClientRequest, TReq, TRes>;
+    proxyReqWs?: httpProxy.ProxyReqWsCallback<http.ClientRequest, TReq>;
+    proxyRes?: httpProxy.ProxyResCallback<TReq, TRes>;
     open?: httpProxy.OpenCallback;
-    close?: httpProxy.CloseCallback;
-    start?: httpProxy.StartCallback;
-    end?: httpProxy.EndCallback;
-    econnreset?: httpProxy.EconnresetCallback;
-};
-export declare type Logger = Pick<Console, 'info' | 'warn' | 'error'>;
-export interface Options extends httpProxy.ServerOptions {
+    close?: httpProxy.CloseCallback<TReq>;
+    start?: httpProxy.StartCallback<TReq, TRes>;
+    end?: httpProxy.EndCallback<TReq, TRes>;
+    econnreset?: httpProxy.EconnresetCallback<Error, TReq, TRes>;
+}
+export type Logger = Pick<Console, 'info' | 'warn' | 'error'>;
+export interface Options<TReq = http.IncomingMessage, TRes = http.ServerResponse> extends httpProxy.ServerOptions {
     /**
      * Narrow down requests to proxy or not.
      * Filter on {@link http.IncomingMessage.url `pathname`} which is relative to the proxy's "mounting" point in the server.
      * Or use the {@link http.IncomingMessage `req`}  object for more complex filtering.
+     * @link https://github.com/chimurai/http-proxy-middleware/blob/master/recipes/pathFilter.md
+     * @since v3.0.0
+     */
+    pathFilter?: Filter<TReq>;
+    /**
+     * Modify request paths before requests are send to the target.
+     * @example
+     * ```js
+     * createProxyMiddleware({
+     *   pathRewrite: {
+     *     '^/api/old-path': '/api/new-path', // rewrite path
+     *   }
+     * });
+     * ```
+     * @link https://github.com/chimurai/http-proxy-middleware/blob/master/recipes/pathRewrite.md
      */
-    pathFilter?: Filter;
     pathRewrite?: {
         [regexp: string]: string;
-    } | ((path: string, req: Request) => string) | ((path: string, req: Request) => Promise<string>);
+    } | ((path: string, req: TReq) => string | undefined) | ((path: string, req: TReq) => Promise<string>);
     /**
      * Access the internal http-proxy server instance to customize behavior
      *
@@ -50,12 +67,15 @@ export interface Options extends httpProxy.ServerOptions {
      *   }]
      * });
      * ```
+     * @link https://github.com/chimurai/http-proxy-middleware#plugins-array
+     * @since v3.0.0
      */
-    plugins?: Plugin[];
+    plugins?: Plugin<TReq, TRes>[];
     /**
      * Eject pre-configured plugins.
      * NOTE: register your own error handlers to prevent server from crashing.
      *
+     * @link https://github.com/chimurai/http-proxy-middleware#ejectplugins-boolean-default-false
      * @since v3.0.0
      */
     ejectPlugins?: boolean;
@@ -72,11 +92,25 @@ export interface Options extends httpProxy.ServerOptions {
      *   }
      * });
      * ```
+     * @link https://github.com/chimurai/http-proxy-middleware/blob/master/recipes/proxy-events.md
+     * @since v3.0.0
+     */
+    on?: OnProxyEvent<TReq, TRes>;
+    /**
+     * Dynamically set the {@link Options.target `options.target`}.
+     * @example
+     * ```js
+     * createProxyMiddleware({
+     *   router: async (req) => {
+     *     return 'http://127:0.0.1:3000';
+     *   }
+     * });
+     * ```
+     * @link https://github.com/chimurai/http-proxy-middleware/blob/master/recipes/router.md
      */
-    on?: OnProxyEvent;
     router?: {
         [hostOrPath: string]: httpProxy.ServerOptions['target'];
-    } | ((req: Request) => httpProxy.ServerOptions['target']) | ((req: Request) => Promise<httpProxy.ServerOptions['target']>);
+    } | ((req: TReq) => httpProxy.ServerOptions['target']) | ((req: TReq) => Promise<httpProxy.ServerOptions['target']>);
     /**
      * Log information from http-proxy-middleware
      * @example
@@ -85,6 +119,8 @@ export interface Options extends httpProxy.ServerOptions {
      *  logger: console
      * });
      * ```
+     * @link https://github.com/chimurai/http-proxy-middleware/blob/master/recipes/logger.md
+     * @since v3.0.0
      */
     logger?: Logger | any;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "http-proxy-middleware",
-  "version": "3.0.0-beta.0",
+  "version": "3.0.0",
   "description": "The one-liner node.js proxy middleware for connect, express, next.js and more",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -8,21 +8,18 @@
     "dist"
   ],
   "scripts": {
-    "clean": "rm -rf dist && rm -rf coverage",
+    "clean": "rm -rf dist coverage tsconfig.tsbuildinfo .eslintcache",
     "lint": "yarn prettier && yarn eslint",
     "lint:fix": "yarn prettier:fix && yarn eslint:fix",
-    "eslint": "eslint '{src,test}/**/*.ts'",
+    "eslint": "eslint '{src,test}/**/*.ts' --cache",
     "eslint:fix": "yarn eslint --fix",
     "prettier": "prettier --list-different \"**/*.{js,ts,md,yml,json,html}\"",
     "prettier:fix": "prettier --write \"**/*.{js,ts,md,yml,json,html}\"",
-    "prebuild": "yarn clean",
-    "build": "tsc",
-    "pretest": "yarn build",
+    "build": "tsc --build",
     "test": "jest",
-    "precoverage": "yarn build",
-    "coverage": "jest --coverage --coverageReporters=lcov",
-    "prepare": "husky install",
-    "prepack": "yarn build && rm dist/tsconfig.tsbuildinfo",
+    "coverage": "jest --coverage",
+    "prepare": "husky",
+    "prepack": "yarn clean && yarn test && yarn build",
     "spellcheck": "npx --yes cspell --show-context --show-suggestions '**/*.*'"
   },
   "repository": {
@@ -54,58 +51,47 @@
   },
   "homepage": "https://github.com/chimurai/http-proxy-middleware#readme",
   "devDependencies": {
-    "@commitlint/cli": "16.2.3",
-    "@commitlint/config-conventional": "16.2.1",
-    "@types/debug": "4.1.7",
-    "@types/express": "4.17.13",
-    "@types/is-glob": "4.0.2",
-    "@types/jest": "27.4.1",
-    "@types/micromatch": "4.0.2",
-    "@types/node": "17.0.25",
+    "@commitlint/cli": "17.7.1",
+    "@commitlint/config-conventional": "17.7.0",
+    "@types/debug": "4.1.12",
+    "@types/express": "4.17.21",
+    "@types/is-glob": "4.0.4",
+    "@types/jest": "29.5.12",
+    "@types/micromatch": "4.0.6",
+    "@types/node": "20.11.30",
     "@types/supertest": "2.0.12",
-    "@types/ws": "8.5.3",
-    "@typescript-eslint/eslint-plugin": "5.20.0",
-    "@typescript-eslint/parser": "5.20.0",
-    "body-parser": "1.20.0",
-    "browser-sync": "2.27.9",
+    "@types/ws": "8.5.10",
+    "@typescript-eslint/eslint-plugin": "7.4.0",
+    "@typescript-eslint/parser": "7.4.0",
+    "body-parser": "1.20.2",
+    "browser-sync": "3.0.2",
     "connect": "3.7.0",
-    "eslint": "8.13.0",
-    "eslint-config-prettier": "8.5.0",
-    "eslint-plugin-prettier": "4.0.0",
-    "express": "4.17.3",
+    "eslint": "8.57.0",
+    "eslint-config-prettier": "9.1.0",
+    "eslint-plugin-prettier": "5.1.3",
+    "express": "4.19.2",
     "get-port": "5.1.1",
-    "husky": "7.0.4",
-    "jest": "27.5.1",
-    "lint-staged": "12.3.8",
-    "mockttp": "2.7.0",
-    "open": "8.4.0",
-    "prettier": "2.6.2",
-    "supertest": "6.2.2",
-    "ts-jest": "27.1.4",
-    "typescript": "4.6.3",
-    "ws": "8.5.0"
+    "husky": "9.0.11",
+    "jest": "29.7.0",
+    "lint-staged": "15.2.2",
+    "mockttp": "3.10.1",
+    "open": "8.4.2",
+    "prettier": "3.2.5",
+    "supertest": "6.3.4",
+    "ts-jest": "29.1.2",
+    "typescript": "5.4.3",
+    "ws": "8.16.0"
   },
   "dependencies": {
-    "@types/http-proxy": "^1.17.8",
+    "@types/http-proxy": "^1.17.10",
     "debug": "^4.3.4",
     "http-proxy": "^1.18.1",
     "is-glob": "^4.0.1",
     "is-plain-obj": "^3.0.0",
     "micromatch": "^4.0.5"
   },
-  "peerDependencies": {
-    "@types/express": "^4.17.13"
-  },
-  "peerDependenciesMeta": {
-    "@types/express": {
-      "optional": true
-    }
-  },
-  "resolutions": {
-    "browser-sync/portscanner": "2.2.0"
-  },
   "engines": {
-    "node": ">=12.0.0"
+    "node": "^14.15.0 || ^16.10.0 || >=18.0.0"
   },
   "commitlint": {
     "extends": [