@crimsonsunset/jsg-logger 1.0.9 → 1.1.0

package/docs/next-session.md

@@ -14,9 +14,9 @@
 
 ---
 
-**Date:** August 6, 2025  
-**Session Goal:** 🎯 **COMPLETE** - ✅ Logger extraction, NPM publication, and documentation structure  
-**Next Session Goal:** 🎨 **DevTools Panel Implementation** - Browser-based log filtering interface (optional enhancement)
+**Date:** August 21, 2025  
+**Session Goal:** 🚀 **API Enhancement - Phase 8** - Eliminate boilerplate code for projects using JSG Logger  
+**Status:** 🔄 **IN PROGRESS** - Core enhancements implemented, testing & publishing remain
 
 ## 🎉 MAJOR ACCOMPLISHMENTS THIS SESSION
 
@@ -61,21 +61,35 @@
 - **Clean Integration** - DeskThing-Apps migration successful
 - **Documentation Complete** - All standard files in place
 
-## 📋 CURRENT PRIORITIES
-
-### **No Immediate Tasks** ✅
-- **Logger is feature complete** - Core functionality fully implemented
-- **Documentation structure complete** - All standard files added
-- **NPM package stable** - Version 1.0.6 published and working
-
-### **Optional Future Enhancements** (Low Priority)
-- [ ] **DevTools Panel** - Browser-based log filtering interface
-  - Runtime-injected widget with Preact
-  - Collapsible sidebar from left side
-  - Controls console filtering without displaying logs
-  - IndexedDB persistence for panel state
+## 📋 CURRENT PRIORITIES - PHASE 8 API ENHANCEMENT
+
+### **🎯 Primary Goal: Eliminate Project Boilerplate** 🔄 IN PROGRESS
+**Problem**: Projects need ~220 lines of boilerplate code to use JSG Logger effectively
+**Solution**: Build essential patterns directly into the JSG Logger package
+
+### **✅ COMPLETED THIS SESSION:**
+- [x] **Static Singleton Pattern** - `CACPLogger.getInstance()` methods
+- [x] **Auto-Discovery Getters** - Both camelCase and kebab-case component access
+- [x] **Non-Destructive Error Handling** - Missing components log but don't break
+- [x] **Static Performance Logging** - `CACPLogger.logPerformance()` utility
+- [x] **Enhanced Export Structure** - Components and getComponent available
+
+### **🔄 REMAINING TASKS:**
+- [ ] **Complete Export Structure** - Ensure static methods accessible
+- [ ] **Version Bump** - Update to 1.1.0 (minor for new features)
+- [ ] **NPM Publish** - Deploy enhanced package
+- [ ] **Test Integration** - Validate simplified project usage
+- [ ] **Update README** - Document new API patterns
+
+### **📊 Expected Impact:**
+- **Project boilerplate**: 220 lines → 15 lines (93% reduction)
+- **Initialization**: Complex setup → Single `getInstance()` call  
+- **Component access**: Manual mapping → Auto-discovery with both naming conventions
+- **Performance logging**: Custom utilities → Built-in static method
+
+### **🚀 Next Steps After Completion:**
+- [ ] **DevTools Panel** - Browser-based log filtering interface (Phase 6)
 - [ ] **Performance Monitoring** - Track logging overhead metrics
-- [ ] **Export Utilities** - Save logs to file formats
 - [ ] **Framework Integration Guides** - React, Vue, Svelte examples
 
 ## 🔧 Technical Notes

package/docs/roadmap.md

@@ -390,10 +390,156 @@ Console filtering updates
 
 ## 🎯 Next Steps
 
-### **Immediate Priorities**
-- None - logger is feature complete and stable
+### **Phase 8: API Enhancement for Project Simplification** 🚀 IN PROGRESS
+**Goal**: Eliminate boilerplate code that every project needs to implement when using JSG Logger
 
-### **Optional Enhancements**
+#### **Background - The Problem**
+Projects using JSG Logger currently need to implement ~220 lines of boilerplate:
+- Singleton/caching patterns
+- Component logger getters with fallback handling  
+- Performance logging utilities
+- Auto-discovery of available components
+- Error handling when components don't exist
+
+**This defeats the purpose of having a reusable logger package.**
+
+#### **Solution - Built-in Enhancement Features**
+
+**✅ Design Decisions Made:**
+1. **getInstance location**: Static on CACPLogger class
+2. **Auto-discovery naming**: Both camelCase and kebab-case support
+3. **Performance logging**: Static utility `JSGLogger.logPerformance(...)`
+4. **Error handling**: Non-destructive with helpful logging (no fallbacks)
+5. **Config auto-discovery**: Strict mode - only configured components work
+6. **Getter creation**: Eagerly during init (not lazy)
+
+#### **🔧 Implementation Plan**
+
+##### **Enhancement 1: Static Singleton Pattern**
+```javascript
+// Static method on CACPLogger class
+const logger = CACPLogger.getInstance(config);
+const logger2 = CACPLogger.getInstance(); // Same instance, no config needed
+```
+
+**Implementation Location**: `index.js` CACPLogger class
+- Add `static _instance = null`
+- Add `static async getInstance(options = {})`
+- Add `static getInstanceSync(options = {})` for sync environments
+
+##### **Enhancement 2: Auto-Discovery Component Getters**
+```javascript
+// From config: { "components": { "astro-build": {}, "react-components": {} }}
+
+// Both naming conventions work:
+logger.components.astroBuild()      // camelCase convenience  
+logger.components['astro-build']()  // original kebab-case
+logger.components.reactComponents() // camelCase
+logger.components['react-components']() // kebab-case
+
+// Plus explicit method
+logger.getComponent('astro-build')
+```
+
+**Implementation**:
+- Add `this.components = {}` to constructor
+- Add `_createAutoDiscoveryGetters()` method - called eagerly during init
+- Create getters for both kebab-case and camelCase from config components
+- Add to `getLoggerExports()` return object
+
+##### **Enhancement 3: Non-Destructive Component Access**
+```javascript
+// If 'missing-component' not in config:
+const missingLogger = logger.getComponent('missing-component');
+// Logs: "Component 'missing-component' not found. Available: astro-build, react-components"
+// Returns: Logger that outputs error context but doesn't break
+
+missingLogger.info('test'); 
+// Outputs: "[MISSING-COMPONENT] ⚠️ Component not configured - test"
+```
+
+**Implementation**:
+- Add `getComponent(componentName)` method
+- Add `_createErrorLogger(componentName)` helper
+- Error prefix: `[COMPONENT-NAME] ⚠️ Component not configured -`
+- Strict mode: Only configured components, log missing ones
+
+##### **Enhancement 4: Static Performance Logging**
+```javascript
+const startTime = performance.now();
+// ... do work ...
+JSGLogger.logPerformance('Page Generation', startTime, 'astro-build');
+// Auto-thresholds: >1000ms = warn, >100ms = info, else = debug
+```
+
+**Implementation**:
+- Add `static async logPerformance(operation, startTime, component = 'performance')`
+- Auto-getInstance() - no manual initialization required
+- Built-in performance thresholds and formatting
+- Fallback to console if logger fails
+
+#### **🎯 Result - Dramatically Simplified Project Usage**
+
+**Before Enhancement** (220+ lines of boilerplate):
+```typescript
+// Complex singleton pattern, fallback handling, component getters, etc.
+let loggerInstance: any = null;
+// ... 200+ lines of infrastructure code ...
+```
+
+**After Enhancement** (15-20 lines):
+```typescript
+import JSGLogger from '@crimsonsunset/jsg-logger';
+
+const logger = JSGLogger.getInstance({
+  configPath: './logger-config.json'
+});
+
+// Optional project-specific convenience exports
+export const loggers = {
+  build: logger.components.astroBuild,
+  react: logger.components.reactComponents, 
+  textUtils: logger.components.textUtils
+};
+
+export { logger, JSGLogger };
+```
+
+#### **📋 Implementation Checklist**
+
+**✅ COMPLETED:**
+- [x] Added static `_instance` property and `getInstance()` methods
+- [x] Added `_createAutoDiscoveryGetters()` calls to init/initSync
+- [x] Implemented `_createAutoDiscoveryGetters()` with both naming conventions
+- [x] Implemented `getComponent()` with non-destructive error handling
+- [x] Implemented `_createErrorLogger()` with proper error messaging
+- [x] Added static `logPerformance()` with auto-getInstance
+- [x] Updated `getLoggerExports()` to include components and getComponent
+
+**🔄 IN PROGRESS:**
+- [ ] Complete export structure for static methods
+- [ ] Version bump and publish to NPM
+- [ ] Test new API with simplified project integration
+- [ ] Update project files to use new simplified API
+
+**📊 Expected Outcome:**
+- **Project boilerplate reduced**: 220 lines → 15 lines (93% reduction)
+- **API simplification**: Single `getInstance()` call vs complex initialization
+- **Auto-discovery**: No manual component mapping required
+- **Non-destructive errors**: Missing components log but don't break apps
+- **Built-in utilities**: Performance logging included
+
+#### **🚀 Next Implementation Steps**
+1. Complete JSG Logger package enhancements
+2. Bump version to 1.1.0 (minor version for new features)
+3. Publish updated package to NPM
+4. Update jsg-tech-check-site to use simplified API
+5. Test and validate 93% boilerplate reduction
+6. Document new API in README examples
+
+---
+
+### **Previous Optional Enhancements** (Lower Priority)
 - **DevTools Panel** - Browser interface for log filtering
 - **Performance Monitoring** - Track logging overhead
 - **Framework Guides** - React, Vue, Svelte integration examples

package/index.js

@@ -18,11 +18,41 @@ import {LogStore} from './stores/log-store.js';
  * Manages logger instances and provides the public API
  */
 class CACPLogger {
+    // Static singleton instance
+    static _instance = null;
+
     constructor() {
         this.loggers = {};
         this.logStore = new LogStore();
         this.environment = getEnvironment();
         this.initialized = false;
+        this.components = {}; // Auto-discovery getters
+    }
+
+    /**
+     * Get singleton instance with auto-initialization
+     * @param {Object} options - Initialization options (only used on first call)
+     * @returns {Promise<CACPLogger>} Singleton logger instance
+     */
+    static async getInstance(options = {}) {
+        if (!CACPLogger._instance) {
+            CACPLogger._instance = new CACPLogger();
+            await CACPLogger._instance.init(options);
+        }
+        return CACPLogger._instance;
+    }
+
+    /**
+     * Get singleton instance synchronously (for environments without async support)
+     * @param {Object} options - Initialization options (only used on first call) 
+     * @returns {CACPLogger} Singleton logger instance
+     */
+    static getInstanceSync(options = {}) {
+        if (!CACPLogger._instance) {
+            CACPLogger._instance = new CACPLogger();
+            CACPLogger._instance.initSync(options);
+        }
+        return CACPLogger._instance;
     }
 
     /**
@@ -50,6 +80,9 @@ class CACPLogger {
             // Add utility methods
             this.addUtilityMethods();
 
+            // Create auto-discovery getters (eager)
+            this._createAutoDiscoveryGetters();
+
             this.initialized = true;
 
             // Log initialization success
@@ -90,6 +123,9 @@ class CACPLogger {
             // Add utility methods
             this.addUtilityMethods();
 
+            // Create auto-discovery getters (eager)
+            this._createAutoDiscoveryGetters();
+
             this.initialized = true;
 
             // Log initialization success
@@ -181,6 +217,12 @@ class CACPLogger {
             // All component loggers
             ...this.loggers,
 
+            // Auto-discovery convenience getters (kebab-case and camelCase)
+            components: this.components,
+
+            // Component getter with error handling
+            getComponent: (componentName) => this.getComponent(componentName),
+
             // Utility methods
             createLogger: (componentName) => {
                 if (!this.loggers[componentName]) {
@@ -219,12 +261,18 @@ class CACPLogger {
                 listComponents: () => Object.keys(this.loggers),
                 enableDebugMode: () => {
                     Object.keys(this.loggers).forEach(component => {
-                        this.controls.setLevel(component, 'debug');
+                        if (this.loggers[component]) {
+                            this.loggers[component].level = 'debug';
+                            this.loggers[component]._effectiveLevel = 'debug';
+                        }
                     });
                 },
                 enableTraceMode: () => {
                     Object.keys(this.loggers).forEach(component => {
-                        this.controls.setLevel(component, 'trace');
+                        if (this.loggers[component]) {
+                            this.loggers[component].level = 'trace';
+                            this.loggers[component]._effectiveLevel = 'trace';
+                        }
                     });
                 },
 
@@ -394,6 +442,99 @@ class CACPLogger {
             }
         };
     }
+
+    /**
+     * Create auto-discovery getters for easy component access
+     * Supports both kebab-case (original) and camelCase naming
+     * @private
+     */
+    _createAutoDiscoveryGetters() {
+        this.components = {};
+        
+        Object.keys(this.loggers).forEach(name => {
+            // Original kebab-case name
+            this.components[name] = () => this.getComponent(name);
+            
+            // camelCase convenience getter
+            const camelName = name.replace(/-([a-z])/g, (match, letter) => letter.toUpperCase());
+            if (camelName !== name) {
+                this.components[camelName] = () => this.getComponent(name);
+            }
+        });
+    }
+
+    /**
+     * Get a specific component logger with non-destructive error handling
+     * @param {string} componentName - Component name to retrieve
+     * @returns {Object} Logger instance or error-context logger
+     */
+    getComponent(componentName) {
+        if (!this.loggers[componentName]) {
+            const available = Object.keys(this.loggers).join(', ');
+            
+            // Log the error using the config logger if available
+            if (this.loggers.config) {
+                this.loggers.config.warn(`Component '${componentName}' not found. Available: ${available}`);
+            } else {
+                console.warn(`[JSG-LOGGER] Component '${componentName}' not found. Available: ${available}`);
+            }
+            
+            // Return non-destructive error logger
+            return this._createErrorLogger(componentName);
+        }
+        
+        return this.loggers[componentName];
+    }
+
+    /**
+     * Create error-context logger that doesn't break the app
+     * @param {string} componentName - Name of the missing component
+     * @returns {Object} Logger with error context in all messages
+     * @private
+     */
+    _createErrorLogger(componentName) {
+        const prefix = `[${componentName.toUpperCase()}]`;
+        const errorMsg = '⚠️ Component not configured -';
+        
+        return {
+            trace: (msg, ...args) => console.log(`${prefix} ${errorMsg}`, msg, ...args),
+            debug: (msg, ...args) => console.log(`${prefix} ${errorMsg}`, msg, ...args),
+            info: (msg, ...args) => console.info(`${prefix} ${errorMsg}`, msg, ...args),
+            warn: (msg, ...args) => console.warn(`${prefix} ${errorMsg}`, msg, ...args),
+            error: (msg, ...args) => console.error(`${prefix} ${errorMsg}`, msg, ...args),
+            fatal: (msg, ...args) => console.error(`${prefix} ${errorMsg}`, msg, ...args)
+        };
+    }
+
+    /**
+     * Static utility for performance logging with auto-getInstance
+     * @param {string} operation - Description of the operation being measured
+     * @param {number} startTime - Start time from performance.now()
+     * @param {string} component - Component name for logging (defaults to 'performance')
+     * @returns {number} Duration in milliseconds
+     */
+    static async logPerformance(operation, startTime, component = 'performance') {
+        try {
+            const instance = await CACPLogger.getInstance();
+            const logger = instance.getComponent(component);
+            const duration = performance.now() - startTime;
+            
+            if (duration > 1000) {
+                logger.warn(`${operation} took ${duration.toFixed(2)}ms (slow)`);
+            } else if (duration > 100) {
+                logger.info(`${operation} took ${duration.toFixed(2)}ms`);
+            } else {
+                logger.debug(`${operation} took ${duration.toFixed(2)}ms (fast)`);
+            }
+            
+            return duration;
+        } catch (error) {
+            // Fallback to console if logger fails
+            const duration = performance.now() - startTime;
+            console.log(`[${component.toUpperCase()}] ${operation} took ${duration.toFixed(2)}ms`);
+            return duration;
+        }
+    }
 }
 
 // Create singleton instance
@@ -408,6 +549,12 @@ if (isBrowser() && typeof window !== 'undefined') {
     window.CACP_Logger = enhancedLoggers.controls;
 }
 
-// Export both the initialized loggers and the init function for advanced usage
+// Add static methods to the enhanced loggers for convenience
+enhancedLoggers.getInstance = CACPLogger.getInstance;
+enhancedLoggers.getInstanceSync = CACPLogger.getInstanceSync;
+enhancedLoggers.logPerformance = CACPLogger.logPerformance;
+enhancedLoggers.CACPLogger = CACPLogger;
+
+// Export both the initialized loggers and the class for advanced usage
 export default enhancedLoggers;
 export {logger as CACPLogger};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crimsonsunset/jsg-logger",
-  "version": "1.0.9",
+  "version": "1.1.0",
   "type": "module",
   "description": "JSG Logger - Multi-environment logger with smart detection, file-level overrides, and beautiful console formatting",
   "main": "index.js",