kerolles-micro-utils

Shared utility helpers for Node.js microservices.

kerolles-micro-utils provides a small set of reusable building blocks that are commonly needed in service-to-service systems: timestamp formatting, correlation IDs, app-level errors, and JSON logs.

Features

• Date formatting using ISO 8601
• App-specific Error class with HTTP status codes
• Correlation ID generation with header fallback
• Structured JSON logger for info, warn, and error

Installation

npm install kerolles-micro-utils

Quick Start

import {
  AppError,
  formatDate,
  generateCorrelationId,
  logger,
} from "kerolles-micro-utils";

const headers = {
  "x-correlation-id": "req-123",
};

const correlationId = generateCorrelationId(headers);

logger.info("Request started", { correlationId });
logger.warn("Slow dependency", { correlationId });

const createdAt = formatDate(new Date());
logger.info(`Resource created at ${createdAt}`, { correlationId });

throw new AppError("Validation failed", 400);

API Reference

formatDate(date: Date): string

Formats a JavaScript Date as an ISO string.

formatDate(new Date());
// Example: 2026-04-08T10:12:30.123Z

generateCorrelationId(headers?: Record<string, unknown>): string

Returns the first valid, non-empty correlation ID found in headers:

• x-correlation-id
• X-Correlation-Id
• X-Correlation-ID

If no valid value is found, it generates a new UUID.

const id = generateCorrelationId(req.headers);

new AppError(message: string, statusCode = 500)

Custom error type for predictable service errors.

• name is set to AppError
• statusCode defaults to 500

throw new AppError("Unauthorized", 401);

logger

Structured logger object with three methods:

• logger.info(message, options?)
• logger.warn(message, options?)
• logger.error(message, options?)

options shape:

{
	correlationId?: string;
}

Each log is emitted as a JSON line with:

{
  "level": "info",
  "message": "Request started",
  "time": "2026-04-08T10:12:30.123Z",
  "correlationId": "req-123"
}

Output stream behavior:

• error -> console.error
• warn -> console.warn
• info -> console.log

Use Cases

• Add traceability in distributed systems with correlation IDs
• Normalize logging format for log aggregation tools
• Throw service-friendly errors with status codes
• Keep utility code centralized and reusable across services

Development

npm install
npm run build

This package is written in TypeScript and compiles to dist.

License

ISC

Author

Kerolles Sobhy