smart-http-res

A lightweight, framework-agnostic TypeScript middleware for Bun (native Bun.serve / Fetch API) and Node.js (Express).

It provides automatic response sanitization (XSS escaping, sensitive key stripping/masking), standardized response envelopes with HTTP method metadata, and structured error payloads.

Features

• 🛡️ Data Sanitization: Deeply strips or masks sensitive fields (e.g. password, token, apiKey, creditCard) and escapes XSS entities.
• 📦 Unified Response Envelopes: Consistent { success, method, statusCode, data, meta } structure.
• 🏷️ Method Hints: Automatically attaches HTTP semantics (action, isSafe, isIdempotent) to response metadata.
• 🚨 Standard Error Mapping: Maps HTTP 4xx/5xx status codes into clean, structured error responses.
• ⚡ Native Bun & Node Support: First-class support for Bun.serve and Node.js Express.

Installation

# Bun
bun add smart-http-res

# npm
npm install smart-http-res

Quick Start

1. Bun (Bun.serve / Fetch API)

import { smartFetchHandler } from "smart-http-res";

Bun.serve({
  port: 3000,
  fetch: smartFetchHandler(async (req) => {
    const url = new URL(req.url);

    if (url.pathname === "/api/user") {
      return Response.json({
        name: "Alice",
        password: "super-secret-password", // Stripped automatically
      });
    }

    return Response.json({ error: "Not Found" }, { status: 404 });
  }),
});

2. Node.js (Express)

import express from "express";
import { expressSmartHttp } from "smart-http-res";

const app = express();
app.use(express.json());
app.use(expressSmartHttp());

app.get("/api/user", (req, res) => {
  res.json({ name: "Alice", token: "secret-jwt-token" }); // token stripped automatically
});

app.listen(3000);

Response Structure

Success Response (200 OK)

{
  "success": true,
  "method": "GET",
  "statusCode": 200,
  "timestamp": "2026-08-24T10:00:00.000Z",
  "data": {
    "name": "Alice"
  },
  "meta": {
    "methodHint": {
      "action": "READ_RETRIEVAL",
      "description": "Resource query or data fetch operation",
      "isIdempotent": true,
      "isSafe": true
    },
    "path": "/api/user"
  }
}

Error Response (401 Unauthorized)

{
  "success": false,
  "method": "POST",
  "statusCode": 401,
  "timestamp": "2026-08-24T10:00:00.000Z",
  "error": {
    "message": "Unauthorized: Authentication is required and has failed or has not been provided.",
    "code": "UNAUTHORIZED"
  },
  "meta": {
    "methodHint": {
      "action": "RESOURCE_CREATION_ACTION",
      "description": "Resource creation, command execution, or submission",
      "isIdempotent": false,
      "isSafe": false
    },
    "path": "/api/login"
  }
}

Configuration Options

Pass options to smartFetchHandler or expressSmartHttp:

smartFetchHandler(handler, {
  // Track handler execution time in response meta
  trackDuration: true,

  // Sanitizer customization
  sanitize: {
    maskWith: "[REDACTED]", // Mask sensitive keys instead of removing them
    stripKeys: ["customSecret", "pin"], // Additional keys to redact
    escapeHtml: true, // Escape HTML entities (default: true)
    removeEmptyFields: false, // Strip undefined/null properties
  },

  // Override status code messages
  statusErrorMessages: {
    404: "Resource not found in database",
  },
});

Development

# Run tests
bun test

# Build package
bun run build