QT JS Logs

A JavaScript/TypeScript client for publishing log messages to an MQTT broker, designed to work with the QTLogs project. This package provides a simple, singleton logger that can be used across a JavaScript/TypeScript application to send structured log messages to a specified MQTT topic.

Installation

Install the package using npm:

npm install qt-js-logs

Or using yarn:

yarn add qt-js-logs

Usage

The SetupLogger function allows you to configure the logger. You can either pass in all the configuration details directly as arguments or provide a path to a YAML configuration file.

Option 1: Configuring with JavaScript/TypeScript arguments

Set up the logger with your MQTT broker details by passing the topic, broker, port, and source directly:

import { SetupLogger } from 'qt-js-logs';

const logger = SetupLogger(
    "your/mqtt/topic",
    "your_mqtt_broker.com",
    1883,
    "your_application_name"
);

Option 2: Configuring with a YAML file

Alternatively, you can configure the logger using a YAML file. Create a config.yaml file (or any other name) with the following structure:

topic: "your/mqtt/topic"
broker: "your_mqtt_broker.com"
port: 1883
source: "your_application_name"

Then, set up the logger by providing the path to your YAML configuration file:

import { SetupLogger } from 'qt-js-logs';

const logger = SetupLogger("path/to/your/config.yaml");

The logger will automatically watch for changes in the YAML file and reload the configuration in real-time, so you don't need to restart your application.

Logging Messages

Once the logger is set up using either method, you can use the logger instance to log messages from anywhere in your application:

import { QTLogger } from 'qt-js-logs';

// Get the logger instance (singleton)
const logger = QTLogger.getInstance();

// Log a message using the generic log method
logger.log("INFO", "This is an informational message.");
logger.log("ERROR", "This is an error message.");

// Or use convenience methods
logger.info("This is an informational message.");
logger.error("This is an error message.");
logger.warn("This is a warning message.");
logger.debug("This is a debug message.");

// Add extra data to the log message
const extraData = { user_id: 1234, operation: "data_processing" };
logger.log("DEBUG", "This is a debug message with extra data.", extraData, false);

// Using convenience method with extra data
logger.debug("Processing completed", { duration_ms: 150, records: 42 });

The log messages will be published to the specified MQTT topic in a JSON format:

{
    "from": "your_application_name",
    "payload": "This is an informational message.",
    "level": "INFO",
    "timestamp": "2025-12-22 10:00:00",
    "caller": "at yourFunction (file.js:45:10)",
    "save": true
}

The save Parameter

The save field indicates whether to save the log message to persistent storage. This is useful when you want to log messages for debugging purposes without cluttering the database:

// This log will not be saved to the database
logger.debug("Temporary debug info", undefined, false);

Cleanup

When your application is shutting down, you can disconnect the logger to clean up resources:

logger.disconnect();

API Reference

SetupLogger

function SetupLogger(topicOrConfig: string, broker?: string, port?: number, source?: string): QTLogger

Configure and retrieve the QTLogger singleton instance.

• topicOrConfig: MQTT topic to publish logs to, or path to YAML config file
• broker: MQTT broker address (optional if using config file)
• port: MQTT broker port (optional if using config file)
• source: Source identifier for the logger (optional if using config file)

QTLogger

Methods

• getInstance(): QTLogger - Get the singleton instance
• log(level: string, message: string, extraData?: Record<string, any>, save?: boolean): void - Log a message
• info(message: string, extraData?: Record<string, any>, save?: boolean): void - Log an INFO message
• error(message: string, extraData?: Record<string, any>, save?: boolean): void - Log an ERROR message
• warn(message: string, extraData?: Record<string, any>, save?: boolean): void - Log a WARN message
• debug(message: string, extraData?: Record<string, any>, save?: boolean): void - Log a DEBUG message
• disconnect(): void - Disconnect from MQTT broker and clean up resources
• toString(): string - Get current configuration as a string

Properties

• topic: string - The MQTT topic
• broker: string - The MQTT broker address
• port: number - The MQTT broker port
• source: string - The source identifier

License

This project is licensed under the Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License. See the LICENSE file for details.

qt-js-logs © 2025 by Austin Ward is licensed under Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International