@xh/hoist 72.3.0 → 72.4.0

package/core/XH.ts

@@ -28,7 +28,8 @@ import {
     PrefService,
     SessionStorageService,
     TrackService,
-    WebSocketService
+    WebSocketService,
+    ClientHealthService
 } from '@xh/hoist/svc';
 import {camelCase, flatten, isString, uniqueId} from 'lodash';
 import {Router, State} from 'router5';
@@ -64,6 +65,7 @@ import {
 import {installServicesAsync} from './impl/InstallServices';
 import {instanceManager} from './impl/InstanceManager';
 import {HoistModel, ModelSelector, RefreshContextModel} from './model';
+import ShortUniqueId from 'short-unique-id';
 
 export const MIN_HOIST_CORE_VERSION = '28.0';
 
@@ -84,6 +86,15 @@ declare const xhIsDevelopmentMode: boolean;
  * Available via import as `XH` - also installed as `window.XH` for troubleshooting purposes.
  */
 export class XHApi {
+    /** Unique id for this loaded instance of the app.  Unique for every refresh of document. */
+    clientId: string = this.genClientId();
+
+    /**
+     * Unique id for this browser tab/window on this domain.
+     * Corresponds to the scope of the built-in sessionStorage object.
+     */
+    sessionId: string = this.genSessionId();
+
     //--------------------------
     // Implementation Delegates
     //--------------------------
@@ -131,6 +142,7 @@ export class XHApi {
     alertBannerService: AlertBannerService;
     autoRefreshService: AutoRefreshService;
     changelogService: ChangelogService;
+    clientHealthService: ClientHealthService;
     configService: ConfigService;
     environmentService: EnvironmentService;
     fetchService: FetchService;
@@ -794,6 +806,19 @@ export class XHApi {
     private get acm(): AppContainerModel {
         return this.appContainerModel;
     }
+
+    private genClientId(): string {
+        return new ShortUniqueId({length: 8}).rnd();
+    }
+
+    private genSessionId(): string {
+        let ret = window.sessionStorage?.getItem('xhSessionId');
+        if (!ret) {
+            ret = new ShortUniqueId({length: 8}).rnd();
+            window.sessionStorage?.setItem('xhSessionId', ret);
+        }
+        return ret;
+    }
 }
 
 /** The app-wide singleton instance. */

package/desktop/cmp/viewmanager/ViewMenu.ts

@@ -12,7 +12,7 @@ import {Icon} from '@xh/hoist/icon';
 import {menu, menuDivider, menuItem} from '@xh/hoist/kit/blueprint';
 import {pluralize} from '@xh/hoist/utils/js';
 import {Dictionary} from 'express-serve-static-core';
-import {each, filter, groupBy, isEmpty, orderBy, some, startCase} from 'lodash';
+import {each, filter, groupBy, isEmpty, isFunction, orderBy, some, startCase} from 'lodash';
 import {ReactNode} from 'react';
 import {ViewManagerLocalModel} from './ViewManagerLocalModel';
 
@@ -162,12 +162,14 @@ function viewMenuItem(view: ViewInfo, model: ViewManagerModel): ReactNode {
     if (!view.isOwned && view.owner) title.push(view.owner);
     if (view.description) title.push(view.description);
 
-    return menuItem({
-        className: 'xh-view-manager__menu-item',
-        key: view.token,
-        text: view.name,
-        title: title.join(' | '),
-        icon,
-        onClick: () => model.selectViewAsync(view).catchDefault()
-    });
+    return isFunction(model.viewMenuItemFn)
+        ? model.viewMenuItemFn(view, model)
+        : menuItem({
+              className: 'xh-view-manager__menu-item',
+              key: view.token,
+              text: view.name,
+              title: title.join(' | '),
+              icon,
+              onClick: () => model.selectViewAsync(view).catchDefault()
+          });
 }

package/format/FormatDate.ts

@@ -4,11 +4,11 @@
  *
  * Copyright © 2025 Extremely Heavy Industries Inc.
  */
-import {isLocalDate, LocalDate} from '@xh/hoist/utils/datetime';
-import {defaults, isString} from 'lodash';
+import {DAYS, isLocalDate, LocalDate} from '@xh/hoist/utils/datetime';
+import {defaults, isFinite, isString} from 'lodash';
 import moment from 'moment';
 import {ReactNode} from 'react';
-import {DateLike} from '../core/types/Types';
+import {DateLike, PlainObject} from '../core/types/Types';
 import {fmtSpan, FormatOptions} from './FormatMisc';
 import {createRenderer} from './FormatUtils';
 import {saveOriginal} from './impl/Utils';
@@ -148,6 +148,48 @@ export function fmtCompactDate(v: DateLike, opts?: CompactDateFormatOptions) {
     return fmtDate(v, dateOpts);
 }
 
+export interface TimestampReplacerConfig {
+    /**
+     * Suffixes used to identify keys that may hold timestamps.
+     * Defaults to ['time', 'date', 'timestamp']
+     */
+    suffixes?: string[];
+
+    /**
+     * Format for replaced timestamp.
+     * Defaults to 'MMM DD HH:mm:ss.SSS'
+     */
+    format?: string;
+}
+
+/**
+ * Replace timestamps in an Object with formatted strings.
+ */
+export function withFormattedTimestamps(
+    obj: PlainObject,
+    config: TimestampReplacerConfig = {}
+): PlainObject {
+    return JSON.parse(JSON.stringify(obj, timestampReplacer(config)));
+}
+
+/**
+ * Create a replacer, suitable for JSON.stringify, that will replace timestamps with
+ * formatted strings.
+ */
+export function timestampReplacer(
+    config: TimestampReplacerConfig = {}
+): (k: string, v: any) => any {
+    const suffixes = config.suffixes ?? ['time', 'date', 'timestamp'],
+        fmt = 'MMM DD HH:mm:ss.SSS';
+    return (k: string, v: any) => {
+        return suffixes.some(s => k.toLowerCase().endsWith(s.toLowerCase())) &&
+            isFinite(v) &&
+            v > Date.now() - 25 * 365 * DAYS // heuristic to avoid catching smaller ms ranges
+            ? fmtDateTime(v, {fmt})
+            : v;
+    };
+}
+
 export const dateRenderer = createRenderer(fmtDate),
     dateTimeRenderer = createRenderer(fmtDateTime),
     dateTimeSecRenderer = createRenderer(fmtDateTimeSec),

package/format/FormatMisc.ts

@@ -5,8 +5,9 @@
  * Copyright © 2025 Extremely Heavy Industries Inc.
  */
 import {span} from '@xh/hoist/cmp/layout';
-import {capitalize, isNil, kebabCase, map} from 'lodash';
+import {capitalize, isNil, isString, kebabCase, map} from 'lodash';
 import {CSSProperties, ReactNode} from 'react';
+import {PlainObject} from '@xh/hoist/core';
 
 export interface FormatOptions<T = any> {
     /** Display value for null values. */
@@ -63,11 +64,12 @@ export interface JSONFormatOptions {
 }
 
 /**
- * Pretty-print a JSON string, adding line breaks and indentation.
+ * Pretty-print a JSON string or (JSON Object), adding line breaks and indentation.
  */
-export function fmtJson(str: string, opts?: JSONFormatOptions): string {
+export function fmtJson(v: string | PlainObject, opts?: JSONFormatOptions): string {
     const {replacer = undefined, space = 2} = opts ?? {};
-    return isNil(str) ? '' : JSON.stringify(JSON.parse(str), replacer, space);
+    if (isString(v)) v = JSON.parse(v);
+    return isNil(v) ? '' : JSON.stringify(v, replacer, space);
 }
 
 /**

package/package.json

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

package/security/Types.ts

@@ -31,8 +31,8 @@ export interface TelemetryResults {
 
 /** Aggregated telemetry results for a single type of event. */
 export interface TelemetryEventResults {
-    firstTime: Date;
-    lastTime: Date;
+    firstTime: number;
+    lastTime: number;
     successCount: number;
     failureCount: number;
     /** Timing info (in ms) for event instances reported with duration. */
@@ -43,7 +43,7 @@ export interface TelemetryEventResults {
         worst: number;
     };
     lastFailure?: {
-        time: Date;
+        time: number;
         duration: number;
         code: string;
         name: string;

package/security/msal/MsalClient.ts

@@ -14,9 +14,10 @@ import {
     PopupRequest,
     SilentRequest
 } from '@azure/msal-browser';
-import {XH} from '@xh/hoist/core';
+import {AppState, PlainObject, XH} from '@xh/hoist/core';
 import {Token} from '@xh/hoist/security/Token';
 import {logDebug, logError, logInfo, logWarn, mergeDeep, throwIf} from '@xh/hoist/utils/js';
+import {withFormattedTimestamps} from '@xh/hoist/format';
 import {flatMap, union, uniq} from 'lodash';
 import {BaseOAuthClient, BaseOAuthClientConfig} from '../BaseOAuthClient';
 import {AccessTokenSpec, TelemetryResults, TokenMap} from '../Types';
@@ -266,9 +267,13 @@ export class MsalClient extends BaseOAuthClient<MsalClientConfig, MsalTokenSpec>
     //------------------------
     // Telemetry
     //------------------------
+    getFormattedTelemetry(): PlainObject {
+        return withFormattedTimestamps(this.telemetryResults);
+    }
+
     enableTelemetry(): void {
         if (this._telemetryCbHandle) {
-            this.logInfo('Telemetry already enabled', this.telemetryResults);
+            this.logInfo('Telemetry already enabled', this.getFormattedTelemetry());
             return;
         }
 
@@ -279,7 +284,7 @@ export class MsalClient extends BaseOAuthClient<MsalClientConfig, MsalTokenSpec>
                 try {
                     const {events} = this.telemetryResults,
                         {name, startTimeMs, durationMs, success, errorName, errorCode} = e,
-                        eTime = startTimeMs ? new Date(startTimeMs) : new Date();
+                        eTime = startTimeMs ?? Date.now();
 
                     const eResult = (events[name] ??= {
                         firstTime: eTime,
@@ -316,15 +321,10 @@ export class MsalClient extends BaseOAuthClient<MsalClientConfig, MsalTokenSpec>
             });
         });
 
-        // Ask TrackService to include in background health check report, if enabled on that service.
-        // Handle TrackService not yet initialized (common, this client likely initialized before.)
+        // Wait for clientHealthService (this client likely initialized during earlier AUTHENTICATING.)
         this.addReaction({
-            when: () => XH.appIsRunning,
-            run: () =>
-                XH.trackService.addClientHealthReportSource(
-                    'msalClient',
-                    () => this.telemetryResults
-                )
+            when: () => XH.appState === AppState.INITIALIZING_APP,
+            run: () => XH.clientHealthService.addSource('msalClient', () => this.telemetryResults)
         });
 
         this.logInfo('Telemetry enabled');
@@ -339,8 +339,8 @@ export class MsalClient extends BaseOAuthClient<MsalClientConfig, MsalTokenSpec>
         this.client.removePerformanceCallback(this._telemetryCbHandle);
         this._telemetryCbHandle = null;
 
-        XH.trackService.removeClientHealthReportSource('msalClient');
-        this.logInfo('Telemetry disabled', this.telemetryResults);
+        XH.clientHealthService.removeSource('msalClient');
+        this.logInfo('Telemetry disabled', this.getFormattedTelemetry());
     }
 
     //------------------------

package/svc/ClientHealthService.ts

@@ -0,0 +1,165 @@
+/*
+ * 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.
+ */
+import {HoistService, PageState, PlainObject, XH} from '@xh/hoist/core';
+import {Timer} from '@xh/hoist/utils/async';
+import {MINUTES} from '@xh/hoist/utils/datetime';
+import {withFormattedTimestamps} from '@xh/hoist/format';
+import {pick, round} from 'lodash';
+
+/**
+ * Service for gathering data about client health.
+ *
+ * Hoist sends this data once on application load, and can be configured to send
+ * it at regularly scheduled intervals.  Configure via soft-config property
+ * 'xhActivityTracking.clientHealthReport'.
+ */
+export class ClientHealthService extends HoistService {
+    static instance: ClientHealthService;
+
+    private sources: Map<string, () => any> = new Map();
+
+    override async initAsync() {
+        const {clientHealthReport} = XH.trackService.conf;
+        Timer.create({
+            runFn: () => this.sendReport(),
+            interval: clientHealthReport.intervalMins * MINUTES,
+            delay: true
+        });
+    }
+
+    /**
+     * Main entry point.  Return a default report of client health.
+     */
+    getReport(): ClientHealthReport {
+        return {
+            general: this.getGeneral(),
+            memory: this.getMemory(),
+            connection: this.getConnection(),
+            ...this.getCustom()
+        };
+    }
+
+    /** Get report, suitable for viewing in console. **/
+    getFormattedReport(): PlainObject {
+        return withFormattedTimestamps(this.getReport());
+    }
+
+    /**
+     * Register a new source for client health report data. No-op if background health report is
+     * not generally enabled via `xhActivityTrackingConfig.clientHealthReport.intervalMins`.
+     *
+     * @param key - key under which to report the data - can be used to remove this source later.
+     * @param callback - function returning serializable to include with each report.
+     */
+    addSource(key: string, callback: () => any) {
+        this.sources.set(key, callback);
+    }
+
+    /** Unregister a previously-enabled source for client health report data. */
+    removeSource(key: string) {
+        this.sources.delete(key);
+    }
+
+    // -----------------------------------
+    // Generate individual report sections
+    //------------------------------------
+    getGeneral(): GeneralData {
+        const startTime = XH.appContainerModel.appStateModel.loadStarted,
+            elapsedMins = (ts: number) => round((Date.now() - ts) / 60_000, 1);
+
+        return {
+            startTime,
+            durationMins: elapsedMins(startTime),
+            idleMins: elapsedMins(XH.lastActivityMs),
+            pageState: XH.pageState,
+            webSocket: XH.webSocketService.channelKey
+        };
+    }
+
+    getConnection(): ConnectionData {
+        const nav = window.navigator as any;
+        if (!nav.connection) return null;
+        return pick(nav.connection, ['downlink', 'effectiveType', 'rtt']);
+    }
+
+    getMemory(): MemoryData {
+        const perf = window.performance as any;
+        if (!perf?.memory) return null;
+
+        const ret: MemoryData = {modelCount: XH.getModels().length};
+        ['jsHeapSizeLimit', 'totalJSHeapSize', 'usedJSHeapSize'].forEach(key => {
+            const raw = perf.memory[key];
+            if (raw) ret[key] = round(raw / 1024 / 1024); // convert to MB
+        });
+
+        const {jsHeapSizeLimit: limit, usedJSHeapSize: used} = ret;
+        if (limit && used) {
+            ret.usedPctLimit = round((used / limit) * 100);
+        }
+
+        return ret;
+    }
+
+    getCustom(): PlainObject {
+        const ret = {};
+        this.sources.forEach((cb, k) => {
+            try {
+                ret[k] = cb();
+            } catch (e) {
+                ret[k] = `Error: ${e.message}`;
+                this.logWarn(`Error running client health report callback for [${k}]`, e);
+            }
+        });
+        return ret;
+    }
+
+    //------------------
+    // Implementation
+    //------------------
+    private sendReport() {
+        const {intervalMins, ...rest} = XH.trackService.conf.clientHealthReport ?? {};
+
+        XH.track({
+            category: 'App',
+            message: 'Submitted health report',
+            ...rest,
+            data: {
+                clientId: XH.clientId,
+                sessionId: XH.sessionId,
+                ...this.getReport()
+            }
+        });
+    }
+}
+
+export interface GeneralData {
+    startTime: number;
+    durationMins: number;
+    idleMins: number;
+    pageState: PageState;
+    webSocket: string;
+}
+
+export interface ConnectionData {
+    downlink: number;
+    effectiveType: string;
+    rtt: number;
+}
+
+export interface MemoryData {
+    modelCount: number;
+    usedPctLimit?: number;
+    jsHeapSizeLimit?: number;
+    totalJSHeapSize?: number;
+    usedJSHeapSize?: number;
+}
+
+export interface ClientHealthReport {
+    general: GeneralData;
+    connection: ConnectionData;
+    memory: MemoryData;
+}

package/svc/TrackService.ts

@@ -5,11 +5,10 @@
  * Copyright © 2025 Extremely Heavy Industries Inc.
  */
 import {HoistService, PlainObject, TrackOptions, XH} from '@xh/hoist/core';
-import {Timer} from '@xh/hoist/utils/async';
-import {MINUTES, SECONDS} from '@xh/hoist/utils/datetime';
+import {SECONDS} from '@xh/hoist/utils/datetime';
 import {isOmitted} from '@xh/hoist/utils/impl';
-import {debounced, getClientDeviceInfo, stripTags, withDefault} from '@xh/hoist/utils/js';
-import {isEmpty, isNil, isString, round} from 'lodash';
+import {debounced, stripTags, withDefault} from '@xh/hoist/utils/js';
+import {isEmpty, isNil, isString} from 'lodash';
 
 /**
  * Primary service for tracking any activity that an application's admins want to track.
@@ -19,21 +18,10 @@ import {isEmpty, isNil, isString, round} from 'lodash';
 export class TrackService extends HoistService {
     static instance: TrackService;
 
-    private clientHealthReportSources: Map<string, () => any> = new Map();
     private oncePerSessionSent = new Map();
     private pending: PlainObject[] = [];
 
     override async initAsync() {
-        const {clientHealthReport} = this.conf;
-        if (clientHealthReport?.intervalMins > 0) {
-            Timer.create({
-                runFn: () => this.sendClientHealthReport(),
-                interval: clientHealthReport.intervalMins,
-                intervalUnits: MINUTES,
-                delay: true
-            });
-        }
-
         window.addEventListener('beforeunload', () => this.pushPendingAsync());
     }
 
@@ -102,22 +90,6 @@ export class TrackService extends HoistService {
         this.pushPendingBuffered();
     }
 
-    /**
-     * Register a new source for client health report data. No-op if background health report is
-     * not generally enabled via `xhActivityTrackingConfig.clientHealthReport.intervalMins`.
-     *
-     * @param key - key under which to report the data - can be used to remove this source later.
-     * @param callback - function returning serializable to include with each report.
-     */
-    addClientHealthReportSource(key: string, callback: () => any) {
-        this.clientHealthReportSources.set(key, callback);
-    }
-
-    /** Unregister a previously-enabled source for client health report data. */
-    removeClientHealthReportSource(key: string) {
-        this.clientHealthReportSources.delete(key);
-    }
-
     //------------------
     // Implementation
     //------------------
@@ -176,42 +148,6 @@ export class TrackService extends HoistService {
 
         this.logInfo(...consoleMsgs);
     }
-
-    private sendClientHealthReport() {
-        const {
-                intervalMins,
-                severity: defaultSeverity,
-                ...rest
-            } = this.conf.clientHealthReport ?? {},
-            {loadStarted} = XH.appContainerModel.appStateModel;
-
-        const data = {
-            session: {
-                started: loadStarted,
-                durationMins: round((Date.now() - loadStarted) / 60_000, 1)
-            },
-            ...getClientDeviceInfo()
-        };
-
-        let severity = defaultSeverity ?? 'INFO';
-        this.clientHealthReportSources.forEach((cb, k) => {
-            try {
-                data[k] = cb();
-                if (data[k]?.severity === 'WARN') severity = 'WARN';
-            } catch (e) {
-                data[k] = `Error: ${e.message}`;
-                this.logWarn(`Error running client health report callback for [${k}]`, e);
-            }
-        });
-
-        this.track({
-            category: 'App',
-            message: 'Submitted health report',
-            severity,
-            ...rest,
-            data
-        });
-    }
 }
 
 interface ActivityTrackingConfig {

package/svc/index.ts

@@ -19,5 +19,6 @@ export * from './JsonBlobService';
 export * from './PrefService';
 export * from './TrackService';
 export * from './WebSocketService';
+export * from './ClientHealthService';
 export * from './storage/LocalStorageService';
 export * from './storage/SessionStorageService';