@crimsonsunset/jsg-logger 1.8.1 → 1.8.3

package/CHANGELOG.md

@@ -5,6 +5,35 @@ 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.8.3] - 2026-03-28 🔌 **addTransport() API**
+
+### Added
+- **`JSGLogger.addTransport(transport)`** — new static method to register a transport on the running singleton without reinitializing. Bypasses the reinit guard entirely. Idempotent (calling with the same instance twice is a no-op). Also exposed on the default export as `logger.addTransport()`.
+
+### Fixed
+- **Transport registration after module-level init** — `jsg-logger` initializes itself with default config at module evaluation time (line 1042). This caused the reinit guard introduced in 1.8.2 to silently drop transports passed to `getInstanceSync(options)` in e.g. Next.js `instrumentation.ts`, because `initialized` was already `true`. `addTransport()` is the correct API for post-init transport registration — it pushes directly to `_instance.transports` and is unaffected by the reinit guard.
+
+### Migration
+Replace `getInstanceSync({ ...config, transports: [myTransport] })` in post-init contexts (e.g. Next.js `register()`) with:
+```ts
+JSGLogger.addTransport(myTransport);
+```
+
+## [1.8.2] - 2026-03-27 🛡️ **Reinit Guard + configure() API**
+
+### Added
+- **`JSGLogger.configure(partialConfig)`** — new static method for post-init config updates. Merges partial config into the running instance without reinitializing or touching registered transports. Exposed on the default export as `logger.configure()` and on the class as `JSGLogger.configure()`. If called before any initialization has occurred, delegates to `getInstanceSync(partialConfig)`.
+
+### Fixed
+- **Reinit guard in `getInstanceSync()`** — calling `getInstanceSync(options)` on an already-initialized instance now returns the existing singleton instead of reinitializing. Previously this would wipe registered transports (e.g. PostHog transport) on every call. A `console.warn` is emitted to surface the misuse at call sites.
+- **Reinit guard in `getInstance()`** — same protection applied to the async path.
+
+### Changed
+- Removed stale comment "// If options are provided, we need to reinitialize even if global instance exists" — the behavior is now the opposite by design.
+
+### Migration
+No breaking changes. If you were relying on calling `getInstanceSync(options)` multiple times to update config post-init (which was always a footgun), switch to `logger.configure(partialConfig)` instead.
+
 ## [1.7.7] - 2025-11-07 🔧 **DevTools Import Path Fix**
 
 ### Fixed

package/index.d.ts

@@ -195,6 +195,12 @@ export interface LoggerInstanceType {
    */
   getInstanceSync?: (config?: JSGLoggerConfig) => LoggerInstanceType;
 
+  /**
+   * Add a transport to the running singleton without reinitializing. Idempotent.
+   * @param transport - LogTransport instance to register
+   */
+  addTransport?: (transport: LogTransport) => void;
+
   /**
    * Static performance logging utility
    */
@@ -225,6 +231,21 @@ export interface JSGLogger {
    */
   getInstanceSync(config?: JSGLoggerConfig): LoggerInstanceType;
 
+  /**
+   * Add a transport to the running singleton without reinitializing.
+   * Safe to call even after the singleton was initialized by module-level code or a
+   * third-party library — bypasses the reinit guard entirely. Idempotent.
+   *
+   * @param transport - LogTransport instance to register
+   *
+   * @example
+   * ```ts
+   * // instrumentation.ts — runs after module-level init, still registers transport cleanly
+   * JSGLogger.addTransport(new PostHogServerTransport(posthogServer, { level: 'warn' }));
+   * ```
+   */
+  addTransport(transport: LogTransport): void;
+
   /**
    * Static performance logging utility
    * @param label - Performance label

package/index.js

@@ -81,14 +81,17 @@ class JSGLogger {
                 window.__JSG_Logger_Enhanced__ = JSGLogger._enhancedLoggers;
             }
         } else if (hasOptions) {
-            // Instance exists but new options provided - reinitialize
-            JSGLogger._enhancedLoggers = await JSGLogger._instance.init(options);
-            
-            // Make runtime controls available globally in browser for debugging
-            // (same as getInstanceSync behavior)
-            if (isBrowser() && typeof window !== 'undefined' && JSGLogger._enhancedLoggers?.controls) {
-                window.JSG_Logger = JSGLogger._enhancedLoggers.controls;
-                window.__JSG_Logger_Enhanced__ = JSGLogger._enhancedLoggers;
+            if (JSGLogger._instance.initialized) {
+                console.warn(
+                    '[JSGLogger] getInstance() called with options on an already-initialized instance — ' +
+                    'options were ignored to preserve registered transports. Use configure() to update settings post-init.'
+                );
+            } else {
+                JSGLogger._enhancedLoggers = await JSGLogger._instance.init(options);
+                if (isBrowser() && typeof window !== 'undefined' && JSGLogger._enhancedLoggers?.controls) {
+                    window.JSG_Logger = JSGLogger._enhancedLoggers.controls;
+                    window.__JSG_Logger_Enhanced__ = JSGLogger._enhancedLoggers;
+                }
             }
         }
 
@@ -104,22 +107,25 @@ class JSGLogger {
     static getInstanceSync(options = {}) {
         const hasOptions = options && Object.keys(options).length > 0;
         
-        // If options are provided, we need to reinitialize even if global instance exists
-        // This ensures config changes (like devtools.enabled) are applied
         if (hasOptions) {
-            // Reinitialize with new options - this will update the global references
+            if (JSGLogger._instance?.initialized) {
+                console.warn(
+                    '[JSGLogger] getInstanceSync() called with options on an already-initialized instance — ' +
+                    'options were ignored to preserve registered transports. Use configure() to update settings post-init.'
+                );
+                return JSGLogger._enhancedLoggers;
+            }
+
             if (!JSGLogger._instance) {
                 JSGLogger._instance = new JSGLogger();
             }
             JSGLogger._enhancedLoggers = JSGLogger._instance.initSync(options);
             
-            // Update global references after reinitialization
             if (isBrowser() && typeof window !== 'undefined' && JSGLogger._enhancedLoggers?.controls) {
                 window.JSG_Logger = JSGLogger._enhancedLoggers.controls;
                 window.__JSG_Logger_Enhanced__ = JSGLogger._enhancedLoggers;
             }
             
-            // Server equivalent: persist to globalThis so cross-bundle module instances can find it
             if (!isBrowser()) {
                 globalThis.__JSG_Logger_Enhanced__ = JSGLogger._enhancedLoggers;
             }
@@ -559,6 +565,9 @@ class JSGLogger {
             // Expose config manager for runtime configuration
             configManager: configManager,
 
+            // Post-init config updater — safe to call after transports are registered
+            configure: (partialConfig) => JSGLogger.configure(partialConfig),
+
             // Log store for popup/debugging
             logStore: this.logStore,
 
@@ -987,6 +996,52 @@ class JSGLogger {
         }
     }
 
+    /**
+     * Update logger configuration post-initialization without reinitializing.
+     * Merges partialConfig into the current config without touching registered transports.
+     * Transports can only be registered at init time — this method cannot add or remove them.
+     * If called before any initialization has occurred, delegates to getInstanceSync(partialConfig).
+     * @param {Object} partialConfig - Partial config to merge into the current config
+     * @returns {Object} Enhanced logger exports
+     */
+    static configure(partialConfig = {}) {
+        if (!JSGLogger._instance?.initialized) {
+            return JSGLogger.getInstanceSync(partialConfig);
+        }
+
+        const currentTransports = JSGLogger._instance.transports;
+        const normalized = configManager._normalizeConfigStructure(partialConfig);
+        configManager.config = configManager.mergeConfigs(configManager.config, normalized);
+        configManager.config.transports = currentTransports;
+        JSGLogger._instance.transports = currentTransports;
+        JSGLogger._instance.refreshLoggers();
+
+        return JSGLogger._enhancedLoggers;
+    }
+
+    /**
+     * Add a transport to the running singleton without reinitializing.
+     * Safe to call even if the singleton was already initialized by module-level code
+     * or a third-party library — bypasses the reinit guard entirely.
+     * Idempotent: calling with the same transport instance twice is a no-op.
+     * @param {Object} transport - LogTransport instance to register
+     * @returns {void}
+     */
+    static addTransport(transport) {
+        if (!transport || typeof transport.send !== 'function') {
+            metaWarn('[JSGLogger] addTransport() received an invalid transport — must have a send() method');
+            return;
+        }
+        if (!JSGLogger._instance) {
+            metaWarn('[JSGLogger] addTransport() called before any initialization — initializing with defaults first');
+            JSGLogger._instance = new JSGLogger();
+            JSGLogger._enhancedLoggers = JSGLogger._instance.initSync({});
+        }
+        if (!JSGLogger._instance.transports.includes(transport)) {
+            JSGLogger._instance.transports.push(transport);
+        }
+    }
+
     /**
      * Get singleton controls without triggering initialization
      * Checks window.JSG_Logger first to ensure singleton works across separate bundles
@@ -1019,6 +1074,8 @@ if (isBrowser() && typeof window !== 'undefined') {
 // Add static methods to the enhanced loggers for convenience
 enhancedLoggers.getInstance = JSGLogger.getInstance;
 enhancedLoggers.getInstanceSync = JSGLogger.getInstanceSync;
+enhancedLoggers.configure = JSGLogger.configure.bind(JSGLogger);
+enhancedLoggers.addTransport = JSGLogger.addTransport.bind(JSGLogger);
 enhancedLoggers.logPerformance = JSGLogger.logPerformance;
 enhancedLoggers.JSGLogger = JSGLogger;
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crimsonsunset/jsg-logger",
-  "version": "1.8.1",
+  "version": "1.8.3",
   "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",