@wsms/logger

A lightweight TypeScript logging utility for structured file logging with flexible configuration support.

Features

• Structured logging in JSONL format
• Multiple log levels: debug, info, warn, error
• Async writes via WriteStream — non-blocking (~700k logs/sec)
• Daily log rotation with optional size limit per file
• Child loggers with inherited context
• Configuration via JSON file or environment variables
• Environment-specific configuration blocks
• Full TypeScript support with type definitions
• Zero dependencies

Installation

npm install @wsms/logger

Usage

Basic

import { createLogger } from '@wsms/logger';

const logger = createLogger({ logFilePath: './logs/app.log' });

logger.info('Application started');
logger.error('Something went wrong', { userId: 123 });

With Config File

Automatically loads logger.config.json or .loggerrc.json from the project root:

const logger = createLogger();

Custom path:

const logger = createLogger(undefined, './config/logger.json');

Rotation Options

// Daily rotation (default) — no size limit
const logger = createLogger({
  logFilePath: './logs/app.log',
});

// Daily rotation + size limit per daily file
const logger = createLogger({
  logFilePath: './logs/app.log',
  maxFileSize: 50 * 1024 * 1024, // 50 MB per daily file
  maxFiles: 5,
  maxDays: 30,
});

// Size-only rotation — no date in filename
const logger = createLogger({
  logFilePath: './logs/app.log',
  rotateByDate: false,
  maxFileSize: 10 * 1024 * 1024,
  maxFiles: 5,
});

Child Loggers

Child loggers share the parent's write stream and add default context fields to every entry:

const logger = createLogger({ logFilePath: './logs/app.log' });

const httpLogger = logger.child({ component: 'http' });
const dbLogger   = logger.child({ component: 'db' });

httpLogger.info('request received', { method: 'GET', path: '/users' });
// → {"level":"info","message":"request received","component":"http","data":{...}}

dbLogger.error('query failed');
// → {"level":"error","message":"query failed","component":"db"}

Contexts merge when nesting children:

const reqLogger = httpLogger.child({ requestId: 'abc-123' });
reqLogger.info('handler called');
// → {..., "component":"http", "requestId":"abc-123"}

Graceful Shutdown

process.on('SIGTERM', async () => {
  await logger.flush(); // drain write buffer
  await logger.close(); // close the file descriptor
  process.exit(0);
});

Configuration

Config File

Create one of these files in your project root:

• logger.config.json
• .loggerrc.json

{
  "logFilePath": "./logs/app.log",
  "maxFileSize": 10485760,
  "maxFiles": 5,
  "env": {
    "development": {
      "logFilePath": "./logs/dev.log"
    },
    "production": {
      "logFilePath": "/var/log/app.log",
      "maxFiles": 20
    },
    "test": {
      "logFilePath": "./logs/test.log",
      "maxFiles": 1
    }
  }
}

Environment Variables

Variable	Description
LOG_FILE_PATH	Path to log file
LOG_MAX_FILE_SIZE	Maximum file size in bytes
LOG_MAX_FILES	Maximum number of rotated files to keep
LOG_ROTATE_BY_DATE	Enable/disable daily rotation (true/false)
LOG_MAX_DAYS	Maximum number of daily log files to keep
NODE_ENV	Current environment (development/production/test)

LOG_FILE_PATH="./logs/app.log" LOG_MAX_DAYS=30 node app.js

Configuration Priority

1. Direct options passed to createLogger(options)
2. Configuration file
3. Environment variables
4. Default values

Log Format

Each entry is written as a single JSON line (JSONL):

{"timestamp":"2024-01-01T12:00:00.000Z","level":"info","message":"Application started"}
{"timestamp":"2024-01-01T12:00:01.000Z","level":"error","message":"Something went wrong","data":{"userId":123}}

Log Rotation

Daily (default)

A new file is created each day:

logs/app-2024-01-01.log
logs/app-2024-01-02.log

Set maxDays to automatically delete files older than N days.

Daily + size limit

Set maxFileSize to also rotate within a day:

logs/app-2024-01-01.log      ← current
logs/app-2024-01-01.log.1
logs/app-2024-01-01.log.2

Size-only (rotateByDate: false)

Classic numbered rotation — no date in filename. When the file exceeds maxFileSize:

1. Oldest file is deleted (if maxFiles reached)
2. Existing files are shifted: .log.4 → .log.5, etc.
3. Current file is renamed: app.log → app.log.1
4. Next write creates a fresh app.log

API

createLogger(options?, configPath?)

Parameter	Type	Description
options	Partial<LoggerOptions>	Direct configuration options
configPath	string	Custom path to configuration file

LoggerOptions

Option	Type	Default	Description
logFilePath	string	—	Path to log file
rotateByDate	boolean	true	Daily rotation with date in filename
maxDays	number	unlimited	Max number of daily files to keep
maxFileSize	number	unlimited	Max file size before rotating within a day
maxFiles	number	5	Max number of size-rotated files to keep

Logger Methods

Method	Description
debug(message, data?)	Log at debug level
info(message, data?)	Log at info level
warn(message, data?)	Log at warn level
error(message, data?)	Log at error level
child(context)	Create a child logger with extra default fields
flush()	Wait for write buffer to drain
close()	Close the file descriptor

Development

npm install
npm run build
npm test
npm run test:coverage
npm run lint

Related

• @wsms/logger-connect-nuxt — Nuxt 3/4 module with auto-imported useLogger() for server routes and components

License

MIT