feat: http proxy util (#106)

LICENSE

@@ -19,3 +19,96 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
+
+---
+
+https://github.com/node-fetch/node-fetch
+
+The MIT License (MIT)
+
+Copyright (c) 2016 - 2020 Node Fetch Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+---
+
+https://github.com/mysticatea/abort-controller
+
+MIT License
+
+Copyright (c) 2017 Toru Nagashima
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+https://github.com/TooTallNate/proxy-agents
+
+(The MIT License)
+
+Copyright (c) 2013 Nathan Rajlich <nathan@tootallnate.net>
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+---
+
+https://github.com/nodejs/undici
+
+MIT License
+
+Copyright (c) Matteo Collina and Undici contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -3,15 +3,17 @@
 [![][npm-version-src]][npm-version-href]
 [![][github-actions-src]][github-actions-href]
 [![][packagephobia-src]][packagephobia-href]
+
 <!-- [![npm downloads][npm-downloads-src]][npm-downloads-href] -->
 <!-- [![Codecov][codecov-src]][codecov-href] -->
 
-A redistribution of [node-fetch v3](https://github.com/node-fetch/node-fetch) for better backward and forward compatibility.
+A redistribution of [node-fetch v3](https://github.com/node-fetch/node-fetch) (+ more!) for better backward and forward compatibility.
 
 **Why this package?**
 
 - We can no longer `require('node-fetch')` with latest version. This stopped popular libraries from upgrading and dependency conflicts between `node-fetch@2` and `node-fetch@3`.
 - With upcoming versions of Node.js, native `fetch` is being supported. We are prepared for native fetch support using this package yet keep supporting older Node versions.
+- With introduction of native fetch to Node.js via [undici](https://github.com/nodejs/undici) there is no easy way to support http proxies!
 
 **Features:**
 
@@ -25,6 +27,8 @@ A redistribution of [node-fetch v3](https://github.com/node-fetch/node-fetch) fo
 
 ✅ Polyfill support for Node.js
 
+✅ Compact and simple proxy supporting both Node.js versions without native fetch using [HTTP Agent](https://github.com/TooTallNate/proxy-agents/tree/main/packages/proxy-agent) and versions with native fetch using [Undici Proxy Agent](https://undici.nodejs.org/#/docs/api/ProxyAgent)
+
 ## Usage
 
 Install `node-fetch-native` dependency:
@@ -44,22 +48,65 @@ You can now either import or require the dependency:
 
 ```js
 // ESM
-import fetch from 'node-fetch-native'
+import fetch from "node-fetch-native";
 
 // CommonJS
-const fetch = require('node-fetch-native')
+const fetch = require("node-fetch-native");
 ```
 
 More named exports:
 
 ```js
 // ESM
-import { fetch, Blob, FormData, Headers, Request, Response, AbortController } from 'node-fetch-native'
+import {
+  fetch,
+  Blob,
+  FormData,
+  Headers,
+  Request,
+  Response,
+  AbortController,
+} from "node-fetch-native";
 
 // CommonJS
-const { fetch, Blob, FormData, Headers, Request, Response, AbortController } = require('node-fetch-native')
+const {
+  fetch,
+  Blob,
+  FormData,
+  Headers,
+  Request,
+  Response,
+  AbortController,
+} = require("node-fetch-native");
+```
+
+## Proxy support
+
+Node.js has no built-in support for HTTP Proxies for fetch ([see nodejs/undici#1650](https://github.com/nodejs/undici/issues/1650) and [nodejs/node#8381](https://github.com/nodejs/node/issues/8381))
+
+This package bundles a compact and simple proxy supported for both Node.js versions without native fetch using [HTTP Agent](https://github.com/TooTallNate/proxy-agents/tree/main/packages/proxy-agent) and versions with native fetch using [Undici Proxy Agent](https://undici.nodejs.org/#/docs/api/ProxyAgent).
+
+**Usage:**
+
+```ts
+import { fetch } from "node-fetch-native"; // or use global fetch
+import { createProxy } from "node-fetch-native/proxy";
+
+const proxy = createProxy(); // Uses HTTPS_PROXY or HTTP_PROXY by default
+
+const proxy = createProxy({ url: "http://localhost:8080" });
+
+await fetch("https://google.com", {
+  ...proxy,
+});
 ```
 
+`createProxy` returns an object with `agent` for older Node.js version and `dispatcher` keys for newer Node.js versions with undici and native fetch.
+
+If no `url` option is provided, `HTTPS_PROXY` or `HTTP_PROXY` value will be used and if they also are not set, both `agent` and `dispatcher` values will be undefined.
+
+**Note:** Using export conditions, this utility works in Node.js and for other runtimes, it will simply return an stubbed version as most of other runtimes now support http proxy out of the box!
+
 ## Force using non-native version
 
 Sometimes you want to explicitly use none native (`node-fetch`) implementation of `fetch` in case of issues with native/polyfill version of `globalThis.fetch` with Node.js or runtime environment.
@@ -77,10 +124,10 @@ Using the polyfill method, we can once ensure global fetch is available in the e
 
 ```js
 // ESM
-import 'node-fetch-native/polyfill'
+import "node-fetch-native/polyfill";
 
 // CJS
-require('node-fetch-native/polyfill')
+require("node-fetch-native/polyfill");
 
 // You can now use fetch() without any import!
 ```
@@ -137,20 +184,16 @@ Made with 💛
 [node-fetch is published under the MIT license](https://github.com/node-fetch/node-fetch/blob/main/LICENSE.md)
 
 <!-- Badges -->
+
 [npm-version-src]: https://flat.badgen.net/npm/v/node-fetch-native
 [npm-version-href]: https://npmjs.com/package/node-fetch-native
-
 [npm-downloads-src]: https://flat.badgen.net/npm/dm/node-fetch-native
 [npm-downloads-href]: https://npmjs.com/package/node-fetch-native
-
 [github-actions-src]: https://flat.badgen.net/github/checks/unjs/node-fetch-native
 [github-actions-href]: https://github.com/unjs/node-fetch-native/actions?query=workflow%3Aci
-
 [packagephobia-src]: https://flat.badgen.net/packagephobia/install/node-fetch-native
 [packagephobia-href]: https://packagephobia.com/result?p=node-fetch-native
-
 [packagephobia-s-src]: https://flat.badgen.net/packagephobia/install/node-fetch-native?label=node-fetch-native&scale=.9
 [packagephobia-s-href]: https://packagephobia.com/result?p=node-fetch-native
-
 [packagephobia-s-alt-src]: https://flat.badgen.net/packagephobia/install/node-fetch?label=node-fetch&scale=.9
 [packagephobia-s-alt-href]: https://packagephobia.com/result?p=node-fetch

build.config.ts

@@ -1,3 +1,5 @@
+import { rm } from "node:fs/promises";
+import { resolve } from "node:path";
 import { defineBuildConfig } from "unbuild";
 
 export default defineBuildConfig({
@@ -13,5 +15,18 @@ export default defineBuildConfig({
       keepNames: true,
     },
   },
-  entries: ["src/index", "src/native", "src/polyfill", "src/node"],
+  entries: [
+    "src/index",
+    "src/native",
+    "src/polyfill",
+    "src/node",
+    "src/proxy",
+    "src/proxy-stub",
+  ],
+  hooks: {
+    async "build:done"(ctx) {
+      // Save few bytes from dist...
+      await rm(resolve(ctx.options.outDir, "proxy.mjs"));
+    },
+  },
 });

lib/proxy.d.cts

@@ -0,0 +1,8 @@
+import type * as http from "node:http";
+import type * as https from "node:https";
+import type * as undici from "undici";
+
+export declare const createProxy: (opts?: { url?: string }) => {
+  agent: http.Agent | https.Agent | undefined;
+  dispatcher: undici.Dispatcher | undefined;
+};

lib/proxy.d.mts

@@ -0,0 +1,8 @@
+import type * as http from "node:http";
+import type * as https from "node:https";
+import type * as undici from "undici";
+
+export declare const createProxy: (opts?: { url?: string }) => {
+  agent: http.Agent | https.Agent | undefined;
+  dispatcher: undici.Dispatcher | undefined;
+};

package.json

@@ -78,6 +78,28 @@
         "types": "./lib/index.d.cts",
         "default": "./lib/index.cjs"
       }
+    },
+    "./proxy": {
+      "node": {
+        "import": {
+          "types": "./lib/proxy.d.mts",
+          "default": "./dist/proxy.cjs"
+        },
+        "require": {
+          "types": "./lib/proxy.d.cts",
+          "default": "./dist/proxy.cjs"
+        }
+      },
+      "default": {
+        "import": {
+          "types": "./lib/proxy.d.mts",
+          "default": "./dist/proxy-stub.mjs"
+        },
+        "require": {
+          "types": "./lib/proxy.d.cts",
+          "default": "./dist/proxy-stub.cjs"
+        }
+      }
     }
   },
   "main": "./lib/index.cjs",
@@ -100,16 +122,22 @@
     "test": "pnpm lint && pnpm build && vitest run --coverage"
   },
   "devDependencies": {
+    "@types/node": "^20.10.5",
     "@vitest/coverage-v8": "^1.1.0",
     "abort-controller": "^3.0.0",
+    "agent-base": "^7.1.0",
     "changelogen": "^0.5.5",
     "eslint": "^8.56.0",
     "eslint-config-unjs": "^0.2.1",
+    "http-proxy-agent": "^7.0.0",
+    "https-proxy-agent": "^7.0.2",
     "node-fetch": "^3.3.2",
     "prettier": "^3.1.1",
+    "proxy-agent": "^6.3.1",
     "typescript": "^5.3.3",
     "unbuild": "^2.0.0",
+    "undici": "^6.2.1",
     "vitest": "^1.1.0"
   },
   "packageManager": "pnpm@8.12.1"
-}
+}