Legacy API

/**
 * @deprecated This function is deprecated and will be removed in a future version.
 * Use {@link createProxyMiddleware} instead.
 * 
 * Legacy factory function supporting v2.x API patterns
 */
function legacyCreateProxyMiddleware<
  TReq = http.IncomingMessage,
  TRes = http.ServerResponse,
>(shortHand: string): RequestHandler<TReq, TRes>;

function legacyCreateProxyMiddleware<
  TReq = http.IncomingMessage,
  TRes = http.ServerResponse,
>(legacyOptions: LegacyOptions<TReq, TRes>): RequestHandler<TReq, TRes>;

function legacyCreateProxyMiddleware<
  TReq = http.IncomingMessage,
  TRes = http.ServerResponse,
>(
  legacyContext: Filter<TReq>,
  legacyOptions: LegacyOptions<TReq, TRes>,
): RequestHandler<TReq, TRes>;

// ❌ DEPRECATED v2.x patterns
import { legacyCreateProxyMiddleware } from "http-proxy-middleware";

// v2.x shorthand
const legacyProxy1 = legacyCreateProxyMiddleware("http://api.example.com");

// v2.x context + options
const legacyProxy2 = legacyCreateProxyMiddleware("/api", {
  target: "http://api.example.com",
  changeOrigin: true,
});

// v2.x options object
const legacyProxy3 = legacyCreateProxyMiddleware({
  context: "/api",
  target: "http://api.example.com",
  changeOrigin: true,
});

// ✅ RECOMMENDED v3.x patterns
import { createProxyMiddleware } from "http-proxy-middleware";

// v3.x equivalent of shorthand
const modernProxy1 = createProxyMiddleware({
  target: "http://api.example.com",
});

// v3.x equivalent of context + options
const modernProxy2 = createProxyMiddleware({
  target: "http://api.example.com",
  pathFilter: "/api",
  changeOrigin: true,
});

// v3.x equivalent of options with context
const modernProxy3 = createProxyMiddleware({
  pathFilter: "/api",
  target: "http://api.example.com", 
  changeOrigin: true,
});

/**
 * Legacy options interface for backward compatibility
 * Extends modern Options while supporting deprecated v2.x patterns
 */
interface LegacyOptions<TReq = http.IncomingMessage, TRes = http.ServerResponse>
  extends Partial<Options<TReq, TRes>> {
  
  /**
   * @deprecated Use pathFilter instead
   * Legacy context filter for determining which requests to proxy
   */
  context?: Filter<TReq>;
  
  /**
   * @deprecated Use pathRewrite instead  
   * Legacy path rewriting configuration
   */
  pathRewrite?: LegacyPathRewrite<TReq>;
  
  /**
   * @deprecated Use on.error instead
   * Legacy error handler
   */
  onError?: (err: Error, req: TReq, res: TRes, target?: string) => void;
  
  /**
   * @deprecated Use on.proxyReq instead
   * Legacy proxy request handler
   */
  onProxyReq?: (proxyReq: http.ClientRequest, req: TReq, res: TRes) => void;
  
  /**
   * @deprecated Use on.proxyRes instead
   * Legacy proxy response handler
   */
  onProxyRes?: (proxyRes: http.IncomingMessage, req: TReq, res: TRes) => void;
  
  /**
   * @deprecated Use logger instead
   * Legacy logging flag
   */
  logLevel?: "debug" | "info" | "warn" | "error" | "silent";
  
  /**
   * @deprecated Configure via plugins instead
   * Legacy logging provider
   */
  logProvider?: (provider: any) => any;
}

/**
 * @deprecated Use pathRewrite from modern Options instead
 */
type LegacyPathRewrite<TReq> = 
  | { [regexp: string]: string }
  | ((path: string, req: TReq) => string);

// ❌ DEPRECATED v2.x options structure
const legacyOptionsProxy = legacyCreateProxyMiddleware({
  context: "/api/**",
  target: "http://api.example.com",
  changeOrigin: true,
  logLevel: "info",
  pathRewrite: {
    "^/api": "",
  },
  onError: (err, req, res, target) => {
    console.error("Legacy error:", err);
  },
  onProxyReq: (proxyReq, req, res) => {
    console.log("Legacy proxy request");
  },
  onProxyRes: (proxyRes, req, res) => {
    console.log("Legacy proxy response");
  },
});

// ✅ RECOMMENDED v3.x equivalent
const modernOptionsProxy = createProxyMiddleware({
  pathFilter: "/api/**",
  target: "http://api.example.com",
  changeOrigin: true,
  logger: console,
  pathRewrite: {
    "^/api": "",
  },
  on: {
    error: (err, req, res, target) => {
      console.error("Modern error:", err);
    },
    proxyReq: (proxyReq, req, res) => {
      console.log("Modern proxy request");
    },
    proxyRes: (proxyRes, req, res) => {
      console.log("Modern proxy response");
    },
  },
});

// Step 1: Replace legacyCreateProxyMiddleware with createProxyMiddleware
// ❌ Before
import { legacyCreateProxyMiddleware } from "http-proxy-middleware";
// ✅ After  
import { createProxyMiddleware } from "http-proxy-middleware";

// Step 2: Move context parameter to pathFilter option
// ❌ Before
const proxy = legacyCreateProxyMiddleware("/api", { target: "http://api.example.com" });
// ✅ After
const proxy = createProxyMiddleware({ pathFilter: "/api", target: "http://api.example.com" });

// Step 3: Move context option to pathFilter
// ❌ Before
const proxy = legacyCreateProxyMiddleware({ context: "/api", target: "http://api.example.com" });
// ✅ After
const proxy = createProxyMiddleware({ pathFilter: "/api", target: "http://api.example.com" });

// Step 4: Move event handlers to 'on' object
// ❌ Before
const proxy = legacyCreateProxyMiddleware({
  target: "http://api.example.com",
  onError: (err, req, res, target) => { /* handler */ },
  onProxyReq: (proxyReq, req, res) => { /* handler */ },
  onProxyRes: (proxyRes, req, res) => { /* handler */ },
});

// ✅ After
const proxy = createProxyMiddleware({
  target: "http://api.example.com",
  on: {
    error: (err, req, res, target) => { /* handler */ },
    proxyReq: (proxyReq, req, res) => { /* handler */ },
    proxyRes: (proxyRes, req, res) => { /* handler */ },
  },
});

// Step 5: Replace logging configuration
// ❌ Before
const proxy = legacyCreateProxyMiddleware({
  target: "http://api.example.com",
  logLevel: "info",
  logProvider: customLogProvider,
});

// ✅ After
const proxy = createProxyMiddleware({
  target: "http://api.example.com",
  logger: console, // or custom logger object
});

// Legacy behavior: Automatic req.url patching for certain middleware combinations
// The legacy API includes special handling for req.url modification compatibility

// ❌ Legacy behavior (automatic)
const legacyProxy = legacyCreateProxyMiddleware("/api", {
  target: "http://api.example.com",
  // Automatically patches req.url in certain scenarios
});

// ✅ Modern explicit control
const modernProxy = createProxyMiddleware({
  pathFilter: "/api",
  target: "http://api.example.com",
  // Explicit control over URL handling via pathRewrite if needed
  pathRewrite: (path, req) => {
    // Custom URL manipulation logic
    return path;
  },
});

// Legacy API includes all default plugins automatically
// Modern API allows ejecting plugins for more control

// Legacy (automatic plugins)
const legacyProxy = legacyCreateProxyMiddleware({
  target: "http://api.example.com",
  // All default plugins included automatically
});

// Modern (explicit plugin control)
const modernProxy = createProxyMiddleware({
  target: "http://api.example.com",
  ejectPlugins: true, // Disable defaults if needed
  plugins: [
    // Custom plugins only
    customPlugin,
  ],
});

// Using legacy API will produce console warnings:
// "Warning: legacyCreateProxyMiddleware is deprecated. Use createProxyMiddleware instead."
// "Warning: options.context is deprecated. Use options.pathFilter instead."
// "Warning: options.onError is deprecated. Use options.on.error instead."

// Disable warnings (not recommended for production)
process.env.HPM_SUPPRESS_WARNINGS = "true";

// Better approach: Migrate to modern API
const modernProxy = createProxyMiddleware({
  // Modern configuration
});

import express from "express";

// ❌ Legacy Express integration
app.use("/api", legacyCreateProxyMiddleware({
  target: "http://api.example.com",
  changeOrigin: true,
  context: "/api",
  pathRewrite: { "^/api": "" },
}));

// ✅ Modern Express integration
app.use("/api", createProxyMiddleware({
  target: "http://api.example.com",
  changeOrigin: true,
  pathFilter: "/api",
  pathRewrite: { "^/api": "" },
}));

// ❌ Legacy development proxy
const devProxy = legacyCreateProxyMiddleware("http://localhost:3001", {
  changeOrigin: true,
  ws: true,
  logLevel: "debug",
});

// ✅ Modern development proxy
const devProxy = createProxyMiddleware({
  target: "http://localhost:3001",
  changeOrigin: true,
  ws: true,
  logger: console,
});

// ❌ Legacy error handling
const errorProxy = legacyCreateProxyMiddleware({
  target: "http://api.example.com",
  onError: (err, req, res, target) => {
    res.writeHead(500, { "Content-Type": "text/plain" });
    res.end("Proxy error: " + err.message);
  },
});

// ✅ Modern error handling
const errorProxy = createProxyMiddleware({
  target: "http://api.example.com",
  on: {
    error: (err, req, res, target) => {
      if (!res.headersSent) {
        res.writeHead(500, { "Content-Type": "application/json" });
        res.end(JSON.stringify({ error: "Proxy error", message: err.message }));
      }
    },
  },
});