@20syldev/logger.ts

A minimalist Node.js module to generate, format, and serve structured logs as JSON.

Installation

npm install @20syldev/logger.ts

Usage

Import

import { createLogger } from "@20syldev/logger.ts";

Create a logger

const logger = createLogger({
    maxEntries: 500,
    order: "desc",
    theme: "detailed",
});

Log entries

logger.log({
    method: "GET",
    url: "/api/users",
    status: 200,
    duration: "45ms",
});

Log from Node.js request/response

import http from "node:http";

const logger = createLogger();

http.createServer((req, res) => {
    const start = Date.now();
    res.end("OK");
    logger.request(req, res, { duration: `${Date.now() - start}ms` });
}).listen(8080);

Serve logs as JSON API

logger.serve(3000);
// → http://127.0.0.1:3000 returns JSON array of logs

Query parameters for ordering and filtering:

GET /?order=desc&sort=timestamp
GET /?limit=50&status=200&method=GET
GET /?_group=auth

Health check

GET /health → { "ok": true, "count": 42 }

Groups

const auth = logger.group("auth");
auth.log({ method: "POST", url: "/login", status: 200 });
// Console: [auth] 12:34:56 ✓ POST /login → 200
// Entry includes _group: "auth"

Events

logger.on("log", (entry) => {
    if (entry.status >= 500) sendAlert(entry);
});

logger.on("clear", () => console.log("Logs cleared"));

Console themes

Built-in themes: minimal, colored (default), detailed, plain.

// Use a preset
const logger = createLogger({ theme: "detailed" });

// Custom theme
const logger = createLogger({
    theme: {
        format: "{time} {icon} {method} {url} → {status} ({duration})",
        colors: {
            timestamp: "\x1b[90m",
            method: "\x1b[36m",
            status2xx: "\x1b[32m",
            status5xx: "\x1b[31m",
        },
        icons: {
            success: "✓",
            serverError: "✗",
        },
    },
});

// Disable console output
const logger = createLogger({ console: false });

// Manual print
logger.print(entry);

Details

createLogger(options)

Creates a logger instance with the following options:

| Option | Default | Description | |---|---|---| | maxEntries | 1000 | Maximum logs in memory (FIFO eviction) | | cors | "*" | CORS origin header for serve() | | order | "asc" | Default sort order ("asc" or "desc") | | sort | "timestamp" | Default sort field | | console | true | Auto-print to console on each .log() | | theme | "colored" | Theme preset name, custom theme object, or false to disable | | maxAge | null | TTL in seconds (auto-removes old entries) | | timeFormat | "time" | Timestamp format: "time", "iso", "locale", "date", "datetime", "utc", or (date: Date) => string |

Methods

| Method | Description | |---|---| | .log(entry) | Adds a structured entry. Auto-adds timestamp if missing. Returns the entry or null. | | .request(req, res, extras) | Logs from Node.js HTTP objects. Returns the entry or null. | | .print(entry) | Manually prints an entry to console. | | .entries() | Returns all stored logs (sorted, TTL-filtered). | | .clear() | Removes all stored logs. | | .serve(port) | Starts an HTTP server serving logs as JSON. | | .group(name) | Creates a sub-logger with a namespace. | | .on(event, cb) | Listens to events ("log", "clear"). | | .off(event, cb) | Removes an event listener. |

Public exports

Beyond createLogger, the module exposes utilities and types for advanced usage:

import {
    createLogger,
    // Theme utilities
    themes,          // Record of built-in theme presets
    resolveTheme,    // Resolve a theme name or config into a Theme object
    defaultColors,   // Default ANSI color palette
    defaultIcons,    // Default status icons
    // Event bus
    createEventBus,  // Standalone event emitter (used internally)
} from "@20syldev/logger.ts";

TypeScript types:

import type {
    LogEntry,
    Logger,
    SubLogger,
    LoggerOptions,
    Theme,
    CustomTheme,
    ThemeColors,
    ThemeIcons,
    TimeFormat,
    LoggerEvent,
    EventCallback,
    EventBus,
    ServeContext,
} from "@20syldev/logger.ts";