@crimsonsunset/jsg-logger 1.7.0 → 1.7.2

package/CHANGELOG.md

@@ -5,7 +5,7 @@ All notable changes to the JSG Logger project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [1.6.0] - 2025-01-XX 🎯 **Config-Driven Tree-Shaking & Enhanced Logging**
+## [1.7.0] - 2025-01-XX 🎯 **Config-Driven Tree-Shaking & Enhanced Logging**
 
 ### Added
 - **Config-Driven Tree-Shaking** - DevTools panel tree-shaking now based on default config at module load time
@@ -56,13 +56,118 @@ No breaking changes. Existing code continues to work.
 - No special Vite config needed for production builds
 - npm link users: add `server.fs.allow: ['..']` to Vite config for dev
 
-## [Unreleased]
+## [1.7.1] - 2025-11-05 🎯 **TypeScript Support & Zero-Optional-Chaining API**
 
-## [1.5.2] - 2025-10-25 🐛 **PATCH: CLI Formatter Custom Component Display**
+### Added
+- **TypeScript Definitions** - Full TypeScript support with `index.d.ts`
+  - Complete type definitions for all logger interfaces
+  - `LoggerInstance`, `LoggerComponents`, `LoggerInstanceType` interfaces
+  - Proper exports configuration in `package.json` with `types` field
+- **Safe Component Getters** - Component getters initialized in constructor
+  - `_initializeSafeComponentGetters()` ensures components accessible before initialization
+  - Common components (reactComponents, astroComponents, etc.) always available
+  - Returns no-op logger factories if logger not initialized yet
+
+### Changed
+- **getComponent Always Available** - `getComponent` is now non-optional in TypeScript types
+  - Removed `?` optional marker from `getComponent` in `LoggerInstanceType`
+  - Always returns a logger instance (no-op if not initialized)
+  - Consumers can call `loggerInstance.getComponent('componentName')` without optional chaining
+- **Fallback Logger Enhancement** - `createFallbackLogger()` now includes `getComponent`
+  - Ensures `getComponent` exists even when initialization fails
+  - Returns no-op logger factory for safe fallback behavior
+- **Enhanced getComponent Safety** - Improved error handling and edge cases
+  - Returns no-op logger if instance not initialized
+  - Returns no-op logger if logger creation fails
+  - Prevents crashes when logger unavailable
 
 ### Fixed
-- **CLI formatter custom component names** - Formatter was using hardcoded `COMPONENT_SCHEME` instead of `configManager`, causing custom component names to display as `[JSG-CORE]` instead of user-defined names like `[SETUP]`
-- **Browser formatter** - Removed redundant component name transformation
+- **Optional Chaining Burden** - Eliminated need for `?.` optional chaining in consumer code
+  - Consumers can now use `loggerInstance.getComponent('componentName').debug(...)` directly
+  - No more `loggerInstance?.getComponent?.('componentName')?.debug(...)` chains
+  - TypeScript types guarantee `getComponent` always exists
+
+### Technical Details
+- **File**: `index.d.ts` (NEW)
+  - Complete TypeScript definitions for the logger package
+  - Non-optional `getComponent` method signature
+  - Proper interface documentation
+  
+- **File**: `index.js`
+  - Added `_initializeSafeComponentGetters()` method called in constructor
+  - Enhanced `getComponent()` to always return logger (no-op fallback)
+  - Added `_createNoOpLogger()` private method for safe fallbacks
+  - Updated `createFallbackLogger()` to include `getComponent`
+  - Modified `_createAutoDiscoveryGetters()` to preserve safe getters
+
+- **File**: `package.json`
+  - Added `"types": "./index.d.ts"` field
+  - Added `index.d.ts` to `files` array
+  - Updated `exports` to include proper TypeScript types export
+
+### Migration Notes
+No breaking changes. Existing code continues to work, but optional chaining is now optional (pun intended).
+
+**For consumers:**
+- Can now use `loggerInstance.getComponent('componentName')` without `?.`
+- TypeScript users get full type safety and autocomplete
+- No-op logger returned if logger not initialized (safe to call)
+- Recommended: Use `getInstanceSync()` for synchronous access instead of `getInstance()` when possible
+
+## [1.7.0] - 2025-01-XX 🎯 **Config-Driven Tree-Shaking & Enhanced Logging**
+
+### Added
+- **Config-Driven Tree-Shaking** - DevTools panel tree-shaking now based on default config at module load time
+  - Tree-shaking determined by `defaultConfig.devtools.enabled` (default: `false`)
+  - When disabled, devtools code completely tree-shaken (zero bundle impact)
+  - When enabled via runtime config, loads dynamically on demand
+  - Static import analysis allows bundlers to eliminate unused code paths
+- **Comprehensive DevTools Logging** - Added detailed logging throughout DevTools lifecycle
+  - Module load: logs default config tree-shaking status
+  - Config loading: logs when devtools enabled/disabled via user config
+  - DevTools activation: logs pre-load status, dynamic loading, and initialization steps
+  - Config merge: logs devtools status changes between defaults and user config
+
+### Changed
+- **DevTools Import Strategy** - Simplified to relative path imports
+  - Removed complex Function constructor + package export path logic
+  - Uses simple relative path: `./devtools/dist/panel-entry.js`
+  - Works in production builds, requires `server.fs.allow: ['..']` for npm link dev
+- **Config Loading Logging** - Enhanced visibility into config loading process
+  - Logs config source (file path vs inline object)
+  - Logs devtools status before/after config merge
+  - Logs initialization start with config source information
+
+### Fixed
+- **Tree-Shaking Detection** - Bundlers can now properly analyze and eliminate devtools code when disabled
+- **DevTools Pre-loading** - Non-blocking pre-load when default config enables devtools
+- **Runtime Config Override** - Dynamic loading works correctly when runtime config enables devtools but default disabled
+
+### Technical Details
+- **File**: `index.js`
+  - Added conditional static import based on `defaultConfig.devtools.enabled`
+  - Lazy initialization pattern to avoid top-level await
+  - Enhanced `enableDevPanel()` with comprehensive logging
+  - Pre-loads devtools module when default config enables it
+  
+- **File**: `config/config-manager.js`
+  - Added logging for config loading (file vs inline)
+  - Added devtools status logging before/after config merge
+  - Enhanced visibility into config changes
+
+### Migration Notes
+No breaking changes. Existing code continues to work.
+
+**For consumers:**
+- DevTools code tree-shaken by default (zero bundle impact)
+- Enable via runtime config: `{ devtools: { enabled: true } }`
+- DevTools loads dynamically when `enableDevPanel()` called
+- No special Vite config needed for production builds
+- npm link users: add `server.fs.allow: ['..']` to Vite config for dev
+
+## [Unreleased]
+
+## [1.5.2] - 2025-10-25 🐛 **PATCH: CLI Formatter Custom Component Display**
 
 ### Technical Changes
 - `formatters/cli-formatter.js` - Use `configManager.getComponentConfig()` instead of static `COMPONENT_SCHEME`

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

@@ -53,6 +53,9 @@ class JSGLogger {
         this.environment = null; // Will be set after config loads
         this.initialized = false;
         this.components = {}; // Auto-discovery getters
+        
+        // Initialize component getters with safe factories that always return loggers
+        this._initializeSafeComponentGetters();
     }
 
     /**
@@ -637,9 +640,13 @@ class JSGLogger {
             fatal: console.error
         };
 
+        // No-op logger factory for getComponent
+        const noOpLogger = () => fallback;
+
         return {
             core: fallback,
             createLogger: () => fallback,
+            getComponent: noOpLogger,
             config: {environment: 'fallback'},
             logStore: {getRecent: () => [], clear: () => {}},
             controls: {
@@ -653,20 +660,46 @@ class JSGLogger {
     }
 
     /**
-     * Create auto-discovery getters for easy component access
-     * Supports both kebab-case (original) and camelCase naming
+     * Initialize safe component getters that always return logger factories
+     * This ensures components can be accessed even before initialization
      * @private
      */
-    _createAutoDiscoveryGetters() {
-        this.components = {};
+    _initializeSafeComponentGetters() {
+        // Create safe getters for common components that always return a logger factory
+        // These will work even if logger isn't initialized yet
+        const commonComponents = [
+            'reactComponents', 'react-components',
+            'astroComponents', 'astro-components',
+            'astroBuild', 'astro-build',
+            'astroIntegration', 'astro-integration',
+            'contentProcessing', 'content-processing',
+            'textUtils', 'text-utils',
+            'dateUtils', 'date-utils',
+            'pages', 'webComponents', 'web-components',
+            'core', 'api', 'ui', 'database', 'test', 'preact',
+            'auth', 'analytics', 'performance', 'websocket',
+            'notification', 'router', 'cache',
+            'config', 'seo', 'devServer', 'dev-server'
+        ];
+
+        commonComponents.forEach(name => {
+            // Create getter that always returns a logger (no-op if not initialized)
+            this.components[name] = () => this.getComponent(name);
+        });
+    }
 
+    _createAutoDiscoveryGetters() {
+        // Don't reset components - preserve safe getters created in constructor
+        // Only add getters for newly created loggers
         Object.keys(this.loggers).forEach(name => {
-            // Original kebab-case name
-            this.components[name] = () => this.getComponent(name);
+            // Only add if not already exists (preserve safe getters)
+            if (!this.components[name]) {
+                this.components[name] = () => this.getComponent(name);
+            }
 
             // camelCase convenience getter
             const camelName = name.replace(/-([a-z])/g, (match, letter) => letter.toUpperCase());
-            if (camelName !== name) {
+            if (camelName !== name && !this.components[camelName]) {
                 this.components[camelName] = () => this.getComponent(name);
             }
         });
@@ -674,12 +707,23 @@ class JSGLogger {
 
     /**
      * Get a specific component logger with auto-creation for custom components
+     * Always returns a logger instance (no-op if initialization failed)
      * @param {string} componentName - Component name to retrieve
-     * @returns {Object} Logger instance (auto-created if needed)
+     * @returns {Object} Logger instance (always returns logger, never undefined)
      */
     getComponent(componentName) {
-        // If logger doesn't exist, auto-create it for custom components
-        if (!this.loggers[componentName]) {
+        // If logger instance isn't initialized, return no-op logger
+        if (!this.initialized || !this.loggers) {
+            return this._createNoOpLogger(componentName);
+        }
+
+        // If logger exists, return it
+        if (this.loggers[componentName]) {
+            return this.loggers[componentName];
+        }
+
+        // Try to create logger - if it fails, return no-op logger
+        try {
             // Check if this is a configured component or custom component
             const hasConfig = configManager.config.components?.[componentName];
             const hasScheme = COMPONENT_SCHEME[componentName];
@@ -700,9 +744,31 @@ class JSGLogger {
             if (camelName !== componentName) {
                 this.components[camelName] = () => this.getComponent(componentName);
             }
+
+            return this.loggers[componentName];
+        } catch (error) {
+            // If logger creation fails, return no-op logger to prevent crashes
+            console.warn(`[JSG-LOGGER] Failed to create logger for component '${componentName}', using no-op logger:`, error);
+            return this._createNoOpLogger(componentName);
         }
+    }
 
-        return this.loggers[componentName];
+    /**
+     * Create a silent no-op logger that can be safely used when logger isn't available
+     * @param {string} componentName - Component name (for consistency)
+     * @returns {Object} Logger instance with all methods as no-ops
+     * @private
+     */
+    _createNoOpLogger(componentName) {
+        // Silent no-op logger - all methods do nothing
+        return {
+            trace: () => {},
+            debug: () => {},
+            info: () => {},
+            warn: () => {},
+            error: () => {},
+            fatal: () => {}
+        };
     }
 
     /**

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "@crimsonsunset/jsg-logger",
-  "version": "1.7.0",
+  "version": "1.7.2",
   "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",