bun-netdiag 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +57 -0
  2. package/index.ts +1 -0
  3. package/package.json +56 -0
package/README.md ADDED
@@ -0,0 +1,57 @@
1
+ # bun-netdiag
2
+
3
+ **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.
4
+
5
+ ```sh
6
+ bun add bun-netdiag
7
+ ```
8
+
9
+ The unscoped front door for [`@bun-win32/netdiag`](https://www.npmjs.com/package/@bun-win32/netdiag) — `export * from '@bun-win32/netdiag'`. A few kilobytes of TypeScript, **zero native binaries**; every DLL it calls already ships in `C:\Windows\System32`.
10
+
11
+ - **Zero child processes** — no `wmic`/`ping.exe`/`netsh`/`tracert`/PowerShell, no CMD-window flash.
12
+ - **Zero native build** — pure `bun:ffi`, no `node-gyp`, no Node-version drift.
13
+ - **Zero Administrator** — ICMP echo and every table read are unprivileged (the selftest runs non-elevated).
14
+ - **Locale-immune** — struct fields don't translate; French/German Windows can't break a `DataView`.
15
+
16
+ ## 10-line wow
17
+
18
+ ```ts
19
+ import { defaultGateway, ping, tcpConnections, throughput } from 'bun-netdiag';
20
+
21
+ defaultGateway(); // '192.168.0.1' — GetIpForwardTable2, no wmic
22
+ (await ping('1.1.1.1')).roundTripMs; // 11 — ICMP reply struct, no admin
23
+ tcpConnections({ resolveNames: 'module' }) // socket → PID → owning module, one syscall
24
+ .filter((c) => c.state === 'established')
25
+ .map((c) => `${c.remoteAddress}:${c.remotePort} ${c.pid} ${c.processName}`);
26
+ // 160.79.104.10:443 20408 claude.exe
27
+ // 52.96.157.162:443 24320 opera.exe
28
+ (await throughput(1000))[0]; // { name: 'Wi-Fi', rxBytesPerSec: 82_700_000, txBytesPerSec }
29
+ ```
30
+
31
+ ## Why this exists
32
+
33
+ Every Windows networking package on npm either **shells out** to a localized command and regex-scrapes stdout, or builds a **node-gyp native addon**. Both break. netdiag reads the same IP Helper / wlanapi / dnsapi structs the OS reads.
34
+
35
+ | incumbent | weekly downloads | what's wrong | netdiag |
36
+ |---|---|---|---|
37
+ | `default-gateway` | 8.1M | **archived 2026-02-05**; spawns `wmic` (being removed from Win11) | `defaultGateway()` reads `GetIpForwardTable2` |
38
+ | `systeminformation` | 5.87M | spawns PowerShell/`netstat`; **PID-only** sockets; 500 ms throttle; CVE-2021-21315 | `tcpConnections()` adds the **module name**; `throughput()` is sub-ms; no shell |
39
+ | `node-ping` | 190k | spawns `ping.exe`, crashes on French Windows (#64) | `ping()` reads `ICMP_ECHO_REPLY` — no locale |
40
+ | `node-wifi` | 2.9k | stale; `netsh` field-drift (#184), Unicode SSID mangling (#198) | wlanapi structs by offset; raw-UTF-8 SSID |
41
+ | `net-ping` / `raw-socket` | 1.4k+1.8k | node-gyp fails Node 20/24 (#91); raw socket needs admin (#88) | `IcmpSendEcho` — no node-gyp, no admin |
42
+
43
+ **No zero-install, pure-FFI Windows network-diagnostics competitor exists on npm** (verified 2026-06-13).
44
+
45
+ ## API & docs
46
+
47
+ `adapters` · `routes`/`defaultGateway` · `neighbors`/`arpTable` · `tcpConnections`/`udpListeners` · `ping`/`pingMany`/`pingSweep`/`traceroute` · `resolve`/`reverse`/`lookup` · `tcp/ip/udpStatistics`/`interfaceCounters`/`throughput` · `bestRoute`/`pathMtu` · `wifiInterfaces`/`wifiScan`/`wifiConnection`/`wifiBssList` · the raw escape hatch.
48
+
49
+ Full surface contract and gotchas: [`@bun-win32/netdiag` AI.md](https://github.com/ObscuritySRL/bun-win32/blob/main/packages/netdiag/AI.md).
50
+
51
+ ## What this does NOT do
52
+
53
+ Cross-platform · HTTP reachability (use `fetch()`) · raw packet capture / ARP writes (need admin) · OUI/vendor lookup · battle-tested WiFi connect (`wifiConnect` is a flagged beta).
54
+
55
+ ## License
56
+
57
+ MIT. Part of [bun-win32](https://github.com/ObscuritySRL/bun-win32).
package/index.ts ADDED
@@ -0,0 +1 @@
1
+ export * from '@bun-win32/netdiag';
package/package.json ADDED
@@ -0,0 +1,56 @@
1
+ {
2
+ "author": "Stev Peifer <stev.p@outlook.com>",
3
+ "bugs": {
4
+ "url": "https://github.com/ObscuritySRL/bun-win32/issues"
5
+ },
6
+ "dependencies": {
7
+ "@bun-win32/netdiag": "1.0.0"
8
+ },
9
+ "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.",
10
+ "devDependencies": {
11
+ "@types/bun": "latest"
12
+ },
13
+ "exports": {
14
+ ".": "./index.ts"
15
+ },
16
+ "license": "MIT",
17
+ "module": "index.ts",
18
+ "name": "bun-netdiag",
19
+ "peerDependencies": {
20
+ "typescript": "^5"
21
+ },
22
+ "private": false,
23
+ "homepage": "https://github.com/ObscuritySRL/bun-win32#readme",
24
+ "repository": {
25
+ "type": "git",
26
+ "url": "git://github.com/ObscuritySRL/bun-win32.git",
27
+ "directory": "packages/bun-netdiag"
28
+ },
29
+ "type": "module",
30
+ "version": "1.0.0",
31
+ "main": "./index.ts",
32
+ "keywords": [
33
+ "bun",
34
+ "ffi",
35
+ "win32",
36
+ "windows",
37
+ "network",
38
+ "netstat",
39
+ "ping",
40
+ "traceroute",
41
+ "dns",
42
+ "wifi",
43
+ "arp",
44
+ "routing",
45
+ "diagnostics",
46
+ "typescript"
47
+ ],
48
+ "files": [
49
+ "README.md",
50
+ "index.ts"
51
+ ],
52
+ "sideEffects": false,
53
+ "engines": {
54
+ "bun": ">=1.1.0"
55
+ }
56
+ }