feat(typescript): export http-proxy-middleware types [BREAKING CHANGE]

Author: chimurai

.prettierrc

@@ -1,4 +1,5 @@
 {
+  "printWidth": 100,
   "tabWidth": 2,
   "semi": true,
   "singleQuote": true

CHANGELOG.md

@@ -1,9 +1,15 @@
 # Changelog
 
+## next
+
+- feat(createProxyMiddleware): explicit import http-proxy-middleware (BREAKING CHANGE)([#400](https://github.com/chimurai/http-proxy-middleware/issues/400#issuecomment-587162378))
+- feat(typescript): export http-proxy-middleware types ([#400](https://github.com/chimurai/http-proxy-middleware/issues/400))
+- fix(typescript): ES6 target - TS1192 ([#400](https://github.com/chimurai/http-proxy-middleware/issues/400#issuecomment-587064349))
+
 ## [v0.21.0](https://github.com/chimurai/http-proxy-middleware/releases/tag/v0.21.0)
 
 - feat(http-proxy): bump to v1.18.0
-- feat: async router ([#379](https://github.com/chimurai/http-proxy-middleware/issues/335)) ([LiranBri](https://github.com/LiranBri))
+- feat: async router ([#379](https://github.com/chimurai/http-proxy-middleware/issues/379)) ([LiranBri](https://github.com/LiranBri))
 - feat(typescript): types support ([#369](https://github.com/chimurai/http-proxy-middleware/pull/369))
 - feat: async pathRewrite ([#397](https://github.com/chimurai/http-proxy-middleware/pull/397)) ([rsethc](https://github.com/rsethc))
 

README.md

@@ -10,20 +10,40 @@ Node.js proxying made simple. Configure proxy middleware with ease for [connect]
 
 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)
 
+## ⚠️ NOTE
+
+This page is showing documentation for version v1.x.x
+
+If you're looking for v0.x documentation. Go to:
+https://github.com/chimurai/http-proxy-middleware/tree/v0.21.0#readme
+
 ## TL;DR
 
 Proxy `/api` requests to `http://www.example.org`
 
 ```javascript
-var express = require('express');
-var proxy = require('http-proxy-middleware');
+// javascript
+
+const express = require('express');
+const { createProxyMiddleware } = require('http-proxy-middleware');
 
-var app = express();
+const app = express();
 
-app.use(
-  '/api',
-  proxy({ target: 'http://www.example.org', changeOrigin: true })
-);
+app.use('/api', createProxyMiddleware({ target: 'http://www.example.org', changeOrigin: true }));
+app.listen(3000);
+
+// http://localhost:3000/api/foo/bar -> http://www.example.org/api/foo/bar
+```
+
+```typescript
+// typescript
+
+import * as express from 'express';
+import { createProxyMiddleware, Filter, Options, RequestHandler } from 'http-proxy-middleware';
+
+const app = express();
+
+app.use('/api', createProxyMiddleware({ target: 'http://www.example.org', changeOrigin: true }));
 app.listen(3000);
 
 // http://localhost:3000/api/foo/bar -> http://www.example.org/api/foo/bar
@@ -68,15 +88,15 @@ $ npm install --save-dev http-proxy-middleware
 
 Proxy middleware configuration.
 
-#### proxy([context,] config)
+#### createProxyMiddleware([context,] config)
 
 ```javascript
-var proxy = require('http-proxy-middleware');
+const { createProxyMiddleware } = require('http-proxy-middleware');
 
-var apiProxy = proxy('/api', { target: 'http://www.example.org' });
-//                   \____/   \_____________________________/
-//                     |                    |
-//                   context             options
+const apiProxy = createProxyMiddleware('/api', { target: 'http://www.example.org' });
+//                                    \____/   \_____________________________/
+//                                      |                    |
+//                                    context             options
 
 // 'apiProxy' is now ready to be used as middleware in a server.
 ```
@@ -87,11 +107,11 @@ var apiProxy = proxy('/api', { target: 'http://www.example.org' });
 
 (full list of [`http-proxy-middleware` configuration options](#options))
 
-#### proxy(uri [, config])
+#### createProxyMiddleware(uri [, config])
 
 ```javascript
 // shorthand syntax for the example above:
-var apiProxy = proxy('http://www.example.org/api');
+const apiProxy = createProxyMiddleware('http://www.example.org/api');
 ```
 
 More about the [shorthand configuration](#shorthand).
@@ -102,11 +122,11 @@ An example with `express` server.
 
 ```javascript
 // include dependencies
-var express = require('express');
-var proxy = require('http-proxy-middleware');
+const express = require('express');
+const { createProxyMiddleware } = require('http-proxy-middleware');
 
 // proxy middleware options
-var options = {
+const options = {
   target: 'http://www.example.org', // target host
   changeOrigin: true, // needed for virtual hosted sites
   ws: true, // proxy websockets
@@ -122,10 +142,10 @@ var options = {
 };
 
 // create the proxy (without context)
-var exampleProxy = proxy(options);
+const exampleProxy = createProxyMiddleware(options);
 
 // mount `exampleProxy` in web server
-var app = express();
+const app = express();
 app.use('/api', exampleProxy);
 app.listen(3000);
 ```
@@ -145,24 +165,24 @@ Providing an alternative way to decide which requests should be proxied; In case
 
 - **path matching**
 
-  - `proxy({...})` - matches any path, all requests will be proxied.
-  - `proxy('/', {...})` - matches any path, all requests will be proxied.
-  - `proxy('/api', {...})` - matches paths starting with `/api`
+  - `createProxyMiddleware({...})` - matches any path, all requests will be proxied.
+  - `createProxyMiddleware('/', {...})` - matches any path, all requests will be proxied.
+  - `createProxyMiddleware('/api', {...})` - matches paths starting with `/api`
 
 - **multiple path matching**
 
-  - `proxy(['/api', '/ajax', '/someotherpath'], {...})`
+  - `createProxyMiddleware(['/api', '/ajax', '/someotherpath'], {...})`
 
 - **wildcard path matching**
 
   For fine-grained control you can use wildcard matching. Glob pattern matching is done by _micromatch_. Visit [micromatch](https://www.npmjs.com/package/micromatch) or [glob](https://www.npmjs.com/package/glob) for more globbing examples.
 
-  - `proxy('**', {...})` matches any path, all requests will be proxied.
-  - `proxy('**/*.html', {...})` matches any path which ends with `.html`
-  - `proxy('/*.html', {...})` matches paths directly under path-absolute
-  - `proxy('/api/**/*.html', {...})` matches requests ending with `.html` in the path of `/api`
-  - `proxy(['/api/**', '/ajax/**'], {...})` combine multiple patterns
-  - `proxy(['/api/**', '!**/bad.json'], {...})` exclusion
+  - `createProxyMiddleware('**', {...})` matches any path, all requests will be proxied.
+  - `createProxyMiddleware('**/*.html', {...})` matches any path which ends with `.html`
+  - `createProxyMiddleware('/*.html', {...})` matches paths directly under path-absolute
+  - `createProxyMiddleware('/api/**/*.html', {...})` matches requests ending with `.html` in the path of `/api`
+  - `createProxyMiddleware(['/api/**', '/ajax/**'], {...})` combine multiple patterns
+  - `createProxyMiddleware(['/api/**', '!**/bad.json'], {...})` exclusion
 
   **Note**: In multiple path matching, you cannot use string paths and wildcard paths together.
 
@@ -174,11 +194,13 @@ Providing an alternative way to decide which requests should be proxied; In case
   /**
    * @return {Boolean}
    */
-  var filter = function(pathname, req) {
+  const filter = function(pathname, req) {
     return pathname.match('^/api') && req.method === 'GET';
   };
 
-  var apiProxy = proxy(filter, { target: 'http://www.example.org' });
+  const apiProxy = createProxyMiddleware(filter, {
+    target: 'http://www.example.org'
+  });
   ```
 
 ## Options
@@ -202,7 +224,7 @@ Providing an alternative way to decide which requests should be proxied; In case
 
   // custom rewriting, returning Promise
   pathRewrite: async function (path, req) {
-    var should_add_something = await httpRequestToDecideSomething(path);
+    const should_add_something = await httpRequestToDecideSomething(path);
     if (should_add_something) path += "something";
     return path;
   }
@@ -248,9 +270,9 @@ Providing an alternative way to decide which requests should be proxied; In case
   ```javascript
   // verbose replacement
   function logProvider(provider) {
-    var logger = new (require('winston').Logger)();
+    const logger = new (require('winston').Logger)();
 
-    var myCustomProvider = {
+    const myCustomProvider = {
       log: logger.log,
       debug: logger.debug,
       info: logger.info,
@@ -272,9 +294,7 @@ Subscribe to [http-proxy events](https://github.com/nodejitsu/node-http-proxy#li
     res.writeHead(500, {
       'Content-Type': 'text/plain'
     });
-    res.end(
-      'Something went wrong. And we are reporting a custom error message.'
-    );
+    res.end('Something went wrong. And we are reporting a custom error message.');
   }
   ```
 
@@ -401,14 +421,14 @@ The following options are provided by the underlying [http-proxy](https://github
 Use the shorthand syntax when verbose configuration is not needed. The `context` and `option.target` will be automatically configured when shorthand is used. Options can still be used if needed.
 
 ```javascript
-proxy('http://www.example.org:8000/api');
-// proxy('/api', {target: 'http://www.example.org:8000'});
+createProxyMiddleware('http://www.example.org:8000/api');
+// createProxyMiddleware('/api', {target: 'http://www.example.org:8000'});
 
-proxy('http://www.example.org:8000/api/books/*/**.json');
-// proxy('/api/books/*/**.json', {target: 'http://www.example.org:8000'});
+createProxyMiddleware('http://www.example.org:8000/api/books/*/**.json');
+// createProxyMiddleware('/api/books/*/**.json', {target: 'http://www.example.org:8000'});
 
-proxy('http://www.example.org:8000/api', { changeOrigin: true });
-// proxy('/api', {target: 'http://www.example.org:8000', changeOrigin: true});
+createProxyMiddleware('http://www.example.org:8000/api', { changeOrigin: true });
+// createProxyMiddleware('/api', {target: 'http://www.example.org:8000', changeOrigin: true});
 ```
 
 ### app.use(path, proxy)
@@ -417,10 +437,7 @@ If you want to use the server's `app.use` `path` parameter to match requests;
 Create and mount the proxy without the http-proxy-middleware `context` parameter:
 
 ```javascript
-app.use(
-  '/api',
-  proxy({ target: 'http://www.example.org', changeOrigin: true })
-);
+app.use('/api', createProxyMiddleware({ target: 'http://www.example.org', changeOrigin: true }));
 ```
 
 `app.use` documentation:
@@ -433,26 +450,26 @@ app.use(
 
 ```javascript
 // verbose api
-proxy('/', { target: 'http://echo.websocket.org', ws: true });
+createProxyMiddleware('/', { target: 'http://echo.websocket.org', ws: true });
 
 // shorthand
-proxy('http://echo.websocket.org', { ws: true });
+createProxyMiddleware('http://echo.websocket.org', { ws: true });
 
 // shorter shorthand
-proxy('ws://echo.websocket.org');
+createProxyMiddleware('ws://echo.websocket.org');
 ```
 
 ### External WebSocket upgrade
 
 In the previous WebSocket examples, http-proxy-middleware relies on a initial http request in order to listen to the http `upgrade` event. If you need to proxy WebSockets without the initial http request, you can subscribe to the server's http `upgrade` event manually.
 
 ```javascript
-var wsProxy = proxy('ws://echo.websocket.org', { changeOrigin: true });
+const wsProxy = createProxyMiddleware('ws://echo.websocket.org', { changeOrigin: true });
 
-var app = express();
+const app = express();
 app.use(wsProxy);
 
-var server = app.listen(3000);
+const server = app.listen(3000);
 server.on('upgrade', wsProxy.upgrade); // <-- subscribe to http 'upgrade'
 ```
 

examples/README.md

@@ -7,7 +7,8 @@ To run and view the [examples](https://github.com/chimurai/http-proxy-middleware
 ```bash
 $ git clone https://github.com/chimurai/http-proxy-middleware.git
 $ cd http-proxy-middleware
-$ npm install
+$ yarn
+$ yarn build
 ```
 
 Run the example from root folder:

examples/_proxy.js

@@ -1,13 +1,13 @@
 /**
  * Module dependencies.
  */
-var browserSync = require('browser-sync').create();
-var proxy = require('../_proxy'); // require('http-proxy-middleware');
+const browserSync = require('browser-sync').create();
+const { createProxyMiddleware } = require('../../dist'); // require('http-proxy-middleware');
 
 /**
  * Configure proxy middleware
  */
-var jsonPlaceholderProxy = proxy('/users', {
+const jsonPlaceholderProxy = createProxyMiddleware('/users', {
   target: 'http://jsonplaceholder.typicode.com',
   changeOrigin: true, // for vhosted sites, changes host header to match to target's host
   logLevel: 'debug'

examples/browser-sync/index.js

@@ -1,20 +1,20 @@
 /**
  * Module dependencies.
  */
-var http = require('http');
-var connect = require('connect');
-var proxy = require('../_proxy'); // require('http-proxy-middleware');
+const http = require('http');
+const connect = require('connect');
+const { createProxyMiddleware } = require('../../dist'); // require('http-proxy-middleware');
 
 /**
  * Configure proxy middleware
  */
-var jsonPlaceholderProxy = proxy({
+const jsonPlaceholderProxy = createProxyMiddleware({
   target: 'http://jsonplaceholder.typicode.com',
   changeOrigin: true, // for vhosted sites, changes host header to match to target's host
   logLevel: 'debug'
 });
 
-var app = connect();
+const app = connect();
 
 /**
  * Add the proxy to connect

examples/connect/index.js

@@ -1,19 +1,19 @@
 /**
  * Module dependencies.
  */
-var express = require('express');
-var proxy = require('../_proxy'); // require('http-proxy-middleware');
+const express = require('express');
+const { createProxyMiddleware } = require('../../dist'); // require('http-proxy-middleware');
 
 /**
  * Configure proxy middleware
  */
-var jsonPlaceholderProxy = proxy({
+const jsonPlaceholderProxy = createProxyMiddleware({
   target: 'http://jsonplaceholder.typicode.com',
   changeOrigin: true, // for vhosted sites, changes host header to match to target's host
   logLevel: 'debug'
 });
 
-var app = express();
+const app = express();
 
 /**
  * Add the proxy to express