refactor: simplify socksDispatcher parameters

Author: Kaciras

README.md

@@ -10,45 +10,45 @@ Socks proxy for Node builtin (also [undici](https://github.com/nodejs/undici)) `
 npm install fetch-socks
 ```
 
-# Usage Example
+# Usage Examples
 
 fetch `http://example.com` through `socks5://[::1]:1080`.
 
 ```javascript
 import { socksDispatcher } from "fetch-socks";
 
 const dispatcher = socksDispatcher({
-    proxy: {
-        type: 5,
-        host: "::1",
-        port: 1080,
-    },
+    type: 5,
+    host: "::1",
+    port: 1080,
 });
 
 const response = await fetch("https://example.com", { dispatcher });
 console.log(response.status);
 console.log(await response.text());
 ```
 
-fetch through proxy chain with two SOCKS proxies.
-
-```javascript
-import { socksDispatcher } from "fetch-socks";
-
-const dispatcher = socksDispatcher({
-    proxy: [{
-        type: 5,
-        host: "::1",
-        port: 1080,
-    }, {
-        type: 5,
-        host: "::1",
-        port: 1081,
-        //userId: "foo",
-        //password: "bar",
-    }],
-    // set some TLS options
+TypeScript example, fetch through proxy chain with two SOCKS proxies.
+
+```typescript
+import { fetch } from "undici";
+import { socksDispatcher, SocksProxies } from "fetch-socks";
+
+const proxyConfig: SocksProxies = [{
+    type: 5,
+    host: "::1",
+    port: 1080,
+}, {
+    type: 5,
+    host: "127.0.0.1",
+    port: 1081,
+    //userId: "foo",
+    //password: "bar",
+}];
+
+const dispatcher = socksDispatcher(proxyConfig, {
     connect: {
+        // set some TLS options
         rejectUnauthorized: false,
     },
 });

index.spec.ts

@@ -66,14 +66,11 @@ it("should throw error if proxy connect timeout", async () => {
 	const addr = blackHole.address() as net.AddressInfo;
 
 	const dispatcher = socksDispatcher({
-		proxy: {
-			type: 5,
-			host: addr.address,
-			port: addr.port,
-		},
-		connect: {
-			timeout: 500,
-		},
+		type: 5,
+		host: addr.address,
+		port: addr.port,
+	}, {
+		connect: { timeout: 500 },
 	});
 	const promise = fetch("https://example.com", { dispatcher });
 	await expect(promise).rejects.toThrow(new TypeError("fetch failed"));
@@ -83,11 +80,9 @@ it("should throw error if proxy connect timeout", async () => {
 
 it("should throw error if the socks server is unreachable", async () => {
 	const dispatcher = socksDispatcher({
-		proxy: {
-			type: 5,
-			host: "::1",
-			port: 111,
-		},
+		type: 5,
+		host: "::1",
+		port: 111,
 	});
 	await httpServer.forGet("/foobar").thenReply(200, "__RESPONSE_DATA__");
 
@@ -98,13 +93,11 @@ it("should throw error if the socks server is unreachable", async () => {
 
 it("should throw error if the target is unreachable", async () => {
 	const dispatcher = socksDispatcher({
-		proxy: {
-			type: 5,
-			host: secureProxy.address,
-			port: secureProxy.port,
-			userId: "foo",
-			password: "_INVALID_",
-		},
+		type: 5,
+		host: secureProxy.address,
+		port: secureProxy.port,
+		userId: "foo",
+		password: "_INVALID_",
 	});
 	await httpServer.forGet("/foobar").thenReply(200, "__RESPONSE_DATA__");
 	const promise = fetch(httpServer.urlFor("/foobar"), { dispatcher });
@@ -113,23 +106,19 @@ it("should throw error if the target is unreachable", async () => {
 
 it("should throw error if authenticate failed", async () => {
 	const dispatcher = socksDispatcher({
-		proxy: {
-			type: 5,
-			host: plainProxy.address,
-			port: plainProxy.port,
-		},
+		type: 5,
+		host: plainProxy.address,
+		port: plainProxy.port,
 	});
 	const promise = fetch("http://[::1]:111", { dispatcher });
 	await expect(promise).rejects.toThrow(new TypeError("fetch failed"));
 });
 
 it("should connect target through socks", async () => {
 	const dispatcher = socksDispatcher({
-		proxy: {
-			type: 5,
-			host: plainProxy.address,
-			port: plainProxy.port,
-		},
+		type: 5,
+		host: plainProxy.address,
+		port: plainProxy.port,
 	});
 	const ep = await httpServer.forGet("/foobar")
 		.thenReply(200, "__RESPONSE_DATA__");
@@ -143,19 +132,17 @@ it("should connect target through socks", async () => {
 });
 
 it("should support proxy chain", async () => {
-	const dispatcher = socksDispatcher({
-		proxy: [{
-			type: 5,
-			host: secureProxy.address,
-			port: secureProxy.port,
-			userId: "foo",
-			password: "bar",
-		}, {
-			type: 5,
-			host: plainProxy.address,
-			port: plainProxy.port,
-		}],
-	});
+	const dispatcher = socksDispatcher([{
+		type: 5,
+		host: secureProxy.address,
+		port: secureProxy.port,
+		userId: "foo",
+		password: "bar",
+	}, {
+		type: 5,
+		host: plainProxy.address,
+		port: plainProxy.port,
+	}]);
 	const ep = await httpServer.forGet("/foobar")
 		.thenReply(200, "__RESPONSE_DATA__");
 
@@ -171,11 +158,10 @@ it("should support proxy chain", async () => {
 
 it("should support TLS over socks", async () => {
 	const dispatcher = socksDispatcher({
-		proxy: {
-			type: 5,
-			host: plainProxy.address,
-			port: plainProxy.port,
-		},
+		type: 5,
+		host: plainProxy.address,
+		port: plainProxy.port,
+	}, {
 		connect: {
 			rejectUnauthorized: false,
 		},

index.ts

@@ -5,7 +5,7 @@ import TLSOptions = buildConnector.BuildOptions;
 
 type onEstablished = Parameters<typeof SocksClient.createConnection>[1];
 
-type Proxies = SocksProxy | SocksProxy[];
+export type SocksProxies = SocksProxy | SocksProxy[];
 
 /**
  * Since socks does not guess HTTP ports, we need to do that.
@@ -23,7 +23,7 @@ function resolvePort(protocol: string, port: string) {
  * @param proxies The proxy server to use or the list of proxy servers to chain.
  * @param tlsOpts TLS upgrade options.
  */
-export function socksConnector(proxies: Proxies, tlsOpts: TLSOptions = {}): Connector {
+export function socksConnector(proxies: SocksProxies, tlsOpts: TLSOptions = {}): Connector {
 	const { timeout = 10e3 } = tlsOpts;
 	const tlsUpgrade = buildConnector(tlsOpts);
 
@@ -63,11 +63,6 @@ export function socksConnector(proxies: Proxies, tlsOpts: TLSOptions = {}): Conn
 
 export interface SocksDispatcherOptions extends Agent.Options {
 
-	/**
-	 * The socks proxy server to use or the list of proxy servers to chain.
-	 */
-	proxy: Proxies;
-
 	/**
 	 * TLS upgrade options, see:
 	 * https://undici.nodejs.org/#/docs/api/Client?id=parameter-connectoptions
@@ -80,8 +75,11 @@ export interface SocksDispatcherOptions extends Agent.Options {
 
 /**
  * Create a undici Agent with socks connector.
+ *
+ * @param proxies The proxy server to use or the list of proxy servers to chain.
+ * @param options Additional options passed to the Agent constructor.
  */
-export function socksDispatcher(options: SocksDispatcherOptions) {
-	const { connect, proxy, ...rest } = options;
-	return new Agent({ ...rest, connect: socksConnector(proxy, connect) });
+export function socksDispatcher(proxies: SocksProxies, options: SocksDispatcherOptions = {}) {
+	const { connect, ...rest } = options;
+	return new Agent({ ...rest, connect: socksConnector(proxies, connect) });
 }