vloggo 1.0.0

package/README.md

@@ -0,0 +1,274 @@
+# VLoggo
+
+Logging library for Node.js and Bun with file rotation, SMTP notifications, and JSON output support.
+
+## Features
+
+- **Multiple log levels**: INFO, WARN, DEBUG, ERROR, FATAL
+- **Automatic file rotation**: Daily rotation with configurable retention
+- **SMTP notifications**: Email alerts for fatal errors with throttling
+- **JSON output**: Optional structured logging in JSONL format
+- **Caller tracking**: Automatic source file and line number tracking
+- **TypeScript support**: Full type definitions included
+- **Zero configuration**: Works out of the box with sensible defaults
+
+## Installation
+
+```bash
+npm install @vinialx/vloggo
+```
+
+```bash
+bun add @vinialx/vloggo
+```
+
+## Quick Start
+
+```typescript
+import { VLoggo } from "@vinialx/vloggo";
+
+const logger = new VLoggo({ client: "MyApp" });
+
+logger.info("APP_START", "Application started");
+logger.warn("HIGH_MEMORY", "Memory usage above 80%");
+logger.error("API_FAIL", "External API request failed");
+logger.fatal("DB_DOWN", "Database connection lost");
+```
+
+## Configuration
+
+### Basic Configuration
+
+```typescript
+const logger = new VLoggo({
+  client: "MyApp", // Application name
+  console: true, // Enable console output
+  debug: false, // Enable debug logs
+  json: false, // Enable JSON output
+});
+```
+
+### File Configuration
+
+```typescript
+const logger = new VLoggo({
+  client: "MyApp",
+  directory: {
+    txt: "/var/log/myapp", // Text log directory
+    json: "/var/log/myapp/json", // JSON log directory
+  },
+  filecount: {
+    txt: 31, // Keep 31 days of text logs
+    json: 7, // Keep 7 days of JSON logs
+  },
+});
+```
+
+### SMTP Configuration
+
+```typescript
+const logger = new VLoggo({
+  client: "MyApp",
+  smtp: {
+    host: "smtp.gmail.com",
+    port: 465,
+    secure: true,
+    username: "your-email@gmail.com",
+    password: "your-password",
+    from: "logs@myapp.com",
+    to: "admin@myapp.com", // Can be string or array
+  },
+  throttle: 300000, // Min 5 minutes between emails
+});
+```
+
+### Environment Variables
+
+SMTP can be configured via environment variables:
+
+```bash
+SMTP_HOST=smtp.gmail.com
+SMTP_PORT=465
+SMTP_USERNAME=your-email@gmail.com
+SMTP_PASSWORD=your-password
+SMTP_FROM=logs@myapp.com
+SMTP_TO=admin@myapp.com
+```
+
+## API Reference
+
+### Constructor
+
+```typescript
+new VLoggo(options?: Partial<VLoggoConfig>)
+```
+
+**Options:**
+
+- `client`: Application name (default: 'VLoggo')
+- `console`: Enable console output (default: true)
+- `debug`: Enable debug mode (default: false)
+- `json`: Enable JSON output (default: false)
+- `directory`: Log directories (default: ~/[client]/logs)
+- `filecount`: Retention days (default: { txt: 31, json: 31 })
+- `smtp`: SMTP configuration (optional)
+- `throttle`: Email throttle in ms (default: 30000)
+
+### Logging Methods
+
+```typescript
+logger.info(code: string, message: string): void
+logger.warn(code: string, message: string): void
+logger.debug(code: string, message: string): void
+logger.error(code: string, message: string): void
+logger.fatal(code: string, message: string): void
+```
+
+**Parameters:**
+
+- `code`: Short identifier for the log entry
+- `message`: Detailed log message
+
+### Configuration Access
+
+```typescript
+// Read configuration
+logger.config.client; // string
+logger.config.debug; // boolean
+logger.config.console; // boolean
+logger.config.json; // boolean
+logger.config.directory; // VLoggoDirectory
+logger.config.filecount; // VLoggoFilecount
+logger.config.notify; // boolean
+logger.config.smtp; // VLoggoSMTPConfig | undefined
+logger.config.throttle; // number
+
+// Clone configuration
+const newConfig = logger.config.clone({ client: "NewApp" });
+
+// Update configuration
+logger.config.update({ debug: true, throttle: 60000 });
+```
+
+## Log Format
+
+### Text Format
+
+```
+[MyApp] [03/11/2025 14:30:45] [INFO] [APP_START] [server.ts:15]: Application started
+```
+
+### JSON Format (JSONL)
+
+```json
+{
+  "client": "MyApp",
+  "timestamp": "2025-11-03T14:30:45.123Z",
+  "level": "INFO",
+  "code": "APP_START",
+  "caller": "server.ts:15",
+  "message": "Application started"
+}
+```
+
+## File Rotation
+
+- Logs rotate daily at midnight
+- Old logs are automatically deleted based on `filecount` setting
+- Separate rotation for text and JSON logs
+- Rotation happens asynchronously without blocking logging
+
+## Email Notifications
+
+- Only sent for `fatal()` logs
+- Throttled to prevent spam (configurable via `throttle`)
+- Includes timestamp, code, caller location, and message
+- HTML formatted emails
+
+## Examples
+
+### Express.js Integration
+
+```typescript
+import express from "express";
+import { VLoggo } from "@vinialx/vloggo";
+
+const app = express();
+const logger = new VLoggo({ client: "API" });
+
+app.use((req, res, next) => {
+  logger.info("REQUEST", `${req.method} ${req.path}`);
+  next();
+});
+
+app.use((err, req, res, next) => {
+  logger.error("ERROR", err.message);
+  res.status(500).json({ error: "Internal Server Error" });
+});
+```
+
+### Database Connection Monitoring
+
+```typescript
+async function connectDatabase() {
+  try {
+    await db.connect();
+    logger.info("DB_CONNECT", "Database connected successfully");
+  } catch (error) {
+    logger.fatal("DB_CONNECT_FAIL", error.message);
+    process.exit(1);
+  }
+}
+```
+
+### Scheduled Task Logging
+
+```typescript
+import cron from "node-cron";
+
+cron.schedule("0 0 * * *", () => {
+  logger.info("CRON_START", "Daily cleanup task started");
+
+  try {
+    performCleanup();
+    logger.info("CRON_SUCCESS", "Daily cleanup completed");
+  } catch (error) {
+    logger.error("CRON_FAIL", error.message);
+  }
+});
+```
+
+## TypeScript Support
+
+Full TypeScript definitions are included:
+
+```typescript
+import { VLoggo, VLoggoConfig, LogLevel, LogEntry } from "vloggo";
+
+const config: Partial<VLoggoConfig> = {
+  client: "TypeScriptApp",
+  debug: true,
+};
+
+const logger = new VLoggo(config);
+```
+
+## Performance Considerations
+
+- File writes are synchronous for data integrity
+- Rotation is asynchronous to avoid blocking
+- Email sending is asynchronous with error handling
+- Minimal overhead for disabled features
+
+## License
+
+MIT
+
+## Support
+
+For issues and feature requests, visit: https://github.com/vinialx/vloggo/issues
+
+
+## Author
+
+Email: vini.aloise.silva@gmail.com

package/build/config/config.d.ts

@@ -0,0 +1,159 @@
+import { VLoggoConfig, VLoggoSMTPConfig, VLoggoDirectory, VLoggoFilecount } from "../interfaces/interfaces";
+/**
+ * Configuration manager for VLoggo.
+ * Manages all settings including SMTP, file rotation and debugging.
+ *
+ * @class Config
+ */
+declare class Config {
+    private _client;
+    private _json;
+    private _debug;
+    private _console;
+    private _filecount;
+    private _directory;
+    private _notify;
+    private _throttle;
+    private _smtp;
+    private format;
+    /**
+     * Creates a new Config instance.
+     * Loads configuration from options or environment variables.
+     *
+     * @param {Partial<VLoggoConfig>} [options] - Optional configuration overrides
+     *
+     * @example
+     * ```typescript
+     * // Minimal config
+     * const config = new Config({ client: 'MyApp' });
+     *
+     * // With SMTP
+     * const config = new Config({
+     *   client: 'MyApp',
+     *   smtp: { host: '...', port: 465, ... }
+     * });
+     * ```
+     */
+    constructor(options?: Partial<VLoggoConfig>);
+    /**
+     * Loads SMTP configuration from environment variables.
+     * Validates port number and sets secure flag based on port 465.
+     * Disables notifications if any required environment variable is missing or invalid.
+     *
+     * Required environment variables:
+     * - SMTP_TO: Recipient email address
+     * - SMTP_FROM: Sender email address
+     * - SMTP_HOST: SMTP server hostname
+     * - SMTP_PORT: SMTP server port
+     * - SMTP_USERNAME: SMTP authentication username
+     * - SMTP_PASSWORD: SMTP authentication password
+     *
+     * @private
+     * @returns {void}
+     */
+    private loadSMTPFromEnv;
+    /**
+     * Updates configuration properties.
+     * Only updates properties that are provided in the options parameter.
+     * Supports partial SMTP configuration updates - merges with existing SMTP settings.
+     *
+     * @param {Partial<VLoggoConfig> & { smtp?: Partial<VLoggoSMTPConfig> }} options - Configuration properties to update
+     * @returns {void}
+     *
+     * @example
+     * ```typescript
+     * // Update simple properties
+     * config.update({ debug: false, throttle: 60000 });
+     *
+     * // Update only specific SMTP properties
+     * config.update({
+     *   smtp: {
+     *     host: 'new-smtp.example.com',
+     *     port: 587
+     *   }
+     * });
+     * ```
+     */
+    update(options: Partial<VLoggoConfig> & {
+        smtp?: Partial<VLoggoSMTPConfig>;
+    }): void;
+    /**
+     * Creates a clone of this config with optional overrides.
+     * The original config is not modified.
+     *
+     * @param {Partial<VLoggoConfig>} [overrides] - Properties to override in the cloned config
+     * @returns {Config} New Config instance with overrides applied
+     *
+     * @example
+     * ```typescript
+     * const baseConfig = new Config();
+     * const apiConfig = baseConfig.clone({ client: 'API' });
+     * ```
+     */
+    clone(overrides?: Partial<VLoggoConfig>): Config;
+    /**
+     * Gets the client/application name.
+     *
+     * @readonly
+     * @returns {string} Client/application name
+     */
+    get client(): string;
+    /**
+     * Gets whether json mode is enabled.
+     *
+     * @readonly
+     * @returns {boolean} True if debug mode is enabled
+     */
+    get json(): boolean;
+    /**
+     * Gets whether debug mode is enabled.
+     *
+     * @readonly
+     * @returns {boolean} True if debug mode is enabled
+     */
+    get debug(): boolean;
+    /**
+     * Gets whether console output is enabled.
+     *
+     * @readonly
+     * @returns {boolean} True if console output is enabled
+     */
+    get console(): boolean;
+    /**
+     * Gets the maximum number of log files to keep.
+     *
+     * @readonly
+     * @returns {number} Maximum file count before rotation
+     */
+    get filecount(): VLoggoFilecount;
+    /**
+     * Gets the log directory path.
+     *
+     * @readonly
+     * @returns {string} Absolute path to log directory
+     */
+    get directory(): VLoggoDirectory;
+    /**
+     * Gets whether email notifications are enabled.
+     *
+     * @readonly
+     * @returns {boolean} True if email notifications are enabled
+     */
+    get notify(): boolean;
+    /**
+     * Gets the SMTP configuration.
+     *
+     * @readonly
+     * @returns {VLoggoSMTPConfig | undefined} SMTP config object or undefined if not configured
+     */
+    get smtp(): VLoggoSMTPConfig | undefined;
+    /**
+     * Gets the email throttle time in milliseconds.
+     *
+     * @readonly
+     * @returns {number} Throttle time in milliseconds
+     */
+    get throttle(): number;
+}
+export declare const defaultConfig: VLoggoConfig;
+export default Config;

package/build/config/config.js

@@ -0,0 +1,291 @@
+import * as os from "os";
+import * as path from "path";
+import FormatService from "../internal/formatService";
+/**
+ * Configuration manager for VLoggo.
+ * Manages all settings including SMTP, file rotation and debugging.
+ *
+ * @class Config
+ */
+class Config {
+    _client;
+    _json;
+    _debug;
+    _console;
+    _filecount;
+    _directory;
+    _notify;
+    _throttle;
+    _smtp = undefined;
+    format = new FormatService();
+    /**
+     * Creates a new Config instance.
+     * Loads configuration from options or environment variables.
+     *
+     * @param {Partial<VLoggoConfig>} [options] - Optional configuration overrides
+     *
+     * @example
+     * ```typescript
+     * // Minimal config
+     * const config = new Config({ client: 'MyApp' });
+     *
+     * // With SMTP
+     * const config = new Config({
+     *   client: 'MyApp',
+     *   smtp: { host: '...', port: 465, ... }
+     * });
+     * ```
+     */
+    constructor(options) {
+        this._client = options?.client || process.env.CLIENT_NAME || "VLoggo";
+        this._json = options?.json ?? false;
+        this._debug = options?.debug ?? false;
+        this._console = options?.console ?? true;
+        this._filecount = options?.filecount ?? { txt: 31, json: 31 };
+        this._directory = options?.directory || {
+            txt: path.resolve(os.homedir(), this._client, "logs"),
+            json: path.resolve(os.homedir(), this._client, "json"),
+        };
+        this._notify = options?.notify ?? false;
+        this._throttle = options?.throttle ?? 30000;
+        if (options?.smtp) {
+            this._smtp = options.smtp;
+            this._notify = true;
+        }
+        else {
+            this.loadSMTPFromEnv();
+        }
+    }
+    /**
+     * Loads SMTP configuration from environment variables.
+     * Validates port number and sets secure flag based on port 465.
+     * Disables notifications if any required environment variable is missing or invalid.
+     *
+     * Required environment variables:
+     * - SMTP_TO: Recipient email address
+     * - SMTP_FROM: Sender email address
+     * - SMTP_HOST: SMTP server hostname
+     * - SMTP_PORT: SMTP server port
+     * - SMTP_USERNAME: SMTP authentication username
+     * - SMTP_PASSWORD: SMTP authentication password
+     *
+     * @private
+     * @returns {void}
+     */
+    loadSMTPFromEnv() {
+        const to = process.env.SMTP_TO;
+        const from = process.env.SMTP_FROM;
+        const host = process.env.SMTP_HOST;
+        const portStr = process.env.SMTP_PORT;
+        const username = process.env.SMTP_USERNAME;
+        const password = process.env.SMTP_PASSWORD;
+        if (!to || !from || !host || !portStr || !username || !password) {
+            console.warn(`[VLoggo] > [${this.client}] [${this.format.date()}] [WARN] : notification service disabled > missing configuration`);
+            this._notify = false;
+            return;
+        }
+        const port = parseInt(portStr);
+        if (isNaN(port) || port <= 0 || port > 65535) {
+            console.error(`[VLoggo] > [${this.client}] [${this.format.date()}] [ERROR] : notification service disabled > invalid port - ${portStr}.`);
+            this._notify = false;
+            return;
+        }
+        const secure = port === 465 ? true : false;
+        this._smtp = {
+            to,
+            from,
+            host,
+            port,
+            username,
+            password,
+            secure,
+        };
+        this._notify = true;
+    }
+    /**
+     * Updates configuration properties.
+     * Only updates properties that are provided in the options parameter.
+     * Supports partial SMTP configuration updates - merges with existing SMTP settings.
+     *
+     * @param {Partial<VLoggoConfig> & { smtp?: Partial<VLoggoSMTPConfig> }} options - Configuration properties to update
+     * @returns {void}
+     *
+     * @example
+     * ```typescript
+     * // Update simple properties
+     * config.update({ debug: false, throttle: 60000 });
+     *
+     * // Update only specific SMTP properties
+     * config.update({
+     *   smtp: {
+     *     host: 'new-smtp.example.com',
+     *     port: 587
+     *   }
+     * });
+     * ```
+     */
+    update(options) {
+        if (options.client) {
+            this._client = options.client;
+        }
+        if (options.json !== undefined) {
+            this._json = options.json;
+        }
+        if (options.debug !== undefined) {
+            this._debug = options.debug;
+        }
+        if (options.console !== undefined) {
+            this._console = options.console;
+        }
+        if (options.filecount) {
+            if (options.filecount.txt) {
+                this._filecount.txt = options.filecount.txt;
+            }
+            if (options.filecount.json) {
+                this._filecount.json = options.filecount.json;
+            }
+        }
+        if (options.directory) {
+            if (options.directory.txt) {
+                this._directory.txt = options.directory.txt;
+            }
+            if (options.directory.json) {
+                this._directory.json = options.directory.json;
+            }
+        }
+        if (options.notify !== undefined) {
+            this._notify = options.notify;
+        }
+        if (options.throttle) {
+            this._throttle = options.throttle;
+        }
+        if (options.smtp) {
+            this._smtp = {
+                ...this._smtp,
+                ...options.smtp,
+            };
+        }
+    }
+    /**
+     * Creates a clone of this config with optional overrides.
+     * The original config is not modified.
+     *
+     * @param {Partial<VLoggoConfig>} [overrides] - Properties to override in the cloned config
+     * @returns {Config} New Config instance with overrides applied
+     *
+     * @example
+     * ```typescript
+     * const baseConfig = new Config();
+     * const apiConfig = baseConfig.clone({ client: 'API' });
+     * ```
+     */
+    clone(overrides) {
+        return new Config({
+            client: overrides?.client ?? this._client,
+            json: overrides?.json ?? this._json,
+            debug: overrides?.debug ?? this._debug,
+            console: overrides?.console ?? this._console,
+            directory: overrides?.directory ?? this._directory,
+            filecount: overrides?.filecount ?? this._filecount,
+            throttle: overrides?.throttle ?? this._throttle,
+            notify: overrides?.notify ?? this._notify,
+            smtp: overrides?.smtp ?? this._smtp,
+        });
+    }
+    /**
+     * Gets the client/application name.
+     *
+     * @readonly
+     * @returns {string} Client/application name
+     */
+    get client() {
+        return this._client;
+    }
+    /**
+     * Gets whether json mode is enabled.
+     *
+     * @readonly
+     * @returns {boolean} True if debug mode is enabled
+     */
+    get json() {
+        return this._json;
+    }
+    /**
+     * Gets whether debug mode is enabled.
+     *
+     * @readonly
+     * @returns {boolean} True if debug mode is enabled
+     */
+    get debug() {
+        return this._debug;
+    }
+    /**
+     * Gets whether console output is enabled.
+     *
+     * @readonly
+     * @returns {boolean} True if console output is enabled
+     */
+    get console() {
+        return this._console;
+    }
+    /**
+     * Gets the maximum number of log files to keep.
+     *
+     * @readonly
+     * @returns {number} Maximum file count before rotation
+     */
+    get filecount() {
+        return this._filecount;
+    }
+    /**
+     * Gets the log directory path.
+     *
+     * @readonly
+     * @returns {string} Absolute path to log directory
+     */
+    get directory() {
+        return this._directory;
+    }
+    /**
+     * Gets whether email notifications are enabled.
+     *
+     * @readonly
+     * @returns {boolean} True if email notifications are enabled
+     */
+    get notify() {
+        return this._notify;
+    }
+    /**
+     * Gets the SMTP configuration.
+     *
+     * @readonly
+     * @returns {VLoggoSMTPConfig | undefined} SMTP config object or undefined if not configured
+     */
+    get smtp() {
+        return this._smtp;
+    }
+    /**
+     * Gets the email throttle time in milliseconds.
+     *
+     * @readonly
+     * @returns {number} Throttle time in milliseconds
+     */
+    get throttle() {
+        return this._throttle;
+    }
+}
+export const defaultConfig = {
+    client: "VLoggo",
+    json: false,
+    debug: false,
+    console: true,
+    filecount: { txt: 31, json: 31 },
+    directory: {
+        txt: path.resolve(os.homedir(), "VLoggo", "logs"),
+        json: path.resolve(os.homedir(), "VLoggo", "json"),
+    },
+    throttle: 30000,
+    notify: false, // Importante: false por padrão
+    smtp: undefined,
+};
+export default Config;