CtrlK
BlogDocsLog inGet started
Tessl Logo

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

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

namespace-management.mddocs/

Namespace Management

Debug-lib style namespacing system for organizing logs by module, component, or feature area. Supports nested namespaces with colon separation and provides methods for namespace inspection and management.

Capabilities

Creating Namespaced Loggers

Create or retrieve loggers for specific namespaces to organize log output by logical boundaries.

/**
 * Creates or retrieves a namespaced logger
 * @param {string} namespace - Namespace string using colon separation (e.g., "module:component")
 * @returns {Logger} Logger instance for the specified namespace
 * @throws {TypeError} If namespace contains invalid characters
 */
log.get(namespace);

Usage Examples:

const log = require("log");

// Create single-level namespace
const dbLogger = log.get("database");
dbLogger.info("Connection established");

// Create nested namespace
const userServiceLogger = log.get("service:user");
userServiceLogger.error("User not found: %d", userId);

// Further nesting
const authLogger = userServiceLogger.get("auth");
authLogger.debug("Token validated for user %s", username);

// Equivalent to:
const authLogger2 = log.get("service:user:auth");
console.log(authLogger === authLogger2); // true - same instance returned

Namespace Properties

Each logger exposes properties describing its namespace configuration.

/**
 * Full namespace string or null for root logger
 * @type {string|null}
 */
log.namespace;

/**
 * Array of namespace components
 * @type {string[]}
 */
log.namespaceTokens;

Usage Examples:

const log = require("log");

// Root logger properties
console.log(log.namespace);        // null
console.log(log.namespaceTokens);  // []

// Namespaced logger properties
const nsLogger = log.get("service:user:auth");
console.log(nsLogger.namespace);       // "service:user:auth"
console.log(nsLogger.namespaceTokens); // ["service", "user", "auth"]

// Single namespace
const dbLogger = log.get("database");
console.log(dbLogger.namespace);       // "database"
console.log(dbLogger.namespaceTokens); // ["database"]

Namespace Validation

Namespace strings must follow specific rules for valid tokens.

/**
 * Valid namespace tokens contain only: a-z, 0-9, hyphen (-)
 * Multiple tokens separated by colon (:)
 * Examples of valid namespaces:
 * - "app"
 * - "user-service"  
 * - "api:v1:users"
 * - "db:connection:pool"
 * 
 * Invalid examples:
 * - "User" (uppercase not allowed)
 * - "api_v1" (underscore not allowed)
 * - "test::double" (empty token not allowed)
 */

Validation Examples:

const log = require("log");

// Valid namespaces
log.get("app");                    // ✓ Valid
log.get("user-service");           // ✓ Valid  
log.get("api:v1:users");           // ✓ Valid
log.get("db:connection:pool");     // ✓ Valid

// Invalid namespaces (throw TypeError)
try {
  log.get("User");                 // ✗ Uppercase not allowed
} catch (e) {
  console.log(e.message); // TypeError with validation details
}

try {
  log.get("api_v1");               // ✗ Underscore not allowed  
} catch (e) {
  console.log(e.message);
}

Namespace Inspection

Methods for checking namespace initialization and retrieving namespace loggers.

/**
 * Check if a namespace has been initialized (logger created)
 * @param {string} namespace - Namespace string to check
 * @returns {boolean} True if namespace logger exists
 */
log.isNamespaceInitialized(namespace);

/**
 * Get all initialized namespace loggers for the current level
 * @returns {Logger[]} Array of initialized namespace logger instances
 */
log.getAllInitializedNamespaces();

Usage Examples:

const log = require("log");

// Check before creation
console.log(log.isNamespaceInitialized("myapp"));        // false

// Create namespace logger
const appLogger = log.get("myapp");

// Check after creation
console.log(log.isNamespaceInitialized("myapp"));        // true

// Nested namespace checking
console.log(log.isNamespaceInitialized("myapp:auth"));   // false
const authLogger = log.get("myapp:auth");
console.log(log.isNamespaceInitialized("myapp:auth"));   // true

// Get all initialized namespaces for current level
const namespaces = log.getAllInitializedNamespaces();
console.log(namespaces.map(logger => logger.namespace)); // ["myapp", "myapp:auth"]

// Different levels have separate namespace tracking
const errorLogger = log.error.get("service");
console.log(log.error.getAllInitializedNamespaces().length); // 1
console.log(log.info.getAllInitializedNamespaces().length);  // Still 2

Namespace Behavior

Logger Instance Reuse

Namespace loggers are singletons - calling get() with the same namespace always returns the same instance.

const log = require("log");

const logger1 = log.get("service");
const logger2 = log.get("service"); 
console.log(logger1 === logger2); // true - same instance

// Works across different access patterns
const logger3 = log.info.get("service");
console.log(logger1 === logger3); // true - same instance

Level Inheritance

Namespaced loggers inherit all level methods from their parent logger.

const log = require("log");

const appLogger = log.get("myapp");

// All level methods available
appLogger.error("Critical error in myapp");
appLogger.warning("Warning in myapp");
appLogger.info("Info from myapp");
appLogger.debug("Debug info from myapp");

// Level properties maintained
console.log(appLogger.level);      // "info" (same as parent)
console.log(appLogger.levelIndex); // 3 (same as parent)

Cross-Level Namespace Access

Each log level maintains its own namespace registry, but namespaces can be accessed across levels.

const log = require("log");

// Create namespace in info level
const infoAppLogger = log.get("myapp");

// Access same namespace in error level
const errorAppLogger = log.error.get("myapp");

// Different instances but same namespace
console.log(infoAppLogger === errorAppLogger);           // false
console.log(infoAppLogger.namespace === errorAppLogger.namespace); // true
console.log(infoAppLogger.level);                        // "info"
console.log(errorAppLogger.level);                       // "error"

Namespace Usage Patterns

Module-Based Organization

// lib/database.js
const log = require("log").get("database");

log.info("Database module loaded");

function connect() {
  const connLogger = log.get("connection");
  connLogger.info("Attempting connection...");
}

// lib/api.js  
const log = require("log").get("api");

log.info("API module loaded");

function handleRequest() {
  const reqLogger = log.get("request");
  reqLogger.debug("Processing request");
}

Feature-Based Organization

// Features organized by capability
const authLog = log.get("auth");
const userLog = log.get("user:management");
const paymentLog = log.get("payment:processing");

authLog.info("User authentication successful");
userLog.warning("User profile incomplete");
paymentLog.error("Payment processing failed");

Hierarchical Organization

// Service layer
const serviceLog = log.get("service");

// Individual services
const userServiceLog = serviceLog.get("user");     // "service:user"
const orderServiceLog = serviceLog.get("order");   // "service:order"

// Service components
const userAuthLog = userServiceLog.get("auth");    // "service:user:auth"
const userProfileLog = userServiceLog.get("profile"); // "service:user:profile"

docs

core-logging.md

enable-disable-control.md

index.md

log-writer-system.md

namespace-management.md

utility-functions.md

tile.json