smartlog-mchapps

A lightweight, robust WebSocket-based logging utility for Node.js.
It streams your structured logs in real-time to a local or remote WebSocket server, captures stack-trace caller insights, handles circular references safely, and queues your logs automatically if the network drops.

✨ Features

• 🔌 Real-time WebSocket Streaming
  Instantly streams JSON payloads over WebSockets.

• 📦 Smart Log Queueing
  If the log server/receiver goes offline, logs are buffered in memory and flushed automatically once reconnected.

• 🔄 Auto-Reconnect
  Attempts to reconnect to your WebSocket host every 3 seconds if disconnected.

• 📍 Automatic Source Tracing
  Extracts exact file, line number, and column number of the code calling the log.

• 🛡️ Circular Dependency Safe
  Safe JSON stringification that intercepts circular object references and prevents application crashes.

• 🪶 Zero Config Fallback
  Automatically falls back to standard console.log mirroring.

📦 Installation

Install the package via npm:

npm install smartlog-mchapps

🚀 Quick Start

1. Initialize and Use

import { Logger } from 'smartlog-mchapps';

// Connects to ws://localhost:9000 by default
const logger = new Logger();

// Simple Logging
logger.info('Application started successfully');

// Logging with Metadata / Context
logger.debug('User profile loaded', {
  userId: 42,
  role: 'admin'
});

// Safe from Circular References (won’t crash!)
const circularObj: any = {};
circularObj.self = circularObj;

logger.warn('Careful with this object', circularObj);

2. Custom Port Specification

If your WebSocket log server is running on a different port:

const logger = new Logger(8080);
// Connects to ws://localhost:8080

🧱 Structured Log Payload

Every log generated streams a highly structured JSON object.

Example:

logger.error('Database connection failed', { attempt: 3 });

Emits:

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "timestamp": 1715975847000,
  "level": "error",
  "message": "Database connection failed",
  "context": {
    "attempt": 3
  },
  "source": {
    "file": "/Users/username/repos/app/src/db.ts",
    "line": 14,
    "column": 12
  }
}

📚 API Reference

new Logger(port?: number)

Creates a new logger instance and immediately opens an asynchronous background WebSocket connection.

Parameters

| Parameter | Type | Default | Description | |---|---|---|---| | port | number | 9000 | Local WebSocket port |

🛠 Methods

All logging methods accept:

• A descriptive message string
• An optional context object containing arbitrary metadata

logger.info(message, context?)

Logs informational events.

logger.info('Server started');

logger.warn(message, context?)

Logs warning events.

logger.warn('Memory usage is high');

logger.error(message, context?)

Logs application errors.

logger.error('Database unavailable', {
  retries: 2
});

logger.debug(message, context?)

Logs debug-level diagnostics.

logger.debug('Cache miss', {
  key: 'user:42'
});

logger.log(level, message, context?)

Logs using a custom log level.

logger.log('critical', 'Payment gateway failure', {
  provider: 'Stripe'
});

✅ Why Use smartlog-mchapps?

• Minimal setup
• Developer-friendly structured logs
• Reliable reconnect + buffering behavior
• Safe serialization
• Helpful source tracing for debugging
• Works great for local development and distributed systems

📄 License

MIT