{"_id":"@david-tobi-peter/request-tracer","_rev":"5-ab80f15a4848c2985508c8ebf836cdba","name":"@david-tobi-peter/request-tracer","dist-tags":{"latest":"1.0.2"},"versions":{"1.0.1":{"name":"@david-tobi-peter/request-tracer","version":"1.0.1","keywords":["http","tracer","dns","tcp","tls","network","timing","performance","diagnostics","debugging"],"author":{"name":"David Oluwatobi","email":"davidoluwatobi41@gmail.com"},"license":"MIT","_id":"@david-tobi-peter/request-tracer@1.0.1","maintainers":[{"name":"david-tobi-peter","email":"davidoluwatobi41@gmail.com"}],"homepage":"https://github.com/david-tobi-peter/request-tracer#readme","bugs":{"url":"https://github.com/david-tobi-peter/request-tracer/issues"},"bin":{"request-tracer":"dist/cli/main.js"},"dist":{"shasum":"ca24ddd808ba68429c7a3cd98809896979da412a","tarball":"https://registry.npmjs.org/@david-tobi-peter/request-tracer/-/request-tracer-1.0.1.tgz","fileCount":47,"integrity":"sha512-QWZDHgMHKI2WFlYnpWcEh6H5gxGXtwsyBBRhYOudNBRLGp23c51mVErzE++Kfz/m3QlSFhvGa3LvtrZRG8fZJw==","signatures":[{"sig":"MEUCIQDlM1ye/EyL4hrLQF0lhRDQmu4Sh7g1h6PqXh7ytFWkEQIgVwb5D8mySFFTXCLxC/KKqEKmXTZBsYvgzoMdmhSeda8=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":35588},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"142cb2daa4039de9560702e8db87ec2381fed9e6","scripts":{"dev":"tsx src/cli/main.ts","build":"npm run clean && tsc","clean":"rm -rf dist","start":"node ./dist/cli/main.js","postbuild":"chmod +x ./dist/cli/main.js","prepublishOnly":"npm run build"},"_npmUser":{"name":"david-tobi-peter","email":"davidoluwatobi41@gmail.com"},"repository":{"url":"git+https://github.com/david-tobi-peter/request-tracer.git","type":"git"},"_npmVersion":"10.9.3","description":"Low-level HTTP request tracer with DNS, TCP, TLS, and HTTP timing measurements","directories":{},"_nodeVersion":"22.18.0","publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.21.0","typescript":"^5.9.3","@types/node":"^25.0.3"},"_npmOperationalInternal":{"tmp":"tmp/request-tracer_1.0.1_1767391591039_0.8542585630484152","host":"s3://npm-registry-packages-npm-production"}},"1.0.2":{"name":"@david-tobi-peter/request-tracer","version":"1.0.2","description":"Low-level HTTP request tracer with DNS, TCP, TLS, and HTTP timing measurements","type":"module","main":"./dist/index.js","types":"./dist/index.d.ts","bin":{"request-tracer":"dist/cli/main.js"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"scripts":{"build":"npm run clean && tsc","clean":"rm -rf dist","start":"node ./dist/cli/main.js","dev":"tsx src/cli/main.ts","prepublishOnly":"npm run build","postbuild":"chmod +x ./dist/cli/main.js"},"keywords":["http","tracer","dns","tcp","tls","network","timing","performance","diagnostics","debugging"],"author":{"name":"David Oluwatobi","email":"davidoluwatobi41@gmail.com"},"maintainers":[{"name":"david-tobi-peter","email":"davidoluwatobi41@gmail.com"}],"license":"MIT","repository":{"type":"git","url":"git+https://github.com/david-tobi-peter/request-tracer.git"},"bugs":{"url":"https://github.com/david-tobi-peter/request-tracer/issues"},"homepage":"https://github.com/david-tobi-peter/request-tracer#readme","engines":{"node":">=18.0.0"},"devDependencies":{"@types/node":"^25.0.3","@types/yargs":"^17.0.35","tsx":"^4.21.0","typescript":"^5.9.3"},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"dependencies":{"yargs":"^18.0.0"},"_id":"@david-tobi-peter/request-tracer@1.0.2","gitHead":"fc0b7d9eb99677666f979179bfb0044f08b87e88","_nodeVersion":"22.18.0","_npmVersion":"10.9.3","dist":{"integrity":"sha512-xFIJji1vPpYl4CzHm9kWOIYl+H6sZhsW0MCQbdBqy+3wbJn/xjd0FPzib9TzYBMOZ6qQaFlqPUE/jXIUt4Wc1w==","shasum":"7641dfc706814c4bffb7082931b3963b2cf14c6e","tarball":"https://registry.npmjs.org/@david-tobi-peter/request-tracer/-/request-tracer-1.0.2.tgz","fileCount":47,"unpackedSize":41568,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCHm6vPrDnjqUvheeHQNX7vOEnm3tfSDS1ZR5QA8RUNJgIgYXYh0ovC45KEmYd1QHiTPHjnAI4CnE91kdgUWS2gHZE="}]},"_npmUser":{"name":"david-tobi-peter","email":"davidoluwatobi41@gmail.com"},"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/request-tracer_1.0.2_1767608755847_0.3635440530082812"},"_hasShrinkwrap":false}},"time":{"created":"2026-01-02T22:06:30.901Z","modified":"2026-01-05T10:25:56.168Z","1.0.0":"2026-01-02T21:41:59.408Z","1.0.1":"2026-01-02T22:06:31.175Z","1.0.2":"2026-01-05T10:25:55.990Z"},"bugs":{"url":"https://github.com/david-tobi-peter/request-tracer/issues"},"author":{"name":"David Oluwatobi","email":"davidoluwatobi41@gmail.com"},"license":"MIT","homepage":"https://github.com/david-tobi-peter/request-tracer#readme","keywords":["http","tracer","dns","tcp","tls","network","timing","performance","diagnostics","debugging"],"repository":{"type":"git","url":"git+https://github.com/david-tobi-peter/request-tracer.git"},"description":"Low-level HTTP request tracer with DNS, TCP, TLS, and HTTP timing measurements","maintainers":[{"name":"david-tobi-peter","email":"davidoluwatobi41@gmail.com"}],"readme":"# Request Tracer\n\nA lightweight Node.js tool to trace network requests and measure timings across **DNS**, **TCP**, **TLS**, and **HTTP**.  \nCan be used as a **CLI tool** or imported as a **package** in your project.\n\n---\n\n## Requirements\n\n- **Node.js:** 18.0.0 or higher\n- **Module System:** ESM only (`\"type\": \"module\"` in `package.json`)\n\n---\n\n## Migration from CommonJS\n\nIf your project uses CommonJS, you must migrate to ESM:\n\n- Add `\"type\": \"module\"` to your `package.json`\n- Replace `require()` with `import`\n- Replace `module.exports` with `export`\n- Use explicit `.js` extensions in relative imports\n- Update your `tsconfig.json` accordingly\n\n---\n\n## Features\n\n- End-to-end request tracing\n- Measures:\n  - DNS resolution\n  - TCP connection\n  - TLS handshake (HTTPS)\n  - HTTP time-to-first-byte (TTFB) and download time\n- Supports HTTP and HTTPS\n- Optional request timeout\n- Supports custom HTTP methods, headers, and body\n- Exposes detailed `ITraceResult` for programmatic use\n- CLI-friendly and scriptable\n\n---\n\n## Installation\n\n```bash\n# Global install (CLI)\nnpm install -g @david-tobi-peter/request-tracer\n\n# Or local project dependency\nnpm install @david-tobi-peter/request-tracer\n````\n\n---\n\n## Usage\n\n### CLI\n\n```bash\n# Basic GET request\nrequest-tracer --url https://example.com\n\n# With timeout (ms)\nrequest-tracer --url https://example.com --timeout 5000\n```\n\n### POST request with body\n\n```bash\nrequest-tracer --url https://api.example.com/users \\\n  --method POST \\\n  --body '{\"name\":\"John\"}'\n```\n\n### Custom headers\n\n> **Note:** `--header` values must be quoted to avoid shell brace expansion.\n\n```bash\nrequest-tracer --url https://api.example.com/data \\\n  --header '{Authorization:BearerToken,X-Env:prod}'\n```\n\n---\n\n### Example Output\n\n```\nTracing: GET https://example.com/\n\nDNS:       7.39 ms → 172.217.14.206 (ipv4)\nTCP:       12.54 ms → local:52345 remote:443\nTLS:       35.67 ms → TLSv1.3 / TLS_AES_256_GCM_SHA384\nALPN:      http/1.1 | Session reused: false\nCert:      Google Trust Services\nHTTP:      101.45 ms TTFB + 2.34 ms download\nStatus:    200 OK (HTTP/1.1)\nBytes:     1.23 KB\n\nTotal time: 159.39 ms\n```\n\n---\n\n## Programmatic Usage\n\n```ts\nimport { RequestTracer, ITraceResult } from \"@david-tobi-peter/request-tracer\";\n\nconst tracer = new RequestTracer();\n\nasync function run() {\n  // Simple GET request\n  const result: ITraceResult = await tracer.trace(\"https://example.com\", 5000);\n  console.log(result);\n\n  /*\n  // POST request with headers and body\n  const postResult: ITraceResult = await tracer.trace(\n    \"https://api.example.com/users\",\n    5000,\n    {\n      method: \"POST\",\n      headers: {\n        \"Content-Type\": \"application/json\",\n        Authorization: \"BearerToken\",\n      },\n      body: JSON.stringify({ name: \"John\" }),\n    }\n  );\n\n  console.log(postResult);\n  */\n}\n\nrun();\n```\n\n---\n\n## `ITraceResult` Shape\n\n```ts\ninterface ITraceResult {\n  url: URL;\n  dns: { time: number; address: string; family: \"ipv4\" | \"ipv6\" };\n  tcp: { time: number; localPort: number; remotePort: number; socket: Socket };\n  tls?: {\n    time: number;\n    protocol: string;\n    cipher: string;\n    alpn: string;\n    sessionReused: boolean;\n    certIssuer: string;\n    socket: TLSSocket;\n  };\n  http: {\n    ttfb: number;\n    download: number;\n    statusCode: number | string;\n    statusMessage: string;\n    httpVersion: string;\n    headers: Record<string, string | string[]>;\n    bytes: number;\n  };\n  totalTime: number;\n}\n```\n\n* All times are in **milliseconds**\n* `timeoutMs` defaults to **30,000 ms** if not specified\n\n---\n\n## CLI Options\n\n| Option      | Description                                     | Default |\n| ----------- | ----------------------------------------------- | ------- |\n| `--url`     | URL to trace (required)                         | —       |\n| `--timeout` | Request timeout in milliseconds                 | 30000   |\n| `--method`  | HTTP method                                     | GET     |\n| `--header`  | HTTP headers in `{k1:v1,k2:v2}` format (quoted) | —       |\n| `--body`    | Request body (POST / PUT / PATCH)               | —       |\n\n---\n\n## License\n\nMIT License – see [LICENSE](./license.md)\n","readmeFilename":"readme.md"}