@beecode/msh-logger

Micro-service helper: logging abstraction using the Strategy Pattern

A TypeScript logging abstraction that decouples formatting from transport. Built on the Strategy Pattern with pluggable formatting strategies, transporting strategies, and ready-made presets for common setups.

• Install
• Quick Start
• Architecture
  • Diagram
  • Format-Transport Separation
• Log Levels
• Presets
  • PresetConsoleSimpleString
  • PresetConsoleJson
  • PresetPino
  • PresetVoid
• Formatting Strategies
  • FormattingStrategySimpleString
  • FormattingStrategyJson
• Transporting Strategies
  • TransportingStrategyConsole
  • TransportingStrategyPino
  • TransportingStrategyStream
  • TransportingStrategyVoid
• Custom LoggerStrategyBase
• Creating Child Loggers (clone)
• API Reference
• Migrating from v1 to v2
• License

Install

npm i @beecode/msh-logger

Quick Start

import { LogLevel } from '@beecode/msh-logger'
import { PresetConsoleSimpleString } from '@beecode/msh-logger/controller/preset/console-simple-string'

const logger = new PresetConsoleSimpleString({ logLevel: LogLevel.INFO })

logger.debug('This is hidden') // filtered out (below INFO)
logger.info('Server started', { port: 3000 })
logger.warn('Deprecation warning')
logger.error('Something went wrong', new Error('boom'))

Output:

2026-05-30T12:00:00.000Z - INFO: Server started { port: 3000 }
2026-05-30T12:00:00.000Z - WARN: Deprecation warning
2026-05-30T12:00:00.000Z - ERROR: Something went wrong Error: boom

Architecture

Diagram

Format-Transport Separation

The logger is built on two independent, composable strategy layers:

• FormattingStrategy — transforms log data (level, meta, category, timestamp) plus messages into structured FormattedLog[] objects.
• TransportingStrategy — receives FormattedLog objects and writes them to a destination (console, Pino, stream, etc.).

The LoggerStrategyBase composes one of each. Presets pre-wire common combinations so you don't have to think about the two layers individually.

src/
├── business/
│   ├── model/
│   │   └── log-level.ts                         # LogLevel enum
│   └── service/
│       ├── logger-strategy.ts                    # LoggerStrategy interface
│       ├── logger-strategy/
│       │   └── base.ts                           # LoggerStrategyBase
│       ├── formatting-strategy.ts                # FormattingStrategy interface
│       ├── formatting-strategy/
│       │   ├── simple-string.ts                  # FormattingStrategySimpleString
│       │   └── json.ts                           # FormattingStrategyJson
│       ├── transporting-strategy.ts              # TransportingStrategy interface
│       └── transporting-strategy/
│           ├── console.ts                        # TransportingStrategyConsole
│           ├── pino.ts                           # TransportingStrategyPino
│           ├── stream.ts                         # TransportingStrategyStream
│           └── void.ts                           # TransportingStrategyVoid
└── controller/preset/                       # Pre-wired presets
    ├── console-simple-string.ts             # PresetConsoleSimpleString
    ├── console-json.ts                      # PresetConsoleJson
    ├── pino.ts                              # PresetPino
    └── void.ts                              # PresetVoid

Presets (convenience wrappers):

| Preset | Formatting | Transporting | |--------|-----------|-------------| | PresetConsoleSimpleString | FormattingStrategySimpleString | TransportingStrategyConsole | | PresetConsoleJson | FormattingStrategyJson | TransportingStrategyConsole | | PresetPino | FormattingStrategyJson | TransportingStrategyPino | | PresetVoid | — | — (no-op) |

Log Levels

The LogLevel enum controls which messages are emitted. Higher numeric severity means more critical:

| Level | Value | Description | |-------|-------|-------------| | LogLevel.FATAL | 60 | Unrecoverable — the process must terminate | | LogLevel.ERROR | 50 | Unexpected failure — a feature failed but the process can continue | | LogLevel.WARN | 40 | Degraded behavior — unexpected but recoverable | | LogLevel.INFO | 30 | Business-significant events — service started, user logged in | | LogLevel.DEBUG | 20 | Diagnostic detail — request/response payloads, branching decisions | | LogLevel.TRACE | 10 | Fine-grained flow — function entry/exit, variable dumps |

When a logger is created, it defaults to LogLevel.ERROR (most restrictive). Any log at or above the configured level is emitted; lower levels are silently dropped.

Presets

Presets are the easiest way to get started. Each pre-wires a specific formatting + transporting combination.

PresetConsoleSimpleString

Human-readable console output with timestamps. Good for local development.

import { LogLevel } from '@beecode/msh-logger'
import { PresetConsoleSimpleString } from '@beecode/msh-logger/controller/preset/console-simple-string'

const logger = new PresetConsoleSimpleString({
  logLevel: LogLevel.DEBUG,
  category: 'my-app',
  meta: { service: 'api', version: '1.0.0' },
})

Constructor params (inherits LoggerStrategyParams, omits strategies):

| Param | Type | Default | Description | |-------|------|---------|-------------| | logLevel | LogLevel | LogLevel.ERROR | Minimum log level to emit | | category | string | undefined | Category label added to every log entry | | meta | ObjectType | undefined | Metadata attached to every log entry |

Output format:

2026-05-30T12:00:00.000Z - INFO: [my-app] Hello world

PresetConsoleJson

JSON-formatted console output. Good for structured log ingestion.

import { LogLevel } from '@beecode/msh-logger'
import { PresetConsoleJson } from '@beecode/msh-logger/controller/preset/console-json'

const logger = new PresetConsoleJson({
  logLevel: LogLevel.INFO,
  category: 'my-app',
  meta: { service: 'api' },
})

Constructor params: same as PresetConsoleSimpleString.

Output format:

{"level":"INFO","timestamp":1748606400000,"category":"my-app","message":"Hello world"}

When meta is provided, it is spread into the JSON payload:

{"service":"api","level":"INFO","timestamp":1748606400000,"category":"my-app","message":"Hello world"}

PresetPino

Production-grade logging via Pino. Delegates formatting and transport to the Pino library.

import { LogLevel } from '@beecode/msh-logger'
import { PresetPino } from '@beecode/msh-logger/controller/preset/pino'

const logger = new PresetPino({
  logLevel: LogLevel.INFO,
})

Constructor params (PresetPinoParams):

| Param | Type | Default | Description | |-------|------|---------|-------------| | logLevel | LogLevel | LogLevel.ERROR | Minimum log level to emit | | category | string | undefined | Category label added to every log entry | | meta | ObjectType | undefined | Metadata attached to every log entry | | pinoLogger | pino.Logger | pino() | Custom Pino logger instance |

PresetVoid

The default no-op logger. All log calls are silently ignored — useful for testing or disabling logging entirely.

import { PresetVoid } from '@beecode/msh-logger/controller/preset/void'

const logger = new PresetVoid()

logger.info('This does nothing')
logger.error('Neither does this')

Formatting Strategies

Formatting strategies transform raw log data into FormattedLog[] objects. Each FormattedLog contains a level, message, and optional metadata.

FormattingStrategySimpleString

Human-readable format with timestamps. Produces messages like 2026-05-30T12:00:00.000Z - INFO: [category] message.

import { FormattingStrategySimpleString } from '@beecode/msh-logger/business/service/formatting-strategy/simple-string'

const formatter = new FormattingStrategySimpleString()

FormattingStrategyJson

Structured JSON format. Extracts message from objects and spreads remaining keys into metadata.

import { FormattingStrategyJson } from '@beecode/msh-logger/business/service/formatting-strategy/json'

const formatter = new FormattingStrategyJson()

Transporting Strategies

Transporting strategies receive FormattedLog objects and write them to a destination.

TransportingStrategyConsole

Writes to console.* methods, mapping log levels to the appropriate console function.

import { TransportingStrategyConsole } from '@beecode/msh-logger/business/service/transporting-strategy/console'

const transport = new TransportingStrategyConsole()

TransportingStrategyPino

Sends logs to a Pino logger instance. Optionally inject a custom Pino logger; defaults to pino().

import { TransportingStrategyPino } from '@beecode/msh-logger/business/service/transporting-strategy/pino'

const transport = new TransportingStrategyPino() // uses default pino()
// or with a custom instance:
// const transport = new TransportingStrategyPino(customPinoLogger)

TransportingStrategyStream

Writes JSON-stringified FormattedLog to any NodeJS.WritableStream. Useful for piping logs to files, HTTP streams, or custom destinations.

import { createWriteStream } from 'node:fs'
import { TransportingStrategyStream } from '@beecode/msh-logger/business/service/transporting-strategy/stream'

const stream = createWriteStream('./app.log')
const transport = new TransportingStrategyStream(stream)

TransportingStrategyVoid

No-op transport. Silently drops all logs.

import { TransportingStrategyVoid } from '@beecode/msh-logger/business/service/transporting-strategy/void'

const transport = new TransportingStrategyVoid()

Custom LoggerStrategyBase

Combine any formatting strategy with any transporting strategy to build a custom logger:

import { LogLevel } from '@beecode/msh-logger'
import { LoggerStrategyBase } from '@beecode/msh-logger/business/service/logger-strategy/base'
import { FormattingStrategyJson } from '@beecode/msh-logger/business/service/formatting-strategy/json'
import { TransportingStrategyStream } from '@beecode/msh-logger/business/service/transporting-strategy/stream'
import { createWriteStream } from 'node:fs'

const logger = new LoggerStrategyBase({
  formattingStrategy: new FormattingStrategyJson(),
  transportingStrategy: new TransportingStrategyStream(createWriteStream('./app.log')),
  logLevel: LogLevel.DEBUG,
  category: 'my-service',
  meta: { env: 'production' },
})

Constructor params (LoggerStrategyBaseParams):

| Param | Type | Default | Description | |-------|------|---------|-------------| | formattingStrategy | FormattingStrategy | — (required) | Strategy for formatting log data | | transportingStrategy | TransportingStrategy | — (required) | Strategy for transporting formatted logs | | logLevel | LogLevel | LogLevel.ERROR | Minimum log level to emit | | category | string | undefined | Category label added to every log entry | | meta | ObjectType | undefined | Metadata attached to every log entry |

Creating Child Loggers (clone)

Use clone() to create a child logger that inherits settings from a parent, with optional overrides:

import { LogLevel } from '@beecode/msh-logger'
import { PresetConsoleSimpleString } from '@beecode/msh-logger/controller/preset/console-simple-string'

const parent = new PresetConsoleSimpleString({
  logLevel: LogLevel.INFO,
  category: 'app',
  meta: { service: 'api' },
})

// Child inherits everything, overrides category and adds meta
const child = parent.clone({
  category: 'app:router',
  meta: { route: '/users' },
})

child.info('User listed')
// Meta is shallow-merged: { service: 'api', route: '/users' }

API Reference

Full API documentation is generated with TypeDoc and available in resource/doc/api/.

Public exports (from @beecode/msh-logger):

| Export | Kind | Description | |--------|------|-------------| | LogLevel | enum | Log level values: FATAL, ERROR, WARN, INFO, DEBUG, TRACE | | LoggerStrategy | interface | Contract for all logger implementations | | LoggerStrategyParams | type | Params for configuring loggers and clone() | | ObjectType | type | Record<string, unknown> — metadata bag |

Formatting types (from @beecode/msh-logger/business/service/formatting-strategy):

| Export | Kind | Description | |--------|------|-------------| | FormattedLog | type | Intermediate structure: { level, message, metadata? } | | FormattingStrategy | interface | Contract for formatting strategies |

Preset imports (via subpath):

| Import path | Export | |-------------|--------| | @beecode/msh-logger/controller/preset/console-simple-string | PresetConsoleSimpleString | | @beecode/msh-logger/controller/preset/console-json | PresetConsoleJson | | @beecode/msh-logger/controller/preset/pino | PresetPino | | @beecode/msh-logger/controller/preset/void | PresetVoid |

Formatting strategy imports (via subpath):

| Import path | Export | |-------------|--------| | @beecode/msh-logger/business/service/formatting-strategy/json | FormattingStrategyJson | | @beecode/msh-logger/business/service/formatting-strategy/simple-string | FormattingStrategySimpleString |

Transporting strategy imports (via subpath):

| Import path | Export | |-------------|--------| | @beecode/msh-logger/business/service/transporting-strategy/console | TransportingStrategyConsole | | @beecode/msh-logger/business/service/transporting-strategy/pino | TransportingStrategyPino | | @beecode/msh-logger/business/service/transporting-strategy/stream | TransportingStrategyStream | | @beecode/msh-logger/business/service/transporting-strategy/void | TransportingStrategyVoid |

Base class import (via subpath):

| Import path | Export | |-------------|--------| | @beecode/msh-logger/business/service/logger-strategy/base | LoggerStrategyBase, LoggerStrategyBaseParams |

Migrating from v1 to v2

See MIGRATION.md for a complete guide covering all breaking changes and code examples.

License

MIT