@apihive/logger-facade

A tiny, framework-agnostic logging facade that standardizes how libraries and applications log.

• Unify logging behind a minimal interface (LoggerFacade + LogLevel).
• Delegate the actual logging to the library of your choice (pino, winston, console, etc.).
• Swap or configure loggers per environment without changing your code.

The core idea: any app/module using this facade delegates logging to a single, unified logger chosen by the project. Libraries depend on the facade – applications decide which logger implementation to plug in.

Why this package?

• Consistency: Libraries and modules don’t need to pick a logging engine. They depend on the facade; your application provides the implementation.
• Flexibility: Swap implementations (console in the browser, pino in Node, mocked logger in tests) without refactoring call sites.
• Simplicity: A minimal API covering common levels and a withMinimumLevel filter.
• Portability: Works in Node, Bun, Deno, and browsers.

Ready made facades

• ConsoleLogger (built-in)
• PinoLoggerFacade for the popular pino logger

Install

npm:

npm i @apihive/logger-facade

yarn:

yarn add @apihive/logger-facade

Deno (via JSR):

import { LoggerFacade, ConsoleLogger } from "jsr:@apihive/logger-facade";

Quick start

import { ConsoleLogger } from "@apihive/logger-facade";

const logger = new ConsoleLogger().withMinimumLevel("info");

logger.debug("hidden"); // filtered out
logger.info("hello world");
logger.error("something went wrong", { code: 123 });

API

export type LogLevel = "none" | "trace" | "debug" | "info" | "warn" | "error" | "fatal";

export type LoggerFacade = {
  withMinimumLevel(level: LogLevel): LoggerFacade;
  trace(message: string, ...args: any[]): void;
  debug(message: string, ...args: any[]): void;
  info(message: string, ...args: any[]): void;
  warn(message: string, ...args: any[]): void;
  error(message: string, ...args: any[]): void;
  fatal(message: string, ...args: any[]): void;
};

Included implementation: ConsoleLogger

A no-dependency logger that writes to the browser/Node console and supports runtime level filtering via withMinimumLevel.

import { ConsoleLogger } from "@apihive/logger-facade";

const log = new ConsoleLogger().withMinimumLevel("warn");
log.info("hidden");
log.warn("visible");
log.error("visible");

Create your own adapter

You can wrap any logger to conform to LoggerFacade.

import MyLogger from "MyLogger";
import type { LoggerFacade, LogLevel } from "@apihive/logger-facade";

export function myLoggerFacade(base = new MyLogger()): LoggerFacade {
  return {
    withMinimumLevel(level: LogLevel) : LoggerFacade {
      return myLoggerFacade(base.spawn({ level }));
    },
    trace: (m, ...a) => base.trace(m, ...a),
    debug: (m, ...a) => base.debug(m, ...a),
    info:  (m, ...a) => base.info(m, ...a),
    warn:  (m, ...a) => base.warn(m, ...a),
    error: (m, ...a) => base.error(m, ...a),
    fatal: (m, ...a) => base.fatal(m, ...a),
  };
}

Usage in libraries

Libraries should accept a LoggerFacade (optionally with a default ConsoleLogger) and use it internally, e.g.:

import type { LoggerFacade } from "@apihive/logger-facade";

export function makeThing(logger: LoggerFacade) {
  logger.debug("creating thing");
  // ...
}

Applications decide which implementation to pass:

import { ConsoleLogger } from "@apihive/logger-facade";
import { makeThing } from "my-lib";

makeThing(new ConsoleLogger().withMinimumLevel("info"));

Design goals

• Minimal: Just the common levels + level threshold.
• Extensible: Add your own wrappers for any logging backend.
• Stable: Low churn surface; easy to depend on from libraries.

License

MIT © apihive