@xh/hoist 76.0.0-SNAPSHOT.1756402657806 → 76.0.0-SNAPSHOT.1756431654493

package/utils/js/LangUtils.ts

@@ -6,7 +6,7 @@
  */
 import {PlainObject, Thunkable} from '@xh/hoist/core';
 import {Exception} from '@xh/hoist/core/exception/Exception';
-import {LogSource, logWarn} from '@xh/hoist/utils/js/LogUtils';
+import {LogSource, logWarn, logError} from '@xh/hoist/utils/js/LogUtils';
 import {
     flatMap,
     forOwn,
@@ -131,7 +131,7 @@ export function throwIf(condition: any, message: unknown) {
  */
 export function warnIf(condition: any, message: any) {
     if (condition) {
-        console.warn(message);
+        logWarn(message);
     }
 }
 
@@ -140,7 +140,7 @@ export function warnIf(condition: any, message: any) {
  */
 export function errorIf(condition: any, message: any) {
     if (condition) {
-        console.error(message);
+        logError(message);
     }
 }
 

package/utils/js/LogUtils.ts

@@ -6,10 +6,62 @@
  */
 import {Some} from '@xh/hoist/core';
 import {castArray, isString} from 'lodash';
+import store from 'store2';
 import {intersperse} from './LangUtils';
 
+/**
+ * Utility functions providing managed, structured logging to Hoist apps.
+ *
+ * Essentially a wrapper around the browser console supporting logging levels, timing, and
+ * miscellaneous Hoist display conventions.
+ *
+ * Objects extending `HoistBase` need not import these functions directly, as they are available
+ * via delegates on `HoistBase`.
+ *
+ * Hoist sets its minimum severity level to 'info' by default.  This prevents performance or
+ * memory impacts that might result from verbose debug logging.  This can be adjusted by calling
+ * XH.logLevel from the console.
+ */
+
+/** Severity Level for log statement */
+export type LogLevel = 'error' | 'warn' | 'info' | 'debug';
+
+/** Object identifying the source of log statement.  Typically, a javascript class */
 export type LogSource = string | {displayName: string} | {constructor: {name: string}};
 
+/**
+ * Current minimum severity for Hoist log utils (default 'info').
+ * Messages logged via managed Hoist log utils with lower severity will be ignored.
+ *
+ * @internal - use public `XH.logLevel`.
+ */
+export function getLogLevel() {
+    return _logLevel;
+}
+
+/**
+ * Set the minimum severity for Hoist log utils until the page is refreshed. Optionally persist
+ * this adjustment to sessionStorage to maintain for the lifetime of the browser tab.
+ *
+ * @internal - use public `XH.setLogLevel()`.
+ */
+export function setLogLevel(level: LogLevel, persistInSessionStorage: boolean = false) {
+    level = level.toLowerCase() as LogLevel;
+
+    const validLevels = ['error', 'warn', 'info', 'debug'];
+    if (!validLevels.includes(level)) {
+        console.error(`Ignored invalid log level '${level}' - must be one of ${validLevels}`);
+        return;
+    }
+    _logLevel = level;
+    if (persistInSessionStorage) {
+        store.session.set('xhLogLevel', level);
+    }
+    if (level != 'info') {
+        console.warn(`Client logging set to level '${level}'.`);
+    }
+}
+
 /**
  * Time and log execution of a function to `console.info()`.
  *
@@ -72,19 +124,14 @@ export function logWarn(msgs: Some<unknown>, source?: LogSource) {
     return loggedDo(msgs, null, source, 'warn');
 }
 
-/** Parse a LogSource in to a canonical string label. */
-export function parseSource(source: LogSource): string {
-    if (!source) return null;
-    if (isString(source)) return source;
-    if (source['displayName']) return source['displayName'];
-    if (source.constructor) return source.constructor.name;
-    return null;
-}
-
 //----------------------------------
 // Implementation
 //----------------------------------
-function loggedDo<T>(messages: Some<unknown>, fn: () => T, source: LogSource, level: LogLevel) {
+function loggedDo<T>(messages: Some<unknown>, fn: () => T, source: LogSource, level: LogLevel): T {
+    if (_severity[level] < _severity[_logLevel]) {
+        return fn?.();
+    }
+
     let src = parseSource(source);
     let msgs = castArray(messages);
 
@@ -147,4 +194,20 @@ function writeLog(msgs: unknown[], src: string, level: LogLevel) {
     }
 }
 
-type LogLevel = 'error' | 'warn' | 'info' | 'debug';
+/** Parse a LogSource in to a canonical string label. */
+function parseSource(source: LogSource): string {
+    if (!source) return null;
+    if (isString(source)) return source;
+    if (source['displayName']) return source['displayName'];
+    if (source.constructor) return source.constructor.name;
+    return null;
+}
+
+//----------------------------------------------------------------
+// Initialization + Level/Severity support.
+// Initialize during parsing to make available immediately.
+//----------------------------------------------------------------
+let _logLevel: LogLevel = 'info';
+const _severity: Record<LogLevel, number> = {error: 3, warn: 2, info: 1, debug: 0};
+
+setLogLevel(store.session.get('xhLogLevel', 'info'));