@xh/hoist 76.0.0-SNAPSHOT.1758209096583 → 76.0.0-SNAPSHOT.1758212424281

package/utils/async/Timer.ts

@@ -7,7 +7,8 @@
 import {XH} from '@xh/hoist/core';
 import {wait} from '@xh/hoist/promise';
 import {MILLISECONDS, MINUTES, olderThan} from '@xh/hoist/utils/datetime';
-import {logError, logWarn, throwIf} from '@xh/hoist/utils/js';
+import {throwIf} from '@xh/hoist/utils/js';
+import {logError, logWarn} from '@xh/hoist/utils/log';
 import {isBoolean, isFinite, isFunction, isNil, isString, pull} from 'lodash';
 
 /**

package/utils/js/Decorators.ts

@@ -7,7 +7,7 @@
 import {XH} from '@xh/hoist/core';
 import {debounce, isFunction} from 'lodash';
 import {getOrCreate, throwIf, warnIf} from './LangUtils';
-import {withDebug, withInfo} from './LogUtils';
+import {withDebug, withInfo} from '../log/LogUtils';
 
 /**
  * Decorates a class method so that it is debounced by the specified duration.

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 {type LogSource} from '@xh/hoist/utils/log';
 import {
     flatMap,
     forOwn,
@@ -170,7 +170,7 @@ export interface APIWarnOptions {
     /** An additional message. Can contain suggestions for alternatives. */
     msg?: string;
 
-    /** Source of message for labelling log message.  */
+    /** Source of message for labeling log message.  */
     source?: LogSource;
 }
 
@@ -198,7 +198,7 @@ export function apiDeprecated(name: string, opts: APIWarnOptions = {}) {
         msg = opts.msg ?? '',
         warn = `The use of '${name}' has been deprecated and will be removed in ${v}. ${msg}`;
     if (!_seenWarnings[warn]) {
-        logWarn(warn, opts.source);
+        console.warn(warn, opts.source);
         _seenWarnings[warn] = true;
     }
 }

package/utils/js/index.ts

@@ -7,7 +7,6 @@
 export * from './HtmlUtils';
 export * from './LangUtils';
 export * from './Decorators';
-export * from './LogUtils';
 export * from './DomUtils';
 export * from './TestUtils';
 export * from './VersionUtils';

package/utils/{js → log}/LogUtils.ts

@@ -6,11 +6,66 @@
  */
 import {Some} from '@xh/hoist/core';
 import {castArray, isString} from 'lodash';
-import {intersperse} from './LangUtils';
+import store from 'store2';
+import {intersperse} from '../js/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() {
+    try {
+        return _logLevel;
+    } catch (e) {
+        return 'info';
+    }
+}
+
+/**
+ * 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()`.
  *
@@ -73,19 +128,16 @@ 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 {
+    const _severity: Record<LogLevel, number> = {error: 3, warn: 2, info: 1, debug: 0};
+
+    if (_severity[level] < _severity[getLogLevel()]) {
+        return fn?.();
+    }
+
     let src = parseSource(source);
     let msgs = castArray(messages);
 
@@ -148,4 +200,19 @@ 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';
+
+setLogLevel(store.session.get('xhLogLevel', 'info'));

package/utils/log/index.ts

@@ -0,0 +1,8 @@
+/*
+ * This file belongs to Hoist, an application development toolkit
+ * developed by Extremely Heavy Industries (www.xh.io | info@xh.io)
+ *
+ * Copyright © 2025 Extremely Heavy Industries Inc.
+ */
+
+export * from './LogUtils';