{"_id":"@bun-win32/netdiag","_rev":"3-e89b1d703f799dfb50abfc36fe42b70c","name":"@bun-win32/netdiag","dist-tags":{"latest":"2.0.1"},"versions":{"1.0.0":{"name":"@bun-win32/netdiag","version":"1.0.0","keywords":["bun","ffi","win32","windows","network","netstat","ping","traceroute","dns","wifi","arp","routing","diagnostics","typescript"],"author":"Stev Peifer <stev.p@outlook.com>","license":"MIT","_id":"@bun-win32/netdiag@1.0.0","maintainers":[{"name":"obscuritysrl","email":"stev@bell.net"}],"homepage":"https://github.com/ObscuritySRL/bun-win32#readme","bugs":{"url":"https://github.com/ObscuritySRL/bun-win32/issues"},"dist":{"shasum":"52c8c353746bd37577b56be687ebd292e8a9bd84","tarball":"https://registry.npmjs.org/@bun-win32/netdiag/-/netdiag-1.0.0.tgz","fileCount":17,"integrity":"sha512-b3VNPQmSQIw8srfuSzrPGuw3zq5sNypO7hraHNtZlaxY5ltKowMpAaiWKXLZG9X4ANC1ZQohB5HnQ7vFr1vDFg==","signatures":[{"sig":"MEYCIQC+C6PUEjiRpuBYeC5oy0au9jVNY719kuMMJvzvyl72IgIhAKMmTh462LGzT7scD6P+m6VZxOWrKrPKZ0LO7quf5XZ9","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":89757},"main":"./index.ts","type":"module","module":"index.ts","shasum":"52c8c353746bd37577b56be687ebd292e8a9bd84","engines":{"bun":">=1.1.0"},"exports":{".":"./index.ts"},"private":false,"scripts":{"example:ping":"bun ./example/ping.ts","example:netwatch":"bun ./example/netwatch.ts","example:selftest":"bun ./example/netdiag.selftest.ts","example:wifi-scan":"bun ./example/wifi-scan.ts","example:net-report":"bun ./example/net-report.ts"},"_npmUser":{"name":"obscuritysrl","email":"stev@bell.net"},"_integrity":"sha512-b3VNPQmSQIw8srfuSzrPGuw3zq5sNypO7hraHNtZlaxY5ltKowMpAaiWKXLZG9X4ANC1ZQohB5HnQ7vFr1vDFg==","repository":{"url":"git://github.com/ObscuritySRL/bun-win32.git","type":"git","directory":"packages/netdiag"},"_npmVersion":"10.8.3","description":"Syscall-grade network diagnostics for Bun on Windows — routing table, socket→PID map, no-admin ICMP ping/traceroute, ARP, DNS, live throughput, and WiFi — decoded from binary structs, zero native dependencies, no netsh/ping.exe/wmic scraping.","directories":{},"sideEffects":false,"_nodeVersion":"24.3.0","dependencies":{"@bun-win32/core":"1.1.4","@bun-win32/dnsapi":"1.0.2","@bun-win32/ws2_32":"1.0.6","@bun-win32/wlanapi":"1.0.4","@bun-win32/iphlpapi":"1.0.5","@bun-win32/kernel32":"1.0.26"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"@types/bun":"latest"},"peerDependencies":{"typescript":"^5"},"_npmOperationalInternal":{"tmp":"tmp/netdiag_1.0.0_1781375348912_0.4114604253769978","host":"s3://npm-registry-packages-npm-production"}},"2.0.0":{"name":"@bun-win32/netdiag","version":"2.0.0","keywords":["bun","ffi","win32","windows","network","netstat","ping","traceroute","dns","wifi","arp","routing","diagnostics","typescript"],"author":"Stev Peifer <stev.p@outlook.com>","license":"MIT","_id":"@bun-win32/netdiag@2.0.0","maintainers":[{"name":"obscuritysrl","email":"stev.p@outlook.com"}],"homepage":"https://github.com/ObscuritySRL/bun-win32#readme","bugs":{"url":"https://github.com/ObscuritySRL/bun-win32/issues"},"dist":{"shasum":"b27ac70bffee0deea035e4ca9452a024a135c9d3","tarball":"https://registry.npmjs.org/@bun-win32/netdiag/-/netdiag-2.0.0.tgz","fileCount":17,"integrity":"sha512-i3mh4G/RFVDbqAN9VktmsaGhJNkNwTkyDpbQveEofItCJxrU7pJS4G1Km4dEzr3TYzRPxFHct3i9iLTARpVOkg==","signatures":[{"sig":"MEYCIQCPABF1X+2Ur4UervrN/c8Yz7O22CImpXVbPNAvY+bDAQIhAMLf2CLZ2aT0JcKK9oTexUaOALH7BF+/apZjNDZqhiiF","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":89756},"main":"./index.ts","type":"module","module":"index.ts","shasum":"b27ac70bffee0deea035e4ca9452a024a135c9d3","engines":{"bun":">=1.1.0"},"exports":{".":"./index.ts"},"private":false,"scripts":{"example:ping":"bun ./example/ping.ts","example:netwatch":"bun ./example/netwatch.ts","example:selftest":"bun ./example/netdiag.selftest.ts","example:wifi-scan":"bun ./example/wifi-scan.ts","example:net-report":"bun ./example/net-report.ts"},"_npmUser":{"name":"obscuritysrl","email":"stev.p@outlook.com"},"_integrity":"sha512-i3mh4G/RFVDbqAN9VktmsaGhJNkNwTkyDpbQveEofItCJxrU7pJS4G1Km4dEzr3TYzRPxFHct3i9iLTARpVOkg==","repository":{"url":"git://github.com/ObscuritySRL/bun-win32.git","type":"git","directory":"packages/netdiag"},"_npmVersion":"10.8.3","description":"Syscall-grade network diagnostics for Bun on Windows — routing table, socket→PID map, no-admin ICMP ping/traceroute, ARP, DNS, live throughput, and WiFi — decoded from binary structs, zero native dependencies, no netsh/ping.exe/wmic scraping.","directories":{},"sideEffects":false,"_nodeVersion":"26.3.0","dependencies":{"@bun-win32/core":"2.0.0","@bun-win32/dnsapi":"2.0.0","@bun-win32/ws2_32":"2.0.0","@bun-win32/wlanapi":"2.0.0","@bun-win32/iphlpapi":"2.0.0","@bun-win32/kernel32":"2.0.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"@types/bun":"latest"},"peerDependencies":{"typescript":"^5"},"_npmOperationalInternal":{"tmp":"tmp/netdiag_2.0.0_1782436018901_0.9939681164483152","host":"s3://npm-registry-packages-npm-production"}},"2.0.1":{"author":"Stev Peifer <stev.p@outlook.com>","bugs":{"url":"https://github.com/ObscuritySRL/bun-win32/issues"},"dependencies":{"@bun-win32/core":"2.0.1","@bun-win32/dnsapi":"2.0.1","@bun-win32/iphlpapi":"2.0.1","@bun-win32/kernel32":"2.0.1","@bun-win32/wlanapi":"2.0.1","@bun-win32/ws2_32":"2.0.1"},"description":"Syscall-grade network diagnostics for Bun on Windows — routing table, socket→PID map, no-admin ICMP ping/traceroute, ARP, DNS, live throughput, and WiFi — decoded from binary structs, zero native dependencies, no netsh/ping.exe/wmic scraping.","devDependencies":{"@types/bun":"latest"},"exports":{".":"./index.ts"},"license":"MIT","module":"index.ts","name":"@bun-win32/netdiag","peerDependencies":{"typescript":"^5"},"private":false,"publishConfig":{"access":"public"},"homepage":"https://github.com/ObscuritySRL/bun-win32#readme","repository":{"type":"git","url":"git://github.com/ObscuritySRL/bun-win32.git","directory":"packages/netdiag"},"type":"module","version":"2.0.1","main":"./index.ts","keywords":["bun","ffi","win32","windows","network","netstat","ping","traceroute","dns","wifi","arp","routing","diagnostics","typescript"],"sideEffects":false,"engines":{"bun":">=1.1.0"},"scripts":{"example:net-report":"bun ./example/net-report.ts","example:netwatch":"bun ./example/netwatch.ts","example:ping":"bun ./example/ping.ts","example:selftest":"bun ./example/netdiag.selftest.ts","example:wifi-scan":"bun ./example/wifi-scan.ts"},"_id":"@bun-win32/netdiag@2.0.1","_integrity":"sha512-fgOYhWOtJfiK91DA3ZTW7BRElKrVL4OsTPGXZbWR3i0kA79MaebFIqT2soS8ZXHsxDweMn8AVOcrh8vlO8AGWg==","_nodeVersion":"26.3.0","_npmVersion":"10.8.3","shasum":"6840ab6460d46f63bbabf626130b1ac4077e2440","dist":{"integrity":"sha512-fgOYhWOtJfiK91DA3ZTW7BRElKrVL4OsTPGXZbWR3i0kA79MaebFIqT2soS8ZXHsxDweMn8AVOcrh8vlO8AGWg==","shasum":"6840ab6460d46f63bbabf626130b1ac4077e2440","tarball":"https://registry.npmjs.org/@bun-win32/netdiag/-/netdiag-2.0.1.tgz","fileCount":17,"unpackedSize":89756,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQC7sGmAy68P37cUO3MBDkDSm12A7gVrZXbLbSRgZ1oOcQIhAPB5G+veLh0Nh2d/7Y5VRcInwNWb47mKnZlyoBDoFyvr"}]},"_npmUser":{"name":"obscuritysrl","email":"stev.p@outlook.com"},"directories":{},"maintainers":[{"name":"obscuritysrl","email":"stev.p@outlook.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/netdiag_2.0.1_1782438244994_0.41309921691524676"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-13T18:29:08.799Z","modified":"2026-06-26T01:44:05.269Z","1.0.0":"2026-06-13T18:29:09.041Z","2.0.0":"2026-06-26T01:06:59.073Z","2.0.1":"2026-06-26T01:44:05.124Z"},"bugs":{"url":"https://github.com/ObscuritySRL/bun-win32/issues"},"author":"Stev Peifer <stev.p@outlook.com>","license":"MIT","homepage":"https://github.com/ObscuritySRL/bun-win32#readme","keywords":["bun","ffi","win32","windows","network","netstat","ping","traceroute","dns","wifi","arp","routing","diagnostics","typescript"],"repository":{"type":"git","url":"git://github.com/ObscuritySRL/bun-win32.git","directory":"packages/netdiag"},"description":"Syscall-grade network diagnostics for Bun on Windows — routing table, socket→PID map, no-admin ICMP ping/traceroute, ARP, DNS, live throughput, and WiFi — decoded from binary structs, zero native dependencies, no netsh/ping.exe/wmic scraping.","maintainers":[{"name":"obscuritysrl","email":"stev.p@outlook.com"}],"readme":"# @bun-win32/netdiag\n\n**Syscall-grade network diagnostics for Bun on Windows.** Routing table, socket→PID(+module) map, no-admin ICMP ping/traceroute, ARP/neighbors, DNS, live throughput, and WiFi — every result decoded from a **binary Win32 struct** via `bun:ffi`, never scraped from `netsh`/`ping.exe`/`wmic`/`arp`/`netstat` text.\n\n- **Zero child processes.** No `wmic`, no `ping.exe`, no `netsh`, no `tracert`, no PowerShell, no CMD-window flash.\n- **Zero native build.** Pure `bun:ffi` — no `node-gyp`, no NAN addon, no Node-version drift.\n- **Zero Administrator.** ICMP echo and every table read are unprivileged. The integration selftest runs in a non-elevated shell.\n- **Zero dependencies** outside the workspace. Every DLL it calls already ships in `C:\\Windows\\System32`.\n- **Locale-immune by construction.** Struct fields don't translate; a French or German Windows can't break a `DataView.getUint32`.\n\n> Windows-only, Bun-only — stated proudly. `bun add bun-netdiag` pulls a few kilobytes of TypeScript and zero native binaries.\n\n## 10-line wow\n\n```ts\nimport { defaultGateway, ping, tcpConnections, throughput } from 'bun-netdiag';\n\ndefaultGateway();                                         // '192.168.0.1'  — GetIpForwardTable2, no wmic\n(await ping('1.1.1.1')).roundTripMs;                      // 11            — ICMP reply struct, no admin\ntcpConnections({ resolveNames: 'module' })                // socket → PID → owning module, one syscall\n  .filter((c) => c.state === 'established')\n  .map((c) => `${c.remoteAddress}:${c.remotePort}  ${c.pid}  ${c.processName}`);\n//  160.79.104.10:443   20408   claude.exe\n//  52.96.157.162:443   24320   opera.exe\n(await throughput(1000))[0];                              // { name: 'Wi-Fi', rxBytesPerSec: 82_700_000, txBytesPerSec }\n```\n\n## Why this exists\n\nEvery Windows networking package on npm either **shells out** to a localized command and regex-scrapes its stdout, or builds a **node-gyp native addon**. Both break. netdiag reads the same IP Helper / wlanapi / dnsapi structs the OS reads.\n\n| incumbent | weekly downloads | what's wrong (receipt) | netdiag |\n|---|---|---|---|\n| `default-gateway` | 8.1M | **GitHub-archived 2026-02-05**; spawns `wmic`, which Microsoft is removing from Windows 11 ([#25](https://github.com/silverwind/default-gateway/issues/25)); maintainer: *\"parsing command output is a wrong approach\"* ([#27](https://github.com/silverwind/default-gateway/issues/27)) | `defaultGateway()` reads `GetIpForwardTable2` directly |\n| `systeminformation` | 5.87M | spawns PowerShell/`netstat`/`netsh`; sockets are **PID-only** (hardcoded `process:''`); `networkStats` has a **500 ms throttle**; CVE-2021-21315 shell-injection class | `tcpConnections()` adds the **module name**; `throughput()` is sub-ms; no shell to inject |\n| `node-ping` | 190k | spawns `ping.exe` + regex-parses localized stdout — crashes on French Windows (`temps`, [#64](https://github.com/danielzzz/node-ping/issues/64)); `alive` always false ([#26](https://github.com/danielzzz/node-ping/issues/26)) | `ping()` reads `ICMP_ECHO_REPLY.RoundTripTime` (u32) — no locale, ever |\n| `node-wifi` | 2.9k | stale since 2021; `netsh` field-reorder on Win11 → `ssid='connected'` ([#184](https://github.com/friedrith/node-wifi/issues/184)); Unicode SSID mangling ([#198](https://github.com/friedrith/node-wifi/issues/198)) | `wifiScan()`/`wifiConnection()` read wlanapi structs by offset; SSID is raw UTF-8 |\n| `local-devices` / arp scrapers | 3.4k | spawn `arp -a` with a fixed-index parser; `arp -n` Unix flag fails on Windows ([#75](https://github.com/DylanPiercey/local-devices/issues/75)); device name always `?` ([#21](https://github.com/DylanPiercey/local-devices/issues/21)) | `neighbors()` reads `GetIpNetTable2` — typed, with reachability **state** and IPv6 ND; `reverse()` for names |\n| `net-ping` / `raw-socket` | 1.4k+1.8k | `node-gyp` build fails on Node 20/24 ([#91](https://github.com/nospaceships/node-raw-socket/issues/91)); raw ICMP socket needs **Administrator** ([#88](https://github.com/nospaceships/node-net-ping/issues/88)) | `ping()`/`traceroute()` over `IcmpSendEcho` — no node-gyp, no admin, no raw socket |\n| `node-netstat` / `windows-netstat` | 2.7k+6 | spawn `netstat` (LISTEN/LISTENING drift, [#42](https://github.com/danielkrainas/node-netstat/issues/42)) or node-gyp IPv4-only | `tcpConnections('all')` + `udpListeners('all')` — TCP4/6 + UDP4/6, canonical state strings |\n\n**No zero-install, pure-FFI Windows network-diagnostics competitor exists on npm** (verified 2026-06-13). The niche is unoccupied.\n\n## Benchmarks\n\nEvery table is one syscall, not a process spawn. Measured on the host below (`bun run example/benchmark.ts` — `Bun.nanoseconds`, warm-up, DFG-verified):\n\n| operation | ns/op | samples/sec |\n|---|---|---|\n| `routes()` poll + decode | ~31,700 | ~31,500 |\n| `tcpConnections()` poll (v4+v6) | ~194,000 | ~5,100 |\n| `IcmpSendEcho` to 127.0.0.1 | ~79,800 | ~12,500 |\n| `interfaceCounters()` poll | ~606,000 | ~1,650 |\n\nSpawning `route print` once costs **~70 ms** (~14/sec). `routes()` polls **~2,200× faster** — the difference between a live dashboard and a stuttering one. (Numbers are host-specific; re-run the benchmark.)\n\n## API\n\n`adapters` · `routes` / `defaultGateway` · `neighbors` / `arpTable` · `tcpConnections` / `udpListeners` · `ping` / `pingMany` / `pingSweep` / `traceroute` · `resolve` / `reverse` / `lookup` · `tcpStatistics` / `ipStatistics` / `udpStatistics` / `interfaceCounters` / `throughput` · `bestRoute` / `pathMtu` · `wifiInterfaces` / `wifiScan` / `wifiConnection` / `wifiBssList` / `wifiConnect`(beta) / `wifiDisconnect`(beta) · the raw escape hatch (`Iphlpapi`, `Wlanapi`, `Dnsapi`, `Ws2_32`, `Kernel32`).\n\nFull surface contract in [`AI.md`](./AI.md). Examples in [`example/`](./example): `net-report`, `netwatch` (live dashboard), `ping`, `wifi-scan`, `benchmark`, `netdiag.selftest`.\n\n## Verified against the OS's own tools\n\n`netdiag.selftest.ts` passes 19 assertions in a non-elevated shell, and the cross-validation matches the OS tools exactly: `defaultGateway()` = `ipconfig`, `neighbors()` = `arp -a`, `tcpConnections()` PIDs = `netstat -ano`, `routes()` = `route print`, `resolve()` = `nslookup`, `ping()` TTL = `ping.exe`, `adapters()` MAC = `ipconfig /all`, `wifiConnection()` = `netsh wlan show interfaces`.\n\n## What this does NOT do\n\n- **Cross-platform.** Windows-only by design — the Windows backend done right. For Linux/macOS/Node, `systeminformation` / `default-gateway` are the answer.\n- **HTTP reachability.** netdiag is layer 3/4; use Bun's built-in `fetch()` for HTTP-level checks.\n- **Raw packet capture / ARP-table writes.** Those need Administrator and are out of the no-admin scope (the raw escape hatch is there if you need them).\n- **OUI/vendor lookup.** Out of the zero-dependency core.\n- **Bullet-proof WiFi connect.** `wifiConnect`/`wifiDisconnect` ship as a flagged beta, unexercised against a live AP.\n\nRoadmap: IPv6 ping/path-MTU (`Icmp6SendEcho2`), ping count/loss statistics + `deadlineMs`, per-connection ESTATS RTT (admin), CIDR/range `discover()`.\n\n## License\n\nMIT. Part of [bun-win32](https://github.com/ObscuritySRL/bun-win32).\n","readmeFilename":"README.md"}