vloggo 1.0.0

package/build/index.d.ts

@@ -0,0 +1,2 @@
+export { VLoggo } from "./services/logService";
+export * from "./interfaces/interfaces";

package/build/index.js

@@ -0,0 +1,2 @@
+export { VLoggo } from "./services/logService";
+export * from "./interfaces/interfaces";

package/build/interfaces/interfaces.d.ts

@@ -0,0 +1,36 @@
+export interface VLoggoConfig {
+    client?: string;
+    json?: boolean;
+    debug?: boolean;
+    console?: boolean;
+    directory?: VLoggoDirectory;
+    filecount?: VLoggoFilecount;
+    notify?: boolean;
+    smtp?: VLoggoSMTPConfig;
+    throttle?: number;
+}
+export interface VLoggoDirectory {
+    txt?: string;
+    json?: string;
+}
+export interface VLoggoFilecount {
+    txt?: number;
+    json?: number;
+}
+export interface VLoggoSMTPConfig {
+    host: string;
+    port: number;
+    username: string;
+    password: string;
+    from: string;
+    to: string | string[];
+    secure: boolean;
+}
+export type LogLevel = "INFO" | "WARN" | "ERROR" | "FATAL" | "DEBUG";
+export interface LogEntry {
+    level: LogLevel;
+    timestamp: string;
+    code: string;
+    caller: string;
+    message: string;
+}

package/build/interfaces/interfaces.js

@@ -0,0 +1 @@
+export {};

package/build/internal/emailService.d.ts

@@ -0,0 +1,57 @@
+import Config from "../config/config";
+/**
+ * Service responsible for sending email notifications via SMTP.
+ * Handles error notifications with throttling to prevent spam.
+ *
+ * @class EmailService
+ */
+declare class EmailService {
+    private config;
+    private format;
+    private transporter;
+    private _ready;
+    private lastEmailSent;
+    /**
+     * Creates an instance of EmailService and initializes the SMTP transport.
+     *
+     * @param {Config} config - Configuration object containing SMTP settings
+     */
+    constructor(config: Config);
+    /**
+     * Initializes SMTP transport using nodemailer.
+     * Sets up connection pooling and authentication.
+     * Logs initialization status if debug mode is enabled.
+     *
+     * @private
+     * @returns {void}
+     */
+    private initialize;
+    /**
+     * Sends an error notification email to configured recipients.
+     * Implements throttling based on config.throttle to prevent email spam.
+     *
+     * @async
+     * @param {string} client - Name of the client/application reporting the error
+     * @param {string} code - Error code identifier
+     * @param {string} error - Detailed error message
+     * @returns {Promise<void>}
+     *
+     * @example
+     * ```typescript
+     * await emailService.sendErrorNotification(
+     *   "MyApp",
+     *   "ERR_DATABASE",
+     *   "Failed to connect to database"
+     * );
+     * ```
+     */
+    sendErrorNotification(client: string, code: string, error: string): Promise<void>;
+    /**
+     * Gets the ready status of the email service.
+     *
+     * @readonly
+     * @returns {boolean} True if the service is initialized and ready to send emails
+     */
+    get ready(): boolean;
+}
+export default EmailService;

package/build/internal/emailService.js

@@ -0,0 +1,132 @@
+import nodemailer from "nodemailer";
+import FormatService from "./formatService";
+/**
+ * Service responsible for sending email notifications via SMTP.
+ * Handles error notifications with throttling to prevent spam.
+ *
+ * @class EmailService
+ */
+class EmailService {
+    config;
+    format = new FormatService();
+    transporter = null;
+    _ready = false;
+    lastEmailSent = 0;
+    /**
+     * Creates an instance of EmailService and initializes the SMTP transport.
+     *
+     * @param {Config} config - Configuration object containing SMTP settings
+     */
+    constructor(config) {
+        this.config = config;
+        this.initialize();
+    }
+    /**
+     * Initializes SMTP transport using nodemailer.
+     * Sets up connection pooling and authentication.
+     * Logs initialization status if debug mode is enabled.
+     *
+     * @private
+     * @returns {void}
+     */
+    initialize() {
+        if (!this.config.smtp) {
+            if (this.config.console) {
+                console.info(`[VLoggo] > [${this.config.client}] [${this.format.date()}] [INFO] : notification service disabled > missing configuration`);
+            }
+            return;
+        }
+        try {
+            this.transporter = nodemailer.createTransport({
+                host: this.config.smtp.host,
+                port: this.config.smtp.port,
+                secure: this.config.smtp.secure ?? this.config.smtp.port === 465,
+                pool: true,
+                auth: {
+                    user: this.config.smtp.username,
+                    pass: this.config.smtp.password,
+                },
+                debug: this.config.debug,
+                logger: this.config.debug,
+            });
+            this._ready = true;
+            if (this.config.debug) {
+                console.info(`[VLoggo] > [${this.config.client}] [${this.format.date()}] [INFO] : notification service initialized successfully`);
+            }
+        }
+        catch (error) {
+            console.error(`[VLoggo] > [${this.config.client}] [${this.format.date()}] [ERROR] : error initializing notification service > ${error.message}`);
+            this.transporter = null;
+        }
+    }
+    /**
+     * Sends an error notification email to configured recipients.
+     * Implements throttling based on config.throttle to prevent email spam.
+     *
+     * @async
+     * @param {string} client - Name of the client/application reporting the error
+     * @param {string} code - Error code identifier
+     * @param {string} error - Detailed error message
+     * @returns {Promise<void>}
+     *
+     * @example
+     * ```typescript
+     * await emailService.sendErrorNotification(
+     *   "MyApp",
+     *   "ERR_DATABASE",
+     *   "Failed to connect to database"
+     * );
+     * ```
+     */
+    async sendErrorNotification(client, code, error) {
+        if (!this.transporter || !this.config.smtp) {
+            console.error(`[VLoggo] > [${this.config.client}] [${this.format.date()}] [ERROR] : failed to send error message > email service not initialized`);
+            return;
+        }
+        const now = Date.now();
+        if (now - this.lastEmailSent < this.config.throttle) {
+            if (this.config.debug) {
+                console.info(`[VLoggo] > [${this.config.client}] [${this.format.date()}] [INFO] : email throttled > ${now - this.lastEmailSent} ms remaining`);
+            }
+            return;
+        }
+        this.lastEmailSent = now;
+        const recipients = Array.isArray(this.config.smtp.to)
+            ? this.config.smtp.to.join(", ")
+            : this.config.smtp.to;
+        const caller = this.format.caller(3);
+        const emailContent = {
+            from: `"${client}" <${this.config.smtp.from}>`,
+            to: recipients,
+            subject: `[${client}] Error Alert - ${code}`,
+            html: `
+        <h2>Error Report</h2>
+        <p><strong>Client:</strong> ${client}</p>
+        <p><strong>Error Code:</strong> ${code}</p>
+        <p><strong>Caller:</strong> ${caller}</p>
+        <p><strong>Error Message:</strong> ${error}</p>
+        <p><strong>Timestamp:</strong> ${new Date().toLocaleString("pt-BR")}</p>
+        <hr>
+      `,
+        };
+        try {
+            await this.transporter.sendMail(emailContent);
+            if (this.config.debug) {
+                console.info(`[VLoggo] > [${this.config.client}] [${this.format.date()}] [INFO] : error email sent successfully to ${recipients}`);
+            }
+        }
+        catch (error) {
+            console.error(`[VLoggo] > [${this.config.client}] [${this.format.date()}] [ERROR] : failed to send error message > ${error.message}`);
+        }
+    }
+    /**
+     * Gets the ready status of the email service.
+     *
+     * @readonly
+     * @returns {boolean} True if the service is initialized and ready to send emails
+     */
+    get ready() {
+        return this._ready;
+    }
+}
+export default EmailService;

package/build/internal/fileService.d.ts

@@ -0,0 +1,68 @@
+import Config from "../config/config";
+/**
+ * Service responsible for managing log file operations.
+ * Handles file creation, writing, rotation, and cleanup based on retention policies.
+ *
+ * @class FileService
+ */
+declare class FileService {
+    private config;
+    private _txtFilename;
+    private _jsonFilename;
+    private _currentDay;
+    private _initialized;
+    private format;
+    /**
+     * Creates an instance of FileService.
+     *
+     * @param {Config} config - Configuration object containing directory and file retention settings
+     */
+    constructor(config: Config);
+    /**
+     * Initializes the file service by creating the log directory and first log file.
+     * Sets up the current day tracking for rotation purposes.
+     * This method is idempotent - calling it multiple times has no effect after first initialization.
+     *
+     * @returns {void}
+     */
+    initialize(): void;
+    /**
+     * Writes a line to the current log file.
+     * Checks if the service is initialized before writing.
+     *
+     * @param {string} line - Log line to write (should include newline character)
+     * @returns {void}
+     *
+     * @example
+     * ```typescript
+     * fileService.write("[INFO] User logged in\n");
+     * ```
+     */
+    write(line: string, json?: string): void;
+    /**
+     * Verifies if log rotation is needed by checking if the day has changed.
+     * If rotation is needed, creates a new log file and triggers cleanup of old files.
+     * This method should be called before each write operation to ensure proper rotation.
+     *
+     * @returns {void}
+     */
+    verify(): void;
+    /**
+     * Rotates log files by removing old files that exceed the retention count.
+     * Scans the log directory, sorts files by modification time (newest first),
+     * and deletes the oldest files when the count exceeds config.filecount.
+     *
+     * @private
+     * @async
+     * @returns {Promise<void>}
+     */
+    private rotate;
+    /**
+     * Gets the initialization status of the file service.
+     *
+     * @readonly
+     * @returns {boolean} True if the service is initialized and ready to write logs
+     */
+    get initialized(): boolean;
+}
+export default FileService;

package/build/internal/fileService.js

@@ -0,0 +1,189 @@
+import * as fs from "fs";
+import * as path from "path";
+import * as fsp from "fs/promises";
+import FormatService from "./formatService";
+/**
+ * Service responsible for managing log file operations.
+ * Handles file creation, writing, rotation, and cleanup based on retention policies.
+ *
+ * @class FileService
+ */
+class FileService {
+    config;
+    _txtFilename = "";
+    _jsonFilename = "";
+    _currentDay = 0;
+    _initialized = false;
+    format;
+    /**
+     * Creates an instance of FileService.
+     *
+     * @param {Config} config - Configuration object containing directory and file retention settings
+     */
+    constructor(config) {
+        this.config = config;
+        this.format = new FormatService(this.config.client);
+    }
+    /**
+     * Initializes the file service by creating the log directory and first log file.
+     * Sets up the current day tracking for rotation purposes.
+     * This method is idempotent - calling it multiple times has no effect after first initialization.
+     *
+     * @returns {void}
+     */
+    initialize() {
+        if (this._initialized) {
+            return;
+        }
+        try {
+            this._currentDay = new Date().getDate();
+            const txtDirectory = this.config.directory.txt;
+            fs.mkdirSync(txtDirectory, { recursive: true });
+            this._txtFilename = path.resolve(txtDirectory, this.format.filename());
+            fs.appendFileSync(this._txtFilename, this.format.separator());
+            if (this.config.json) {
+                const jsonDirectory = this.config.directory.json;
+                fs.mkdirSync(jsonDirectory, { recursive: true });
+                this._jsonFilename = path.resolve(jsonDirectory, this.format.jsonFilename());
+                fs.appendFileSync(this._jsonFilename, this.format.jsonSeparator());
+            }
+            this._initialized = true;
+        }
+        catch (error) {
+            console.error(`[VLoggo] > [${this.config.client}] [${this.format.date()}] [ERROR] : error initializing VLoggo > ${error.message}`);
+        }
+    }
+    /**
+     * Writes a line to the current log file.
+     * Checks if the service is initialized before writing.
+     *
+     * @param {string} line - Log line to write (should include newline character)
+     * @returns {void}
+     *
+     * @example
+     * ```typescript
+     * fileService.write("[INFO] User logged in\n");
+     * ```
+     */
+    write(line, json) {
+        if (!this.initialized) {
+            console.warn(`[VLoggo] > [${this.config.client}] [${this.format.date()}] [WARN] : file service not initialized`);
+            return;
+        }
+        try {
+            fs.appendFileSync(this._txtFilename, line);
+            if (this.config.json && json != undefined) {
+                fs.appendFileSync(this._jsonFilename, json);
+            }
+        }
+        catch (error) {
+            console.error(`[VLoggo] > [${this.config.client}] [${this.format.date()}] [ERROR] : failed to write to log file > ${error.message}`);
+        }
+    }
+    /**
+     * Verifies if log rotation is needed by checking if the day has changed.
+     * If rotation is needed, creates a new log file and triggers cleanup of old files.
+     * This method should be called before each write operation to ensure proper rotation.
+     *
+     * @returns {void}
+     */
+    verify() {
+        const today = new Date().getDate();
+        if (today === this._currentDay) {
+            return;
+        }
+        try {
+            fs.mkdirSync(this.config.directory.txt, { recursive: true });
+            this._txtFilename = path.resolve(this.config.directory.txt, this.format.filename());
+            fs.appendFileSync(this._txtFilename, this.format.separator());
+            if (this.config.json) {
+                fs.mkdirSync(this.config.directory.json, { recursive: true });
+                this._jsonFilename = path.resolve(this.config.directory.json, this.format.jsonFilename());
+                fs.appendFileSync(this._jsonFilename, this.format.jsonSeparator());
+            }
+            this._initialized = true;
+            this.rotate().catch((error) => console.error(`[VLoggo] > [${this.config.client}] [${this.format.date()}] [ERROR] : error rotating VLoggo > ${error.message}`));
+        }
+        catch (error) {
+            console.error(`[VLoggo] > [${this.config.client}] [${this.format.date()}] [ERROR] : error verifying VLoggo rotation > ${error.message}`);
+        }
+    }
+    /**
+     * Rotates log files by removing old files that exceed the retention count.
+     * Scans the log directory, sorts files by modification time (newest first),
+     * and deletes the oldest files when the count exceeds config.filecount.
+     *
+     * @private
+     * @async
+     * @returns {Promise<void>}
+     */
+    async rotate() {
+        try {
+            const txtDirectory = this.config.directory.txt;
+            const txtFiles = await fsp.readdir(txtDirectory);
+            const logFilesPromises = txtFiles
+                .filter((file) => file.endsWith(".txt"))
+                .map(async (file) => {
+                const filePath = path.join(txtDirectory, file);
+                const stats = await fsp.stat(filePath);
+                return {
+                    name: file,
+                    path: filePath,
+                    mtime: stats.mtime.getTime(),
+                };
+            });
+            const logFiles = (await Promise.all(logFilesPromises)).sort((a, b) => b.mtime - a.mtime);
+            if (logFiles.length > this.config.filecount.txt) {
+                const filesToDelete = logFiles.slice(this.config.filecount.txt);
+                await Promise.allSettled(filesToDelete.map(async (file) => {
+                    try {
+                        await fsp.unlink(file.path);
+                    }
+                    catch (error) {
+                        console.error(`[VLoggo] > [${this.config.client}] [${this.format.date()}] [ERROR] : error deleting old .txt file > ${error.message}`);
+                    }
+                }));
+            }
+            if (this.config.json) {
+                const jsonDirectory = this.config.directory.json;
+                const jsonFiles = await fsp.readdir(jsonDirectory);
+                const logFilesPromises = jsonFiles
+                    .filter((file) => file.endsWith(".jsonl"))
+                    .map(async (file) => {
+                    const filePath = path.join(jsonDirectory, file);
+                    const stats = await fsp.stat(filePath);
+                    return {
+                        name: file,
+                        path: filePath,
+                        mtime: stats.mtime.getTime(),
+                    };
+                });
+                const logFiles = (await Promise.all(logFilesPromises)).sort((a, b) => b.mtime - a.mtime);
+                if (logFiles.length > this.config.filecount.json) {
+                    const filesToDelete = logFiles.slice(this.config.filecount.json);
+                    await Promise.allSettled(filesToDelete.map(async (file) => {
+                        try {
+                            await fsp.unlink(file.path);
+                        }
+                        catch (error) {
+                            console.error(`[VLoggo] > [${this.config.client}] [${this.format.date()}] [ERROR] : error deleting old .json file > ${error.message}`);
+                        }
+                    }));
+                }
+            }
+        }
+        catch (error) {
+            console.error(`[VLoggo] > [${this.config.client}] [${this.format.date()}] [ERROR] : VLoggo cleanup failed > ${error.message}`);
+        }
+    }
+    /**
+     * Gets the initialization status of the file service.
+     *
+     * @readonly
+     * @returns {boolean} True if the service is initialized and ready to write logs
+     */
+    get initialized() {
+        return this._initialized;
+    }
+}
+export default FileService;

package/build/internal/formatService.d.ts

@@ -0,0 +1,64 @@
+import { LogEntry } from "../interfaces/interfaces";
+/**
+ * Service responsible for formatting log-related strings.
+ * Provides utilities for date formatting, filename generation, separators, and caller traceability.
+ *
+ * @class FormatService
+ */
+declare class FormatService {
+    private client?;
+    constructor(client?: string | undefined);
+    /**
+     * Formats a date object into DD/MM/YYYY HH:mm:ss format.
+     * @param date - Date to format
+     * @returns Formatted date string
+     */
+    date(date?: Date): string;
+    /**
+     * Formats a date into ISO 8601 format for JSON logs.
+     * @param date - Date to format
+     * @returns ISO formatted date string
+     */
+    isoDate(date?: Date): string;
+    /**
+     * Formats a filename based on the current date (YYYY-MM-DD).
+     * @returns Filename in format log-YYYY-MM-DD.txt
+     */
+    filename(): string;
+    /**
+     * Formats a JSON filename based on the current date.
+     * @returns Filename in format log-YYYY-MM-DD.jsonl
+     */
+    jsonFilename(): string;
+    /**
+     * Formats a complete log entry into a single line.
+     * @param entry - Log entry to format
+     * @returns Formatted log line
+     */
+    line(entry: LogEntry): string;
+    /**
+     * Formats a log entry as JSON.
+     * @param entry - Log entry to format
+     * @param pretty - Whether to pretty-print the JSON
+     * @returns JSON string with newline
+     */
+    jsonLine(entry: LogEntry, pretty?: boolean): string;
+    /**
+     * Creates a separator line for log file initialization.
+     * @param message - Optional message to include
+     * @returns Formatted separator with message
+     */
+    separator(): string;
+    /**
+     * Creates a JSON separator for log file initialization.
+     * @returns JSON formatted initialization entry
+     */
+    jsonSeparator(): string;
+    /**
+     * Gets caller location as "file.ts:line"
+     * @param skip - Number of stack frames to skip (default: 0)
+     * @returns Formatted string like "server.ts:123" or empty string if failed
+     */
+    caller(skip?: number): string;
+}
+export default FormatService;

package/build/internal/formatService.js

@@ -0,0 +1,135 @@
+/**
+ * Service responsible for formatting log-related strings.
+ * Provides utilities for date formatting, filename generation, separators, and caller traceability.
+ *
+ * @class FormatService
+ */
+class FormatService {
+    client;
+    constructor(client) {
+        this.client = client;
+        if (!client) {
+            client = "VLoggo";
+        }
+    }
+    /**
+     * Formats a date object into DD/MM/YYYY HH:mm:ss format.
+     * @param date - Date to format
+     * @returns Formatted date string
+     */
+    date(date = new Date()) {
+        const pad = (num) => num.toString().padStart(2, "0");
+        const d = pad(date.getDate());
+        const m = pad(date.getMonth() + 1);
+        const y = date.getFullYear();
+        const h = pad(date.getHours());
+        const min = pad(date.getMinutes());
+        const s = pad(date.getSeconds());
+        return `${d}/${m}/${y} ${h}:${min}:${s}`;
+    }
+    /**
+     * Formats a date into ISO 8601 format for JSON logs.
+     * @param date - Date to format
+     * @returns ISO formatted date string
+     */
+    isoDate(date = new Date()) {
+        return date.toISOString();
+    }
+    /**
+     * Formats a filename based on the current date (YYYY-MM-DD).
+     * @returns Filename in format log-YYYY-MM-DD.txt
+     */
+    filename() {
+        const now = new Date();
+        const year = now.getFullYear();
+        const month = String(now.getMonth() + 1).padStart(2, "0");
+        const day = String(now.getDate()).padStart(2, "0");
+        return `log-${year}-${month}-${day}.txt`;
+    }
+    /**
+     * Formats a JSON filename based on the current date.
+     * @returns Filename in format log-YYYY-MM-DD.jsonl
+     */
+    jsonFilename() {
+        const now = new Date();
+        const year = now.getFullYear();
+        const month = String(now.getMonth() + 1).padStart(2, "0");
+        const day = String(now.getDate()).padStart(2, "0");
+        return `log-${year}-${month}-${day}.jsonl`;
+    }
+    /**
+     * Formats a complete log entry into a single line.
+     * @param entry - Log entry to format
+     * @returns Formatted log line
+     */
+    line(entry) {
+        const timestamp = this.date(new Date());
+        return `[${this.client}] [${timestamp}] [${entry.level}] [${entry.code}] [${entry.caller}]: ${entry.message}\n`;
+    }
+    /**
+     * Formats a log entry as JSON.
+     * @param entry - Log entry to format
+     * @param pretty - Whether to pretty-print the JSON
+     * @returns JSON string with newline
+     */
+    jsonLine(entry, pretty = true) {
+        const jsonEntry = {
+            client: this.client,
+            timestamp: this.isoDate(new Date()),
+            level: entry.level,
+            code: entry.code,
+            caller: entry.caller,
+            message: entry.message,
+        };
+        return JSON.stringify(jsonEntry) + "\n";
+    }
+    /**
+     * Creates a separator line for log file initialization.
+     * @param message - Optional message to include
+     * @returns Formatted separator with message
+     */
+    separator() {
+        const separator = "\n" + "_".repeat(50) + "\n\n";
+        const timestamp = this.date();
+        return `${separator}[${this.client}] [${timestamp}] [INIT] : VLoggo initialized successfully \n`;
+    }
+    /**
+     * Creates a JSON separator for log file initialization.
+     * @returns JSON formatted initialization entry
+     */
+    jsonSeparator() {
+        const initEntry = {
+            client: this.client,
+            timestamp: this.isoDate(new Date()),
+            level: "INIT",
+            message: "VLoggo initialized successfully",
+        };
+        return JSON.stringify(initEntry) + "\n";
+    }
+    /**
+     * Gets caller location as "file.ts:line"
+     * @param skip - Number of stack frames to skip (default: 0)
+     * @returns Formatted string like "server.ts:123" or empty string if failed
+     */
+    caller(skip = 0) {
+        const err = new Error();
+        const stack = err.stack;
+        if (!stack) {
+            return "(unknown:0)";
+        }
+        const lines = stack.split("\n");
+        const targetLine = lines[skip + 2];
+        if (!targetLine) {
+            return "(unknown:0)";
+        }
+        const match = targetLine.match(/\((.+?):(\d+):\d+\)/) ||
+            targetLine.match(/at\s+(.+?):(\d+):\d+/);
+        if (!match) {
+            return "(unknown:0)";
+        }
+        const [, filepath, line] = match;
+        const filename = filepath.split(/[/\\]/).pop() || filepath;
+        return `${filename}:${line}`;
+    }
+}
+export default FormatService;