@xh/hoist 59.3.2 → 59.4.0

package/desktop/cmp/treemap/TreeMap.ts

@@ -22,7 +22,7 @@ import {mask} from '@xh/hoist/desktop/cmp/mask';
 import '@xh/hoist/desktop/register';
 import {Highcharts} from '@xh/hoist/kit/highcharts';
 import {wait} from '@xh/hoist/promise';
-import {logWithDebug, withDebug} from '@xh/hoist/utils/js';
+import {logWithDebug} from '@xh/hoist/utils/js';
 import {
     createObservableRef,
     getLayoutProps,
@@ -193,13 +193,9 @@ class TreeMapLocalModel extends HoistModel {
         if (parentDims.width === 0 || parentDims.height === 0) return;
 
         assign(config.chart, parentDims, {renderTo: chartElem});
-        withDebug(
-            `Creating new TreeMap | ${newData.length} records`,
-            () => {
-                this.chart = Highcharts.chart(config);
-            },
-            this
-        );
+        this.withDebug(['Creating new TreeMap', `${newData.length} records`], () => {
+            this.chart = Highcharts.chart(config);
+        });
     }
 
     @logWithDebug

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xh/hoist",
-  "version": "59.3.2",
+  "version": "59.4.0",
   "description": "Hoist add-on for building and deploying React Applications.",
   "repository": "github:xh/hoist-react",
   "homepage": "https://xh.io",

package/svc/AutoRefreshService.ts

@@ -7,7 +7,7 @@
 import {HoistService, managed, XH} from '@xh/hoist/core';
 import {Timer} from '@xh/hoist/utils/async';
 import {olderThan, ONE_SECOND, SECONDS} from '@xh/hoist/utils/datetime';
-import {logDebug, withDefault} from '@xh/hoist/utils/js';
+import {withDefault} from '@xh/hoist/utils/js';
 
 /**
  * Service to triggers an app-wide auto-refresh (if enabled, on a configurable interval) via the
@@ -58,7 +58,7 @@ export class AutoRefreshService extends HoistService {
     // Implementation
     //------------------------
     private async onTimerAsync() {
-        if (!this.enabled || document.hidden) return;
+        if (!this.enabled || !XH.pageIsVisible) return;
 
         // Wait interval after lastCompleted -- this prevents extra refreshes if user refreshes
         // manually, or loading slow.  Note auto-loads skipped if any load in progress.
@@ -69,7 +69,7 @@ export class AutoRefreshService extends HoistService {
             pendingLoad = lastRequested && lastRequested > lastCompleted;
 
         if (!pendingLoad && olderThan(last, this.interval * SECONDS)) {
-            logDebug('Triggering application auto-refresh.', this);
+            this.logDebug('Triggering application auto-refresh.');
             await ctx.autoRefreshAsync();
         }
     }

package/svc/FetchService.ts

@@ -4,7 +4,7 @@
  *
  * Copyright © 2023 Extremely Heavy Industries Inc.
  */
-import {HoistService, XH, Exception, PlainObject, Thunkable, FetchResponse} from '@xh/hoist/core';
+import {HoistService, XH, Exception, PlainObject, FetchResponse, LoadSpec} from '@xh/hoist/core';
 import {isLocalDate, SECONDS, ONE_MINUTE, olderThan} from '@xh/hoist/utils/datetime';
 import {throwIf} from '@xh/hoist/utils/js';
 import {StatusCodes} from 'http-status-codes';
@@ -66,7 +66,7 @@ export class FetchService extends HoistService {
      * Set default headers to be sent with all subsequent requests.
      * @param headers - to be sent with all fetch requests, or a function to generate.
      */
-    setDefaultHeaders(headers: Thunkable<PlainObject>) {
+    setDefaultHeaders(headers: PlainObject | ((arg: FetchOptions) => PlainObject)) {
         this.defaultHeaders = headers;
     }
 
@@ -328,9 +328,9 @@ export interface FetchOptions {
 
     /**
      * Data to send in the request body (for POSTs/PUTs of JSON).
-     * When using `fetch`, provide a string. Otherwise, provide a PlainObject.
+     * When using `fetch`, provide a string. Otherwise, provide a JSON Serializable object
      */
-    body?: PlainObject | string;
+    body?: any;
 
     /**
      * Parameters to encode and append as a query string, or send with the request body
@@ -360,7 +360,7 @@ export interface FetchOptions {
      * Optional metadata about the underlying request. Passed through for downstream processing by
      * utils such as {@link ExceptionHandler}.
      */
-    loadSpec?: PlainObject;
+    loadSpec?: LoadSpec;
 
     /**
      * Options to pass to the underlying fetch request.

package/svc/GridAutosizeService.ts

@@ -60,24 +60,21 @@ export class GridAutosizeService extends HoistService {
             );
 
         if (!requiredWidths) {
-            console.debug('Autosize aborted, grid data is obsolete.');
+            this.logDebug('Autosize aborted, grid data is obsolete.');
             return;
         }
 
         runInAction(() => {
             // 4) Set columns to their required widths.
             gridModel.applyColumnStateChanges(requiredWidths);
-            console.debug(
-                `Column widths autosized via GridAutosizeService (${records.length} records)`,
-                requiredWidths
-            );
+            this.logDebug(`Auto-sized columns`, `${records.length} records`, requiredWidths);
 
             // 5) Grow columns to fill any remaining space, if enabled.
             const {fillMode} = options;
             if (fillMode && fillMode !== 'none') {
                 const fillWidths = this.calcFillWidths(gridModel, colIds, fillMode);
                 gridModel.applyColumnStateChanges(fillWidths);
-                console.debug('Column widths filled via GridAutosizeService', fillWidths);
+                this.logDebug('Auto-sized columns using fillMode', fillWidths);
             }
         });
     }
@@ -170,7 +167,7 @@ export class GridAutosizeService extends HoistService {
             available = agApi?.gridPanel?.eBodyViewport?.clientWidth;
 
         if (!agApi || !isFinite(available)) {
-            console.warn('Grid not rendered - unable to fill columns.');
+            this.logWarn('Grid not rendered - unable to fill columns.');
             return [];
         }
 

package/svc/TrackService.ts

@@ -97,19 +97,19 @@ export class TrackService extends HoistService {
 
             const {maxDataLength} = this.conf;
             if (params.data?.length > maxDataLength) {
-                console.warn(
-                    `[TrackService] | Track log includes ${params.data.length} chars of JSON data | exceeds limit of ${maxDataLength} | data will not be persisted`,
+                this.logWarn(
+                    `Track log includes ${params.data.length} chars of JSON data`,
+                    `exceeds limit of ${maxDataLength}`,
+                    'data will not be persisted',
                     options.data
                 );
                 params.data = null;
             }
 
             const elapsedStr = params.elapsed != null ? `${params.elapsed}ms` : null,
-                consoleMsg = ['[Track]', params.category, params.msg, elapsedStr]
-                    .filter(it => it != null)
-                    .join(' | ');
+                consoleMsgs = [params.category, params.msg, elapsedStr].filter(it => it != null);
 
-            console.log(consoleMsg);
+            this.logInfo(...consoleMsgs);
 
             await XH.fetchJson({url: 'xh/track', params});
         } catch (e) {

package/svc/WebSocketService.ts

@@ -6,7 +6,7 @@
  */
 import {HoistService, XH} from '@xh/hoist/core';
 import {Icon} from '@xh/hoist/icon';
-import {action, observable, makeObservable} from '@xh/hoist/mobx';
+import {action, makeObservable, observable} from '@xh/hoist/mobx';
 import {Timer} from '@xh/hoist/utils/async';
 import {SECONDS} from '@xh/hoist/utils/datetime';
 import {throwIf} from '@xh/hoist/utils/js';
@@ -55,11 +55,11 @@ export class WebSocketService extends HoistService {
         return !!this.channelKey;
     }
 
-    /** set to true to log all sent/received messages - very chatty. */
+    /** Set to true to log all sent/received messages - very chatty. */
     logMessages: boolean = false;
 
-    private _timer;
-    private _socket;
+    private _timer: Timer;
+    private _socket: WebSocket;
     private _subsByTopic = {};
 
     enabled: boolean = XH.appSpec.webSocketsEnabled;
@@ -72,9 +72,8 @@ export class WebSocketService extends HoistService {
     override async initAsync() {
         if (!this.enabled) return;
         if (XH.environmentService.get('webSocketsEnabled') === false) {
-            console.error(
-                'WebSockets have been enabled on this client app, but are disabled on the server. ' +
-                    'Please adjust your server-side configuration to use WebSockets.'
+            this.logError(
+                `WebSockets enabled on this client app but disabled on server. Adjust your server-side config.`
             );
             this.enabled = false;
             return;
@@ -151,7 +150,7 @@ export class WebSocketService extends HoistService {
             };
             this._socket = s;
         } catch (e) {
-            console.error('Failure creating WebSocket in WebSocketService', e);
+            this.logError('Failure creating WebSocket', e);
         }
 
         this.updateConnectedStatus();
@@ -170,7 +169,7 @@ export class WebSocketService extends HoistService {
         if (this.connected) {
             this.sendMessage({topic: this.HEARTBEAT_TOPIC, data: 'ping'});
         } else {
-            console.warn('Heartbeat found websocket not connected - attempting to reconnect.');
+            this.logWarn('Heartbeat found websocket not connected - attempting to reconnect...');
             this.disconnect();
             this.connect();
         }
@@ -185,17 +184,17 @@ export class WebSocketService extends HoistService {
     // Socket events impl
     //------------------------
     onOpen(ev) {
-        console.debug('WebSocket connection opened', ev);
+        this.logDebug('WebSocket connection opened', ev);
         this.updateConnectedStatus();
     }
 
     onClose(ev) {
-        console.debug('WebSocket connection closed', ev);
+        this.logDebug('WebSocket connection closed', ev);
         this.updateConnectedStatus();
     }
 
     onError(ev) {
-        console.error('WebSocket connection error', ev);
+        this.logError('WebSocket connection error', ev);
         this.updateConnectedStatus();
     }
 
@@ -221,7 +220,7 @@ export class WebSocketService extends HoistService {
 
             this.notifySubscribers(msg);
         } catch (e) {
-            console.error('Error decoding websocket message', rawMsg, e);
+            this.logError('Error decoding websocket message', rawMsg, e);
         }
         this.updateConnectedStatus();
     }
@@ -236,7 +235,7 @@ export class WebSocketService extends HoistService {
             try {
                 sub.fn(message);
             } catch (e) {
-                console.error(`Failure in subscription handler for topic ${message.topic}`, e);
+                this.logError(`Handler for topic ${message.topic} threw`, e);
             }
         });
     }
@@ -287,7 +286,7 @@ export class WebSocketService extends HoistService {
     }
 
     maybeLogMessage(...args) {
-        if (this.logMessages) console.log(...args);
+        if (this.logMessages) this.logDebug(args);
     }
 }
 

package/utils/async/AsyncUtils.ts

@@ -4,6 +4,7 @@
  *
  * Copyright © 2023 Extremely Heavy Industries Inc.
  */
+import {XH} from '@xh/hoist/core';
 import {wait} from '@xh/hoist/promise';
 
 /**
@@ -15,7 +16,7 @@ import {wait} from '@xh/hoist/promise';
  * allowing ongoing rendering of UI updates (e.g. load masks) and generally keeping the browser
  * event loop running.
  *
- * Note that if the browser tab is hidden (i.e. document.hidden is true) this loop will be executed
+ * Note that if the content tab is hidden (i.e. `!XH.pageIsVisible`) this loop will be executed
  * without pauses.  In this case the pauses would be unduly large due to throttling of the event
  * loop by the browser, and there is no user benefit to avoiding blocking the main thread.
  *
@@ -55,7 +56,7 @@ export async function whileAsync(
     const {waitAfter = 50, waitFor = 0} = opts ?? {};
 
     // Fallback to basic loop when doc hidden: no user benefit, and throttling causes outsize waits
-    if (document.hidden) {
+    if (!XH.pageIsVisible) {
         while (conditionFn()) fn();
         return;
     }

package/utils/async/Timer.ts

@@ -7,7 +7,7 @@
 import {XH} from '@xh/hoist/core';
 import {wait} from '@xh/hoist/promise';
 import {MILLISECONDS, MINUTES, olderThan} from '@xh/hoist/utils/datetime';
-import {throwIf} from '@xh/hoist/utils/js';
+import {logWarn, throwIf} from '@xh/hoist/utils/js';
 import {isBoolean, isFinite, isFunction, isNil, isString, pull} from 'lodash';
 
 /**
@@ -152,8 +152,9 @@ export class Timer {
         if (ret > 0 && ret < min) {
             if (!warnedIntervals.has(ret)) {
                 warnedIntervals.add(ret);
-                console.warn(
-                    `Timer interval of ${ret}ms requested - forcing to min interval of ${min}ms.`
+                logWarn(
+                    `Interval of ${ret}ms requested - forcing to min interval of ${min}ms.`,
+                    this
                 );
             }
             ret = min;

package/utils/js/BrowserUtils.ts

@@ -10,8 +10,7 @@ import {pick} from 'lodash';
  * Extract information (if available) about the client browser's window, screen, and network speed.
  */
 export function getClientDeviceInfo() {
-    const data: any = pick(
-        window,
+    const data: any = pick(window, [
         'screen',
         'devicePixelRatio',
         'screenX',
@@ -20,10 +19,10 @@ export function getClientDeviceInfo() {
         'innerHeight',
         'outerWidth',
         'outerHeight'
-    );
+    ]);
+
     if (data.screen) {
-        data.screen = pick(
-            data.screen,
+        data.screen = pick(data.screen, [
             'availWidth',
             'availHeight',
             'width',
@@ -33,14 +32,15 @@ export function getClientDeviceInfo() {
             'availLeft',
             'availTop',
             'orientation'
-        );
+        ]);
         if (data.screen.orientation) {
-            data.screen.orientation = pick(data.screen.orientation, 'angle', 'type');
+            data.screen.orientation = pick(data.screen.orientation, ['angle', 'type']);
         }
     }
+
     const nav = window.navigator as any;
     if (nav.connection) {
-        data.connection = pick(nav.connection, 'downlink', 'effectiveType', 'rtt');
+        data.connection = pick(nav.connection, ['downlink', 'effectiveType', 'rtt']);
     }
 
     return data;

package/utils/js/LangUtils.ts

@@ -12,7 +12,7 @@ import {
     isEmpty,
     isFunction,
     isObject,
-    isObjectLike,
+    isPlainObject,
     isUndefined,
     mixin,
     uniq,
@@ -53,22 +53,23 @@ export function withDefault<T>(...args: T[]): T {
 }
 
 /**
- * Recursively freeze an object, preventing future modifications. Not all objects are supported -
- * FREEZABLE_TYPES limits what we will attempt to freeze to a whitelist of types known to be safely
- * freezable without side effects. This avoids freezing other types of objects where this routine
+ * Recursively freeze an object, preventing future modifications. Only the specific declared
+ * input types will be frozen.  This avoids freezing other types of objects where this routine
  * could be problematic - e.g. application or library classes (such as `moment`!) which rely on
  * their internal state remaining mutable to function.
  */
-const FREEZABLE_TYPES: Set<String> = new Set(['Object', 'Array', 'Map', 'Set']);
-export function deepFreeze(obj: object) {
-    if (!isObjectLike(obj) || !FREEZABLE_TYPES.has(obj.constructor.name)) return obj;
+export function deepFreeze<
+    T extends Record<string, unknown> | Array<unknown> | Map<unknown, unknown> | Set<unknown>
+>(obj: T): Readonly<T> {
+    if (!(isPlainObject(obj) || isArray(obj) || obj instanceof Map || obj instanceof Set)) {
+        return obj;
+    }
 
     const propNames = Object.getOwnPropertyNames(obj);
     for (const name of propNames) {
         deepFreeze(obj[name]);
     }
-
-    return Object.freeze(obj);
+    return Object.freeze<T>(obj);
 }
 
 /**

package/utils/js/LogUtils.ts

@@ -4,10 +4,14 @@
  *
  * Copyright © 2023 Extremely Heavy Industries Inc.
  */
+import {Some} from '@xh/hoist/core';
 import {castArray, isString} from 'lodash';
+import {intersperse} from './LangUtils';
+
+export type LogSource = string | {displayName: string} | {constructor: {name: string}};
 
 /**
- * Track a function execution with console.log.
+ * Time and log execution of a function to `console.info()`.
  *
  * This method will log the provided message(s) with timing information in a single message *after*
  * the tracked function returns.
@@ -20,61 +24,78 @@ import {castArray, isString} from 'lodash';
  * @param fn - function to execute
  * @param source - class, function or string to label the source of the message
  */
-export function withInfo<T>(msgs: string[] | string, fn: () => T, source?: any): T {
+export function withInfo<T>(msgs: Some<unknown>, fn: () => T, source?: LogSource): T {
     return loggedDo(msgs, fn, source, 'info');
 }
 
 /**
- * Track a function execution with console.debug.
+ * Time and log execution of a function to `console.debug()`.
  * @see withInfo
  */
-export function withDebug<T>(msgs: string[] | string, fn: () => T, source?: any): T {
+export function withDebug<T>(msgs: Some<unknown>, fn: () => T, source?: LogSource): T {
     return loggedDo(msgs, fn, source, 'debug');
 }
 
 /**
- * Log a message with console.log.
- *
+ * Write to `console.log()` with standardized formatting and source info.
  * @param msgs - message(s) to output
  * @param source - class, function or string to label the source of the message
  */
-export function logInfo(msgs: string[] | string, source?: any) {
+export function logInfo(msgs: Some<unknown>, source?: LogSource) {
     return loggedDo(msgs, null, source, 'info');
 }
 
 /**
- * Log a message with console.debug.
- * @see logInfo
+ * Write to `console.debug()` with standardized formatting and source info.
+ * @param msgs - message(s) to output
+ * @param source - class, function or string to label the source of the message
  */
-export function logDebug(msgs: string[] | string, source?: any) {
+export function logDebug(msgs: Some<unknown>, source?: LogSource) {
     return loggedDo(msgs, null, source, 'debug');
 }
 
+/**
+ * Write to `console.error()` with standardized formatting and source info.
+ * @param msgs - message(s) to output
+ * @param source - class, function or string to label the source of the message
+ */
+export function logError(msgs: Some<unknown>, source?: LogSource) {
+    return loggedDo(msgs, null, source, 'error');
+}
+
+/**
+ * Write to `console.warn()` with standardized formatting and source info.
+ * @param msgs - message(s) to output
+ * @param source - class, function or string to label the source of the message
+ */
+export function logWarn(msgs: Some<unknown>, source?: LogSource) {
+    return loggedDo(msgs, null, source, 'warn');
+}
+
 //----------------------------------
 // Implementation
 //----------------------------------
-function loggedDo(msgs, fn, source, level) {
-    source = parseSource(source);
-    msgs = castArray(msgs);
-    const msg = msgs.join(' | ');
+function loggedDo<T>(messages: Some<unknown>, fn: () => T, source: LogSource, level: LogLevel) {
+    let src = parseSource(source);
+    let msgs = castArray(messages);
 
     // Support simple message only.
     if (!fn) {
-        writeLog(msg, source, level);
+        writeLog(msgs, src, level);
         return;
     }
 
     // Otherwise, wrap the call to the provided fn.
-    let start, ret;
+    let start: number, ret: T;
     const logCompletion = () => {
             const elapsed = Date.now() - start;
-            writeLog(`${msg} | ${elapsed}ms`, source, level);
+            writeLog([...msgs, `${elapsed}ms`], src, level);
         },
         logException = e => {
             const elapsed = Date.now() - start;
             writeLog(
-                `${msg} | failed - ${e.message ?? e.name ?? 'Unknown error'} | ${elapsed}ms`,
-                source,
+                [...msgs, `failed - ${e.message ?? e.name ?? 'Unknown error'}`, `${elapsed}ms`, e],
+                src,
                 level
             );
         };
@@ -96,14 +117,33 @@ function loggedDo(msgs, fn, source, level) {
     return ret;
 }
 
-function parseSource(source) {
+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 '';
+    if (source['displayName']) return source['displayName'];
+    if (source.constructor) return source.constructor.name;
+    return null;
 }
 
-function writeLog(msg, source, level) {
-    if (source) msg = `[${source}] ${msg}`;
-    level === 'info' ? console.log(msg) : console.debug(msg);
+function writeLog(msgs: unknown[], src: string, level: LogLevel) {
+    if (src) msgs = [`[${src}]`, ...msgs];
+
+    msgs = intersperse(msgs, '|');
+
+    switch (level) {
+        case 'error':
+            console.error(...msgs);
+            break;
+        case 'warn':
+            console.warn(...msgs);
+            break;
+        case 'debug':
+            console.debug(...msgs);
+            break;
+        case 'info':
+            console.log(...msgs);
+            break;
+    }
 }
+
+type LogLevel = 'error' | 'warn' | 'info' | 'debug';

package/utils/react/LayoutPropUtils.ts

@@ -4,7 +4,7 @@
  *
  * Copyright © 2023 Extremely Heavy Industries Inc.
  */
-import {HoistProps, LayoutProps, PlainObject} from '@xh/hoist/core';
+import {HoistProps, LayoutProps} from '@xh/hoist/core';
 import {forOwn, isEmpty, isNumber, isString, isNil, omit, pick} from 'lodash';
 
 /**
@@ -40,9 +40,9 @@ import {forOwn, isEmpty, isNumber, isString, isNil, omit, pick} from 'lodash';
  * that afforded by the underlying flexbox styles. In particular, it accepts flex and sizing props
  * as raw numbers rather than strings.
  */
-export function getLayoutProps(props: PlainObject): LayoutProps {
+export function getLayoutProps(props: HoistProps): LayoutProps {
     // Harvest all keys of interest
-    const ret: LayoutProps = pick(props, allKeys);
+    const ret: LayoutProps = pick(props, allKeys) as LayoutProps;
 
     // flexXXX: convert raw number to string
     const flexConfig = pick(ret, flexKeys);