@napp/logger

Low-overhead, extensible logger core for Node.js and modern browsers.

• Runtime dependency-free
• Hierarchical logger names (app.core.api)
• Writer routing with filterLogname + filterLevel
• Pluggable levelParser and errorParser
• Full + short methods: trace/debug/info/warn/error/fatal and t/d/i/w/e/f
• TypeScript types included (dist/index.d.ts)

Install

npm install @napp/logger

Quick Start

import { LogManager, LogLevel, getLogger } from '@napp/logger';

const manager = new LogManager();

manager.addWriter({
  writerName: 'console',
  filterLogname: 'app',
  filterLevel: LogLevel.Warn,
  doWriter: (log) => {
    console.log(
      `[${log.levelText}] ${log.logname} ${log.message}`,
      log.attr
    );
  }
});

LogManager.setDefault(manager);

const logger = getLogger('app.core');
logger.info('not written (below Warn)');
logger.warn('written', { module: 'bootstrap' });
logger.error('failed');

Core Concepts

LogManager

• Owns writers and dispatches each ILogItem
• addWriter({ writerName?, filterLogname?, filterLevel?, doWriter })
• removeWriter(writerName)
• Global default manager:
  • LogManager.setDefault(manager)
  • LogManager.getDefault()

Logger

Created from:

• manager.factory(logname, opt?), or
• getLogger(logname, opt?) (requires default manager)

Main methods:

• trace/debug/info/warn/error/fatal
• aliases: t/d/i/w/e/f
• log(level: string | number, message, attr?)
• errorThrow(err, message, attr?)
• child(childName, { inheritBaseAttr?, baseAttr?, errorParser?, levelParser? })
• isLevelEnabled(level)

Writer Filtering

• filterLogname: string | string[]
  • Prefix match on logger path
  • Example: app.core matches app.core and app.core.repo
• filterLevel: LogLevel | string
  • Minimum accepted severity for that writer

Levels

LogLevel values:

• Trace = 1
• Debug = 5
• Info = 9
• Warn = 13
• Error = 17
• Fatal = 21

Helpers:

• LogManager.getSeverityText(level) -> TRACE|DEBUG|INFO|WARN|ERROR|FATAL
• Built-in parser accepts:
  • strings: trace|debug|info|warn|error|fatal
  • numeric ranges (mapped to nearest level band)

Attributes and Error Handling

ILogItem includes:

• timestamp
• level
• levelText
• logname
• logpath
• message
• attr?

Attribute sanitization behavior:

• Date -> ISO string
• Error -> parsed with active errorParser
• arrays/objects -> recursively sanitized

Custom Parsers

import { LogLevel, LogManager } from '@napp/logger';

// Level parser for logger.log(level, ...)
LogManager.setDefaultLevelParser((level) => {
  if (level === 'notice') return LogLevel.Info;
  return false;
});

// Error parser for logger.errorThrow(...)
LogManager.setDefaultErrorParser((error) => ({
  name: error.name,
  message: error.message,
  stack: error.stack
}));

API Snapshot

import {
  LogManager,
  LogLevel,
  getLogger,
  type ILogItem,
  type IAttrObject,
  type IError,
  type IErrorParser,
  type ILevelParser
} from '@napp/logger';

Notes

• Package exports both ESM and CJS builds
• Development/test engine in package.json: Node >=22
• Works in browser and Node.js (writer implementation is user-defined)

License

MIT