scharff

Scharff

Scharff is a lightweight Node.js interceptor that logs all fetch activity — outgoing requests, incoming responses, and related errors. It gives you clear, file-based visibility into your app's HTTP interactions with minimal setup.

Installation

npm install scharff

Or clone from GitHub:

git clone https://github.com/Minka1902/scharff.git

Quick Start

CommonJS:

const listen = require('scharff');

// Optional: override destinations
listen.updateConfig({ outgoingLog: './logs/outgoing.log' });

// Stop logging later
listen();

TypeScript / ESM:

import listen = require('scharff');

listen.updateConfig({ incomingLog: './logs/incoming.log' });
// ... your app code
listen(); // unregister

What to Expect

1. The package creates newline-delimited JSON (NDJSON) logs (defaults):
   • outgoingRequest.log
   • outgoingRequestError.log
   • incomingResponse.log
   • incomingResponseError.log
2. Each fetch call is logged; request errors and response errors are separated.
3. Example outgoing request entry:

{
    "url":"http://127.0.0.1:3000/update/www.example.com",
    "ip":"192.168.1.10",
    "date":{
        "date":"2025-12-22",
        "time":"14:05:10"
    },
    "originUrl":"/update/www.example.com",
    "method":"PUT",
    "headers":{
        "Content-Type":"application/json",
        "Access-Control-Allow-Origin":"*"
    },
    "body":{
        "isActive":true,
        "status":200,
        "lastChecked":"2025-12-22T14:05:10.200Z"
    }
}

New in this release

1. Added request error logging
2. Added response logging
3. Added response error logging
4. Made log file names configurable via environment variables
5. Added runtime config API: listen.updateConfig() and listen.getConfig()

Requirements

• Node.js v18+ (for native fetch and modern APIs)

Configuration

Default log paths live in config/default.js. You can override them with environment variables or at runtime:

SCHARFF_OUTGOING_LOG=./outgoingRequest.log
SCHARFF_OUTGOING_ERROR_LOG=./outgoingRequestError.log
SCHARFF_INCOMING_LOG=./incomingResponse.log
SCHARFF_INCOMING_ERROR_LOG=./incomingResponseError.log

Runtime Overrides

const listen = require('scharff');

// Change any log destination at runtime
listen.updateConfig({
    outgoingLog: './logs/outgoing.log',
    outgoingErrorLog: './logs/outgoing-errors.log',
    incomingLog: './logs/incoming.log',
    incomingErrorLog: './logs/incoming-errors.log'
});

// Inspect current config
console.log(listen.getConfig());

API

• listen() – unregisters all interceptors (stops logging)
• listen.updateConfig(overrides) – update any of outgoingLog, outgoingErrorLog, incomingLog, incomingErrorLog
• listen.getConfig() – returns the current effective config

Features

• Outgoing request logging: URL, method, headers, body, local IP, timestamps
• Request error logging: errors before a request is sent
• Incoming response logging: status, URL, redirects, timestamps
• Response error logging: errors from failed responses
• Configurable destinations: via env vars or runtime API
• Runtime configuration: update settings without restarting
• IPv4 detection: includes your machine’s IPv4 in entries
• Safe JSON parsing: gracefully handles non‑JSON bodies
• Base URL stripping: store clean paths alongside full URLs
• TypeScript types: ships dist/index.d.ts

Project Structure

scharff/
├── src/
│   ├── config/default.ts     # Configuration defaults and loader
│   ├── constants/functions.ts # Helper utilities (URL manipulation)
│   ├── index.ts              # Main interceptor and API
│   └── types/fetch-intercept.d.ts
├── dist/                     # Build output (generated by `npm run build`)
├── package.json
├── tsconfig.json
└── README.md

Development / Publish

• Build: npm run build (outputs to dist/)
• Publish: npm publish --access public (runs build via prepare)
• Entry points: main → dist/index.js, types → dist/index.d.ts

Tip: Logs are newline‑delimited JSON (NDJSON). Use tools like jq, ripgrep, or grep to filter and analyze.