@eliware/log

A minimal, flexible logging library for Node.js, built on top of winston. Supports ESM, with TypeScript types included.

Table of Contents

• Features
• Installation
• Usage
  • ESM Example
  • API
• TypeScript
• Errors / Troubleshooting
• Development
• Operations
• Support
• License
• Links

Features

• Simple, consistent logging API for Node.js
• Built on winston
• Supports ESM
• Default and named exports for maximum flexibility
• TypeScript type definitions included
• Supports structured JSON output with optional timestamps
• Supports child loggers with persistent context
• Serializes Error objects with name, message, and stack
• Supports configurable metadata redaction
• Exports safeSerialize for defensive metadata summarization
• Supports logging primitives and arrays as meta:
  • log.info('msg', 42) logs { value: 42 }
  • log.info('msg', [1,2,3]) logs { value: [1,2,3] }

Requirements

• Node.js 26 or newer

Installation

npm install @eliware/log

Usage

ESM Example

// Example usage for ESM
import log, { log as namedLog, createLogger } from '@eliware/log';

log.info('Hello from example.mjs (default import)', { foo: 'bar' });
log.info('Primitive value', 42); // primitive value
log.info('Array value', [1,2,3]); // array value

namedLog.info('Hello from example.mjs (named import)', { foo: 'bar' });
namedLog.info('Primitive value', 'test'); // primitive value

const customLogger = createLogger({ level: 'debug' });
customLogger.debug('Custom logger debug message', { custom: true });
customLogger.debug('Primitive debug', true); // primitive value

API

log (default and named export)

A pre-configured logger instance. Available as both the default and a named export (log).

• .info(message, meta?)
• .debug(message, meta?)
• .warn(message, meta?)
• .error(message, meta?)
• ...and all other winston logger methods.

Meta argument:

• If you pass a primitive or array as the second argument, it will be logged as { value: ... }.
• If you pass an object, it will be logged as usual.

createLogger(options)

Creates a new winston logger instance.

Options:

• level (string): Log level (default: process.env.LOG_LEVEL or 'info')
• transports (array): Array of winston transports (default: Console)
• format (text or json): Output format (default: text)
• timestamp (boolean): Include timestamps in JSON output (default: false)
• redactKeys (string[]): Metadata keys to redact, case-insensitively

Returns: a winston.Logger with the configured transports, format, timestamp behavior, and redaction rules.

safeSerialize(value, redactKeys?)

Safely summarizes a value for logging without invoking toJSON or expanding arbitrary nested objects. Errors intentionally include only their name, message, and stack; enumerable custom Error properties are omitted. Functions, BigInts, arrays, circular references, and hostile property access are handled defensively. Arrays are preserved recursively, while ordinary nested objects are reduced to a safe type/id/name summary; circular values encountered during traversal are replaced with [Circular]. Pass a Set of keys to redact matching object keys and Error fields; keys are normalized case-insensitively for both direct safeSerialize calls and createLogger. JSON-format redaction covers enumerable string-keyed metadata present when Winston formats the record; transport-added metadata is outside this boundary.

TypeScript

Type definitions are included:

export declare function createLogger(options?: {
  level?: string;
  transports?: import('winston').Transport[];
  format?: 'text' | 'json';
  timestamp?: boolean;
  redactKeys?: string[];
}): import('winston').Logger & {
  debug(message: string, meta?: unknown): void;
  info(message: string, meta?: unknown): void;
  warn(message: string, meta?: unknown): void;
  error(message: string, meta?: unknown): void;
};
export type SafeSerializedValue = null | boolean | number | string | SafeSerializedValue[] | { [key: string]: SafeSerializedValue };
export declare function safeSerialize(value: unknown, redactKeys?: Set<string>): SafeSerializedValue;
export declare const log: import('winston').Logger & {
  debug(message: string, meta?: unknown): void;
  info(message: string, meta?: unknown): void;
  warn(message: string, meta?: unknown): void;
  error(message: string, meta?: unknown): void;
};
export default log;

Errors / Troubleshooting

Use redactKeys for sensitive metadata. Ordinary nested objects are summarized rather than recursively expanded, while arrays are preserved and circular values encountered during traversal are replaced with [Circular]. Error fields are also subject to redaction. JSON output includes timestamps only when timestamp: true; text output safely summarizes objects and serializes BigInt values. Configure transports explicitly for tests and alternate destinations. safeSerialize returns a recursive SafeSerializedValue shape; functions and unsupported values are represented by safe strings.

Development

npm test
npm run lint
npm run typecheck
npm audit --omit=dev --audit-level=moderate
npm run pack

Operations

The package has no import-time external I/O. Inject Winston transports with createLogger() for application-specific destinations and configure LOG_LEVEL or the explicit level option for runtime verbosity. CI validates tests, lint, type declarations, dependency security, and package contents on Ubuntu and Windows; the deployment definition runs the same checks after a deployment trigger. Metadata is sanitized eagerly before formatting so records are deterministic even when a transport later filters them by level.

Security

Do not log secrets or sensitive payloads. Configure redactKeys for credential-bearing metadata and review custom transports before enabling them.

Support

For help, questions, or to chat with the author and community, visit:

eliware.org on Discord

License

MIT © 2025 Eli Sterling, eliware.org

Links

• Home Page
• GitHub
• npm
• Discord
• Winston Logger