@hiprax/logger

Fully typed, production-grade logging toolkit for Node.js applications. Built on top of Winston with first-class TypeScript support, rotating file transports, timezone mirroring, and an HTTP middleware that outperforms traditional solutions.

Features

• ✅ Multi-target logging (console, per-module files, shared files, custom transports). Console output stays enabled but omits timestamps so only files capture the full timeline.
• ✅ Daily rotation with independent retention rules
• ✅ Guaranteed UTC timestamps plus optional verified IANA timezones
• ✅ Automatic log directory creation (including nested module scopes)
• ✅ Batteries-included Express middleware with structured payloads
• ✅ Zero-config ESM & CommonJS builds, rich IntelliSense docs
• ✅ Comprehensive Jest suite with 100% coverage

Installation

npm install @hiprax/logger

The package ships with precompiled dual builds. No transpilation is required in consuming projects.

Quick Start

import { createLogger } from "@hiprax/logger";

const securityLogger = createLogger({
  moduleName: "security/failedLogins",
  extraTimezones: ["Europe/London"],
});

securityLogger.warn(`Failed login attempt\nEmail: ${email}\nIP: ${req.realIp}`);

CommonJS usage is equally simple:

const { createLogger } = require("@hiprax/logger");

API

createLogger(options?: LoggerOptions)

Option	Type	Default	Description
moduleName	string	'global'	Label used in log lines and for module-specific files. Supports nested scopes (security/failedLogins).
logDirectory	string	<process.cwd()>/logs	Target directory (auto-created).
level	LogLevel	'info'	Default level for all transports.
consoleLevel	LogLevel	level	Console-specific level.
includeConsole	boolean	true	Enables console logging. Console lines omit timestamps; files keep the full multi-timezone output.
includeFile	boolean	true	Enables module-specific rotating file logging.
includeGlobalFile	boolean	true	Enables shared rotating file logging.
globalModuleName	string	'all-logs'	Label for the shared log file.
extraTimezones	string | string[]	[]	Additional IANA zones to render beside UTC. Validity is enforced.
rotation	RotationStrategy	20 MB / 14 days / daily	Rotation config for the module file.
globalRotation	RotationStrategy	rotation	Override rotation for the shared file.
additionalTransports	winston.transport[]	[]	Appends custom transports (e.g., HTTP, Kafka).

RotationStrategy

interface RotationStrategy {
  maxSize?: string; // e.g., '20m', '200k'
  maxFiles?: string; // e.g., '14d', '30'
  datePattern?: string; // default: 'YYYY-MM-DD'
  zippedArchive?: boolean;
}

Request Logging Middleware

import express from "express";
import { createRequestLogger } from "@hiprax/logger";

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

app.use(
  createRequestLogger({
    includeRequestBody: true,
    includeRequestHeaders: ["authorization"],
    includeResponseHeaders: true,
    maskBodyKeys: ["password", "token"],
    enrich: (req) => ({ tenantId: req.headers["x-tenant-id"] }),
  }),
);

When includeHttpContext is enabled, the middleware attaches rich structured metadata via info.http while emitting a concise human-readable message. It relies on plain Node events (finish/close) and does not depend on on-finished, keeping the surface secure and modern.

Option	Type	Default	Description
logger	winston.Logger	Scoped http logger	Provide your own logger or reuse the scoped one.
level	LogLevel | (status: number) => LogLevel	Auto (info/warn/error)	Override severity per response.
label	string	'http'	Included in the auto-generated logger name (http/<label>).
messageBuilder	(entry) => string	"METHOD URL status latency (event)"	Customize the final message string.
skip	(req, res) => boolean	false	Allowlist/denylist support.
enrich	(req, res, durationMs) => Record<string, unknown>	undefined	Inject extra context (e.g., tenant, user).
includeRequestHeaders	boolean | string[]	false	Toggle or limit header emission.
includeResponseHeaders	boolean | string[]	false	Same as above for responses.
includeRequestBody	boolean	false	Logs parsed body (with redaction).
maskBodyKeys	string[]	[]	Keys replaced with [REDACTED]. Applies deeply, including arrays.
maxBodyLength	number	3000	Caps serialized body size to prevent log floods.
includeHttpContext	boolean	false	Adds the structured payload under info.http.
loggingEnabled	boolean	true	Hard enable/disable switch.
loggingMode	RequestLoggingMode	'always'	Env-aware control. Supports 'dev-only', 'prod-only', 'test-only', or custom rules.

Environment-aware request logging

• Use loggingMode: 'dev-only' to automatically log when NODE_ENV, APP_ENV, or ENV equals dev, development, or local (case-insensitive).
• Use loggingMode: 'prod-only' to emit logs exclusively when the env matches prod, production, or live.
• Use loggingMode: 'test-only' to limit logging to test, testing, qa, or staging.
• Provide a custom configuration, e.g.:

  loggingMode: { sources: ["DEPLOYMENT_STAGE"], allow: ["staging", "qa"], fallback: false }

• Pair loggingEnabled with boolean expressions (loggingEnabled: process.env.FEATURE_LOGS === "on") for one-line toggles.
• Keep log output lightweight unless needed by turning includeHttpContext on only when you want the structured payload.

Timezone Handling

• UTC is always logged.
• Additional zones must be valid IANA identifiers (moment-timezone validation). Invalid entries throw InvalidTimezoneError.
• Provide a single string or an array: extraTimezones: ['Europe/London', 'America/New_York'].

Custom Transports

import { PassThrough } from "node:stream";
import winston from "winston";

const capture = new PassThrough();
const logger = createLogger({
  moduleName: "audit",
  includeConsole: false,
  includeFile: false,
  includeGlobalFile: false,
  additionalTransports: [new winston.transports.Stream({ stream: capture })],
});

Scripts

Command	Description
npm run build	Generates dual ESM/CJS bundles plus type declarations.
npm test	Runs Jest with 100% coverage enforcement.

Testing & Coverage

npm test

• ts-jest compiles TypeScript on the fly.
• Coverage thresholds are locked at 100% global branches/functions/lines/statements.

Security Notes

• All filesystem interactions are sandboxed to the configured log directory.
• Timezones are validated against the Moment timezone database before use.
• Sensitive request payload fields can be masked recursively via maskBodyKeys.

Contributing

1. Clone the repo and install dependencies.
2. Run npm test to ensure the suite passes before submitting changes.
3. Follow the existing TypeScript, linting, and documentation patterns.

📄 License

MIT License - see LICENSE file for details.

🔗 Links

• NPM Package
• GitHub Repository
• Issue Tracker

---

Made with ❤️ for secure applications