saxoph

A lightweight, extensible, TypeScript-first logging library for Node.js applications.

Why Another Logger?

There are already many excellent logging libraries available, such as Pino and Winston. However, Saxoph was built with a different set of goals:

• Simple and predictable API
• TypeScript-first design
• Minimal dependencies
• Extensible architecture
• Easy to understand and customize
• Suitable for learning how logging systems work internally
• Production-ready foundations without unnecessary complexity

The focus is on providing a clean logging experience while keeping the internal architecture approachable and maintainable.

Features

• Multiple log levels
• Console transport
• File transport
• JSON formatter
• Pretty formatter
• Child loggers
• Structured metadata
• Error serialization
• Multiple transports
• TypeScript support

Installation

npm install saxoph

Quick Start

import { createLogger } from 'saxoph';

import { createConsoleTransport } from 'saxoph/transports';
import { prettyFormatter } from 'saxoph/formatters';

const logger = createLogger({
  transports: [createConsoleTransport(prettyFormatter)],
});

logger.info('Application started');

Example output:

[2026-05-31T10:00:00.000Z] INFO Application started

Log Levels

Supported log levels:

trace
debug
info
warn
error
fatal

Configure the minimum log level:

const logger = createLogger({
  level: 'warn',
  transports: [createConsoleTransport(prettyFormatter)],
});

Only logs at warn level and above will be emitted.

Metadata

Attach structured metadata to log entries.

logger.info('User created', {
  userId: '123',
  email: '[email protected]',
});

Child Loggers

Create child loggers that automatically include additional metadata.

const logger = createLogger({
  transports: [createConsoleTransport(prettyFormatter)],
});

const requestLogger = logger.child({
  requestId: 'req-123',
});

requestLogger.info('Request started');
requestLogger.info('Request completed');

Every log emitted by the child logger includes the provided metadata.

Error Logging

Errors are automatically serialized.

try {
  throw new Error('Database connection failed');
} catch (error) {
  logger.error('Unable to connect to database', {
    error,
  });
}

Example output:

{
  "level": "error",
  "message": "Unable to connect to database",
  "metadata": {
    "error": {
      "name": "Error",
      "message": "Database connection failed",
      "stack": "..."
    }
  }
}

JSON Formatter

Use structured JSON logs for production environments.

import { createLogger } from 'saxoph';

import { createConsoleTransport } from 'saxoph/transports';
import { jsonFormatter } from 'saxoph/formatters';

const logger = createLogger({
  transports: [createConsoleTransport(jsonFormatter)],
});

Example output:

{
  "level": "info",
  "message": "Application started",
  "timestamp": "2026-05-31T10:00:00.000Z"
}

Pretty Formatter

Human-friendly logs for local development.

import { createLogger } from 'saxoph';

import { createConsoleTransport } from 'saxoph/transports';
import { prettyFormatter } from 'saxoph/formatters';

const logger = createLogger({
  transports: [createConsoleTransport(prettyFormatter)],
});

Example output:

[2026-05-31T10:00:00.000Z] INFO Application started

File Transport

Write logs to a file.

import { createLogger } from 'saxoph';

import { createFileTransport } from 'saxoph/transports';
import { jsonFormatter } from 'saxoph/formatters';

const logger = createLogger({
  transports: [
    createFileTransport({
      path: './logs/app.log',
      formatter: jsonFormatter,
    }),
  ],
});

Directories are created automatically if they do not exist.

Multiple Transports

Send logs to multiple destinations simultaneously.

const logger = createLogger({
  transports: [
    createConsoleTransport(prettyFormatter),
    createFileTransport({
      path: './logs/app.log',
      formatter: jsonFormatter,
    }),
  ],
});

A single log event can be written to both the console and a file at the same time.

Public API

Core

import { createLogger } from 'saxoph';

Transports

import { createConsoleTransport, createFileTransport } from 'saxoph/transports';

Formatters

import { jsonFormatter, prettyFormatter } from 'saxoph/formatters';

Example Project Setup

import { createLogger } from 'saxoph';

import { createConsoleTransport, createFileTransport } from 'saxoph/transports';

import { prettyFormatter, jsonFormatter } from 'saxoph/formatters';

export const logger = createLogger({
  level: 'info',
  transports: [
    createConsoleTransport(prettyFormatter),
    createFileTransport({
      path: './logs/app.log',
      formatter: jsonFormatter,
    }),
  ],
});

Roadmap

Future enhancements may include:

• Log file rotation
• Log retention policies
• Colorized console output
• Async transports
• HTTP transports
• Trace and span identifiers
• OpenTelemetry integration
• Custom timestamp formatting

License

MIT License. See LICENSE for details.