@crimsonsunset/jsg-logger 1.7.0 → 1.7.4

package/index.d.ts

@@ -0,0 +1,192 @@
+/**
+ * TypeScript definitions for @crimsonsunset/jsg-logger
+ */
+
+export interface LoggerInstance {
+  info: (message: string, data?: any) => void;
+  debug: (message: string, data?: any) => void;
+  warn: (message: string, data?: any) => void;
+  error: (message: string, data?: any) => void;
+  fatal: (message: string, data?: any) => void;
+  trace: (message: string, data?: any) => void;
+  [key: string]: any;
+}
+
+export interface LoggerComponents {
+  /**
+   * Component loggers - factory functions that ALWAYS return LoggerInstance
+   * Components return no-op logger if not initialized or unavailable
+   * Safe to call without null checks: components.reactComponents?.().info(...)
+   */
+  reactComponents?: () => LoggerInstance;
+  astroComponents?: () => LoggerInstance;
+  astroBuild?: () => LoggerInstance;
+  astroIntegration?: () => LoggerInstance;
+  contentProcessing?: () => LoggerInstance;
+  textUtils?: () => LoggerInstance;
+  dateUtils?: () => LoggerInstance;
+  pages?: () => LoggerInstance;
+  config?: () => LoggerInstance;
+  seo?: () => LoggerInstance;
+  performance?: () => LoggerInstance;
+  devServer?: () => LoggerInstance;
+  webComponents?: () => LoggerInstance;
+  core?: () => LoggerInstance;
+  api?: () => LoggerInstance;
+  ui?: () => LoggerInstance;
+  database?: () => LoggerInstance;
+  test?: () => LoggerInstance;
+  preact?: () => LoggerInstance;
+  auth?: () => LoggerInstance;
+  analytics?: () => LoggerInstance;
+  websocket?: () => LoggerInstance;
+  notification?: () => LoggerInstance;
+  router?: () => LoggerInstance;
+  cache?: () => LoggerInstance;
+  /**
+   * Dynamic component access - always returns a logger factory
+   * The factory function always returns LoggerInstance (no-op if unavailable)
+   */
+  [key: string]: (() => LoggerInstance) | undefined;
+}
+
+export interface JSGLoggerConfig {
+  configPath?: string;
+  config?: Record<string, any>;
+  devtools?: {
+    enabled?: boolean;
+  };
+  [key: string]: any;
+}
+
+export interface LoggerControls {
+  setLevel?: (component: string, level: string) => void;
+  getLevel?: (component: string) => string | undefined;
+  listComponents?: () => string[];
+  enableDebugMode?: () => void;
+  enableTraceMode?: () => void;
+  addFileOverride?: (filePath: string, overrideConfig: Record<string, any>) => void;
+  removeFileOverride?: (filePath: string) => void;
+  listFileOverrides?: () => string[];
+  setTimestampMode?: (mode: string) => void;
+  getTimestampMode?: () => string;
+  getTimestampModes?: () => string[];
+  setDisplayOption?: (option: string, enabled: boolean) => void;
+  getDisplayConfig?: () => Record<string, boolean>;
+  toggleDisplayOption?: (option: string) => void;
+  getStats?: () => any;
+  subscribe?: (callback: Function) => void;
+  clearLogs?: () => void;
+  getConfigSummary?: () => any;
+  setComponentLevel?: (component: string, level: string) => void;
+  getComponentLevel?: (component: string) => string | undefined;
+  enableDevPanel?: () => Promise<any>;
+  disableDevPanel?: () => boolean;
+  refresh?: () => void;
+  reset?: () => void;
+  [key: string]: any;
+}
+
+export interface LoggerConfig {
+  environment?: string;
+  components?: Record<string, any>;
+  summary?: any;
+}
+
+export interface LoggerInstanceType {
+  /**
+   * Direct access to component loggers
+   */
+  [componentName: string]: LoggerInstance | any;
+
+  /**
+   * Auto-discovery convenience getters (factory functions)
+   */
+  components?: LoggerComponents;
+
+  /**
+   * Get a specific component logger - always returns a logger instance
+   * Returns no-op logger if component unavailable or logger not initialized
+   * Always available - never undefined
+   */
+  getComponent: (componentName: string) => LoggerInstance;
+
+  /**
+   * Create a logger for a specific component
+   */
+  createLogger?: (componentName: string) => LoggerInstance;
+
+  /**
+   * Configuration and debugging info
+   */
+  config?: LoggerConfig;
+
+  /**
+   * Configuration manager instance
+   */
+  configManager?: any;
+
+  /**
+   * Log store instance
+   */
+  logStore?: any;
+
+  /**
+   * Enhanced runtime controls
+   */
+  controls?: LoggerControls;
+
+  /**
+   * Get singleton instance (async)
+   */
+  getInstance?: (config?: JSGLoggerConfig) => Promise<LoggerInstanceType> | LoggerInstanceType;
+
+  /**
+   * Get singleton instance (sync)
+   */
+  getInstanceSync?: (config?: JSGLoggerConfig) => LoggerInstanceType;
+
+  /**
+   * Static performance logging utility
+   */
+  logPerformance?: (label: string, startTime: number, component?: string) => Promise<number>;
+}
+
+export interface JSGLogger {
+  /**
+   * Get singleton instance with auto-initialization
+   * @param config - Initialization options (only used on first call)
+   * @returns Enhanced logger exports with controls API
+   * 
+   * Note: Returns Promise if initialization is needed, sync value if already initialized.
+   * Use `await` to handle both cases safely.
+   * 
+   * @example
+   * ```ts
+   * const logger = await JSGLogger.getInstance({ configPath: 'logger-config.json' });
+   * logger.components?.reactComponents?.().info('Hello');
+   * ```
+   */
+  getInstance(config?: JSGLoggerConfig): Promise<LoggerInstanceType> | LoggerInstanceType;
+
+  /**
+   * Get singleton instance synchronously (for environments without async support)
+   * @param config - Initialization options (only used on first call)
+   * @returns Enhanced logger exports with controls API
+   */
+  getInstanceSync(config?: JSGLoggerConfig): LoggerInstanceType;
+
+  /**
+   * Static performance logging utility
+   * @param label - Performance label
+   * @param startTime - Start time from performance.now()
+   * @param component - Optional component name (defaults to 'performance')
+   * @returns Duration in milliseconds
+   */
+  logPerformance(label: string, startTime: number, component?: string): Promise<number>;
+}
+
+declare const JSGLogger: JSGLogger;
+export default JSGLogger;
+export { JSGLogger };
+

package/index.js

@@ -12,6 +12,7 @@ import {createBrowserFormatter} from './formatters/browser-formatter.js';
 import {createCLIFormatter} from './formatters/cli-formatter.js';
 import {createServerFormatter, getServerConfig} from './formatters/server-formatter.js';
 import {LogStore} from './stores/log-store.js';
+import {metaLog, metaWarn, metaError} from './utils/meta-logger.js';
 
 // Check default config for devtools at module load time
 // This allows bundlers to tree-shake if disabled
@@ -23,19 +24,19 @@ const defaultDevtoolsEnabled = defaultConfig.devtools?.enabled ?? false;
 let devtoolsModule = null;
 let devtoolsModulePromise = null;
 if (defaultDevtoolsEnabled) {
-    console.log('[JSG-LOGGER] DevTools module pre-loading started (default config enabled)');
+    metaLog('[JSG-LOGGER] DevTools module pre-loading started (default config enabled)');
     // Start loading immediately but don't await (non-blocking)
     // Bundlers can still analyze this static import for tree-shaking
     devtoolsModulePromise = import('./devtools/dist/panel-entry.js').then(module => {
         devtoolsModule = module;
-        console.log('[JSG-LOGGER] DevTools module pre-loaded successfully');
+        metaLog('[JSG-LOGGER] DevTools module pre-loaded successfully');
         return module;
     }).catch(error => {
-        console.error('[JSG-LOGGER] DevTools module pre-load failed:', error);
+        metaError('[JSG-LOGGER] DevTools module pre-load failed:', error);
         return null;
     });
 } else {
-    console.log('[JSG-LOGGER] DevTools module NOT pre-loaded (default config disabled - will tree-shake)');
+    metaLog('[JSG-LOGGER] DevTools module NOT pre-loaded (default config disabled - will tree-shake)');
 }
 
 /**
@@ -113,7 +114,7 @@ class JSGLogger {
      */
     async init(options = {}) {
         try {
-            console.log('[JSG-LOGGER] Initializing logger...', options.configPath ? `configPath: ${options.configPath}` : options.config ? 'inline config provided' : 'using defaults');
+            metaLog('[JSG-LOGGER] Initializing logger...', options.configPath ? `configPath: ${options.configPath}` : options.config ? 'inline config provided' : 'using defaults');
             
             // Load configuration FIRST (before environment detection)
             if (options.configPath || options.config) {
@@ -162,7 +163,12 @@ class JSGLogger {
 
             return this.getLoggerExports();
         } catch (error) {
-            console.error('JSG Logger initialization failed:', error);
+            // Try to use actual logger if partially initialized, otherwise fallback to console
+            if (this.loggers?.core) {
+                this.loggers.core.error('JSG Logger initialization failed:', error);
+            } else {
+                console.error('JSG Logger initialization failed:', error);
+            }
             // Return minimal fallback logger
             return this.createFallbackLogger();
         }
@@ -232,7 +238,12 @@ class JSGLogger {
 
             return this.getLoggerExports();
         } catch (error) {
-            console.error('JSG Logger sync initialization failed:', error);
+            // Try to use actual logger if partially initialized, otherwise fallback to console
+            if (this.loggers?.core) {
+                this.loggers.core.error('JSG Logger sync initialization failed:', error);
+            } else {
+                console.error('JSG Logger sync initialization failed:', error);
+            }
             // Return minimal fallback logger
             return this.createFallbackLogger();
         }
@@ -485,18 +496,22 @@ class JSGLogger {
 
                 // DevTools panel controls
                 enableDevPanel: async () => {
+                    const devtoolsLogger = this.getComponent('devtools-ui');
+                    
                     // Early config check - uses consumer's runtime config
                     const runtimeDevtoolsEnabled = configManager.config.devtools?.enabled ?? false;
                     
-                    console.log(`[JSG-LOGGER] enableDevPanel() called - runtime config: ${runtimeDevtoolsEnabled ? 'ENABLED' : 'DISABLED'}`);
+                    devtoolsLogger.info('enableDevPanel() called', {
+                        runtimeConfig: runtimeDevtoolsEnabled ? 'ENABLED' : 'DISABLED'
+                    });
                     
                     if (!runtimeDevtoolsEnabled) {
-                        console.warn('[JSG-LOGGER] DevTools disabled via config. Set devtools.enabled: true to enable.');
+                        devtoolsLogger.warn('DevTools disabled via config. Set devtools.enabled: true to enable.');
                         return null;
                     }
 
                     if (typeof window === 'undefined') {
-                        console.warn('[JSG-LOGGER] DevTools panel only available in browser environments');
+                        devtoolsLogger.warn('DevTools panel only available in browser environments');
                         return null;
                     }
 
@@ -505,44 +520,49 @@ class JSGLogger {
                         if (!devtoolsModule) {
                             // Check if we have a promise for pre-loading
                             if (devtoolsModulePromise) {
-                                console.log('[JSG-LOGGER] Waiting for pre-loaded DevTools module...');
+                                devtoolsLogger.info('Waiting for pre-loaded DevTools module...');
                                 // Wait for pre-load to complete
                                 devtoolsModule = await devtoolsModulePromise;
                             } else {
                                 // Runtime config override: consumer enabled devtools but default was disabled
                                 // Load on demand via dynamic import
-                                console.log('[JSG-LOGGER] Loading DevTools module dynamically (runtime config override)...');
+                                devtoolsLogger.info('Loading DevTools module dynamically (runtime config override)...');
                                 devtoolsModule = await import('./devtools/dist/panel-entry.js');
                             }
                         } else {
-                            console.log('[JSG-LOGGER] Using pre-loaded DevTools module');
+                            devtoolsLogger.info('Using pre-loaded DevTools module');
                         }
                         
                         if (!devtoolsModule || !devtoolsModule.initializePanel) {
                             throw new Error('DevTools panel module missing initializePanel export');
                         }
                         
-                        console.log('[JSG-LOGGER] Initializing DevTools panel...');
+                        devtoolsLogger.info('Initializing DevTools panel...');
                         const panel = devtoolsModule.initializePanel();
-                        console.log('[JSG-LOGGER] DevTools panel initialized successfully');
+                        devtoolsLogger.info('DevTools panel initialized successfully');
                         return panel;
                     } catch (error) {
-                        console.error('[JSG-LOGGER] Failed to load DevTools panel:', error);
-                        console.error('[JSG-LOGGER] If using npm link, ensure Vite config has: server.fs.allow: [\'..\']');
+                        devtoolsLogger.error('Failed to load DevTools panel', { error: error.message, stack: error.stack });
+                        devtoolsLogger.error('If using npm link, ensure Vite config has: server.fs.allow: [\'..\']');
                         return null;
                     }
                 },
 
                 disableDevPanel: () => {
+                    const devtoolsLogger = this.getComponent('devtools-ui');
+                    
                     if (typeof window !== 'undefined' && window.JSG_DevTools?.destroy) {
                         window.JSG_DevTools.destroy();
-                        console.log('[JSG-LOGGER] DevTools panel disabled and destroyed');
+                        devtoolsLogger.info('DevTools panel disabled and destroyed');
                         return true;
                     }
-                    console.warn('[JSG-LOGGER] DevTools panel not loaded or already destroyed');
+                    devtoolsLogger.warn('DevTools panel not loaded or already destroyed');
                     return false;
                 },
 
+                // Project info
+                getProjectName: () => configManager.config.projectName || 'JSG Logger',
+
                 // System controls
                 refresh: () => this.refreshLoggers(),
                 reset: () => {

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "@crimsonsunset/jsg-logger",
-  "version": "1.7.0",
+  "version": "1.7.4",
   "type": "module",
   "description": "Multi-environment logger with smart detection, file-level overrides, and beautiful console formatting. Test it live: https://logger.joesangiorgio.com/",
   "main": "index.js",
+  "types": "./index.d.ts",
   "keywords": [
     "logging",
     "pino",
@@ -50,6 +51,7 @@
   },
   "files": [
     "index.js",
+    "index.d.ts",
     "config/",
     "formatters/",
     "stores/",
@@ -63,7 +65,11 @@
     "LICENSE"
   ],
   "exports": {
-    ".": "./index.js",
+    ".": {
+      "import": "./index.js",
+      "require": "./index.js",
+      "types": "./index.d.ts"
+    },
     "./config": "./config/config-manager.js",
     "./config/manager": "./config/config-manager.js",
     "./config/schemes": "./config/component-schemes.js",

package/utils/meta-logger.js

@@ -0,0 +1,80 @@
+/**
+ * Meta-Logger Utilities
+ * Handles logging about the logger itself BEFORE initialization (bootstrap logs only)
+ * Respects metaLogging config setting: true (show console logs), false (silent)
+ * 
+ * IMPORTANT: Use meta-logger ONLY for pre-initialization logs. Once logger is initialized,
+ * use the actual logger with proper components for all logging.
+ */
+
+import { configManager } from '../config/config-manager.js';
+
+/**
+ * Meta log function - logs about the logger itself (BOOTSTRAP ONLY)
+ * @param {string} message - Log message
+ * @param {...any} args - Additional arguments
+ */
+export const metaLog = (message, ...args) => {
+    try {
+        const metaLoggingConfig = configManager?.config?.metaLogging;
+        
+        // If config not loaded yet or explicitly true, use console.log
+        if (metaLoggingConfig === undefined || metaLoggingConfig === true) {
+            console.log(message, ...args);
+            return;
+        }
+        
+        // If explicitly false, stay silent
+        if (metaLoggingConfig === false) {
+            return;
+        }
+    } catch (error) {
+        // If anything fails, fall back to console.log
+        console.log(message, ...args);
+    }
+};
+
+/**
+ * Meta warn function - warnings about the logger itself (BOOTSTRAP ONLY)
+ * @param {string} message - Warning message
+ * @param {...any} args - Additional arguments
+ */
+export const metaWarn = (message, ...args) => {
+    try {
+        const metaLoggingConfig = configManager?.config?.metaLogging;
+        
+        if (metaLoggingConfig === undefined || metaLoggingConfig === true) {
+            console.warn(message, ...args);
+            return;
+        }
+        
+        if (metaLoggingConfig === false) {
+            return;
+        }
+    } catch (error) {
+        console.warn(message, ...args);
+    }
+};
+
+/**
+ * Meta error function - errors about the logger itself (BOOTSTRAP ONLY)
+ * @param {string} message - Error message
+ * @param {...any} args - Additional arguments
+ */
+export const metaError = (message, ...args) => {
+    try {
+        const metaLoggingConfig = configManager?.config?.metaLogging;
+        
+        if (metaLoggingConfig === undefined || metaLoggingConfig === true) {
+            console.error(message, ...args);
+            return;
+        }
+        
+        if (metaLoggingConfig === false) {
+            return;
+        }
+    } catch (error) {
+        console.error(message, ...args);
+    }
+};
+