npm package: @napp/logger
Description: low level log archigture. minimum resources, user friendly, powerfull logger library. supported browser & nodejs
Author: farcek@gmail.com
Latest version: 4.1.9

# @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

```bash
npm install @napp/logger
```

## Quick Start

```ts
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

```ts
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

```ts
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