fetch-socks-bw

library1.4.3jsnpmunverified

Socks proxy for Node.js built-in fetch (undici) with bandwidth monitoring. Version 1.4.3 is a fork of fetch-socks that adds per-domain and global byte counters for sent/received data. Features SOCKS4/5 support, proxy chaining, HTTP tunnel connector, and TypeScript types. Actively maintained fork with experimental AI-assisted additions. Differentiators: unique bandwidth tracking capability not present in original fetch-socks; lightweight; uses undici dispatcher pattern.

devops

npm install fetch-socks-bw

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · FETCH-SOCKS-BW

fetch-socks-bw

devopsjavascriptv1.4.3

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

socksDispatcher

✓ import { socksDispatcher } from 'fetch-socks-bw'

✗ const socksDispatcher = require('fetch-socks-bw').socksDispatcher

ESM-only; CommonJS require works but TypeScript may complain about types.

socksConnector

✓ import { socksConnector } from 'fetch-socks-bw'

✗ import socksConnector from 'fetch-socks-bw'

Named export, not default.

getStatsForDomain

✓ import { getStatsForDomain } from 'fetch-socks-bw'

✗ import { getStatsForDomain } from 'fetch-socks-bw/stats'

Stats functions are top-level exports, not from a subpath.

Shows how to create a SOCKS5 dispatcher with bandwidth monitoring enabled, make a fetch request, and retrieve global stats.

import { socksDispatcher, getGlobalStats } from 'fetch-socks-bw'; import { fetch } from 'undici'; // or use global fetch const proxyConfig = { type: 5, host: '::1', port: 1080 }; const dispatcher = socksDispatcher(proxyConfig, { connect: { enableStats: true } }); async function main() { const response = await fetch('https://example.com', { dispatcher }); console.log(await response.text()); console.log('Global stats:', getGlobalStats()); } main().catch(console.error);

Debug

Known issues

gotchaenableStats must be set in the connect options to collect bandwidth data; it's not enabled by default.

fix

Pass { connect: { enableStats: true } } as second argument to socksDispatcher.

affects: >=1.0.0

gotchaStats are tracked per domain (hostname+port) but do not separate by protocol (http vs https).

fix

Ensure unique identification; consider extending if you need per-protocol stats.

affects: >=1.0.0

gotchaThis fork is experimental and may have untested edge cases. Not recommended for production without thorough testing.

fix

Evaluate stability before deploying; consider using original fetch-socks if stats not needed.

affects: >=1.0.0

deprecatedThe global dispatcher symbol 'Symbol.for("undici.globalDispatcher.1")' is undici internal; may change in future undici versions.

fix

Use undici's setGlobalDispatcher from 'undici' if available, or watch undici deprecations.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: socksDispatcher is not a function

Using default import instead of named import.

fix

Use named import: import { socksDispatcher } from 'fetch-socks-bw'

Error: SOCKS connection failed: connect ECONNREFUSED ::1:1080

SOCKS proxy not running or wrong host/port.

fix

Start a SOCKS proxy like: ssh -D 1080 user@host or use a socks library.

Cannot find module 'undici' or its corresponding type declarations.

Missing peer dependency undici.

fix

npm install undici

TypeError: Failed to parse URL from undefined

fetch called without URL or with invalid URL.

fix

Ensure fetch receives a valid URL string: await fetch('https://example.com', { dispatcher })

Upgrade

Version history

1.4.3latest on npm

Audit

Dependencies

undicioptionalPeer dependency for fetch API and global dispatcher integration

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/clouedoc/fetch-socks-bw ↗

packagefetch-socks-bw ↗

homepagehttps://github.com/clouedoc/fetch-socks-bw#readme ↗