tessl/npm-log

Universal pluggable logging utility with configurable levels and namespacing support

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Log

Name: tessl/npm-log
Author: tessl

Universal pluggable logging utility that provides structured, configurable logging with level support and debug-style namespacing. Designed for maximum reusability across Node.js applications, libraries, and serverless environments.

Package Information

Package Name: log
Package Type: npm
Language: JavaScript
Installation: npm install log

Core Imports

const log = require("log");

For ES modules:

import log from "log";

Basic Usage

const log = require("log");

// Log at different levels
log("Basic info message");
log.error("Something went wrong");
log.warning("This is a warning");
log.debug("Debug information");

// Create namespaced loggers
const myLibLog = log.get("my-lib");
myLibLog.info("Info message in my-lib namespace");

// Nested namespaces
const funcLog = myLibLog.get("func");
funcLog.error("Error in my-lib:func namespace");

// Enable/disable logging
const { restore } = log.disable();
log("This won't be logged");
restore();
log("This will be logged again");

Architecture

The log package is built around several key components:

Logger Prototype: Core logger functionality with level management and method chaining
Level System: Five syslog-compatible levels (error, warning, notice, info, debug) with severity ordering
Namespace System: Debug-lib style namespacing with colon separation for organized log categorization
Event System: Global event emitter for 'init' and 'log' events that writers can subscribe to
Writer System: Pluggable architecture where separate writer modules handle actual log output
Visibility Control: Runtime enable/disable functionality with restore capability

Capabilities

Core Logging

Primary logging functionality with five severity levels and printf-style message formatting. Supports both direct logging and level-specific methods.

// Main logger function (callable at 'info' level)
function log(message, ...args);

// Level-specific loggers
log.debug(message, ...args);    // Debug level (hidden by default)
log.info(message, ...args);     // Info level  
log.notice(message, ...args);   // Notice level
log.warning(message, ...args);  // Warning level
log.warn(message, ...args);     // Alias for warning
log.error(message, ...args);    // Error level

Core Logging

Namespace Management

Debug-lib style namespacing system for organizing logs by module, component, or feature area. Supports nested namespaces with colon separation.

// Create/get namespaced logger
log.get(namespace);

// Check namespace initialization
log.isNamespaceInitialized(namespace);

// Get all initialized namespaces  
log.getAllInitializedNamespaces();

Namespace Management

Enable/Disable Control

Runtime control over log visibility with restore functionality. Allows temporarily disabling logs and restoring previous state.

// Control properties and methods
log.isEnabled;           // boolean property
log.enable();           // returns restore object
log.disable();          // returns restore object

Enable/Disable Control

Log Writer System

Abstract writer system for creating custom log output handlers. Writers subscribe to log events and handle actual output formatting and destination.

// Abstract writer constructor
new LogWriter(env, options);

// Writer registration
getMasterWriter();
getMasterWriter.register(writer);

Log Writer System

Utility Functions

Helper functions for logger validation and type checking in applications that need to verify logger instances.

// Validation functions
isLogger(logger);      // boolean check
ensureLogger(logger);  // throws if invalid

Utility Functions

Types

// Logger instance properties
interface Logger {
  // Callable function
  (message, ...args): void;
  
  // Level properties
  level: string;          // e.g., 'info', 'error'
  levelIndex: number;     // severity index (0=error, 4=debug)
  levelRoot: Logger;      // root logger for this level
  
  // Namespace properties  
  namespace: string | null;     // full namespace or null
  namespaceTokens: string[];    // namespace components
  
  // Control properties
  isEnabled: boolean;     // visibility state
  
  // Level loggers
  debug: Logger;
  info: Logger; 
  notice: Logger;
  warning: Logger;
  warn: Logger;    // alias for warning
  error: Logger;
  
  // Methods (see capability docs for details)
  get(namespace: string): Logger;
  isNamespaceInitialized(namespace: string): boolean;
  getAllInitializedNamespaces(): Logger[];
  isLevelInitialized(level: string): boolean;
  getAllInitializedLevels(): Logger[];
  enable(): RestoreObject;
  disable(): RestoreObject;
}

interface RestoreObject {
  restore(): void;
}

interface LogWriter {
  constructor(env: object, options?: object);
  writeMessage(event: LogEvent): void;
  isLoggerEnabled(logger: Logger): boolean;
  setupLevelLogger(logger: Logger): void;
}

interface LogEvent {
  logger: Logger;
  messageTokens: any[];
  message?: string;
}