logs-gateway 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 nx-morpheus
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,299 @@
+# logs-gateway
+
+A standardized logging gateway for Node.js applications. Provides flexible logging with console output, file output, environment variable configuration, and custom logger injection.
+
+## Features
+
+- ✅ **Console output** (default)
+- ✅ **File output** (optional)
+- ✅ **Dual output** (console + file)
+- ✅ **Environment variable configuration**
+- ✅ **Custom logger injection** (Winston, Pino, etc.)
+- ✅ **Package-specific prefixes**
+- ✅ **Multiple log levels** (debug, info, warn, error)
+- ✅ **Multiple formats** (text, json)
+- ✅ **TypeScript support**
+
+## Installation
+
+```bash
+npm install logs-gateway
+```
+
+## Quick Start
+
+```typescript
+import { createLogger } from 'logs-gateway';
+
+// Create a package-specific logger
+const logger = createLogger(
+  { packageName: 'MY_APP', envPrefix: 'MY_APP' },
+  { logToFile: true, logFilePath: '/var/log/myapp.log' }
+);
+
+// Use it
+logger.info('Application initialized');
+logger.debug('Debug info', { data: 'some data' });
+logger.error('Error occurred', { error: new Error('Something went wrong') });
+```
+
+## Configuration
+
+### Via Constructor
+
+```typescript
+const logger = createLogger(
+  { packageName: 'MY_PACKAGE', envPrefix: 'MY_PACKAGE' },
+  {
+    logToConsole: true,              // default: true
+    logToFile: true,                 // default: false
+    logFilePath: '/var/log/app.log', // required if logToFile
+    logLevel: 'debug',               // debug|info|warn|error
+    logFormat: 'json'                // text|json
+  }
+);
+```
+
+### Via Environment Variables
+
+```bash
+# Console logging
+MY_APP_LOG_TO_CONSOLE=true|false
+
+# File logging
+MY_APP_LOG_TO_FILE=true|false
+MY_APP_LOG_FILE=/path/to/log
+
+# Log level
+MY_APP_LOG_LEVEL=debug|info|warn|error
+
+# Log format
+MY_APP_LOG_FORMAT=text|json
+
+# Debug mode (enables debug level)
+DEBUG=my-app-namespace
+```
+
+## Usage Examples
+
+### Example 1: Web Application
+
+```typescript
+// src/logger.ts
+import { createLogger, LoggingConfig, LogsGateway } from 'logs-gateway';
+
+export function createAppLogger(config?: LoggingConfig): LogsGateway {
+  return createLogger(
+    {
+      packageName: 'WEB_APP',
+      envPrefix: 'WEB_APP',
+      debugNamespace: 'web-app'
+    },
+    config
+  );
+}
+
+// src/index.ts
+import { createAppLogger } from './logger';
+
+export class WebApp {
+  private logger: LogsGateway;
+
+  constructor(config: AppConfig & { logging?: LoggingConfig }) {
+    this.logger = createAppLogger(config.logging);
+    this.logger.info('Web application initialized', { version: '1.0.0' });
+  }
+
+  async handleRequest(request: Request): Promise<Response> {
+    this.logger.debug('Handling request', { requestId: request.id });
+    // ... processing
+    this.logger.info('Request processed', { responseTime: Date.now() - request.startTime });
+    return response;
+  }
+}
+```
+
+### Example 2: Database Service
+
+```typescript
+// src/logger.ts
+import { createLogger, LoggingConfig, LogsGateway } from 'logs-gateway';
+
+export function createDbLogger(config?: LoggingConfig): LogsGateway {
+  return createLogger(
+    {
+      packageName: 'DATABASE_SERVICE',
+      envPrefix: 'DB_SERVICE',
+      debugNamespace: 'db-service'
+    },
+    config
+  );
+}
+
+// src/index.ts
+import { createDbLogger } from './logger';
+
+export class DatabaseService {
+  private logger: LogsGateway;
+
+  constructor(config: DbConfig & { logging?: LoggingConfig }) {
+    this.logger = createDbLogger(config.logging);
+    this.logger.info('Database service initialized');
+  }
+
+  async query(sql: string): Promise<any> {
+    this.logger.debug('Executing query', { sql });
+    // ... execute query
+  }
+}
+```
+
+### Example 3: Custom Logger Integration (Winston)
+
+```typescript
+import winston from 'winston';
+import { createLogger, LoggingConfig } from '@nx-morpheus/logs-gateway';
+
+const winstonLogger = winston.createLogger({
+  level: 'info',
+  format: winston.format.json(),
+  transports: [
+    new winston.transports.File({ filename: 'error.log', level: 'error' }),
+    new winston.transports.File({ filename: 'combined.log' })
+  ]
+});
+
+const customLogger = {
+  debug: (msg: string, data?: any) => winstonLogger.debug(msg, data),
+  info: (msg: string, data?: any) => winstonLogger.info(msg, data),
+  warn: (msg: string, data?: any) => winstonLogger.warn(msg, data),
+  error: (msg: string, data?: any) => winstonLogger.error(msg, data)
+};
+
+const logger = createLogger(
+  { packageName: 'MY_APP', envPrefix: 'MY_APP' },
+  { customLogger }  // Use Winston instead of built-in logger
+);
+```
+
+### Example 4: Multiple Services Using the Same Gateway
+
+Each service just needs:
+
+1. **Add dependency**: `"logs-gateway": "^1.0.0"`
+2. **Create factory**:
+
+```typescript
+// Service 1: Web API
+export const logger = createLogger({ packageName: 'WEB_API', envPrefix: 'WEB_API' });
+
+// Service 2: Database
+export const logger = createLogger({ packageName: 'DATABASE', envPrefix: 'DATABASE' });
+
+// Service 3: Cache
+export const logger = createLogger({ packageName: 'CACHE_SERVICE', envPrefix: 'CACHE' });
+
+// Service 4: Queue
+export const logger = createLogger({ packageName: 'QUEUE_SERVICE', envPrefix: 'QUEUE' });
+
+// Service 5: Auth
+export const logger = createLogger({ packageName: 'AUTH_SERVICE', envPrefix: 'AUTH' });
+
+// Service 6: Monitoring
+export const logger = createLogger({ packageName: 'MONITORING', envPrefix: 'MONITOR' });
+
+// Service 7: File Storage
+export const logger = createLogger({ packageName: 'FILE_STORAGE', envPrefix: 'STORAGE' });
+
+// Service 8: Email Service
+export const logger = createLogger({ packageName: 'EMAIL_SERVICE', envPrefix: 'EMAIL' });
+
+// Service 9: Analytics
+export const logger = createLogger({ packageName: 'ANALYTICS', envPrefix: 'ANALYTICS' });
+
+// Service 10: Notifications
+export const logger = createLogger({ packageName: 'NOTIFICATIONS', envPrefix: 'NOTIFY' });
+```
+
+**Update logs-gateway once, all services benefit!**
+
+## API Reference
+
+### `createLogger(packageConfig, userConfig?)`
+
+Creates a new logger instance.
+
+**Parameters:**
+- `packageConfig: LoggerPackageConfig` - Package identification
+- `userConfig?: LoggingConfig` - Optional logging configuration
+
+**Returns:** `LogsGateway` instance
+
+### `LogsGateway` Class
+
+#### Methods
+
+- `debug(message: string, data?: any): void` - Log debug message
+- `info(message: string, data?: any): void` - Log info message  
+- `warn(message: string, data?: any): void` - Log warning message
+- `error(message: string, data?: any): void` - Log error message
+- `getConfig(): Readonly<InternalLoggingConfig>` - Get current configuration
+- `isLevelEnabled(level: LogLevel): boolean` - Check if level is enabled
+
+#### Log Levels
+
+- `debug` - Detailed information (lowest priority)
+- `info` - General information
+- `warn` - Warning messages
+- `error` - Error messages (highest priority)
+
+#### Log Formats
+
+**Text Format:**
+```
+[2024-01-15T10:30:45.123Z] [MY_APP] [INFO] Application initialized {"version":"1.0.0"}
+```
+
+**JSON Format:**
+```json
+{
+  "timestamp": "2024-01-15T10:30:45.123Z",
+  "package": "MY_APP",
+  "level": "INFO",
+  "message": "Application initialized",
+  "data": {"version": "1.0.0"}
+}
+```
+
+## Environment Variables
+
+All environment variables follow the pattern: `{ENV_PREFIX}_{SETTING}`
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `{PREFIX}_LOG_TO_CONSOLE` | Enable console output | `true` |
+| `{PREFIX}_LOG_TO_FILE` | Enable file output | `false` |
+| `{PREFIX}_LOG_FILE` | Log file path | Required if file logging |
+| `{PREFIX}_LOG_LEVEL` | Minimum log level | `info` |
+| `{PREFIX}_LOG_FORMAT` | Output format | `text` |
+| `DEBUG` | Debug namespace | Enables debug level |
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build the project
+npm run build
+
+# Watch mode
+npm run dev
+
+# Clean build artifacts
+npm run clean
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,35 @@
+/**
+ * logs-gateway - Main Entry Point
+ *
+ * This file exports all public APIs and provides the main factory function.
+ */
+export type { LogLevel, LogFormat, LoggingConfig, CustomLogger, LoggerPackageConfig, LogEntry, InternalLoggingConfig } from './types';
+export { LogsGateway } from './logger';
+import { LogsGateway } from './logger';
+import type { LoggerPackageConfig, LoggingConfig } from './types';
+/**
+ * Create a package-specific logger instance
+ *
+ * @param packageConfig - Package identification (name, env prefix, debug namespace)
+ * @param userConfig - Optional logging configuration
+ * @returns LogsGateway instance configured for the package
+ *
+ * @example
+ * ```typescript
+ * import { createLogger } from 'logs-gateway';
+ *
+ * const logger = createLogger(
+ *   { packageName: 'MY_APP', envPrefix: 'MY_APP', debugNamespace: 'my-app' },
+ *   { logToFile: true, logFilePath: '/var/log/myapp.log' }
+ * );
+ *
+ * logger.info('Application initialized');
+ * ```
+ */
+export declare function createLogger(packageConfig: LoggerPackageConfig, userConfig?: LoggingConfig): LogsGateway;
+declare const _default: {
+    createLogger: typeof createLogger;
+    LogsGateway: typeof LogsGateway;
+};
+export default _default;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,YAAY,EACV,QAAQ,EACR,SAAS,EACT,aAAa,EACb,YAAY,EACZ,mBAAmB,EACnB,QAAQ,EACR,qBAAqB,EACtB,MAAM,SAAS,CAAC;AAGjB,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAGvC,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AACvC,OAAO,KAAK,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAElE;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,YAAY,CAC1B,aAAa,EAAE,mBAAmB,EAClC,UAAU,CAAC,EAAE,aAAa,GACzB,WAAW,CAEb;;;;;AAGD,wBAGE"}

package/dist/index.js

@@ -0,0 +1,42 @@
+"use strict";
+/**
+ * logs-gateway - Main Entry Point
+ *
+ * This file exports all public APIs and provides the main factory function.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LogsGateway = void 0;
+exports.createLogger = createLogger;
+// Re-export the LogsGateway class
+var logger_1 = require("./logger");
+Object.defineProperty(exports, "LogsGateway", { enumerable: true, get: function () { return logger_1.LogsGateway; } });
+// Import LogsGateway for the factory function
+const logger_2 = require("./logger");
+/**
+ * Create a package-specific logger instance
+ *
+ * @param packageConfig - Package identification (name, env prefix, debug namespace)
+ * @param userConfig - Optional logging configuration
+ * @returns LogsGateway instance configured for the package
+ *
+ * @example
+ * ```typescript
+ * import { createLogger } from 'logs-gateway';
+ *
+ * const logger = createLogger(
+ *   { packageName: 'MY_APP', envPrefix: 'MY_APP', debugNamespace: 'my-app' },
+ *   { logToFile: true, logFilePath: '/var/log/myapp.log' }
+ * );
+ *
+ * logger.info('Application initialized');
+ * ```
+ */
+function createLogger(packageConfig, userConfig) {
+    return new logger_2.LogsGateway(packageConfig, userConfig);
+}
+// Default export for convenience
+exports.default = {
+    createLogger,
+    LogsGateway: logger_2.LogsGateway
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;;AAuCH,oCAKC;AA/BD,kCAAkC;AAClC,mCAAuC;AAA9B,qGAAA,WAAW,OAAA;AAEpB,8CAA8C;AAC9C,qCAAuC;AAGvC;;;;;;;;;;;;;;;;;;GAkBG;AACH,SAAgB,YAAY,CAC1B,aAAkC,EAClC,UAA0B;IAE1B,OAAO,IAAI,oBAAW,CAAC,aAAa,EAAE,UAAU,CAAC,CAAC;AACpD,CAAC;AAED,iCAAiC;AACjC,kBAAe;IACb,YAAY;IACZ,WAAW,EAAX,oBAAW;CACZ,CAAC"}

package/dist/logger.d.ts

@@ -0,0 +1,64 @@
+/**
+ * logs-gateway - Core LogsGateway Implementation
+ *
+ * This file contains the main Logger class that handles all logging functionality.
+ */
+import { LogLevel, LoggingConfig, LoggerPackageConfig, InternalLoggingConfig } from './types';
+/**
+ * Main LogsGateway class for handling all logging operations
+ */
+export declare class LogsGateway {
+    private config;
+    private packageConfig;
+    private levelPriority;
+    constructor(packageConfig: LoggerPackageConfig, userConfig?: LoggingConfig);
+    /**
+     * Ensure the log directory exists, creating it if necessary
+     */
+    private ensureLogDirectory;
+    /**
+     * Check if a log level should be output based on current configuration
+     */
+    private shouldLog;
+    /**
+     * Format a log entry according to the configured format
+     */
+    private formatLogEntry;
+    /**
+     * Write formatted message to console
+     */
+    private writeToConsole;
+    /**
+     * Write formatted message to log file
+     */
+    private writeToFile;
+    /**
+     * Core logging method that handles all log output
+     */
+    private log;
+    /**
+     * Log debug message (only shown when logLevel is 'debug')
+     */
+    debug(message: string, data?: any): void;
+    /**
+     * Log informational message
+     */
+    info(message: string, data?: any): void;
+    /**
+     * Log warning message
+     */
+    warn(message: string, data?: any): void;
+    /**
+     * Log error message
+     */
+    error(message: string, data?: any): void;
+    /**
+     * Get current logger configuration (for debugging/testing)
+     */
+    getConfig(): Readonly<InternalLoggingConfig>;
+    /**
+     * Check if a specific log level is enabled
+     */
+    isLevelEnabled(level: LogLevel): boolean;
+}
+//# sourceMappingURL=logger.d.ts.map

package/dist/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,EACL,QAAQ,EAER,aAAa,EACb,mBAAmB,EAEnB,qBAAqB,EACtB,MAAM,SAAS,CAAC;AAEjB;;GAEG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,MAAM,CAAwB;IACtC,OAAO,CAAC,aAAa,CAAsB;IAC3C,OAAO,CAAC,aAAa,CAKnB;gBAEU,aAAa,EAAE,mBAAmB,EAAE,UAAU,CAAC,EAAE,aAAa;IAmD1E;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAc1B;;OAEG;IACH,OAAO,CAAC,SAAS;IAMjB;;OAEG;IACH,OAAO,CAAC,cAAc;IAsBtB;;OAEG;IACH,OAAO,CAAC,cAAc;IAUtB;;OAEG;IACH,OAAO,CAAC,WAAW;IAcnB;;OAEG;IACH,OAAO,CAAC,GAAG;IAwBX;;OAEG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG,GAAG,IAAI;IAIxC;;OAEG;IACH,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG,GAAG,IAAI;IAIvC;;OAEG;IACH,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG,GAAG,IAAI;IAIvC;;OAEG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG,GAAG,IAAI;IAIxC;;OAEG;IACH,SAAS,IAAI,QAAQ,CAAC,qBAAqB,CAAC;IAI5C;;OAEG;IACH,cAAc,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO;CAGzC"}

package/dist/logger.js

@@ -0,0 +1,223 @@
+"use strict";
+/**
+ * logs-gateway - Core LogsGateway Implementation
+ *
+ * This file contains the main Logger class that handles all logging functionality.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LogsGateway = void 0;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+/**
+ * Main LogsGateway class for handling all logging operations
+ */
+class LogsGateway {
+    constructor(packageConfig, userConfig) {
+        this.levelPriority = {
+            debug: 0,
+            info: 1,
+            warn: 2,
+            error: 3
+        };
+        this.packageConfig = packageConfig;
+        // Check DEBUG environment variable
+        const envPrefix = packageConfig.envPrefix;
+        const debugEnabled = process.env.DEBUG?.includes(packageConfig.debugNamespace || packageConfig.packageName.toLowerCase());
+        // Build configuration with precedence: user config > env vars > defaults
+        this.config = {
+            logToConsole: userConfig?.logToConsole ??
+                (process.env[`${envPrefix}_LOG_TO_CONSOLE`] !== 'false'),
+            logToFile: userConfig?.logToFile ??
+                (process.env[`${envPrefix}_LOG_TO_FILE`] === 'true'),
+            logFilePath: userConfig?.logFilePath ??
+                process.env[`${envPrefix}_LOG_FILE`] ??
+                '',
+            logLevel: userConfig?.logLevel ??
+                process.env[`${envPrefix}_LOG_LEVEL`] ??
+                (debugEnabled ? 'debug' : 'info'),
+            logFormat: userConfig?.logFormat ??
+                process.env[`${envPrefix}_LOG_FORMAT`] ??
+                'text',
+            packageName: packageConfig.packageName,
+            ...(userConfig?.customLogger && { customLogger: userConfig.customLogger })
+        };
+        // Validate configuration
+        if (this.config.logToFile && !this.config.logFilePath) {
+            throw new Error(`[logs-gateway] ${packageConfig.packageName}: logFilePath is required when logToFile is true. ` +
+                `Set it via config or ${envPrefix}_LOG_FILE environment variable.`);
+        }
+        // Ensure log directory exists if file logging is enabled
+        if (this.config.logToFile && this.config.logFilePath) {
+            this.ensureLogDirectory(this.config.logFilePath);
+        }
+    }
+    // --------------------------------------------------------------------------
+    // PRIVATE METHODS
+    // --------------------------------------------------------------------------
+    /**
+     * Ensure the log directory exists, creating it if necessary
+     */
+    ensureLogDirectory(filePath) {
+        try {
+            const dir = path.dirname(filePath);
+            if (!fs.existsSync(dir)) {
+                fs.mkdirSync(dir, { recursive: true });
+            }
+        }
+        catch (err) {
+            console.error(`[logs-gateway] ${this.packageConfig.packageName}: Failed to create log directory:`, err);
+        }
+    }
+    /**
+     * Check if a log level should be output based on current configuration
+     */
+    shouldLog(level) {
+        const currentLevelPriority = this.levelPriority[this.config.logLevel];
+        const messageLevelPriority = this.levelPriority[level];
+        return messageLevelPriority >= currentLevelPriority;
+    }
+    /**
+     * Format a log entry according to the configured format
+     */
+    formatLogEntry(level, message, data) {
+        const timestamp = new Date().toISOString();
+        const logEntry = {
+            timestamp,
+            package: this.packageConfig.packageName,
+            level: level.toUpperCase(),
+            message,
+            ...(data !== undefined && { data })
+        };
+        if (this.config.logFormat === 'json') {
+            return JSON.stringify(logEntry);
+        }
+        else {
+            // Text format: [timestamp] [PACKAGE] [LEVEL] message
+            let formatted = `[${timestamp}] [${this.packageConfig.packageName}] [${level.toUpperCase()}] ${message}`;
+            if (data !== undefined) {
+                formatted += ` ${typeof data === 'object' ? JSON.stringify(data) : data}`;
+            }
+            return formatted;
+        }
+    }
+    /**
+     * Write formatted message to console
+     */
+    writeToConsole(level, formattedMessage) {
+        if (!this.config.logToConsole)
+            return;
+        if (level === 'error') {
+            console.error(formattedMessage);
+        }
+        else {
+            console.log(formattedMessage);
+        }
+    }
+    /**
+     * Write formatted message to log file
+     */
+    writeToFile(formattedMessage) {
+        if (!this.config.logToFile || !this.config.logFilePath)
+            return;
+        try {
+            fs.appendFileSync(this.config.logFilePath, formattedMessage + '\n', 'utf8');
+        }
+        catch (err) {
+            // Fallback to console if file write fails
+            console.error(`[logs-gateway] ${this.packageConfig.packageName}: Failed to write to log file (${this.config.logFilePath}):`, err);
+        }
+    }
+    /**
+     * Core logging method that handles all log output
+     */
+    log(level, message, data) {
+        // Check if we should log this level
+        if (!this.shouldLog(level))
+            return;
+        // Use custom logger if provided
+        if (this.config.customLogger) {
+            this.config.customLogger[level](message, data);
+            return;
+        }
+        // Format the log entry
+        const formattedMessage = this.formatLogEntry(level, message, data);
+        // Write to console
+        this.writeToConsole(level, formattedMessage);
+        // Write to file
+        this.writeToFile(formattedMessage);
+    }
+    // --------------------------------------------------------------------------
+    // PUBLIC API
+    // --------------------------------------------------------------------------
+    /**
+     * Log debug message (only shown when logLevel is 'debug')
+     */
+    debug(message, data) {
+        this.log('debug', message, data);
+    }
+    /**
+     * Log informational message
+     */
+    info(message, data) {
+        this.log('info', message, data);
+    }
+    /**
+     * Log warning message
+     */
+    warn(message, data) {
+        this.log('warn', message, data);
+    }
+    /**
+     * Log error message
+     */
+    error(message, data) {
+        this.log('error', message, data);
+    }
+    /**
+     * Get current logger configuration (for debugging/testing)
+     */
+    getConfig() {
+        return { ...this.config };
+    }
+    /**
+     * Check if a specific log level is enabled
+     */
+    isLevelEnabled(level) {
+        return this.shouldLog(level);
+    }
+}
+exports.LogsGateway = LogsGateway;
+//# sourceMappingURL=logger.js.map

package/dist/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,68 @@
+/**
+ * logs-gateway - TypeScript Type Definitions
+ *
+ * This file contains all TypeScript interfaces and types for the logs gateway package.
+ */
+/**
+ * Supported log levels in order of priority
+ */
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+/**
+ * Output format options for log entries
+ */
+export type LogFormat = 'text' | 'json';
+/**
+ * Configuration for logging behavior
+ */
+export interface LoggingConfig {
+    /** Enable console output (default: true) */
+    logToConsole?: boolean;
+    /** Enable file output (default: false) */
+    logToFile?: boolean;
+    /** File path for logs (required if logToFile is true) */
+    logFilePath?: string;
+    /** Minimum log level to output (default: 'info') */
+    logLevel?: LogLevel;
+    /** Output format: 'text' or 'json' (default: 'text') */
+    logFormat?: LogFormat;
+    /** Custom logger implementation (advanced use) */
+    customLogger?: CustomLogger;
+}
+/**
+ * Custom logger interface for injecting external loggers (Winston, Pino, etc.)
+ */
+export interface CustomLogger {
+    debug: (message: string, data?: any) => void;
+    info: (message: string, data?: any) => void;
+    warn: (message: string, data?: any) => void;
+    error: (message: string, data?: any) => void;
+}
+/**
+ * Package identification configuration
+ */
+export interface LoggerPackageConfig {
+    /** Display name in logs (e.g., 'MY_APP', 'DATABASE_SERVICE') */
+    packageName: string;
+    /** Environment variable prefix (e.g., 'MY_APP', 'DB_SERVICE') */
+    envPrefix: string;
+    /** Debug namespace for DEBUG env var (e.g., 'my-app', 'db-service') */
+    debugNamespace?: string;
+}
+/**
+ * Structured log entry (used for JSON format)
+ */
+export interface LogEntry {
+    timestamp: string;
+    package: string;
+    level: string;
+    message: string;
+    data?: any;
+}
+/**
+ * Internal configuration type with all required fields
+ */
+export type InternalLoggingConfig = Required<Omit<LoggingConfig, 'customLogger'>> & {
+    customLogger?: CustomLogger;
+    packageName: string;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAE3D;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,MAAM,CAAC;AAExC;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,4CAA4C;IAC5C,YAAY,CAAC,EAAE,OAAO,CAAC;IAEvB,0CAA0C;IAC1C,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB,yDAAyD;IACzD,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,oDAAoD;IACpD,QAAQ,CAAC,EAAE,QAAQ,CAAC;IAEpB,wDAAwD;IACxD,SAAS,CAAC,EAAE,SAAS,CAAC;IAEtB,kDAAkD;IAClD,YAAY,CAAC,EAAE,YAAY,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG,KAAK,IAAI,CAAC;IAC7C,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG,KAAK,IAAI,CAAC;IAC5C,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG,KAAK,IAAI,CAAC;IAC5C,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG,KAAK,IAAI,CAAC;CAC9C;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,gEAAgE;IAChE,WAAW,EAAE,MAAM,CAAC;IAEpB,iEAAiE;IACjE,SAAS,EAAE,MAAM,CAAC;IAElB,uEAAuE;IACvE,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,GAAG,CAAC;CACZ;AAED;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAAG,QAAQ,CAAC,IAAI,CAAC,aAAa,EAAE,cAAc,CAAC,CAAC,GAAG;IAClF,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC"}

package/dist/types.js

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * logs-gateway - TypeScript Type Definitions
+ *
+ * This file contains all TypeScript interfaces and types for the logs gateway package.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";AAAA;;;;GAIG"}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "logs-gateway",
+  "version": "1.0.0",
+  "description": "Standardized logging gateway for Node.js applications",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run clean && npm run build"
+  },
+  "keywords": [
+    "logging",
+    "logger",
+    "typescript",
+    "node",
+    "console",
+    "file",
+    "json"
+  ],
+  "author": "nx-morpheus",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nx-intelligence/logs-gateway.git"
+  },
+  "homepage": "https://github.com/nx-intelligence/logs-gateway#readme",
+  "bugs": {
+    "url": "https://github.com/nx-intelligence/logs-gateway/issues"
+  },
+  "files": [
+    "dist/**/*",
+    "README.md",
+    "LICENSE"
+  ],
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0"
+  },
+  "peerDependencies": {
+    "typescript": ">=4.0.0"
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "type": "commonjs"
+}