batch-stdout

Small batch stdout logger built on top of Sonic Boom.

Features

• Batching: Buffers logs up to a configurable size before writing, reducing stdout overhead.
• Log Levels: Supports debug, info, warning, error, and disabled.
• Injection: Easily inject metadata (like timestamps, trace IDs).
• Pretty Printing: Optional pretty-printed log outputs.

---

Installation

npm install batch-stdout

---

Usage

Basic Setup

import { logger } from "batch-stdout";

const log = logger({
    batchSizeMb: 1,
});

log.info("Hello, world!");
log.error("Something went wrong.");

Custom Options

const log = logger({
    batchSizeMb: 1, // maximum batch size in MB
    logLevel: "info", // "debug" | "info" | "warning" | "error" | "disabled"
    inject: () => ({
        timestamp: new Date().toISOString(),
        traceId: "abc123"
    }),
    isPrettyPrint: true, // pretty print output
    batchWindowMs: 10 // ms to flush logs if no new logs are added within timeframe
});

// You can add contextual data:
log.info("Processed user", { userId: 42, user: "alice" });
log.warning("Slow request", { ms: 5123 });
log.debug("Debug details", { meta: { ... } });

Log Levels

• debug, info, warning, error
  Only messages at or above the set logLevel are logged.
• Use disabled to turn off all logging.

---

API

logger(options?) → Logger

Options

Name	Type	Default	Description
batchLimitType	string	"size"	Whether to limit batch to megabytes ("size") or item count ("count")
batchLimit	number	0.25	Depending on limit type either megabytes or count of items
logLevel	string	"debug"	Log level filter
inject	function	undefined	Injected metadata for every log
isPrettyPrint	boolean	false	Use JSON pretty printing
batchWindowMs	number	0	Flush logs after timeframe. 0 is disabled

Logger methods

• log.debug(...args)
• log.info(...args)
• log.warning(...args)
• log.error(...args)

Each accepts any serializable argument(s).

Benchmark

Benchmark done using a benchmark script, comparing console.log, process.stdout.write, pino, and raw sonic-boom to this library. 1000 iterations of a log fixture

"batch-stdout": "2.06ms",
"batch-stdout with injection & pretty-print": "5.15ms",
"console.log": "196.62ms",
"process.stdout.write": "51.83ms",
"process.stdout.write with pretty-print": "154.57ms",
"sonic-boom": "1.59ms",
"pino": "3.86ms"

---

License

MIT @OkayestDev